CHANGES-1.4.txt
---------------
+CHANGES IN CUPS V1.4.8
+
+ - The scheduler would delete job data files when restarted (STR #3880)
+ - The network backends could crash if a printer returned a value of 0
+ for the maximum capacity for a supply (STR #3875)
+
+
CHANGES IN CUPS V1.4.7
- Documentation changes (STR #3710, STR #3720, STR #3745, STR #3750,
STR #3755, STR #3769, STR #3783)
- Configure script fixes (STR #3659, STR #3691)
- Compilation fixes (STR #3718, STR #3771, STR #3774)
+ - The imageto* filters could crash with bad GIF files (STR #3867)
- The scheduler might leave old job data files in the spool directory
(STR #3795)
- CUPS did not work with locales using the ASCII character set
-CHANGES.txt - 2011-06-14
+CHANGES.txt - 2011-08-06
------------------------
+CHANGES IN CUPS V1.5.1
+
+ - Documentation updates (STR #3885)
+ - The scheduler did not report the correct version in the Server: header
+ (STR #3903)
+ - The scheduler did not support 1284 device IDs reported by driver
+ interface programs longer than 127 characters (STR #3871)
+ - The image filters did not support loading images larger than the
+ RIPCache setting (STR #3901)
+ - "PAGE: total NNN" messages did not get logged properly (STR #3887)
+ - Updated the PWG Raster support to conform to the current draft of the
+ PWG Raster Format specification.
+ - The PWG Raster filter did not always write the correct number of
+ padding lines on the bottom of the page (STR #3904)
+ - When reporting a denial-of-service attack from the domain socket, the
+ address reported does not always contain the correct path (STR #3888)
+ - Badly formed GIF files could cause the image filters to crash
+ (STR #3914)
+ - Jobs canceled at the printer were retried by the IPP backend.
+ - "cupsfilter -u" deleted the input file instead of the PPD file.
+ - The scheduler did not compute the cost of PPD filters defined using
+ the cupsFilter2 keyword properly.
+ - The scheduler did not correctly support the maxsize() attribute for
+ PPD filters.
+
+
+CHANGES IN CUPS V1.5.0
+
+ - Documentation updates.
+ - Localization update (STR #3865)
+ - Needed to limit TLS to v1.0 on some versions of Mac OS X.
+ - The snmp backend did not work with some printers.
+
+
CHANGES IN CUPS V1.5rc1
- Compile fixes (STR #3849, STR #3850)
-INSTALL - CUPS v1.5rc1 - 2011-06-14
------------------------------------
+INSTALL - CUPS v1.5.0 - 2011-07-25
+----------------------------------
This file describes how to compile and install CUPS from source code. For more
information on CUPS see the file called "README.txt". A complete change log can
-README - CUPS v1.5rc1 - 2011-06-14
+README - CUPS v1.5.0 - 2011-07-25
----------------------------------
Looking for compile instructions? Read the file "INSTALL.txt"
goto cleanup;
}
}
+ else if (ipp_status == IPP_ERROR_JOB_CANCELED)
+ goto cleanup;
else
{
/*
else if (ipp_status == IPP_DOCUMENT_FORMAT ||
ipp_status == IPP_CONFLICT)
return (CUPS_BACKEND_FAILED);
- else if (ipp_status > IPP_OK_CONFLICT)
+ else if (ipp_status > IPP_OK_CONFLICT && ipp_status != IPP_ERROR_JOB_CANCELED)
return (CUPS_BACKEND_RETRY_CURRENT);
else
{
debug_printf("DEBUG: request-id=%d\n", packet.request_id);
debug_printf("DEBUG: error-status=%d\n", packet.error_status);
- if (packet.error_status)
+ if (packet.error_status && packet.request_id != DEVICE_TYPE)
return;
/*
char(3,0xe4) char(3,0xe5) char(3,0xe6) char(3,0xe7)\
char(3,0xe8) char(3,0xe9) char(3,0xea) char(3,0xeb)\
char(3,0xec) char(3,0xed) char(3,0xee) char(3,0xef))
-image/pwg-raster string(0,"RaS2") + string(356,<0000000000000000>) priority(100)
+image/pwg-raster string(0,"RaS2") + string(4,PwgRaster<00>) priority(100)
image/tiff tiff tif string(0,MM<002A>) string(0,II<2A00>)
image/x-photocd pcd string(2048,PCD_IPI)
image/x-portable-anymap pnm
AC_CONFIG_HEADER(config.h)
dnl Version number information...
-CUPS_VERSION="1.5rc1"
+CUPS_VERSION="1.5.1"
CUPS_REVISION=""
#if test -z "$CUPS_REVISION" -a -d .svn; then
# CUPS_REVISION="-r`svnversion . | awk -F: '{print $NF}' | sed -e '1,$s/[[a-zA-Z]]*//g'`"
AC_CHECK_HEADER(Security/SecIdentitySearchPriv.h,
AC_DEFINE(HAVE_SECIDENTITYSEARCHPRIV_H))
+ dnl Check for SSLSetProtocolVersionMax...
+ SAVELIBS="$LIBS"
+ LIBS="$LIBS -framework Security"
+ AC_CHECK_FUNC(SSLSetProtocolVersionMax)
+ LIBS="$SAVELIBS"
+
dnl Check for SecCertificateCopyData..
AC_MSG_CHECKING(for SecCertificateCopyData)
if test $uversion -ge 100; then
#undef HAVE_SECPOLICYCREATESSL
+/*
+ * Do we have the SSLSetProtocolVersionMax function?
+ */
+
+#undef HAVE_SSLSETPROTOCOLVERSIONMAX
+
+
/*
* Do we have the cssmErrorString function?
*/
* Constants...
*/
-# define CUPS_VERSION 1.0499
+# define CUPS_VERSION 1.0501
# define CUPS_VERSION_MAJOR 1
# define CUPS_VERSION_MINOR 5
-# define CUPS_VERSION_PATCH -1
+# define CUPS_VERSION_PATCH 1
# define CUPS_BC_FD 3 /* Back-channel file descriptor for select/poll */
# define CUPS_DATE_ANY (time_t)-1
#ifdef AF_LOCAL
if (addr->addr.sa_family == AF_LOCAL)
- strlcpy(s, addr->un.sun_path, slen);
+ {
+ if (addr->un.sun_path[0] == '/')
+ strlcpy(s, addr->un.sun_path, slen);
+ else
+ strlcpy(s, "localhost", slen);
+ }
else
#endif /* AF_LOCAL */
if (addr->addr.sa_family == AF_INET)
cg->expired_root, (int)error));
}
+# ifdef HAVE_SSLSETPROTOCOLVERSIONMAX
+ if (!error)
+ {
+ error = SSLSetProtocolVersionMax(http->tls, kTLSProtocol1);
+ DEBUG_printf(("4http_setup_ssl: SSLSetProtocolVersionMax(kTLSProtocol1), "
+ "error=%d", (int)error));
+ }
+# endif /* HAVE_SSLSETPROTOCOLVERSIONMAX */
+
# ifdef HAVE_SECCERTIFICATECOPYDATA
if (!error)
{
"Cancel-Jobs",
"Cancel-My-Jobs",
"Resubmit-Job",
- "Close-Job"
+ "Close-Job",
+ "Identify-Printer"
},
* const ipp_cups_ops[] =
{
IPP_CANCEL_MY_JOBS, /* Cancel-My-Jobs */
IPP_RESUBMIT_JOB, /* Resubmit-Job */
IPP_CLOSE_JOB, /* Close-Job */
+ IPP_IDENTIFY_PRINTER, /* Identify-Printer (proposed IPP JPS3) */
IPP_PRIVATE = 0x4000, /* Reserved @private@ */
CUPS_GET_DEFAULT, /* Get the default printer */
CUPS_GET_PRINTERS, /* Get a list of printers and/or classes */
<H1 CLASS="title">Using Kerberos Authentication</H1>
-<P>CUPS allows you to use a Key Distribution Center (KDC) for authentication
-on your local CUPS server and when printing to a remote authenticated queue.
-This document describes how to configure CUPS to use Kerberos authentication
-and provides links to the MIT help pages for configuring Kerberos on your
-systems and network.</P>
+<P>CUPS allows you to use a Key Distribution Center (KDC) for authentication on your local CUPS server and when printing to a remote authenticated queue. This document describes how to configure CUPS to use Kerberos authentication and provides links to the MIT help pages for configuring Kerberos on your systems and network.</P>
<H2 CLASS="title"><A NAME="REQUIREMENTS">System Requirements</A></H2>
<li>Heimdal Kerberos (any version) or MIT Kerberos (1.6.3 or newer)</li>
- <li>Properly configured Domain Name System (DNS)
- infrastructure:<ol type='a'>
- <li>DNS server(s) with static IP addresses for all CUPS clients
- and servers or configured to allow DHCP updates to the host
- addresses</li>
+ <li>Properly configured Domain Name System (DNS) infrastructure (for your servers):<ol type='a'>
+ <li>DNS server(s) with static IP addresses for all CUPS servers or configured to allow DHCP updates to the host addresses and</li>
<li>All CUPS clients and servers configured to use the same
- DNS server(s)</li>
+DNS server(s).</li>
</ol></li>
<li>Properly configured Kerberos infrastructure:<ol type='a'>
- <li>KDC configured to allow CUPS clients and servers to obtain
- Service Granting Tickets (SGTs) for the "ipp" service</li>
- <li>LDAP-based user accounts - both OpenDirectory and
- ActiveDirectory provide this with the KDC</li>
- <li>CUPS clients and servers bound to the KDC and LDAP
- server(s)</li>
+ <li>KDC configured to allow CUPS servers to obtain Service Granting Tickets (SGTs) for the "host" service,</li>
+ <li>LDAP-based user accounts - both OpenDirectory and ActiveDirectory provide this with the KDC, and</li>
+ <li>CUPS clients and servers bound to the same KDC and LDAP
+ server(s).</li>
</ol></li>
- <li>An "ipp" Service Granting Ticket (SGT) for every CUPS client and
- server</li>
+ <li>A "host" Service Granting Ticket (SGT) for every CUPS server</li>
</ol>
<H2 CLASS="title"><A NAME="KRB5">Configuring Kerberos on Your System</A></H2>
-<P>Before you can use Kerberos with CUPS, you will need to configure
-Kerberos on your system and setup a system as a KDC. Because this
-configuration is highly system and site-specific, please consult
-the following on-line resources provided by the creators of Kerberos
-at the Massachusetts Institute of Technology (MIT):</P>
+<P>Before you can use Kerberos with CUPS, you will need to configure Kerberos on your system and setup a system as a KDC. Because this configuration is highly system and site-specific, please consult the following on-line resources provided by the creators of Kerberos at the Massachusetts Institute of Technology (MIT):</P>
<UL>
- <LI><A HREF="http://web.mit.edu/kerberos/">Kerberos: The Network
- Authentication Protocol</A></LI>
+ <LI><A HREF="http://web.mit.edu/kerberos/">Kerberos: The Network Authentication Protocol</A></LI>
<LI><A HREF="http://web.mit.edu/macdev/KfM/Common/Documentation/faq-osx.html">Kerberos
on Mac OS X Frequently Asked Questions</A></LI>
<H2 CLASS="title"><A NAME="CUPS">Configuring CUPS to Use Kerberos</A></H2>
-<P>Once you have configured Kerberos on your system(s), you can then
-enable Kerberos authentication by selecting the <tt>Negotiate</tt>
-authentication type. The simplest way to do this is using the
-<tt>cupsctl(8)</tt> command:</P>
+<P>Once youhave configured Kerberos on your system(s), you can then enable Kerberos authentication by selecting the <tt>Negotiate</tt> authentication type. The simplest way to do this is using the <tt>cupsctl(8)</tt> command on your server(s):</P>
<PRE CLASS="command">
<KBD>cupsctl DefaultAuthType=Negotiate</KBD>
</PRE>
-<P>You can also enable Kerberos from the web interface by checking the
-<VAR>Use Kerberos Authentication</VAR> box and clicking <VAR>Change
-Settings</VAR>:</P>
+<P>You can also enable Kerberos from the web interface by checking the <VAR>Use Kerberos Authentication</VAR> box and clicking <VAR>Change Settings</VAR>:</P>
<PRE CLASS="command">
-http://localhost:631/admin
+http://server.example.com:631/admin
</PRE>
-<P>After you have enabled Kerberos authentication, use the built-in
-"authenticated" policy or your own custom policies with the printers you
-will be sharing. See <a href="policies.html">Managing Operation Policies</a>
-for more information.</P>
+<P>After you have enabled Kerberos authentication, use the built-in "authenticated" policy or your own custom policies with the printers you will be sharing. See <a href="policies.html">Managing Operation Policies</a> for more information.</P>
<H2 CLASS="title"><A NAME="IMPLEMENT">Implementation Information</A></H2>
-<P>CUPS implements Kerberos over HTTP using GSSAPI and the service name
-"host". Because of limitations in the HTTP GSSAPI protocol extension, only
-a single domain/KDC is supported for authentication.</P>
-
-<P>When doing printing tasks that require authentication, CUPS requests a
-single-use "ticket" from your login session to authenticate who you are.
-This ticket gives CUPS a username of the form "user@REALM", which is then
-converted to just "user" for purposes of user and group checks.</P>
-
-<P>In order to support printing to a shared printer, CUPS has to ask the KDC
-for a copy of your credentials (this is called delegation) that can be sent to
-the remote server for authentication. Delegation only works when the system
-has a stable hostname which maps to the current address of the system, which
-is why you need a static IP address or DHCP that updates the DNS entry for your
-system.</P>
+<P>CUPS implements Kerberos over HTTP using GSSAPI and the service name "host". Because of limitations in the HTTP GSSAPI protocol extension, only a single domain/KDC is supported for authentication. The HTTP extension is described in <a href="http://tools.ietf.org/html/rfc4559">RFC 4559</a>.</P>
+
+<P>When doing printing tasks that require authentication, CUPS requests single-use "tickets" from your login session to authenticate who you are. These tickets give CUPS a username of the form "user@REALM", which is then converted to just "user" for purposes of user and group checks.</P>
+
+<P>In order to support printing to a shared printer, CUPS runs the IPP backend as the owner of the print job so it can obtain the necessary credentials.</P>
</BODY>
</HTML>
<H3>Description</H3>
<P>The <CODE>LogFilePerm</CODE> directive specifies the
-permissions to use when writing configuration files. The default
+permissions to use when writing log files. The default
is @CUPS_LOG_FILE_PERM@.</P>
* Read in another buffer...
*/
- if ((count = gif_get_block (fp, buf + last_byte)) <= 0)
+ if ((count = gif_get_block(fp, buf + last_byte)) <= 0)
{
/*
* Whoops, no more data!
gif_get_code(fp, 0, 1);
/*
- * Wipe the decompressor table...
+ * Wipe the decompressor table (already mostly 0 due to the calloc above...)
*/
fresh = 1;
- for (i = 0; i < clear_code; i ++)
- {
- table[0][i] = 0;
+ for (i = 1; i < clear_code; i ++)
table[1][i] = i;
- }
-
- for (; i < 4096; i ++)
- table[0][i] = table[1][0] = 0;
sp = stack;
fresh = 0;
do
+ {
firstcode = oldcode = gif_get_code(fp, code_size, 0);
+ }
while (firstcode == clear_code);
- return (firstcode);
+ return (firstcode & 255);
}
else if (!table)
return (0);
if (sp > stack)
- return (*--sp);
+ return ((*--sp) & 255);
- while ((code = gif_get_code (fp, code_size, 0)) >= 0)
+ while ((code = gif_get_code(fp, code_size, 0)) >= 0)
{
if (code == clear_code)
{
- for (i = 0; i < clear_code; i ++)
- {
- table[0][i] = 0;
- table[1][i] = i;
- }
+ /*
+ * Clear/reset the compression table...
+ */
- for (; i < 4096; i ++)
- table[0][i] = table[1][i] = 0;
+ memset(table, 0, 2 * sizeof(gif_table_t));
+ for (i = 1; i < clear_code; i ++)
+ table[1][i] = i;
code_size = set_code_size + 1;
max_code_size = 2 * clear_code;
firstcode = oldcode = gif_get_code(fp, code_size, 0);
- return (firstcode);
+ return (firstcode & 255);
}
- else if (code == end_code)
+ else if (code == end_code || code > max_code)
{
- unsigned char buf[260];
-
+ unsigned char buf[260]; /* Block buffer */
if (!gif_eof)
while (gif_get_block(fp, buf) > 0);
incode = code;
- if (code >= max_code)
+ if (code == max_code)
{
- *sp++ = firstcode;
- code = oldcode;
+ if (sp < (stack + 8192))
+ *sp++ = firstcode;
+
+ code = oldcode;
}
- while (code >= clear_code)
+ while (code >= clear_code && sp < (stack + 8192))
{
*sp++ = table[1][code];
if (code == table[0][code])
code = table[0][code];
}
- *sp++ = firstcode = table[1][code];
- code = max_code;
+ if (sp < (stack + 8192))
+ *sp++ = firstcode = table[1][code];
+
+ code = max_code;
if (code < 4096)
{
oldcode = incode;
if (sp > stack)
- return (*--sp);
+ return ((*--sp) & 255);
}
- return (code);
+ return (code & 255);
}
* Load the image as appropriate...
*/
- img->max_ics = CUPS_TILE_MINIMUM;
- img->xppi = 128;
- img->yppi = 128;
+ img->cachefile = -1;
+ img->max_ics = CUPS_TILE_MINIMUM;
+ img->xppi = 128;
+ img->yppi = 128;
if (!memcmp(header, "GIF87a", 6) || !memcmp(header, "GIF89a", 6))
status = _cupsImageReadGIF(img, fp, primary, secondary, saturation, hue,
cups_page_header2_t fh; /* File page header */
memset(&fh, 0, sizeof(fh));
- fh.HWResolution[0] = htonl(r->header.HWResolution[0]);
- fh.HWResolution[1] = htonl(r->header.HWResolution[1]);
- fh.cupsWidth = htonl(r->header.cupsWidth);
- fh.cupsHeight = htonl(r->header.cupsHeight);
- fh.cupsBitsPerColor = htonl(r->header.cupsBitsPerColor);
- fh.cupsBitsPerPixel = htonl(r->header.cupsBitsPerPixel);
- fh.cupsBytesPerLine = htonl(r->header.cupsBytesPerLine);
- fh.cupsColorOrder = htonl(r->header.cupsColorOrder);
- fh.cupsColorSpace = htonl(r->header.cupsColorSpace);
- fh.cupsNumColors = htonl(r->header.cupsNumColors);
+ strlcpy(fh.MediaClass, "PwgRaster", sizeof(fh.MediaClass));
+ strlcpy(fh.MediaColor, r->header.MediaColor, sizeof(fh.MediaColor));
+ strlcpy(fh.MediaType, r->header.MediaType, sizeof(fh.MediaType));
+ strlcpy(fh.OutputType, r->header.OutputType, sizeof(fh.OutputType));
+ strlcpy(fh.cupsRenderingIntent, r->header.cupsRenderingIntent,
+ sizeof(fh.cupsRenderingIntent));
+ strlcpy(fh.cupsPageSizeName, r->header.cupsPageSizeName,
+ sizeof(fh.cupsPageSizeName));
+
+ fh.CutMedia = htonl(r->header.CutMedia);
+ fh.Duplex = htonl(r->header.Duplex);
+ fh.HWResolution[0] = htonl(r->header.HWResolution[0]);
+ fh.HWResolution[1] = htonl(r->header.HWResolution[1]);
+ fh.ImagingBoundingBox[0] = htonl(r->header.ImagingBoundingBox[0]);
+ fh.ImagingBoundingBox[1] = htonl(r->header.ImagingBoundingBox[1]);
+ fh.ImagingBoundingBox[2] = htonl(r->header.ImagingBoundingBox[2]);
+ fh.ImagingBoundingBox[3] = htonl(r->header.ImagingBoundingBox[3]);
+ fh.InsertSheet = htonl(r->header.InsertSheet);
+ fh.Jog = htonl(r->header.Jog);
+ fh.LeadingEdge = htonl(r->header.LeadingEdge);
+ fh.ManualFeed = htonl(r->header.ManualFeed);
+ fh.MediaPosition = htonl(r->header.MediaPosition);
+ fh.MediaWeight = htonl(r->header.MediaWeight);
+ fh.NumCopies = htonl(r->header.NumCopies);
+ fh.Orientation = htonl(r->header.Orientation);
+ fh.PageSize[0] = htonl(r->header.PageSize[0]);
+ fh.PageSize[1] = htonl(r->header.PageSize[1]);
+ fh.Tumble = htonl(r->header.Tumble);
+ fh.cupsWidth = htonl(r->header.cupsWidth);
+ fh.cupsHeight = htonl(r->header.cupsHeight);
+ fh.cupsBitsPerColor = htonl(r->header.cupsBitsPerColor);
+ fh.cupsBitsPerPixel = htonl(r->header.cupsBitsPerPixel);
+ fh.cupsBytesPerLine = htonl(r->header.cupsBytesPerLine);
+ fh.cupsColorOrder = htonl(r->header.cupsColorOrder);
+ fh.cupsColorSpace = htonl(r->header.cupsColorSpace);
+ fh.cupsNumColors = htonl(r->header.cupsNumColors);
+ fh.cupsInteger[0] = htonl(r->header.cupsInteger[0]);
+ fh.cupsInteger[1] = htonl(r->header.cupsInteger[1]);
+ fh.cupsInteger[2] = htonl(r->header.cupsInteger[2]);
+ fh.cupsInteger[3] = htonl(r->header.cupsImagingBBox[0] *
+ r->header.HWResolution[0]);
+ fh.cupsInteger[4] = htonl(r->header.cupsImagingBBox[1] *
+ r->header.HWResolution[1]);
+ fh.cupsInteger[5] = htonl(r->header.cupsImagingBBox[2] *
+ r->header.HWResolution[0]);
+ fh.cupsInteger[6] = htonl(r->header.cupsImagingBBox[3] *
+ r->header.HWResolution[1]);
+ fh.cupsInteger[7] = htonl(0xffffff);
return (cups_raster_io(r, (unsigned char *)&fh, sizeof(fh)) == sizeof(fh));
}
}
memset(line, white, linesize);
- for (y = page_top; y > 0; y --)
+ for (y = page_bottom; y > 0; y --)
if (!cupsRasterWritePixels(outras, line, outheader.cupsBytesPerLine))
{
_cupsLangPrintFilter(stderr, "ERROR", _("Error sending raster data."));
expected.cupsHeight = 256;
expected.cupsBytesPerLine = 256;
+ if (mode == CUPS_RASTER_WRITE_PWG)
+ {
+ strlcpy(expected.MediaClass, "PwgRaster", sizeof(expected.MediaClass));
+ expected.cupsInteger[7] = 0xffffff;
+ }
+
if (page & 1)
{
expected.cupsBytesPerLine *= 2;
#
msgid ""
msgstr ""
-"Project-Id-Version: CUPS 1.4\n"
+"Project-Id-Version: CUPS 1.5\n"
"Report-Msgid-Bugs-To: http://www.cups.org/str.php\n"
-"POT-Creation-Date: 2010-03-03 10:36-0800\n"
-"PO-Revision-Date: 2009-07-02 20:00+0100\n"
+"POT-Creation-Date: 2011-05-25 23:53-0400\n"
+"PO-Revision-Date: 2011-06-18 19:16+0100\n"
"Last-Translator: Juan Pablo González Riopedre <riopedre13@yahoo.es>\n"
"Language-Team: Spanish\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
-msgid "\t\t(all)\n"
-msgstr "\t\t(todos)\n"
+#: systemv/lpstat.c:1873
+#: systemv/lpstat.c:1998
+msgid "\t\t(all)"
+msgstr "\t\t(todos)"
-msgid "\t\t(none)\n"
-msgstr "\t\t(ninguno)\n"
+#: systemv/lpstat.c:1876
+#: systemv/lpstat.c:1879
+#: systemv/lpstat.c:2001
+#: systemv/lpstat.c:2004
+msgid "\t\t(none)"
+msgstr "\t\t(ninguno)"
+#: berkeley/lpc.c:433
#, c-format
-msgid "\t%d entries\n"
-msgstr "\t%d entradas\n"
+msgid "\t%d entries"
+msgstr "\t%d entradas"
-msgid "\tAfter fault: continue\n"
-msgstr "\tTras fallo: continuar\n"
+#: systemv/lpstat.c:753
+#: systemv/lpstat.c:769
+#, c-format
+msgid "\t%s"
+msgstr "\t%s"
+
+#: systemv/lpstat.c:1854
+#: systemv/lpstat.c:1979
+msgid "\tAfter fault: continue"
+msgstr "\tTras fallo: continuar"
+
+#: systemv/lpstat.c:1478
+#: systemv/lpstat.c:1823
+#: systemv/lpstat.c:1949
+#, c-format
+msgid "\tAlerts: %s"
+msgstr "\tAlertas: %s"
-msgid "\tAlerts:"
-msgstr "\tAlertas:"
+#: systemv/lpstat.c:1877
+#: systemv/lpstat.c:2002
+msgid "\tBanner required"
+msgstr "\tSe necesita un rótulo"
-msgid "\tBanner required\n"
-msgstr "\tSe necesita un rótulo\n"
+#: systemv/lpstat.c:1878
+#: systemv/lpstat.c:2003
+msgid "\tCharset sets:"
+msgstr "\tAjustes del juego de caracteres:"
-msgid "\tCharset sets:\n"
-msgstr "\tAjustes del juego de caracteres:\n"
+#: systemv/lpstat.c:1842
+#: systemv/lpstat.c:1967
+msgid "\tConnection: direct"
+msgstr "\tConexión: directa"
-msgid "\tConnection: direct\n"
-msgstr "\tConexión: directa\n"
+#: systemv/lpstat.c:1833
+#: systemv/lpstat.c:1959
+msgid "\tConnection: remote"
+msgstr "\tConexión: remota"
-msgid "\tConnection: remote\n"
-msgstr "\tConexión: remota\n"
+#: systemv/lpstat.c:1797
+#: systemv/lpstat.c:1923
+msgid "\tContent types: any"
+msgstr "\tTipos de contenido: cualesquiera"
-msgid "\tDefault page size:\n"
-msgstr "\tTamaño de página predeterminado:\n"
+#: systemv/lpstat.c:1881
+#: systemv/lpstat.c:2006
+msgid "\tDefault page size:"
+msgstr "\tTamaño de página predeterminado:"
-msgid "\tDefault pitch:\n"
-msgstr "\tPaso predeterminado:\n"
+#: systemv/lpstat.c:1880
+#: systemv/lpstat.c:2005
+msgid "\tDefault pitch:"
+msgstr "\tPaso predeterminado:"
-msgid "\tDefault port settings:\n"
-msgstr "\tAjustes del puerto predeterminados:\n"
+#: systemv/lpstat.c:1882
+#: systemv/lpstat.c:2007
+msgid "\tDefault port settings:"
+msgstr "\tAjustes del puerto predeterminados:"
+#: systemv/lpstat.c:1803
+#: systemv/lpstat.c:1929
#, c-format
-msgid "\tDescription: %s\n"
-msgstr "\tDescripción: %s\n"
+msgid "\tDescription: %s"
+msgstr "\tDescripción: %s"
-msgid ""
-"\tForm mounted:\n"
-"\tContent types: any\n"
-"\tPrinter types: unknown\n"
-msgstr ""
-"\tFormulario montado:\n"
-"\tTipos de contenido: cualquiera\n"
-"\tTipos de impresora: desconocido\n"
+#: systemv/lpstat.c:1796
+#: systemv/lpstat.c:1922
+msgid "\tForm mounted:"
+msgstr "\tFormulario montado:"
-msgid "\tForms allowed:\n"
-msgstr "\tFormularios permitidos:\n"
+#: systemv/lpstat.c:1875
+#: systemv/lpstat.c:2000
+msgid "\tForms allowed:"
+msgstr "\tFormularios permitidos:"
+#: systemv/lpstat.c:1837
+#: systemv/lpstat.c:1963
#, c-format
-msgid "\tInterface: %s.ppd\n"
-msgstr "\tInterfaz: %s.ppd\n"
+msgid "\tInterface: %s.ppd"
+msgstr "\tInterfaz: %s.ppd"
+#: systemv/lpstat.c:1846
+#: systemv/lpstat.c:1971
#, c-format
-msgid "\tInterface: %s/interfaces/%s\n"
-msgstr "\tInterfaz: %s/interfaces/%s\n"
+msgid "\tInterface: %s/interfaces/%s"
+msgstr "\tInterfaz: %s/interfaces/%s"
+#: systemv/lpstat.c:1850
+#: systemv/lpstat.c:1975
#, c-format
-msgid "\tInterface: %s/ppd/%s.ppd\n"
-msgstr "\tInterfaz: %s/ppd/%s.ppd\n"
+msgid "\tInterface: %s/ppd/%s.ppd"
+msgstr "\tInterfaz: %s/ppd/%s.ppd"
+#: systemv/lpstat.c:1828
+#: systemv/lpstat.c:1954
#, c-format
-msgid "\tLocation: %s\n"
-msgstr "\tUbicación: %s\n"
+msgid "\tLocation: %s"
+msgstr "\tUbicación: %s"
+
+#: systemv/lpstat.c:1853
+#: systemv/lpstat.c:1978
+msgid "\tOn fault: no alert"
+msgstr "\tEn fallo: no alertar"
+
+#: systemv/lpstat.c:1798
+#: systemv/lpstat.c:1924
+msgid "\tPrinter types: unknown"
+msgstr "\tTipos de impresora: desconocidos"
-msgid "\tOn fault: no alert\n"
-msgstr "\tEn fallo: no alertar\n"
+#: systemv/lpstat.c:1459
+#, c-format
+msgid "\tStatus: %s"
+msgstr "\tEstado: %s"
-msgid "\tUsers allowed:\n"
-msgstr "\tUsuarios permitidos:\n"
+#: systemv/lpstat.c:1858
+#: systemv/lpstat.c:1872
+#: systemv/lpstat.c:1983
+#: systemv/lpstat.c:1997
+msgid "\tUsers allowed:"
+msgstr "\tUsuarios permitidos:"
-msgid "\tUsers denied:\n"
-msgstr "\tUsuarios denegados:\n"
+#: systemv/lpstat.c:1865
+#: systemv/lpstat.c:1990
+msgid "\tUsers denied:"
+msgstr "\tUsuarios denegados:"
-msgid "\tdaemon present\n"
-msgstr "\tdemonio presente\n"
+#: berkeley/lpc.c:435
+msgid "\tdaemon present"
+msgstr "\tdemonio presente"
-msgid "\tno entries\n"
-msgstr "\tno hay entradas\n"
+#: berkeley/lpc.c:431
+msgid "\tno entries"
+msgstr "\tno hay entradas"
+#: berkeley/lpc.c:403
+#: berkeley/lpc.c:415
#, c-format
-msgid "\tprinter is on device '%s' speed -1\n"
-msgstr "\tla impresora está conectada a '%s' velocidad -1\n"
+msgid "\tprinter is on device '%s' speed -1"
+msgstr "\tla impresora está conectada a '%s' velocidad -1"
-msgid "\tprinting is disabled\n"
-msgstr "\tla impresión está desactivada\n"
+#: berkeley/lpc.c:428
+msgid "\tprinting is disabled"
+msgstr "\tla impresión está desactivada"
-msgid "\tprinting is enabled\n"
-msgstr "\tla impresión está activada\n"
+#: berkeley/lpc.c:426
+msgid "\tprinting is enabled"
+msgstr "\tla impresión está activada"
+#: systemv/lpstat.c:1481
#, c-format
-msgid "\tqueued for %s\n"
-msgstr "\ten cola para %s\n"
+msgid "\tqueued for %s"
+msgstr "\ten cola para %s"
-msgid "\tqueuing is disabled\n"
-msgstr "\tla cola está desactivada\n"
+#: berkeley/lpc.c:423
+msgid "\tqueuing is disabled"
+msgstr "\tla cola está desactivada"
-msgid "\tqueuing is enabled\n"
-msgstr "\tla cola está activada\n"
+#: berkeley/lpc.c:421
+msgid "\tqueuing is enabled"
+msgstr "\tla cola está activada"
-msgid "\treason unknown\n"
-msgstr "\trazón desconocida\n"
+#: systemv/lpstat.c:1789
+#: systemv/lpstat.c:1915
+msgid "\treason unknown"
+msgstr "\trazón desconocida"
+#: systemv/cupstestppd.c:436
msgid ""
"\n"
-" DETAILED CONFORMANCE TEST RESULTS\n"
+" DETAILED CONFORMANCE TEST RESULTS"
msgstr ""
"\n"
-" RESULTADOS DETALLADOS DE LA PRUEBA DE CONFORMIDAD\n"
+" RESULTADOS DETALLADOS DE LA PRUEBA DE CONFORMIDAD"
-msgid " REF: Page 15, section 3.1.\n"
-msgstr " REF: Página 15, sección 3.1.\n"
+#: systemv/cupstestppd.c:3619
+msgid " Ignore specific warnings."
+msgstr " Ignorar advertencias (warnings) especÃficas."
-msgid " REF: Page 15, section 3.2.\n"
-msgstr " REF: Página 15, sección 3.2.\n"
+#: systemv/cupstestppd.c:3623
+msgid " Issue warnings instead of errors."
+msgstr " Emitor advertencias (warnings) en vez de errores."
-msgid " REF: Page 19, section 3.3.\n"
-msgstr " REF: Página 19, sección 3.3.\n"
+#: systemv/cupstestppd.c:392
+#: systemv/cupstestppd.c:397
+msgid " REF: Page 15, section 3.1."
+msgstr " REF: Página 15, sección 3.1."
-msgid " REF: Page 20, section 3.4.\n"
-msgstr " REF: Página 20, sección 3.4.\n"
+#: systemv/cupstestppd.c:387
+msgid " REF: Page 15, section 3.2."
+msgstr " REF: Página 15, sección 3.2."
-msgid " REF: Page 27, section 3.5.\n"
-msgstr " REF: Página 27, sección 3.5.\n"
+#: systemv/cupstestppd.c:407
+msgid " REF: Page 19, section 3.3."
+msgstr " REF: Página 19, sección 3.3."
-msgid " REF: Page 42, section 5.2.\n"
-msgstr " REF: Página 42, sección 5.2.\n"
+#: systemv/cupstestppd.c:360
+msgid " REF: Page 20, section 3.4."
+msgstr " REF: Página 20, sección 3.4."
-msgid " REF: Pages 16-17, section 3.2.\n"
-msgstr " REF: Páginas 16-17, sección 3.2.\n"
+#: systemv/cupstestppd.c:412
+msgid " REF: Page 27, section 3.5."
+msgstr " REF: Página 27, sección 3.5."
-msgid " REF: Pages 42-45, section 5.2.\n"
-msgstr " REF: Páginas 42-45, sección 5.2.\n"
+#: systemv/cupstestppd.c:355
+msgid " REF: Page 42, section 5.2."
+msgstr " REF: Página 42, sección 5.2."
-msgid " REF: Pages 45-46, section 5.2.\n"
-msgstr " REF: Páginas 45-46, sección 5.2.\n"
+#: systemv/cupstestppd.c:402
+msgid " REF: Pages 16-17, section 3.2."
+msgstr " REF: Páginas 16-17, sección 3.2."
-msgid " REF: Pages 48-49, section 5.2.\n"
-msgstr " REF: Páginas 48-49, sección 5.2.\n"
+#: systemv/cupstestppd.c:372
+msgid " REF: Pages 42-45, section 5.2."
+msgstr " REF: Páginas 42-45, sección 5.2."
-msgid " REF: Pages 52-54, section 5.2.\n"
-msgstr " REF: Páginas 52-54, sección 5.2.\n"
+#: systemv/cupstestppd.c:366
+msgid " REF: Pages 45-46, section 5.2."
+msgstr " REF: Páginas 45-46, sección 5.2."
-#, c-format
-msgid " %-39.39s %.0f bytes\n"
-msgstr " %-39.39s %.0f bytes\n"
+#: systemv/cupstestppd.c:377
+msgid " REF: Pages 48-49, section 5.2."
+msgstr " REF: Páginas 48-49, sección 5.2."
+#: systemv/cupstestppd.c:382
+msgid " REF: Pages 52-54, section 5.2."
+msgstr " REF: Páginas 52-54, sección 5.2."
+
+#: berkeley/lpq.c:554
#, c-format
-msgid " PASS Default%s\n"
-msgstr " PASA %s predeterminado\n"
+msgid " %-39.39s %.0f bytes"
+msgstr " %-39.39s %.0f bytes"
-msgid " PASS DefaultImageableArea\n"
-msgstr " PASA DefaultImageableArea\n"
+#: systemv/cupstestppd.c:555
+#, c-format
+msgid " PASS Default%s"
+msgstr " PASA Default%s"
-msgid " PASS DefaultPaperDimension\n"
-msgstr " PASA DefaultPaperDimension\n"
+#: systemv/cupstestppd.c:490
+msgid " PASS DefaultImageableArea"
+msgstr " PASA DefaultImageableArea"
-msgid " PASS FileVersion\n"
-msgstr " PASA FileVersion\n"
+#: systemv/cupstestppd.c:524
+msgid " PASS DefaultPaperDimension"
+msgstr " PASA DefaultPaperDimension"
-msgid " PASS FormatVersion\n"
-msgstr " PASA FormatVersion\n"
+#: systemv/cupstestppd.c:597
+msgid " PASS FileVersion"
+msgstr " PASA FileVersion"
-msgid " PASS LanguageEncoding\n"
-msgstr " PASA LanguageEncoding\n"
+#: systemv/cupstestppd.c:641
+msgid " PASS FormatVersion"
+msgstr " PASA FormatVersion"
-msgid " PASS LanguageVersion\n"
-msgstr " PASA LanguageVersion\n"
+#: systemv/cupstestppd.c:661
+msgid " PASS LanguageEncoding"
+msgstr " PASA LanguageEncoding"
-msgid " PASS Manufacturer\n"
-msgstr " PASA Manufacturer\n"
+#: systemv/cupstestppd.c:681
+msgid " PASS LanguageVersion"
+msgstr " PASA LanguageVersion"
-msgid " PASS ModelName\n"
-msgstr " PASA ModelName\n"
+#: systemv/cupstestppd.c:733
+msgid " PASS Manufacturer"
+msgstr " PASA Manufacturer"
-msgid " PASS NickName\n"
-msgstr " PASA NickName\n"
+#: systemv/cupstestppd.c:773
+msgid " PASS ModelName"
+msgstr " PASA ModelName"
-msgid " PASS PCFileName\n"
-msgstr " PASA PCFileName\n"
+#: systemv/cupstestppd.c:793
+msgid " PASS NickName"
+msgstr " PASA NickName"
-msgid " PASS PSVersion\n"
-msgstr " PASA PSVersion\n"
+#: systemv/cupstestppd.c:853
+msgid " PASS PCFileName"
+msgstr " PASA PCFileName"
-msgid " PASS PageRegion\n"
-msgstr " PASA PageRegion\n"
+#: systemv/cupstestppd.c:928
+msgid " PASS PSVersion"
+msgstr " PASA PSVersion"
-msgid " PASS PageSize\n"
-msgstr " PASA PageSize\n"
+#: systemv/cupstestppd.c:833
+msgid " PASS PageRegion"
+msgstr " PASA PageRegion"
-msgid " PASS Product\n"
-msgstr " PASA Product\n"
+#: systemv/cupstestppd.c:813
+msgid " PASS PageSize"
+msgstr " PASA PageSize"
-msgid " PASS ShortNickName\n"
-msgstr " PASA ShortNickName\n"
+#: systemv/cupstestppd.c:888
+msgid " PASS Product"
+msgstr " PASA Product"
-#, c-format
-msgid ""
-" WARN \"%s %s\" conflicts with \"%s %s\"\n"
-" (constraint=\"%s %s %s %s\")\n"
-msgstr ""
-" ADVERTENCIA \"%s %s\" está en conflicto con \"%s %s\"\n"
-" (restricción=\"%s %s %s %s\")\n"
+#: systemv/cupstestppd.c:963
+msgid " PASS ShortNickName"
+msgstr " PASA ShortNickName"
+#: systemv/cupstestppd.c:1338
#, c-format
-msgid " WARN %s has no corresponding options\n"
-msgstr ""
+msgid " WARN %s has no corresponding options."
+msgstr " ADVERTENCIA %s tiene opciones que no corresponden."
+#: systemv/cupstestppd.c:1450
#, c-format
msgid ""
" WARN %s shares a common prefix with %s\n"
-" REF: Page 15, section 3.2.\n"
+" REF: Page 15, section 3.2."
msgstr ""
" ADVERTENCIA %s comparte un prefijo común con %s\n"
-" REF: Página 15, sección 3.2.\n"
-
-msgid " WARN Default choices conflicting\n"
-msgstr ""
+" REF: Página 15, sección 3.2."
+#: systemv/cupstestppd.c:1309
#, c-format
msgid ""
-" WARN Duplex option keyword %s may not work as expected and should "
-"be named Duplex\n"
-" REF: Page 122, section 5.17\n"
+" WARN Duplex option keyword %s may not work as expected and should be named Duplex.\n"
+" REF: Page 122, section 5.17"
msgstr ""
+" ADVERTENCIA La clave de opción Duplex %s puede que no funcione como se espera y deberÃa llamarse Duplex.\n"
+" REF: Página 122, sección 5.17"
-msgid " WARN File contains a mix of CR, LF, and CR LF line endings\n"
-msgstr ""
+#: systemv/cupstestppd.c:1708
+msgid " WARN File contains a mix of CR, LF, and CR LF line endings."
+msgstr " ADVERTENCIA El archivo contiene una mezcla de lÃneas acabadas en CR, LF y CR LF."
+#: systemv/cupstestppd.c:1354
msgid ""
" WARN LanguageEncoding required by PPD 4.3 spec.\n"
-" REF: Pages 56-57, section 5.3.\n"
+" REF: Pages 56-57, section 5.3."
msgstr ""
-" ADVERTENCIA Se necesita LanguageEncoding por especificación de "
-"PPD 4.3.\n"
-" REF: Páginas 56-57, sección 5.3.\n"
+" ADVERTENCIA Se necesita LanguageEncoding por especificación de PPD 4.3.\n"
+" REF: Páginas 56-57, sección 5.3."
+#: systemv/cupstestppd.c:1690
#, c-format
-msgid " WARN Line %d only contains whitespace\n"
-msgstr ""
+msgid " WARN Line %d only contains whitespace."
+msgstr " ADVERTENCIA La lÃnea %d solo contiene espacios en blanco."
+#: systemv/cupstestppd.c:1362
msgid ""
" WARN Manufacturer required by PPD 4.3 spec.\n"
-" REF: Pages 58-59, section 5.3.\n"
+" REF: Pages 58-59, section 5.3."
msgstr ""
-" ADVERTENCIA Se necesita Manufacturer por especificación de PPD "
-"4.3.\n"
-" REF: Páginas 58-59, sección 5.3.\n"
+" ADVERTENCIA Se necesita Manufacturer por especificación de PPD 4.3.\n"
+" REF: Páginas 58-59, sección 5.3."
-msgid ""
-" WARN Non-Windows PPD files should use lines ending with only LF, "
-"not CR LF\n"
-msgstr ""
+#: systemv/cupstestppd.c:1713
+msgid " WARN Non-Windows PPD files should use lines ending with only LF, not CR LF."
+msgstr " ADVERTENCIA Los archivos PPD que no sean de Windows deben tener lÃneas que acaben sólo en LF, no en CR LF."
+#: systemv/cupstestppd.c:1346
#, c-format
msgid ""
-" WARN Obsolete PPD version %.1f\n"
-" REF: Page 42, section 5.2.\n"
+" WARN Obsolete PPD version %.1f.\n"
+" REF: Page 42, section 5.2."
msgstr ""
+" ADVERTENCIA Versión de PPD %.1f anticuada.\n"
+" REF: Página 42, sección 5.2."
+#: systemv/cupstestppd.c:1377
msgid ""
" WARN PCFileName longer than 8.3 in violation of PPD spec.\n"
-" REF: Pages 61-62, section 5.3.\n"
+" REF: Pages 61-62, section 5.3."
msgstr ""
-" ADVERTENCIA PCFileName es mas largo que 8.3 violando la "
-"especificación PPD.\n"
-" REF: Páginas 61-62, sección 5.3.\n"
+" ADVERTENCIA PCFileName es mas largo que 8.3 violando la especificación PPD.\n"
+" REF: Páginas 61-62, sección 5.3."
+#: systemv/cupstestppd.c:1385
msgid ""
" WARN PCFileName should contain a unique filename.\n"
-" REF: Pages 61-62, section 5.3.\n"
+" REF: Pages 61-62, section 5.3."
msgstr ""
+" ADVERTENCIA PCFileName debe contener un único nombre de archivo.\n"
+" REF: Páginas 61-62, sección 5.3."
+#: systemv/cupstestppd.c:1420
msgid ""
" WARN Protocols contains PJL but JCL attributes are not set.\n"
-" REF: Pages 78-79, section 5.7.\n"
+" REF: Pages 78-79, section 5.7."
msgstr ""
-" ADVERTENCIA Los protocolos contienen PJL pero no se especifican "
-"los atributos JCL.\n"
-" REF: Páginas 78-79, sección 5.7.\n"
+" ADVERTENCIA Los protocolos contienen PJL pero no se especifican los atributos JCL.\n"
+" REF: Páginas 78-79, sección 5.7."
+#: systemv/cupstestppd.c:1411
msgid ""
" WARN Protocols contains both PJL and BCP; expected TBCP.\n"
-" REF: Pages 78-79, section 5.7.\n"
+" REF: Pages 78-79, section 5.7."
msgstr ""
-" ADVERTENCIA Los protocolos contienen a ambos, PJL y BCP; se "
-"esperaba TBCP.\n"
-" REF: Páginas 78-79, sección 5.7.\n"
+" ADVERTENCIA Los protocolos contienen a ambos, PJL y BCP; se esperaba TBCP.\n"
+" REF: Páginas 78-79, sección 5.7."
+#: systemv/cupstestppd.c:1394
msgid ""
" WARN ShortNickName required by PPD 4.3 spec.\n"
-" REF: Pages 64-65, section 5.3.\n"
-msgstr ""
-" ADVERTENCIA Se necesita ShortNickName por especificación de PPD "
-"4.3.\n"
-" REF: Páginas 64-65, sección 5.3.\n"
-
-#, c-format
-msgid " %s %s %s does not exist\n"
+" REF: Pages 64-65, section 5.3."
msgstr ""
+" ADVERTENCIA Se necesita ShortNickName por especificación de PPD 4.3.\n"
+" REF: Páginas 64-65, sección 5.3."
-#, c-format
-msgid " %s %s file \"%s\" has the wrong capitalization\n"
-msgstr ""
+#: systemv/cupsaddsmb.c:282
+msgid " cupsaddsmb [options] -a"
+msgstr " cupsaddsmb [opciones] -a"
-#, c-format
-msgid ""
-" %s Bad %s choice %s\n"
-" REF: Page 122, section 5.17\n"
-msgstr ""
+#: systemv/cupstestdsc.c:427
+msgid " cupstestdsc [options] -"
+msgstr " cupstestdsc [opciones] -"
-#, c-format
-msgid " %s Bad UTF-8 \"%s\" translation string for option %s\n"
-msgstr ""
+#: systemv/cupstestppd.c:3614
+msgid " program | cupstestppd [options] -"
+msgstr " programa | cupstestppd [opciones] -"
+#: systemv/cupstestppd.c:3546
#, c-format
msgid ""
-" %s Bad UTF-8 \"%s\" translation string for option %s, choice %s\n"
+" %s \"%s %s\" conflicts with \"%s %s\"\n"
+" (constraint=\"%s %s %s %s\")."
msgstr ""
+" %s \"%s %s\" está en conflictocon \"%s %s\"\n"
+" (restricción=\"%s %s %s %s\")."
+#: systemv/cupstestppd.c:2212
#, c-format
-msgid " %s Bad cupsFilter value \"%s\"\n"
-msgstr ""
-
-#, c-format
-msgid " %s Bad cupsICCProfile %s\n"
-msgstr ""
-
-#, c-format
-msgid " %s Bad cupsPreFilter value \"%s\"\n"
-msgstr ""
-
-#, c-format
-msgid " %s Bad cupsUIConstraints %s: \"%s\"\n"
-msgstr ""
-
-#, c-format
-msgid " %s Bad language \"%s\"\n"
-msgstr ""
-
-#, c-format
-msgid " %s Bad permissions on APDialogExtension file \"%s\"\n"
-msgstr ""
+msgid " %s %s %s does not exist."
+msgstr " %s %s %s no existe."
+#: systemv/cupstestppd.c:3703
#, c-format
-msgid " %s Bad permissions on APPrinterIconPath file \"%s\"\n"
-msgstr ""
+msgid " %s %s file \"%s\" has the wrong capitalization."
+msgstr " %s archivo %s \"%s\" tiene las mayúsculas equivocadas"
+#: systemv/cupstestppd.c:2282
#, c-format
-msgid " %s Bad permissions on APPrinterLowInkTool file \"%s\"\n"
+msgid ""
+" %s Bad %s choice %s.\n"
+" REF: Page 122, section 5.17"
msgstr ""
+" %s Preferencia %s incorrecta %s.\n"
+" REF: Página 122, sección 5.17"
+#: systemv/cupstestppd.c:3306
+#: systemv/cupstestppd.c:3355
+#: systemv/cupstestppd.c:3394
#, c-format
-msgid " %s Bad permissions on APPrinterUtilityPath file \"%s\"\n"
-msgstr ""
+msgid " %s Bad UTF-8 \"%s\" translation string for option %s, choice %s."
+msgstr " %s Cadena de traducción UTF-8 \"%s\" incorrecta para opción %s, preferencia %s."
+#: systemv/cupstestppd.c:3260
#, c-format
-msgid " %s Bad permissions on APScanAppPath file \"%s\"\n"
-msgstr ""
+msgid " %s Bad UTF-8 \"%s\" translation string for option %s."
+msgstr " %s Cadena de traducción UTF-8 \"%s\" incorrecta para opción %s."
+#: systemv/cupstestppd.c:2335
#, c-format
-msgid " %s Bad permissions on cupsFilter file \"%s\"\n"
-msgstr ""
+msgid " %s Bad cupsFilter value \"%s\"."
+msgstr " %s Valor cupsFilter \"%s\" incorrecto."
+#: systemv/cupstestppd.c:2814
#, c-format
-msgid " %s Bad permissions on cupsICCProfile file \"%s\"\n"
-msgstr ""
+msgid " %s Bad cupsICCProfile %s."
+msgstr " %s cupsICCProfile %s incorrecto."
+#: systemv/cupstestppd.c:2421
#, c-format
-msgid " %s Bad permissions on cupsPreFilter file \"%s\"\n"
-msgstr ""
+msgid " %s Bad cupsPreFilter value \"%s\"."
+msgstr " %s Valor cupsPreFilter \"%s\" incorrecto."
+#: systemv/cupstestppd.c:1786
#, c-format
-msgid " %s Bad spelling of %s - should be %s\n"
-msgstr ""
+msgid " %s Bad cupsUIConstraints %s: \"%s\""
+msgstr " %s cupsUIConstraints %s: \"%s\" incorrecto"
+#: systemv/cupstestppd.c:3210
#, c-format
-msgid " %s Cannot provide both APScanAppPath and APScanAppBundleID\n"
-msgstr ""
+msgid " %s Bad language \"%s\"."
+msgstr " %s Idioma incorrecto \"%s\"."
+#: systemv/cupstestppd.c:2379
+#: systemv/cupstestppd.c:2465
+#: systemv/cupstestppd.c:2523
+#: systemv/cupstestppd.c:2578
+#: systemv/cupstestppd.c:2633
+#: systemv/cupstestppd.c:2688
+#: systemv/cupstestppd.c:2741
+#: systemv/cupstestppd.c:2863
#, c-format
-msgid " %s Empty cupsUIConstraints %s\n"
-msgstr ""
+msgid " %s Bad permissions on %s file \"%s\"."
+msgstr " %s Permisos incorrectos en el archivo %s \"%s\"."
+#: systemv/cupstestppd.c:2405
+#: systemv/cupstestppd.c:2492
+#: systemv/cupstestppd.c:2547
+#: systemv/cupstestppd.c:2602
+#: systemv/cupstestppd.c:2657
+#: systemv/cupstestppd.c:2712
#, c-format
-msgid " %s Missing \"%s\" translation string for option %s\n"
-msgstr ""
+msgid " %s Bad spelling of %s - should be %s."
+msgstr " %s %s mal escrito - deberÃa ser %s."
+#: systemv/cupstestppd.c:2757
#, c-format
-msgid " %s Missing \"%s\" translation string for option %s, choice %s\n"
-msgstr ""
+msgid " %s Cannot provide both APScanAppPath and APScanAppBundleID."
+msgstr " %s No puede proporcionar APScanAppPath y APScanAppBundleID."
+#: systemv/cupstestppd.c:2169
#, c-format
-msgid " %s Missing APDialogExtension file \"%s\"\n"
-msgstr " %s Falta el archivo APDialogExtension \"%s\"\n"
+msgid " %s Default choices conflicting."
+msgstr " %s Las preferencias predeterminadas están en conflicto."
+#: systemv/cupstestppd.c:1767
#, c-format
-msgid " %s Missing APPrinterIconPath file \"%s\"\n"
-msgstr " %s Falta el archivo APPrinterIconPath \"%s\"\n"
+msgid " %s Empty cupsUIConstraints %s"
+msgstr " %s cupsUIConstraints %s vacÃo."
+#: systemv/cupstestppd.c:3338
+#: systemv/cupstestppd.c:3378
#, c-format
-msgid " %s Missing APPrinterLowInkTool file \"%s\"\n"
-msgstr " %s Falta el archivo APPrinterLowInkTool \"%s\"\n"
+msgid " %s Missing \"%s\" translation string for option %s, choice %s."
+msgstr " %s Falta cadena de traducción \"%s\" para opción %s, preferencia %s."
+#: systemv/cupstestppd.c:3246
#, c-format
-msgid " %s Missing APPrinterUtilityPath file \"%s\"\n"
-msgstr " %s Falta el archivo APPrinterUtilityPath \"%s\"\n"
+msgid " %s Missing \"%s\" translation string for option %s."
+msgstr " %s Falta cadena de traducción \"%s\" para opción %s."
+#: systemv/cupstestppd.c:2364
+#: systemv/cupstestppd.c:2450
+#: systemv/cupstestppd.c:2508
+#: systemv/cupstestppd.c:2563
+#: systemv/cupstestppd.c:2618
+#: systemv/cupstestppd.c:2673
+#: systemv/cupstestppd.c:2725
+#: systemv/cupstestppd.c:2848
#, c-format
-msgid " %s Missing APScanAppPath file \"%s\"\n"
-msgstr " %s Falta el archivo APScanAppPath \"%s\"\n"
+msgid " %s Missing %s file \"%s\"."
+msgstr " %s Falta archivo %s \"%s\"."
+#: systemv/cupstestppd.c:2971
#, c-format
msgid ""
-" %s Missing REQUIRED PageRegion option\n"
-" REF: Page 100, section 5.14.\n"
+" %s Missing REQUIRED PageRegion option.\n"
+" REF: Page 100, section 5.14."
msgstr ""
+" %s Falta la opción NECESARIA PageRegion.\n"
+" REF: Página 100, sección 5.14."
+#: systemv/cupstestppd.c:2956
#, c-format
msgid ""
-" %s Missing REQUIRED PageSize option\n"
-" REF: Page 99, section 5.14.\n"
-msgstr ""
-
-#, c-format
-msgid " %s Missing choice *%s %s in UIConstraints \"*%s %s *%s %s\"\n"
-msgstr ""
-
-#, c-format
-msgid " %s Missing choice *%s %s in cupsUIConstraints %s: \"%s\"\n"
+" %s Missing REQUIRED PageSize option.\n"
+" REF: Page 99, section 5.14."
msgstr ""
+" %s Falta la opción NECESARIA PageSize.\n"
+" REF: Página 99, sección 5.14."
+#: systemv/cupstestppd.c:1977
+#: systemv/cupstestppd.c:2018
#, c-format
-msgid " %s Missing cupsFilter file \"%s\"\n"
-msgstr " %s Falta archivo cupsFilter \"%s\"\n"
+msgid " %s Missing choice *%s %s in UIConstraints \"*%s %s *%s %s\"."
+msgstr " %s Falta la preferencia *%s %s en UIConstraint \"*%s %s *%s %s\"."
+#: systemv/cupstestppd.c:1872
#, c-format
-msgid " %s Missing cupsICCProfile file \"%s\"\n"
-msgstr ""
+msgid " %s Missing choice *%s %s in cupsUIConstraints %s: \"%s\""
+msgstr " %s Falta la preferencia *%s %s en cupsUIConstraints %s: \"%s\""
+#: systemv/cupstestppd.c:1804
#, c-format
-msgid " %s Missing cupsPreFilter file \"%s\"\n"
-msgstr " %s Falta archivo cupsPreFilter \"%s\"\n"
+msgid " %s Missing cupsUIResolver %s"
+msgstr " %s Falta cupsUIResolver %s"
+#: systemv/cupstestppd.c:1963
+#: systemv/cupstestppd.c:2004
#, c-format
-msgid " %s Missing cupsUIResolver %s\n"
-msgstr ""
+msgid " %s Missing option %s in UIConstraints \"*%s %s *%s %s\"."
+msgstr " %s Falta la opción %s en UIConstraints \"*%s %s *%s %s\"."
+#: systemv/cupstestppd.c:1856
#, c-format
-msgid " %s Missing option %s in UIConstraints \"*%s %s *%s %s\"\n"
-msgstr ""
+msgid " %s Missing option %s in cupsUIConstraints %s: \"%s\""
+msgstr " %s Falta la opción %s en cupsUIConstraints %s: \"%s\""
+#: systemv/cupstestppd.c:3432
#, c-format
-msgid " %s Missing option %s in cupsUIConstraints %s: \"%s\"\n"
-msgstr ""
+msgid " %s No base translation \"%s\" is included in file."
+msgstr " %s No hay traducción base \"%s\" incluida en el archivo."
+#: systemv/cupstestppd.c:2258
#, c-format
-msgid " %s No base translation \"%s\" is included in file\n"
+msgid ""
+" %s REQUIRED %s does not define choice None.\n"
+" REF: Page 122, section 5.17"
msgstr ""
+" %s NECESARIA %s no define la opción None.\n"
+" REF: Página 122, sección 5.17"
+#: systemv/cupstestppd.c:3029
+#: systemv/cupstestppd.c:3043
#, c-format
-msgid ""
-" %s Non-standard size name \"%s\"\n"
-" REF: Page 187, section B.2.\n"
-msgstr ""
+msgid " %s Size \"%s\" defined for %s but not for %s."
+msgstr " %s Tamaño \"%s\" definido para %s pero no para %s."
+#: systemv/cupstestppd.c:3009
#, c-format
-msgid ""
-" %s REQUIRED %s does not define choice None\n"
-" REF: Page 122, section 5.17\n"
-msgstr ""
+msgid " %s Size \"%s\" has unexpected dimensions (%gx%g)."
+msgstr " %s El tamaño \"%s\" tiene dimensiones inesperadas (%gx%g)."
+#: systemv/cupstestppd.c:3152
#, c-format
-msgid " %s Size \"%s\" defined for %s but not for %s\n"
-msgstr ""
+msgid " %s Size \"%s\" should be \"%s\"."
+msgstr " %s Tamaño \"%s\" deberÃa ser \"%s\"."
+#: systemv/cupstestppd.c:3118
#, c-format
-msgid " %s Size \"%s\" has unexpected dimensions (%gx%g)\n"
-msgstr ""
+msgid " %s Size \"%s\" should be the Adobe standard name \"%s\"."
+msgstr " %s Tamaño \"%s\" deberÃa ser el nombre estandar de Adobe \"%s\"."
+#: systemv/cupstestppd.c:2891
#, c-format
-msgid " %s cupsICCProfile %s hash value collides with %s\n"
-msgstr ""
+msgid " %s cupsICCProfile %s hash value collides with %s."
+msgstr " %s valor hash de cupsICCProfile %s colisiona con %s."
+#: systemv/cupstestppd.c:1927
#, c-format
-msgid " %s cupsUIResolver %s causes a loop\n"
-msgstr ""
+msgid " %s cupsUIResolver %s causes a loop."
+msgstr " %s cupsUIResolver %s genera un bucle."
+#: systemv/cupstestppd.c:1909
#, c-format
-msgid ""
-" %s cupsUIResolver %s does not list at least two different options\n"
-msgstr ""
+msgid " %s cupsUIResolver %s does not list at least two different options."
+msgstr " %s cupsUIResolver %s no lista al menos dos opciones diferentes."
+#: systemv/cupstestppd.c:2127
#, c-format
-msgid " **FAIL** %s choice names %s and %s differ only by case\n"
-msgstr ""
+msgid " **FAIL** %s choice names %s and %s differ only by case."
+msgstr " **FALLO** %s nombres de opción %s y %s se diferencian sólo en la capitalización."
+#: systemv/cupstestppd.c:1132
#, c-format
msgid ""
" **FAIL** %s must be 1284DeviceID\n"
-" REF: Page 72, section 5.5\n"
+" REF: Page 72, section 5.5"
msgstr ""
+" **FALLO** %s debe ser 1284DeviceID\n"
+" REF: Página 72, sección 5.5"
+#: systemv/cupstestppd.c:546
#, c-format
msgid ""
" **FAIL** BAD Default%s %s\n"
-" REF: Page 40, section 4.5.\n"
+" REF: Page 40, section 4.5."
msgstr ""
" **FALLO** Default%s %s INCORRECTO\n"
-" REF: Página 40, sección 4.5.\n"
+" REF: Página 40, sección 4.5."
+#: systemv/cupstestppd.c:480
#, c-format
msgid ""
" **FAIL** BAD DefaultImageableArea %s\n"
-" REF: Page 102, section 5.15.\n"
+" REF: Page 102, section 5.15."
msgstr ""
+" **FALLO** DefaultImageableArea %s INCORRECTO\n"
+" REF: Página 102, sección 5.15."
+#: systemv/cupstestppd.c:516
#, c-format
msgid ""
" **FAIL** BAD DefaultPaperDimension %s\n"
-" REF: Page 103, section 5.15.\n"
+" REF: Page 103, section 5.15."
msgstr ""
+" **FALLO** DefaultPaperDimension %s INCORRECTO\n"
+" REF: Página 103, sección 5.15."
+#: systemv/cupstestppd.c:989
msgid ""
" **FAIL** BAD JobPatchFile attribute in file\n"
-" REF: Page 24, section 3.4.\n"
+" REF: Page 24, section 3.4."
msgstr ""
" **FALLO** Atributo JobPatchFile en archivo, INCORRECTO\n"
-" REF: Página 24, sección 3.4.\n"
+" REF: Página 24, sección 3.4."
+#: systemv/cupstestppd.c:709
msgid ""
" **FAIL** BAD Manufacturer (should be \"HP\")\n"
-" REF: Page 211, table D.1.\n"
+" REF: Page 211, table D.1."
msgstr ""
" **FALLO** Fabricante INCORRECTO (deberÃa ser \"HP\")\n"
-" REF: Página 211, tabla D.1.\n"
+" REF: Página 211, tabla D.1."
+#: systemv/cupstestppd.c:725
msgid ""
" **FAIL** BAD Manufacturer (should be \"Oki\")\n"
-" REF: Page 211, table D.1.\n"
+" REF: Page 211, table D.1."
msgstr ""
" **FALLO** Fabricante INCORRECTO (deberÃa ser \"Oki\")\n"
-" REF: Página 211, tabla D.1.\n"
+" REF: Página 211, tabla D.1."
+#: systemv/cupstestppd.c:764
#, c-format
msgid ""
" **FAIL** BAD ModelName - \"%c\" not allowed in string.\n"
-" REF: Pages 59-60, section 5.3.\n"
+" REF: Pages 59-60, section 5.3."
msgstr ""
-" **FALLO** ModelName - \"%c\" INCORRECTO no permitido en la cadena.\n"
-" REF: Páginas 59-60, sección 5.3.\n"
+" **FALLO** ModelName INCORRECTO - \"%c\" no permitido en la cadena.\n"
+" REF: Páginas 59-60, sección 5.3."
+#: systemv/cupstestppd.c:920
msgid ""
" **FAIL** BAD PSVersion - not \"(string) int\".\n"
-" REF: Pages 62-64, section 5.3.\n"
+" REF: Pages 62-64, section 5.3."
msgstr ""
" **FALLO** PSVersion INCORRECTO - no es \"(string) int\".\n"
-" REF: Páginas 62-64, sección 5.3.\n"
+" REF: Páginas 62-64, sección 5.3."
+#: systemv/cupstestppd.c:881
msgid ""
" **FAIL** BAD Product - not \"(string)\".\n"
-" REF: Page 62, section 5.3.\n"
+" REF: Page 62, section 5.3."
msgstr ""
" **FALLO** Product INCORRECTO - no es \"(string)\".\n"
-" REF: Página 62, sección 5.3.\n"
+" REF: Página 62, sección 5.3."
+#: systemv/cupstestppd.c:955
msgid ""
" **FAIL** BAD ShortNickName - longer than 31 chars.\n"
-" REF: Pages 64-65, section 5.3.\n"
+" REF: Pages 64-65, section 5.3."
msgstr ""
" **FALLO** ShortNickName INCORRECTO - mayor de 31 caracteres.\n"
-" REF: Páginas 64-65, sección 5.3.\n"
+" REF: Páginas 64-65, sección 5.3."
+#: systemv/cupstestppd.c:1113
#, c-format
msgid ""
" **FAIL** Bad %s choice %s\n"
-" REF: Page 84, section 5.9\n"
+" REF: Page 84, section 5.9"
msgstr ""
+" **FALLO** Preferencia %s incorrecta %s\n"
+" REF: Página 84, sección 5.9"
+#: systemv/cupstestppd.c:589
#, c-format
msgid ""
" **FAIL** Bad FileVersion \"%s\"\n"
-" REF: Page 56, section 5.3.\n"
+" REF: Page 56, section 5.3."
msgstr ""
" **FALLO** FileVersion \"%s\" incorrecto\n"
-" REF: Página 56, sección 5.3.\n"
+" REF: Página 56, sección 5.3."
+#: systemv/cupstestppd.c:633
#, c-format
msgid ""
" **FAIL** Bad FormatVersion \"%s\"\n"
-" REF: Page 56, section 5.3.\n"
+" REF: Page 56, section 5.3."
msgstr ""
" **FALLO** FormatVersion \"%s\" incorrecto\n"
-" REF: Página 56, sección 5.3.\n"
+" REF: Página 56, sección 5.3."
+#: systemv/cupstestppd.c:1177
#, c-format
-msgid " **FAIL** Bad LanguageEncoding %s - must be ISOLatin1\n"
-msgstr ""
+msgid " **FAIL** Bad LanguageEncoding %s - must be ISOLatin1."
+msgstr " **FALLO** LanguageEncoding %s incorrecto: deberÃa ser ISOLatin1."
+#: systemv/cupstestppd.c:1191
#, c-format
-msgid " **FAIL** Bad LanguageVersion %s - must be English\n"
-msgstr ""
+msgid " **FAIL** Bad LanguageVersion %s - must be English."
+msgstr " **FALLO** LanguageVersion %s incorrecto: deberÃa ser English (Inglés)."
+#: systemv/cupstestppd.c:3573
+#: systemv/cupstestppd.c:3595
#, c-format
-msgid " **FAIL** Default option code cannot be interpreted: %s\n"
-msgstr ""
-" **FALLO** El código de opción predeterminado no puede ser "
-"interpretado: %s\n"
+msgid " **FAIL** Default option code cannot be interpreted: %s"
+msgstr " **FALLO** El código de opción predeterminado no puede ser interpretado: %s"
+#: systemv/cupstestppd.c:1250
#, c-format
-msgid ""
-" **FAIL** Default translation string for option %s choice %s contains "
-"8-bit characters\n"
-msgstr ""
+msgid " **FAIL** Default translation string for option %s choice %s contains 8-bit characters."
+msgstr " **FALLO** Cadena de traducción predeterminada para opción %s preferencia %s contiene caracteres de 8-bits."
+#: systemv/cupstestppd.c:1223
#, c-format
-msgid ""
-" **FAIL** Default translation string for option %s contains 8-bit "
-"characters\n"
-msgstr ""
+msgid " **FAIL** Default translation string for option %s contains 8-bit characters."
+msgstr " **FALLO** Cadena de traducción predeterminada para opción %s contiene caracteres de 8-bits."
+#: systemv/cupstestppd.c:2065
#, c-format
-msgid " **FAIL** Group names %s and %s differ only by case\n"
-msgstr ""
+msgid " **FAIL** Group names %s and %s differ only by case."
+msgstr " **FALLO** Nombres de grupo %s y %s se diferencian sólo en la capitalización."
+#: systemv/cupstestppd.c:2110
#, c-format
-msgid " **FAIL** Multiple occurrences of %s choice name %s\n"
-msgstr ""
+msgid " **FAIL** Multiple occurrences of %s choice name %s."
+msgstr " **FALLO** Múltiples apariciones de %s nombre de opción %s."
+#: systemv/cupstestppd.c:2087
#, c-format
-msgid " **FAIL** Option names %s and %s differ only by case\n"
-msgstr ""
+msgid " **FAIL** Option names %s and %s differ only by case."
+msgstr " **FALLO** Nombres de opción %s y %s se diferencian sólo en la capitalización."
+#: systemv/cupstestppd.c:566
#, c-format
msgid ""
" **FAIL** REQUIRED Default%s\n"
-" REF: Page 40, section 4.5.\n"
+" REF: Page 40, section 4.5."
msgstr ""
" **FALLO** SE NECESITA Default%s\n"
-" REF: Página 40, sección 4.5.\n"
+" REF: Página 40, sección 4.5."
+#: systemv/cupstestppd.c:465
msgid ""
" **FAIL** REQUIRED DefaultImageableArea\n"
-" REF: Page 102, section 5.15.\n"
+" REF: Page 102, section 5.15."
msgstr ""
" **FALLO** SE NECESITA DefaultImageableArea\n"
-" REF: Página 102, sección 5.15.\n"
+" REF: Página 102, sección 5.15."
+#: systemv/cupstestppd.c:501
msgid ""
" **FAIL** REQUIRED DefaultPaperDimension\n"
-" REF: Page 103, section 5.15.\n"
+" REF: Page 103, section 5.15."
msgstr ""
" **FALLO** SE NECESITA DefaultPaperDimension\n"
-" REF: Página 103, sección 5.15.\n"
+" REF: Página 103, sección 5.15."
+#: systemv/cupstestppd.c:607
msgid ""
" **FAIL** REQUIRED FileVersion\n"
-" REF: Page 56, section 5.3.\n"
+" REF: Page 56, section 5.3."
msgstr ""
" **FALLO** SE NECESITA FileVersion\n"
-" REF: Página 56, sección 5.3.\n"
+" REF: Página 56, sección 5.3."
+#: systemv/cupstestppd.c:651
msgid ""
" **FAIL** REQUIRED FormatVersion\n"
-" REF: Page 56, section 5.3.\n"
+" REF: Page 56, section 5.3."
msgstr ""
" **FALLO** SE NECESITA FormatVersion\n"
-" REF: Página 56, sección 5.3.\n"
+" REF: Página 56, sección 5.3."
+#: systemv/cupstestppd.c:1040
#, c-format
msgid ""
" **FAIL** REQUIRED ImageableArea for PageSize %s\n"
" REF: Page 41, section 5.\n"
-" REF: Page 102, section 5.15.\n"
+" REF: Page 102, section 5.15."
msgstr ""
" **FALLO** SE NECESITA ImageableArea para PageSize %s\n"
" REF: Página 41, sección 5.\n"
-" REF: Página 102, sección 5.15.\n"
+" REF: Página 102, sección 5.15."
+#: systemv/cupstestppd.c:671
msgid ""
" **FAIL** REQUIRED LanguageEncoding\n"
-" REF: Pages 56-57, section 5.3.\n"
+" REF: Pages 56-57, section 5.3."
msgstr ""
" **FALLO** SE NECESITA LanguageEncoding\n"
-" REF: Páginas 56-57, sección 5.3.\n"
+" REF: Páginas 56-57, sección 5.3."
+#: systemv/cupstestppd.c:691
msgid ""
" **FAIL** REQUIRED LanguageVersion\n"
-" REF: Pages 57-58, section 5.3.\n"
+" REF: Pages 57-58, section 5.3."
msgstr ""
" **FALLO** SE NECESITA LanguageVersion\n"
-" REF: Páginas 57-58, sección 5.3.\n"
+" REF: Páginas 57-58, sección 5.3."
+#: systemv/cupstestppd.c:743
msgid ""
" **FAIL** REQUIRED Manufacturer\n"
-" REF: Pages 58-59, section 5.3.\n"
+" REF: Pages 58-59, section 5.3."
msgstr ""
" **FALLO** SE NECESITA Manufacturer\n"
-" REF: Páginas 58-59, sección 5.3.\n"
+" REF: Páginas 58-59, sección 5.3."
+#: systemv/cupstestppd.c:783
msgid ""
" **FAIL** REQUIRED ModelName\n"
-" REF: Pages 59-60, section 5.3.\n"
+" REF: Pages 59-60, section 5.3."
msgstr ""
" **FALLO** SE NECESITA ModelName\n"
-" REF: Páginas 59-60, sección 5.3.\n"
+" REF: Páginas 59-60, sección 5.3."
+#: systemv/cupstestppd.c:803
msgid ""
" **FAIL** REQUIRED NickName\n"
-" REF: Page 60, section 5.3.\n"
+" REF: Page 60, section 5.3."
msgstr ""
" **FALLO** SE NECESITA NickName\n"
-" REF: Página 60, sección 5.3.\n"
+" REF: Página 60, sección 5.3."
+#: systemv/cupstestppd.c:863
msgid ""
" **FAIL** REQUIRED PCFileName\n"
-" REF: Pages 61-62, section 5.3.\n"
+" REF: Pages 61-62, section 5.3."
msgstr ""
" **FALLO** SE NECESITA PCFileName\n"
-" REF: Páginas 61-62, sección 5.3.\n"
+" REF: Páginas 61-62, sección 5.3."
+#: systemv/cupstestppd.c:938
msgid ""
" **FAIL** REQUIRED PSVersion\n"
-" REF: Pages 62-64, section 5.3.\n"
+" REF: Pages 62-64, section 5.3."
msgstr ""
" **FALLO** SE NECESITA PSVersion\n"
-" REF: Páginas 62-64, sección 5.3.\n"
+" REF: Páginas 62-64, sección 5.3."
+#: systemv/cupstestppd.c:843
msgid ""
" **FAIL** REQUIRED PageRegion\n"
-" REF: Page 100, section 5.14.\n"
+" REF: Page 100, section 5.14."
msgstr ""
" **FALLO** SE NECESITA PageRegion\n"
-" REF: Página 100, sección 5.14.\n"
+" REF: Página 100, sección 5.14."
+#: systemv/cupstestppd.c:1009
msgid ""
" **FAIL** REQUIRED PageSize\n"
" REF: Page 41, section 5.\n"
-" REF: Page 99, section 5.14.\n"
+" REF: Page 99, section 5.14."
msgstr ""
" **FALLO** SE NECESITA PageSize\n"
" REF: Página 41, sección 5.\n"
-" REF: Página 99, sección 5.14.\n"
+" REF: Página 99, sección 5.14."
+#: systemv/cupstestppd.c:823
msgid ""
" **FAIL** REQUIRED PageSize\n"
-" REF: Pages 99-100, section 5.14.\n"
+" REF: Pages 99-100, section 5.14."
msgstr ""
" **FALLO** SE NECESITA PageSize\n"
-" REF: Páginas 99-100, sección 5.14.\n"
+" REF: Páginas 99-100, sección 5.14."
+#: systemv/cupstestppd.c:1062
#, c-format
msgid ""
" **FAIL** REQUIRED PaperDimension for PageSize %s\n"
" REF: Page 41, section 5.\n"
-" REF: Page 103, section 5.15.\n"
+" REF: Page 103, section 5.15."
msgstr ""
" **FALLO** SE NECESITA PaperDimension para PageSize %s\n"
" REF: Página 41, sección 5.\n"
-" REF: Página 103, sección 5.15.\n"
+" REF: Página 103, sección 5.15."
+#: systemv/cupstestppd.c:898
msgid ""
" **FAIL** REQUIRED Product\n"
-" REF: Page 62, section 5.3.\n"
+" REF: Page 62, section 5.3."
msgstr ""
" **FALLO** SE NECESITA Product\n"
-" REF: Página 62, sección 5.3.\n"
+" REF: Página 62, sección 5.3."
+#: systemv/cupstestppd.c:973
msgid ""
" **FAIL** REQUIRED ShortNickName\n"
-" REF: Page 64-65, section 5.3.\n"
+" REF: Page 64-65, section 5.3."
msgstr ""
" **FALLO** SE NECESITA ShortNickName\n"
-" REF: Página 64-65, sección 5.3.\n"
+" REF: Página 64-65, sección 5.3."
+
+#: systemv/cupstestppd.c:335
+#, c-format
+msgid " **FAIL** Unable to open PPD file - %s"
+msgstr " **FALLO** No se ha podido abrir el archivo PPD - %s"
+
+#: systemv/cupstestppd.c:347
+#, c-format
+msgid " **FAIL** Unable to open PPD file - %s on line %d."
+msgstr " **FALLO** No se ha podido abrir el archivo PPD - %s en la lÃnea %d."
+#: systemv/cupstestppd.c:1462
#, c-format
-msgid " %d ERRORS FOUND\n"
-msgstr " %d ERRORES ENCONTRADOS\n"
+msgid " %d ERRORS FOUND"
+msgstr " %d ERRORES ENCONTRADOS"
+#: systemv/cupstestdsc.c:431
+msgid " -h Show program usage"
+msgstr " -h Mostrar el uso del programa"
+
+#: systemv/cupstestdsc.c:234
+#: systemv/cupstestdsc.c:276
#, c-format
msgid ""
-" Bad %%%%BoundingBox: on line %d\n"
-" REF: Page 39, %%%%BoundingBox:\n"
+" Bad %%%%BoundingBox: on line %d.\n"
+" REF: Page 39, %%%%BoundingBox:"
msgstr ""
+" %%%%BoundingBox: incorrecto en lÃnea %d.\n"
+" REF: Página 39, %%%%BoundingBox:"
+#: systemv/cupstestdsc.c:305
#, c-format
msgid ""
-" Bad %%%%Page: on line %d\n"
-" REF: Page 53, %%%%Page:\n"
+" Bad %%%%Page: on line %d.\n"
+" REF: Page 53, %%%%Page:"
msgstr ""
+" %%%%Page: incorrecto en lÃnea %d.\n"
+" REF: Página 53, %%%%Page:"
+#: systemv/cupstestdsc.c:218
+#: systemv/cupstestdsc.c:258
#, c-format
msgid ""
-" Bad %%%%Pages: on line %d\n"
-" REF: Page 43, %%%%Pages:\n"
+" Bad %%%%Pages: on line %d.\n"
+" REF: Page 43, %%%%Pages:"
msgstr ""
+" %%%%Pages: incorrecto en lÃnea %d.\n"
+" REF: Página 43, %%%%Pages:"
+#: systemv/cupstestdsc.c:176
#, c-format
msgid ""
-" Line %d is longer than 255 characters (%d)\n"
-" REF: Page 25, Line Length\n"
+" Line %d is longer than 255 characters (%d).\n"
+" REF: Page 25, Line Length"
msgstr ""
+" La lÃnea %d es más larga de 255 caracteres (%d).\n"
+" REF: Página 25, Longitud de LÃnea"
+#: systemv/cupstestdsc.c:192
msgid ""
-" Missing %!PS-Adobe-3.0 on first line\n"
-" REF: Page 17, 3.1 Conforming Documents\n"
+" Missing %!PS-Adobe-3.0 on first line.\n"
+" REF: Page 17, 3.1 Conforming Documents"
msgstr ""
+" Falta %!PS-Adobe-3.0 en la primera lÃnea.\n"
+" REF: Página 17, 3.1 Conformidad de documentos"
+#: systemv/cupstestdsc.c:362
#, c-format
-msgid ""
-" Missing %%EndComments comment\n"
-" REF: Page 41, %%EndComments\n"
-msgstr ""
+msgid " Missing %%EndComments comment. REF: Page 41, %%EndComments"
+msgstr " Falta comentario %%EndComments. REF: Página 41, %%EndComments"
+#: systemv/cupstestdsc.c:342
#, c-format
msgid ""
-" Missing or bad %%BoundingBox: comment\n"
-" REF: Page 39, %%BoundingBox:\n"
+" Missing or bad %%BoundingBox: comment.\n"
+" REF: Page 39, %%BoundingBox:"
msgstr ""
+" Falta comentario %%BoundingBox: o incorrecto.\n"
+" REF: Página 39, %%BoundingBox:"
+#: systemv/cupstestdsc.c:372
#, c-format
msgid ""
-" Missing or bad %%Page: comments\n"
-" REF: Page 53, %%Page:\n"
+" Missing or bad %%Page: comments.\n"
+" REF: Page 53, %%Page:"
msgstr ""
+" Falta comentario %%Page: o incorrecto.\n"
+" REF: Página 53, %%Page:"
+#: systemv/cupstestdsc.c:352
#, c-format
msgid ""
-" Missing or bad %%Pages: comment\n"
-" REF: Page 43, %%Pages:\n"
+" Missing or bad %%Pages: comment.\n"
+" REF: Page 43, %%Pages:"
msgstr ""
+" Falta comentario %%Pages: o incorrecto.\n"
+" REF: Página 43, %%Pages:"
-msgid " NO ERRORS FOUND\n"
-msgstr " NO SE HAN ENCONTRADO ERRORES\n"
+#: systemv/cupstestppd.c:1464
+msgid " NO ERRORS FOUND"
+msgstr " NO SE HAN ENCONTRADO ERRORES"
+#: systemv/cupstestdsc.c:395
#, c-format
-msgid " Saw %d lines that exceeded 255 characters\n"
-msgstr ""
+msgid " Saw %d lines that exceeded 255 characters."
+msgstr " Se han visto %d lÃneas que exceden de 255 caracteres."
+#: systemv/cupstestdsc.c:390
#, c-format
-msgid " Too many %%BeginDocument comments\n"
-msgstr ""
+msgid " Too many %%BeginDocument comments."
+msgstr " Demasiados comentarios %%BeginDocument."
+#: systemv/cupstestdsc.c:382
#, c-format
-msgid " Too many %%EndDocument comments\n"
-msgstr ""
+msgid " Too many %%EndDocument comments."
+msgstr " Demasiados comentarios %%EndDocument."
-msgid " Warning: file contains binary data\n"
-msgstr ""
+#: systemv/cupstestdsc.c:402
+msgid " Warning: file contains binary data."
+msgstr " Advertencia: el archivo contiene datos binarios."
+#: systemv/cupstestdsc.c:410
#, c-format
-msgid " Warning: no %%EndComments comment in file\n"
-msgstr ""
+msgid " Warning: no %%EndComments comment in file."
+msgstr " Advertencia: no hay comentario %%EndComments en el archivo."
+#: systemv/cupstestdsc.c:406
#, c-format
-msgid " Warning: obsolete DSC version %.1f in file\n"
-msgstr ""
+msgid " Warning: obsolete DSC version %.1f in file."
+msgstr " Advertencia: versión DSC %.1f obsoleta en el archivo."
-msgid " FAIL\n"
-msgstr " FALLO\n"
+#: systemv/cupsctl.c:216
+msgid " --[no-]debug-logging Turn debug logging on/off."
+msgstr " --[no-]debug-logging Activar/desactivar registro de depuración."
-#, c-format
-msgid ""
-" FAIL\n"
-" **FAIL** Unable to open PPD file - %s\n"
-msgstr ""
-" FALLO\n"
-" **FALLO** No se ha podido abrir el archivo PPD - %s\n"
+#: systemv/cupsctl.c:218
+msgid " --[no-]remote-admin Turn remote administration on/off."
+msgstr " --[no-]remote-admin Activar/desactivar administración remota."
-#, c-format
-msgid ""
-" FAIL\n"
-" **FAIL** Unable to open PPD file - %s on line %d.\n"
-msgstr ""
-" FALLO\n"
-" **FALLO** No se ha podido abrir el archivo PPD - %s en la lÃnea %d.\n"
+#: systemv/cupsctl.c:220
+msgid " --[no-]remote-any Allow/prevent access from the Internet."
+msgstr " --[no-]remote-any Permitir/evitar acceso desde Internet."
-msgid " PASS\n"
-msgstr " PASA\n"
+#: systemv/cupsctl.c:222
+msgid " --[no-]remote-printers Show/hide remote printers."
+msgstr " --[no-]remote-printers Mostrar/ocultar impresoras remotas."
-msgid "#10 Envelope"
-msgstr "Sobre nº 10"
+#: systemv/cupsctl.c:224
+msgid " --[no-]share-printers Turn printer sharing on/off."
+msgstr " --[no-]share-printers Activar/desactivar compartición de impresoras."
-msgid "#11 Envelope"
-msgstr "Sobre nº 11"
+#: systemv/cupsctl.c:226
+msgid " --[no-]user-cancel-any Allow/prevent users to cancel any job."
+msgstr " --[no-]user-cancel-any Permitir/evitar a usuarios que cancelen cualquier trabajo."
-msgid "#12 Envelope"
-msgstr "Sobre nº 12"
+#: ppdc/ppdc.cxx:456
+msgid " --cr End lines with CR (Mac OS 9)."
+msgstr " --cr Finalizar lÃneas con CR (Mac OS 9)."
-msgid "#14 Envelope"
-msgstr "Sobre nº 14"
+#: ppdc/ppdc.cxx:458
+msgid " --crlf End lines with CR + LF (Windows)."
+msgstr " --crlf Finalizar lÃneas con CR + LF (Windows)."
-msgid "#9 Envelope"
-msgstr "Sobre nº 9"
+#: ppdc/ppdc.cxx:460
+msgid " --lf End lines with LF (UNIX/Linux/Mac OS X)."
+msgstr " --lf Finalizar lÃneas con LF (UNIX/Linux/Mac OS X)."
-#, c-format
-msgid "%-6s %-10.10s %-4d %-10d %-27.27s %.0f bytes\n"
-msgstr "%-6s %-10.10s %-4d %-10d %-27.27s %.0f bytes\n"
+#: test/ipptool.c:3922
+msgid " -4 Connect using IPv4."
+msgstr " -4 Conectar usando IPv4."
-#, c-format
-msgid "%-7s %-7.7s %-7d %-31.31s %.0f bytes\n"
-msgstr "%-7s %-7.7s %-7d %-31.31s %.0f bytes\n"
+#: test/ipptool.c:3923
+msgid " -6 Connect using IPv6."
+msgstr " -6 Conectar usando IPv6."
+
+#: test/ipptool.c:3924
+msgid " -C Send requests using chunking (default)."
+msgstr " -C Enviar peticiones usando fragmentación (predeterminado)."
+
+#: scheduler/cupsfilter.c:1441
+#: scheduler/cupsfilter.c:1468
+msgid " -D Remove the input file when finished."
+msgstr " -D Eliminar el archivo de entrada al terminar."
+
+#: ppdc/ppdc.cxx:438
+#: ppdc/ppdhtml.cxx:175
+#: ppdc/ppdpo.cxx:255
+msgid " -D name=value Set named variable to value."
+msgstr " -D nombre=valor Establece la variable nombre al valor."
+
+#: systemv/cupsctl.c:211
+msgid " -E Enable encryption."
+msgstr " -E Activar cifrado."
+
+#: systemv/cupsaddsmb.c:285
+msgid " -E Encrypt the connection to the server."
+msgstr " -E Cifra la conexión al servidor."
+
+#: test/ipptool.c:3926
+msgid " -E Test with TLS encryption."
+msgstr " -E Prueba con cifrado TLS."
+
+#: scheduler/main.c:2062
+msgid " -F Run in the foreground but detach from console."
+msgstr " -F Ejecuta en primer plano pero separado de la consola."
+#: systemv/cupsaddsmb.c:287
+msgid " -H samba-server Use the named SAMBA server."
+msgstr " -H servidor-samba Usa el servidor SAMBA nombrado."
+
+#: test/ipptool.c:3928
+msgid " -I Ignore errors."
+msgstr " -I Ignora errores."
+
+#: ppdc/ppdc.cxx:440
+#: ppdc/ppdhtml.cxx:177
+#: ppdc/ppdi.cxx:131
+#: ppdc/ppdpo.cxx:257
+msgid " -I include-dir Add include directory to search path."
+msgstr " -I include-dir Añade directorio include a la ruta de búsqueda."
+
+#: systemv/cupstestppd.c:3618
+msgid " -I {filename,filters,none,profiles}"
+msgstr " -I {filename,filters,none,profiles}"
+
+#: scheduler/cupsfilter.c:1470
+msgid " -J title Set title."
+msgstr " -J tÃtulo Establece tÃtulo."
+
+#: test/ipptool.c:3929
+msgid " -L Send requests using content-length."
+msgstr " -L EnvÃa peticiones usando content-length."
+
+#: scheduler/cupsfilter.c:1443
+#: scheduler/cupsfilter.c:1471
+msgid " -P filename.ppd Set PPD file."
+msgstr " -P nombre_archivo.ppd Establece archivo PPD."
+
+#: systemv/cupstestppd.c:3620
+msgid " -R root-directory Set alternate root."
+msgstr " -R directorio-raÃz Establece directorio raÃz alternativo."
+
+#: test/ipptool.c:3931
+msgid " -S Test with SSL encryption."
+msgstr " -S Prueba con cifrado SSL."
+
+#: test/ipptool.c:3933
+msgid " -T Set the receive/send timeout in seconds."
+msgstr " -T Establece el tiempo de espera de recepción/envÃo en segundos."
+
+#: systemv/cupsaddsmb.c:289
+msgid " -U samba-user Authenticate using the named SAMBA user."
+msgstr " -U ususario-samba Autentifica usando el usuario SAMBA especificado."
+
+#: scheduler/cupsfilter.c:1444
+#: scheduler/cupsfilter.c:1472
+msgid " -U username Set username for job."
+msgstr " -U nombre_usuario Establece el nombre de usuario para el trabajo."
+
+#: systemv/cupsctl.c:212
+msgid " -U username Specify username."
+msgstr " -U nombre_usuario Especifica el nombre de usuario."
+
+#: test/ipptool.c:3935
+msgid " -V version Set default IPP version."
+msgstr " -V versión Establece la versión IPP predeterminada."
+
+#: systemv/cupstestppd.c:3621
+msgid " -W {all,none,constraints,defaults,duplex,filters,profiles,sizes,translations}"
+msgstr " -W {all,none,constraints,defaults,duplex,filters,profiles,sizes,translations}"
+
+#: test/ipptool.c:3937
+msgid " -X Produce XML plist instead of plain text."
+msgstr " -X Produce XML plist en vez de texto sin formato."
+
+#: systemv/cupsaddsmb.c:291
+msgid " -a Export all printers."
+msgstr " -a Exporta todas las impresoras."
+
+#: scheduler/cupsfilter.c:1473
+msgid " -a 'name=value ...' Set option(s)."
+msgstr " -a 'nombre=valor ...' Establece opción(es)."
+
+#: ppdc/ppdc.cxx:442
+msgid " -c catalog.po Load the specified message catalog."
+msgstr " -c catálogo.po Carga el catálogo de mensajes especificado."
+
+#: scheduler/main.c:2059
+msgid " -c config-file Load alternate configuration file."
+msgstr " -c archivo-config Carga archivo de configuración alternativo."
+
+#: scheduler/cupsfilter.c:1474
+msgid " -c copies Set number of copies."
+msgstr " -c copias Establece el número de copias."
+
+#: scheduler/cupsfilter.c:1445
+msgid " -c cupsd.conf Set cupsd.conf file to use."
+msgstr " -c cupsd.conf Establece el archivo cupsd.conf a usar."
+
+#: test/ipptool.c:3939
+msgid " -d name=value Set named variable to value."
+msgstr " -d nombre=valor Establece la variable al valor."
+
+#: ppdc/ppdc.cxx:444
+msgid " -d output-dir Specify the output directory."
+msgstr " -d dir-salida Especifica el directorio de salida."
+
+#: scheduler/cupsfilter.c:1447
+#: scheduler/cupsfilter.c:1475
+msgid " -d printer Use the named printer."
+msgstr " -d impresora Usa la impresora especificada."
+
+#: scheduler/cupsfilter.c:1449
+#: scheduler/cupsfilter.c:1477
+msgid " -e Use every filter from the PPD file."
+msgstr " -e Usa cada filtro desde el archivo PPD."
+
+#: scheduler/main.c:2061
+msgid " -f Run in the foreground."
+msgstr " -f Ejecuta en primer plano."
+
+#: test/ipptool.c:3941
+msgid " -f filename Set default request filename."
+msgstr " -f nombre_archivo Establece nombre de archivo predeterminado."
+
+#: scheduler/cupsfilter.c:1479
+msgid " -f filename Set file to be converted (otherwise stdin)."
+msgstr " -f nombre_archivo Establece el archivo que va a ser convertido (si no, stdin)."
+
+#: scheduler/main.c:2064
+msgid " -h Show this usage message."
+msgstr " -h Muestra este mensaje de uso."
+
+#: systemv/cupsaddsmb.c:292
+msgid " -h cups-server Use the named CUPS server."
+msgstr " -h servidor-cups Usa el servidor CUPS especificado."
+
+#: systemv/cupsctl.c:213
+msgid " -h server[:port] Specify server address."
+msgstr " -h servidor[:puerto] Especifica la dirección del servidor."
+
+#: scheduler/cupsfilter.c:1451
+#: scheduler/cupsfilter.c:1481
+msgid " -i mime/type Set input MIME type (otherwise auto-typed)."
+msgstr " -i tipo/mime Establece el tipo MIME de entrada (si no, auto-typed)."
+
+#: test/ipptool.c:3943
+msgid " -i seconds Repeat the last file with the given time interval."
+msgstr " -i segundos Repite el último archivo con el intervalo de tiempo dado."
+
+#: scheduler/cupsfilter.c:1453
+msgid " -j job-id[,N] Filter file N from the specified job (default is file 1)."
+msgstr " -j id-trabajo[,N] Filtra el archivo N desde el trabajo especificado (predeterminado archivo 1)."
+
+#: scheduler/cupsfilter.c:1483
+msgid " -j mime/type Set output MIME type (otherwise application/pdf)."
+msgstr " -j tipo/mime Establece el tipo MIME de salida (si no, application/pdf)."
+
+#: scheduler/main.c:2065
+msgid " -l Run cupsd from launchd(8)."
+msgstr " -l Ejecuta cupsd desde launchd(8)."
+
+#: ppdc/ppdc.cxx:446
+msgid " -l lang[,lang,...] Specify the output language(s) (locale)."
+msgstr " -l idioma[,idioma,...] Especifica los idiomas de salida (código regional)."
+
+#: ppdc/ppdc.cxx:448
+msgid " -m Use the ModelName value as the filename."
+msgstr " -m Usa el valor ModelName como nombre de archivo."
+
+#: scheduler/cupsfilter.c:1455
+msgid " -m mime/type Set output MIME type (otherwise application/pdf)."
+msgstr " -m tipo/mime Establece el tipo MIME de salida (si no, application/pdf)."
+
+#: scheduler/cupsfilter.c:1457
+msgid " -n copies Set number of copies."
+msgstr " -n copias Establece el número de copias."
+
+#: test/ipptool.c:3945
+msgid " -n count Repeat the last file the given number of times."
+msgstr " -n contador Repite el último archivo el número de veces especificado."
+
+#: scheduler/cupsfilter.c:1485
+msgid " -o filename Set file to be generated (otherwise stdout)."
+msgstr " -o nombre_archivo Establece el archivo que va a ser generado (si no, stdout)."
+
+#: ppdc/ppdi.cxx:133
+msgid " -o filename.drv Set driver information file (otherwise ppdi.drv)."
+msgstr " -o nombre_archivo.drv Establece el archivo de información del controlador (si no, ppdi.drv)."
+
+#: ppdc/ppdmerge.cxx:370
+msgid " -o filename.ppd[.gz] Set output file (otherwise stdout)."
+msgstr " -o nombre_archivo.ppd[.gz] Establece el archivo de salida (si no, stdout)."
+
+#: scheduler/cupsfilter.c:1458
+msgid " -o name=value Set option(s)."
+msgstr " -o nombre=valor Establece opciones."
+
+#: scheduler/cupsfilter.c:1459
+msgid " -p filename.ppd Set PPD file."
+msgstr " -p nombre_archivo.ppd Establece archivo PPD."
+
+#: test/ipptool.c:3947
+msgid " -q Be quiet - no output except errors."
+msgstr " -q Silencioso - sin salida excepto errores."
+
+#: systemv/cupstestppd.c:3625
+msgid " -q Run silently."
+msgstr " -q Ejecución silenciosa."
+
+#: systemv/cupstestppd.c:3626
+msgid " -r Use 'relaxed' open mode."
+msgstr " -r Usa modo abierto 'relajado'."
+
+#: test/ipptool.c:3949
+msgid " -t Produce a test report."
+msgstr " -t Produce un informe de la prueba."
+
+#: ppdc/ppdc.cxx:450
+msgid " -t Test PPDs instead of generating them."
+msgstr " -t Prueba los PPDs en vez de generarlos."
+
+#: scheduler/main.c:2066
+msgid " -t Test the configuration file."
+msgstr " -t Prueba el archivo de configuración."
+
+#: scheduler/cupsfilter.c:1460
+msgid " -t title Set title."
+msgstr " -t tÃtulo Establece tÃtulo."
+
+#: scheduler/cupsfilter.c:1461
+#: scheduler/cupsfilter.c:1487
+msgid " -u Remove the PPD file when finished."
+msgstr " -u Borra el archivo PPD tras terminar."
+
+#: systemv/cupstestppd.c:3627
+msgid " -v Be slightly verbose."
+msgstr " -v Ser ligeramente detallado."
+
+#: ppdc/ppdc.cxx:452
+#: ppdc/ppdpo.cxx:259
+msgid " -v Be verbose (more v's for more verbosity)."
+msgstr " -v Ser detallado (más v's para más detalle)."
+
+#: systemv/cupsaddsmb.c:294
+msgid " -v Be verbose (show commands)."
+msgstr " -v Ser detallado (mostrar comandos)."
+
+#: test/ipptool.c:3950
+msgid " -v Show all attributes sent and received."
+msgstr " -v Mostrar todos los atributos enviados y recibidos."
+
+#: systemv/cupstestppd.c:3628
+msgid " -vv Be very verbose."
+msgstr " -vv Ser muy detallado."
+
+#: ppdc/ppdc.cxx:454
+msgid " -z Compress PPD files using GNU zip."
+msgstr " -z Comprimir archivos PPD usando GNU zip."
+
+#: systemv/cupstestppd.c:333
+#: systemv/cupstestppd.c:345
+#: systemv/cupstestppd.c:462
+#: systemv/cupstestppd.c:477
+#: systemv/cupstestppd.c:498
+#: systemv/cupstestppd.c:513
+#: systemv/cupstestppd.c:543
+#: systemv/cupstestppd.c:563
+#: systemv/cupstestppd.c:586
+#: systemv/cupstestppd.c:604
+#: systemv/cupstestppd.c:630
+#: systemv/cupstestppd.c:648
+#: systemv/cupstestppd.c:668
+#: systemv/cupstestppd.c:688
+#: systemv/cupstestppd.c:706
+#: systemv/cupstestppd.c:722
+#: systemv/cupstestppd.c:740
+#: systemv/cupstestppd.c:761
+#: systemv/cupstestppd.c:780
+#: systemv/cupstestppd.c:800
+#: systemv/cupstestppd.c:820
+#: systemv/cupstestppd.c:840
+#: systemv/cupstestppd.c:860
+#: systemv/cupstestppd.c:878
+#: systemv/cupstestppd.c:895
+#: systemv/cupstestppd.c:917
+#: systemv/cupstestppd.c:935
+#: systemv/cupstestppd.c:952
+#: systemv/cupstestppd.c:970
+#: systemv/cupstestppd.c:986
+#: systemv/cupstestppd.c:1006
+#: systemv/cupstestppd.c:1037
+#: systemv/cupstestppd.c:1059
+#: systemv/cupstestppd.c:1110
+#: systemv/cupstestppd.c:1129
+#: systemv/cupstestppd.c:1173
+#: systemv/cupstestppd.c:1187
+#: systemv/cupstestppd.c:1219
+#: systemv/cupstestppd.c:1246
+#: systemv/cupstestppd.c:1764
+#: systemv/cupstestppd.c:1783
+#: systemv/cupstestppd.c:1801
+#: systemv/cupstestppd.c:1853
+#: systemv/cupstestppd.c:1869
+#: systemv/cupstestppd.c:1906
+#: systemv/cupstestppd.c:1924
+#: systemv/cupstestppd.c:1960
+#: systemv/cupstestppd.c:1974
+#: systemv/cupstestppd.c:2001
+#: systemv/cupstestppd.c:2015
+#: systemv/cupstestppd.c:2061
+#: systemv/cupstestppd.c:2083
+#: systemv/cupstestppd.c:2106
+#: systemv/cupstestppd.c:2123
+#: systemv/cupstestppd.c:2165
+#: systemv/cupstestppd.c:2208
+#: systemv/cupstestppd.c:2255
+#: systemv/cupstestppd.c:2279
+#: systemv/cupstestppd.c:2331
+#: systemv/cupstestppd.c:2361
+#: systemv/cupstestppd.c:2375
+#: systemv/cupstestppd.c:2401
+#: systemv/cupstestppd.c:2417
+#: systemv/cupstestppd.c:2447
+#: systemv/cupstestppd.c:2461
+#: systemv/cupstestppd.c:2488
+#: systemv/cupstestppd.c:2505
+#: systemv/cupstestppd.c:2519
+#: systemv/cupstestppd.c:2543
+#: systemv/cupstestppd.c:2560
+#: systemv/cupstestppd.c:2574
+#: systemv/cupstestppd.c:2598
+#: systemv/cupstestppd.c:2615
+#: systemv/cupstestppd.c:2629
+#: systemv/cupstestppd.c:2653
+#: systemv/cupstestppd.c:2670
+#: systemv/cupstestppd.c:2684
+#: systemv/cupstestppd.c:2708
+#: systemv/cupstestppd.c:2722
+#: systemv/cupstestppd.c:2737
+#: systemv/cupstestppd.c:2754
+#: systemv/cupstestppd.c:2810
+#: systemv/cupstestppd.c:2845
+#: systemv/cupstestppd.c:2859
+#: systemv/cupstestppd.c:2887
+#: systemv/cupstestppd.c:2952
+#: systemv/cupstestppd.c:2967
+#: systemv/cupstestppd.c:3005
+#: systemv/cupstestppd.c:3025
+#: systemv/cupstestppd.c:3039
+#: systemv/cupstestppd.c:3206
+#: systemv/cupstestppd.c:3242
+#: systemv/cupstestppd.c:3256
+#: systemv/cupstestppd.c:3302
+#: systemv/cupstestppd.c:3334
+#: systemv/cupstestppd.c:3351
+#: systemv/cupstestppd.c:3374
+#: systemv/cupstestppd.c:3390
+#: systemv/cupstestppd.c:3428
+#: systemv/cupstestppd.c:3569
+#: systemv/cupstestppd.c:3591
+#: systemv/cupstestppd.c:3699
+msgid " FAIL"
+msgstr " FALLO"
+
+#: systemv/cupstestppd.c:1270
+msgid " PASS"
+msgstr " PASA"
+
+#: berkeley/lpq.c:560
+#, c-format
+msgid "%-6s %-10.10s %-4d %-10d %-27.27s %.0f bytes"
+msgstr "%-6s %-10.10s %-4d %-10d %-27.27s %.0f bytes"
+
+#: berkeley/lpq.c:565
+#, c-format
+msgid "%-7s %-7.7s %-7d %-31.31s %.0f bytes"
+msgstr "%-7s %-7.7s %-7d %-31.31s %.0f bytes"
+
+#: filter/bannertops.c:784
#, c-format
msgid "%.0f x %.0f millimeters"
msgstr "%.0f x %.0f milÃmetros"
+#: filter/bannertops.c:805
#, c-format
msgid "%.0f x %.0f to %.0f x %.0f millimeters"
msgstr "%.0f x %.0f a %.0f x %.0f milÃmetros"
+#: filter/bannertops.c:775
#, c-format
msgid "%.2f x %.2f inches"
msgstr "%.2f x %.2f pulgadas"
+#: filter/bannertops.c:794
#, c-format
msgid "%.2f x %.2f to %.2f x %.2f inches"
msgstr "%.2f x %.2f a %.2f x %.2f pulgadas"
+#: systemv/lpstat.c:747
#, c-format
-msgid "%s accepting requests since %s\n"
-msgstr "%s aceptando peticiones desde %s\n"
+msgid "%s accepting requests since %s"
+msgstr "%s aceptando peticiones desde %s"
+#: scheduler/ipp.c:11187
#, c-format
msgid "%s cannot be changed."
msgstr "%s no puede ser cambiado."
+#: berkeley/lpc.c:189
#, c-format
-msgid "%s is not implemented by the CUPS version of lpc.\n"
-msgstr "%s no está implementado en la versión de CUPS de lpc.\n"
-
-#, c-format
-msgid "%s is not ready\n"
-msgstr "%s no está preparada\n"
-
-#, c-format
-msgid "%s is ready\n"
-msgstr "%s está preparada\n"
-
-#, c-format
-msgid "%s is ready and printing\n"
-msgstr "%s está preparada e imprimiendo\n"
-
-#, c-format
-msgid ""
-"%s not accepting requests since %s -\n"
-"\t%s\n"
-msgstr ""
-"%s no acepta peticiones desde %s -\n"
-"\t%s\n"
+msgid "%s is not implemented by the CUPS version of lpc."
+msgstr "%s no está implementado en la versión de CUPS de lpc."
+#: berkeley/lpq.c:651
#, c-format
-msgid "%s not supported"
-msgstr ""
+msgid "%s is not ready"
+msgstr "%s no está preparada"
+#: berkeley/lpq.c:644
#, c-format
-msgid "%s/%s accepting requests since %s\n"
-msgstr "%s/%s aceptando peticiones desde %s\n"
+msgid "%s is ready"
+msgstr "%s está preparada"
+#: berkeley/lpq.c:647
#, c-format
-msgid ""
-"%s/%s not accepting requests since %s -\n"
-"\t%s\n"
-msgstr ""
-"%s/%s no acepta peticiones desde %s -\n"
-"\t%s\n"
+msgid "%s is ready and printing"
+msgstr "%s está preparada e imprimiendo"
+#: driver/rastertoescpx.c:1775
+#: driver/rastertopclx.c:1800
+#: filter/rastertoepson.c:985
+#: filter/rastertohp.c:711
+#: filter/rastertolabel.c:1134
#, c-format
-msgid "%s: %-33.33s [job %d localhost]\n"
-msgstr "%s: %-33.33s [trabajo %d localhost]\n"
+msgid "%s job-id user title copies options [file]"
+msgstr "%s job-id usuario tÃtulo copias opciones [archivo]"
+#: systemv/lpstat.c:751
#, c-format
-msgid "%s: %s failed: %s\n"
-msgstr "%s: %s ha fallado: %s\n"
+msgid "%s not accepting requests since %s -"
+msgstr "%s no acepta peticiones desde %s -"
+#: scheduler/ipp.c:718
#, c-format
-msgid "%s: Don't know what to do\n"
-msgstr ""
+msgid "%s not supported."
+msgstr "No se admite el uso de %s."
+#: systemv/lpstat.c:762
#, c-format
-msgid ""
-"%s: Error - %s environment variable names non-existent destination \"%s\"\n"
-msgstr ""
+msgid "%s/%s accepting requests since %s"
+msgstr "%s/%s aceptando peticiones desde %s"
+#: systemv/lpstat.c:767
#, c-format
-msgid "%s: Error - bad job ID\n"
-msgstr ""
+msgid "%s/%s not accepting requests since %s -"
+msgstr "%s/%s no acepta peticiones desde %s -"
+#: berkeley/lpq.c:552
#, c-format
-msgid "%s: Error - cannot print files and alter jobs simultaneously\n"
-msgstr ""
+msgid "%s: %-33.33s [job %d localhost]"
+msgstr "%s: %-33.33s [trabajo %d localhost]"
+#. TRANSLATORS: Message is "subject: error"
+#: cups/langprintf.c:86
+#: scheduler/cupsfilter.c:722
+#: systemv/lpadmin.c:805
+#: systemv/lpadmin.c:856
+#: systemv/lpadmin.c:906
+#: systemv/lpadmin.c:962
+#: systemv/lpadmin.c:1060
+#: systemv/lpadmin.c:1113
+#: systemv/lpadmin.c:1170
+#: systemv/lpadmin.c:1481
#, c-format
-msgid "%s: Error - cannot print from stdin if files or a job ID are provided\n"
-msgstr ""
+msgid "%s: %s"
+msgstr "%s: %s"
+#: systemv/cancel.c:294
+#: systemv/cancel.c:357
#, c-format
-msgid "%s: Error - expected character set after '-S' option\n"
-msgstr ""
+msgid "%s: %s failed: %s"
+msgstr "%s: %s ha fallado: %s"
+#: systemv/cupsaccept.c:68
#, c-format
-msgid "%s: Error - expected content type after '-T' option\n"
-msgstr ""
+msgid "%s: Don't know what to do."
+msgstr "%s: No sé que hay que hacer."
+#: berkeley/lpq.c:236
+#: berkeley/lpr.c:344
+#: systemv/lp.c:584
#, c-format
-msgid "%s: Error - expected copies after '-n' option\n"
-msgstr ""
+msgid "%s: Error - %s environment variable names non-existent destination \"%s\"."
+msgstr "%s: Error - %s nombres de variables de entorno no existen en destino \"%s\"."
+#: systemv/lp.c:231
#, c-format
-msgid "%s: Error - expected copy count after '-#' option\n"
-msgstr ""
+msgid "%s: Error - bad job ID."
+msgstr "%s: Error - ID de trabajo incorrecta."
+#: systemv/lp.c:219
#, c-format
-msgid "%s: Error - expected destination after '-P' option\n"
-msgstr ""
+msgid "%s: Error - cannot print files and alter jobs simultaneously."
+msgstr "%s: Error - no se pueden imprimir archivos y alterar trabajos al mismo tiempo."
+#: systemv/lp.c:505
#, c-format
-msgid "%s: Error - expected destination after '-b' option\n"
-msgstr ""
+msgid "%s: Error - cannot print from stdin if files or a job ID are provided."
+msgstr "%s: Error - no se puede imprimir desde stdin si se proporcionan archivos o una ID de trabajo."
+#: systemv/lp.c:461
#, c-format
-msgid "%s: Error - expected destination after '-d' option\n"
-msgstr ""
+msgid "%s: Error - expected character set after \"-S\" option."
+msgstr "%s: Error - se esperaba un juego de caracteres tras la opción \"-S\"."
+#: systemv/lp.c:480
#, c-format
-msgid "%s: Error - expected form after '-f' option\n"
-msgstr ""
+msgid "%s: Error - expected content type after \"-T\" option."
+msgstr "%s: Error - se esperaba un tipo de contenido tras la opción \"-T\"."
+#: berkeley/lpr.c:240
#, c-format
-msgid "%s: Error - expected hold name after '-H' option\n"
-msgstr ""
+msgid "%s: Error - expected copies after \"-#\" option."
+msgstr "%s: Error - se esperaba número de copias tras la opción \"-#\"."
+#: systemv/lp.c:264
#, c-format
-msgid "%s: Error - expected hostname after '-H' option\n"
-msgstr ""
+msgid "%s: Error - expected copies after \"-n\" option."
+msgstr "%s: Error - se esperaba número de copias tras la opción \"-n\"."
+#: berkeley/lpr.c:209
#, c-format
-msgid "%s: Error - expected hostname after '-h' option\n"
-msgstr ""
+msgid "%s: Error - expected destination after \"-P\" option."
+msgstr "%s: Error - se esperaba un destino tras la opción \"-P\"."
+#: systemv/lpstat.c:231
#, c-format
-msgid "%s: Error - expected mode list after '-y' option\n"
-msgstr ""
+msgid "%s: Error - expected destination after \"-b\" option."
+msgstr "%s: Error - se esperaba un destino tras la opción \"-b\"."
+#: systemv/lp.c:138
#, c-format
-msgid "%s: Error - expected name after '-%c' option\n"
-msgstr ""
+msgid "%s: Error - expected destination after \"-d\" option."
+msgstr "%s: Error - se esperaba un destino tras la opción \"-d\"."
+#: systemv/lp.c:168
#, c-format
-msgid "%s: Error - expected option string after '-o' option\n"
-msgstr ""
+msgid "%s: Error - expected form after \"-f\" option."
+msgstr "%s: Error - se esperaba un formulario tras la opción \"-f\"."
+#: systemv/lp.c:391
#, c-format
-msgid "%s: Error - expected page list after '-P' option\n"
-msgstr ""
+msgid "%s: Error - expected hold name after \"-H\" option."
+msgstr "%s: Error - se esperaba un nombre de retención tras la opción \"-H\"."
+#: berkeley/lpr.c:103
#, c-format
-msgid "%s: Error - expected priority after '-%c' option\n"
-msgstr ""
+msgid "%s: Error - expected hostname after \"-H\" option."
+msgstr "%s: Error - se esperaba un nombre de ordenador tras la opción \"-H\"."
+#: berkeley/lpq.c:180
+#: berkeley/lprm.c:123
+#: systemv/cancel.c:124
+#: systemv/cupsaccept.c:123
+#: systemv/lp.c:189
+#: systemv/lpstat.c:291
#, c-format
-msgid "%s: Error - expected reason text after '-r' option\n"
-msgstr ""
+msgid "%s: Error - expected hostname after \"-h\" option."
+msgstr "%s: Error - se esperaba un nombre de ordenador tras la opción \"-h\"."
+#: systemv/lp.c:371
#, c-format
-msgid "%s: Error - expected title after '-t' option\n"
-msgstr ""
+msgid "%s: Error - expected mode list after \"-y\" option."
+msgstr "%s: Error - se esperaba una lista de modos tras la opción \"-y\"."
+#: berkeley/lpr.c:263
#, c-format
-msgid "%s: Error - expected username after '-U' option\n"
-msgstr ""
+msgid "%s: Error - expected name after \"-%c\" option."
+msgstr "%s: Error - se esperaba un nombre tras la opción \"%c\"."
+#: berkeley/lpr.c:153
+#: systemv/lp.c:288
#, c-format
-msgid "%s: Error - expected username after '-U' option!n"
-msgstr ""
+msgid "%s: Error - expected option=value after \"-o\" option."
+msgstr "%s: Error - se esperaba opción=valor tras la opción \"-o\"."
+#: systemv/lp.c:441
#, c-format
-msgid "%s: Error - expected username after '-u' option\n"
-msgstr ""
+msgid "%s: Error - expected page list after \"-P\" option."
+msgstr "%s: Error - se esperaba una lista de páginas tras la opción \"-P\"."
+#: systemv/lp.c:308
#, c-format
-msgid "%s: Error - expected value after '-%c' option\n"
-msgstr ""
+msgid "%s: Error - expected priority after \"-%c\" option."
+msgstr "%s: Error - se esperaba un valor de prioridad tras la opción \"-%c\"."
+#: systemv/cupsaccept.c:141
#, c-format
-msgid ""
-"%s: Error - need \"completed\", \"not-completed\", or \"all\" after '-W' "
-"option\n"
-msgstr ""
+msgid "%s: Error - expected reason text after \"-r\" option."
+msgstr "%s: Error - se esperaba un texto con una razón tras la opción \"-r\"."
+#: systemv/lp.c:354
#, c-format
-msgid "%s: Error - no default destination available.\n"
-msgstr "%s: Error - destino predeterminado no disponible.\n"
+msgid "%s: Error - expected title after \"-t\" option."
+msgstr "%s: Error - se esperaba un tÃtulo tras la opción \"-t\"."
+#: berkeley/lpq.c:111
+#: berkeley/lpr.c:84
+#: berkeley/lprm.c:104
+#: systemv/cancel.c:94
+#: systemv/cupsaccept.c:101
+#: systemv/lp.c:116
+#: systemv/lpadmin.c:438
+#: systemv/lpstat.c:137
#, c-format
-msgid "%s: Error - priority must be between 1 and 100.\n"
-msgstr "%s: Error - la prioridad debe estar entre 1 y 100.\n"
+msgid "%s: Error - expected username after \"-U\" option."
+msgstr "%s: Error - se esperaba un nombre de usuario tras la opción \"-U\"."
+#: systemv/cancel.c:145
#, c-format
-msgid "%s: Error - scheduler not responding\n"
-msgstr ""
+msgid "%s: Error - expected username after \"-u\" option."
+msgstr "%s: Error - se esperaba un nombre de usuario tras la opción \"-u\"."
+#: berkeley/lpr.c:125
#, c-format
-msgid "%s: Error - too many files - \"%s\"\n"
-msgstr "%s: Error - demasiados archivos - \"%s\"\n"
+msgid "%s: Error - expected value after \"-%c\" option."
+msgstr "%s: Error - se esperaba un valor tras la opción \"%c\"."
+#: systemv/lpstat.c:157
+#: systemv/lpstat.c:171
#, c-format
-msgid "%s: Error - unable to access \"%s\" - %s\n"
-msgstr "%s: Error - no se ha podido acceder a \"%s\" - %s\n"
+msgid "%s: Error - need \"completed\", \"not-completed\", or \"all\" after \"-W\" option."
+msgstr "%s: Error - se necesita \"completed\", \"not completed\", o \"all\" tras la opción \"-W\"."
+#: berkeley/lpq.c:241
+#: berkeley/lpr.c:349
+#: systemv/lp.c:589
#, c-format
-msgid "%s: Error - unable to queue from stdin - %s\n"
-msgstr "%s: Error - no se ha podido poner en cola desde stdin - %s\n"
+msgid "%s: Error - no default destination available."
+msgstr "%s: Error - destino predeterminado no disponible."
+#: systemv/lp.c:330
#, c-format
-msgid "%s: Error - unknown destination \"%s\"\n"
-msgstr ""
+msgid "%s: Error - priority must be between 1 and 100."
+msgstr "%s: Error - la prioridad debe estar entre 1 y 100."
+#: berkeley/lpr.c:352
+#: systemv/lp.c:592
#, c-format
-msgid "%s: Error - unknown destination \"%s/%s\"\n"
-msgstr ""
+msgid "%s: Error - scheduler not responding."
+msgstr "%s: Error - el programa planificador de tareas no responde."
+#: berkeley/lpr.c:305
+#: systemv/lp.c:537
#, c-format
-msgid "%s: Error - unknown option '%c'\n"
-msgstr ""
+msgid "%s: Error - too many files - \"%s\"."
+msgstr "%s: Error - demasiados archivos - \"%s\"."
+#: berkeley/lpr.c:287
+#: systemv/lp.c:520
#, c-format
-msgid "%s: Error - unknown option '%s'\n"
-msgstr ""
+msgid "%s: Error - unable to access \"%s\" - %s"
+msgstr "%s: Error - no se ha podido acceder a \"%s\" - %s"
+#: berkeley/lpr.c:396
+#: systemv/lp.c:624
#, c-format
-msgid "%s: Expected job ID after '-i' option\n"
-msgstr ""
+msgid "%s: Error - unable to queue from stdin - %s."
+msgstr "%s: Error - no se ha podido poner en cola desde stdin - %s."
+#: berkeley/lprm.c:87
+#: berkeley/lprm.c:172
+#: systemv/cancel.c:214
#, c-format
-msgid "%s: Filter \"%s\" not available: %s\n"
-msgstr "%s: Filtro \"%s\" no disponible: %s\n"
+msgid "%s: Error - unknown destination \"%s\"."
+msgstr "%s: Error - destino \"%s\" desconocido."
+#: berkeley/lpq.c:150
#, c-format
-msgid "%s: Invalid destination name in list \"%s\"\n"
-msgstr ""
+msgid "%s: Error - unknown destination \"%s/%s\"."
+msgstr "%s: Error - destino \"%s/%s\" desconocido."
+#: berkeley/lpr.c:274
+#: berkeley/lprm.c:139
+#: systemv/cancel.c:156
+#: systemv/cupsaccept.c:164
+#: systemv/lp.c:496
+#: systemv/lpstat.c:452
#, c-format
-msgid "%s: Invalid filter string \"%s\"\n"
-msgstr "%s: Cadena de filtro \"%s\" inválida\n"
+msgid "%s: Error - unknown option \"%c\"."
+msgstr "%s: Error - opción \"%c\" desconocida."
+#: systemv/cupsaccept.c:157
#, c-format
-msgid "%s: Need job ID ('-i jobid') before '-H restart'\n"
-msgstr ""
+msgid "%s: Error - unknown option \"%s\"."
+msgstr "%s: Error: opción \"%s\" desconocida."
+#: systemv/lp.c:208
#, c-format
-msgid "%s: No filter to convert from %s/%s to %s/%s\n"
-msgstr ""
+msgid "%s: Expected job ID after \"-i\" option."
+msgstr "%s : Se esperaba una ID de trabajo tras la opción \"-i\"."
+#: systemv/lpstat.c:504
+#: systemv/lpstat.c:543
#, c-format
-msgid "%s: Operation failed: %s\n"
-msgstr "%s: La operación ha fallado: %s\n"
+msgid "%s: Invalid destination name in list \"%s\"."
+msgstr "%s: Nombre de destino no válido en la lista \"%s\"."
+#: scheduler/cupsfilter.c:575
#, c-format
-msgid "%s: Sorry, no encryption support compiled in\n"
-msgstr ""
+msgid "%s: Invalid filter string \"%s\"."
+msgstr "%s: Cadena de filtro \"%s\" no válida."
+#: systemv/lp.c:418
#, c-format
-msgid "%s: Unable to connect to server\n"
-msgstr "%s: No se ha podido conectar al servidor\n"
+msgid "%s: Need job ID (\"-i jobid\") before \"-H restart\"."
+msgstr "%s: Se necesita un ID de trabajo (\"-i id_trabajo\") antes de \"-H restart\"."
+#: scheduler/cupsfilter.c:466
#, c-format
-msgid "%s: Unable to contact server\n"
-msgstr ""
+msgid "%s: No filter to convert from %s/%s to %s/%s."
+msgstr "%s: No hay ningún filtro para convertir de %s/%s a %s/%s."
+#: systemv/cupsaccept.c:198
#, c-format
-msgid "%s: Unable to determine MIME type of \"%s\"\n"
-msgstr ""
+msgid "%s: Operation failed: %s"
+msgstr "%s: La operación ha fallado: %s"
+#: berkeley/lpq.c:97
+#: berkeley/lpr.c:70
+#: berkeley/lprm.c:67
+#: systemv/cancel.c:81
+#: systemv/cupsaccept.c:88
+#: systemv/cupsaddsmb.c:86
+#: systemv/lp.c:102
+#: systemv/lpadmin.c:239
+#: systemv/lpinfo.c:88
+#: systemv/lpmove.c:73
+#: systemv/lpstat.c:102
+#: test/ipptool.c:278
+#: test/ipptool.c:295
#, c-format
-msgid "%s: Unable to open %s: %s\n"
-msgstr "%s: No se pudo abrir %s: %s\n"
+msgid "%s: Sorry, no encryption support."
+msgstr "%s: Lo siento, no está compilado con la opción de cifrado."
+#: berkeley/lpq.c:295
+#: scheduler/cupsfilter.c:1229
+#: systemv/cancel.c:237
+#: systemv/cupsaddsmb.c:144
+#: systemv/cupsaddsmb.c:171
#, c-format
-msgid "%s: Unable to open PPD file: %s on line %d\n"
-msgstr "%s: No se pudo abrir archivo PPD: %s en lÃnea %d\n"
+msgid "%s: Unable to connect to server."
+msgstr "%s: No se ha podido conectar al servidor."
+#: systemv/cancel.c:317
#, c-format
-msgid "%s: Unable to open PPD file: %s on line %d.\n"
-msgstr "%s: No se ha podido abrir el archivo PPD: %s en la lÃnea %d.\n"
+msgid "%s: Unable to contact server."
+msgstr "%s: No se ha podido contactar con el servidor."
+#: scheduler/cupsfilter.c:432
#, c-format
-msgid "%s: Unable to read MIME database from \"%s\" or \"%s\"\n"
-msgstr ""
+msgid "%s: Unable to determine MIME type of \"%s\"."
+msgstr "%s: No se ha podido determinar el tipo MIME de \"%s\"."
+#: ppdc/ppdmerge.cxx:96
#, c-format
-msgid "%s: Unknown destination \"%s\"\n"
-msgstr ""
+msgid "%s: Unable to open %s: %s"
+msgstr "%s: No se pudo abrir %s: %s"
+#: scheduler/cupsfilter.c:670
+#: ppdc/ppdmerge.cxx:112
#, c-format
-msgid "%s: Unknown destination MIME type %s/%s\n"
-msgstr ""
+msgid "%s: Unable to open PPD file: %s on line %d."
+msgstr "%s: No se ha podido abrir el archivo PPD: %s en la lÃnea %d."
+#: scheduler/cupsfilter.c:397
#, c-format
-msgid "%s: Unknown option '%c'\n"
-msgstr ""
+msgid "%s: Unable to read MIME database from \"%s\" or \"%s\"."
+msgstr "%s: No se pudo leer base de datos MIME desde \"%s\" o \"%s\"."
+#: berkeley/lpq.c:153
+#: systemv/lpstat.c:558
#, c-format
-msgid "%s: Unknown source MIME type %s/%s\n"
-msgstr ""
+msgid "%s: Unknown destination \"%s\"."
+msgstr "%s: Destino \"%s\" desconocido."
+#: scheduler/cupsfilter.c:443
#, c-format
-msgid ""
-"%s: Warning - '%c' format modifier not supported - output may not be "
-"correct\n"
-msgstr ""
+msgid "%s: Unknown destination MIME type %s/%s."
+msgstr "%s: Tipo MIME de destino %s/%s desconocido."
+#: scheduler/cupsfilter.c:1435
#, c-format
-msgid "%s: Warning - character set option ignored\n"
-msgstr ""
+msgid "%s: Unknown option \"%c\"."
+msgstr "%s: Opción \"%c\" desconocida."
+#: scheduler/cupsfilter.c:424
#, c-format
-msgid "%s: Warning - content type option ignored\n"
-msgstr ""
+msgid "%s: Unknown source MIME type %s/%s."
+msgstr "%s: Tipo MIME de origen %s/%s desconocido."
+#: berkeley/lpr.c:139
#, c-format
-msgid "%s: Warning - form option ignored\n"
-msgstr ""
+msgid "%s: Warning - \"%c\" format modifier not supported - output may not be correct."
+msgstr "%s: Advertencia - no se admite el uso del modificador de formato \"%c\" - la salida puede no ser correcta."
+#: systemv/lp.c:468
#, c-format
-msgid "%s: Warning - mode option ignored\n"
-msgstr ""
+msgid "%s: Warning - character set option ignored."
+msgstr "%s: Advertencia - opción de juego de caracteres no tenida en cuenta."
+#: systemv/lp.c:487
#, c-format
-msgid ""
-"%s: error - %s environment variable names non-existent destination \"%s\"\n"
-msgstr ""
+msgid "%s: Warning - content type option ignored."
+msgstr "%s: Advertencia - opción de tipo de contenido no tenida en cuenta."
+#: systemv/lp.c:175
#, c-format
-msgid "%s: error - expected option=value after '-o' option\n"
-msgstr ""
+msgid "%s: Warning - form option ignored."
+msgstr "%s: Advertencia - opción de formulario no tenida en cuenta."
+#: systemv/lp.c:378
#, c-format
-msgid "%s: error - no default destination available.\n"
-msgstr "%s: error - destino predeterminado no disponible.\n"
+msgid "%s: Warning - mode option ignored."
+msgstr "%s: Advertencia - opción de modo no tenida en cuenta."
+#: ppdc/sample.c:319
msgid "-1"
msgstr "-1"
+#: ppdc/sample.c:310
msgid "-10"
msgstr "-10"
+#: ppdc/sample.c:402
msgid "-100"
msgstr "-100"
+#: ppdc/sample.c:401
msgid "-105"
msgstr "-105"
+#: ppdc/sample.c:309
msgid "-11"
msgstr "-11"
+#: ppdc/sample.c:400
msgid "-110"
msgstr "-110"
+#: ppdc/sample.c:399
msgid "-115"
msgstr "-115"
+#: ppdc/sample.c:308
msgid "-12"
msgstr "-12"
+#: ppdc/sample.c:398
msgid "-120"
msgstr "-120"
+#: ppdc/sample.c:307
msgid "-13"
msgstr "-13"
+#: ppdc/sample.c:306
msgid "-14"
msgstr "-14"
+#: ppdc/sample.c:305
msgid "-15"
msgstr "-15"
+#: ppdc/sample.c:318
msgid "-2"
msgstr "-2"
+#: ppdc/sample.c:418
msgid "-20"
msgstr "-20"
+#: ppdc/sample.c:417
msgid "-25"
msgstr "-25"
+#: ppdc/sample.c:317
msgid "-3"
msgstr "-3"
+#: ppdc/sample.c:416
msgid "-30"
msgstr "-30"
+#: ppdc/sample.c:415
msgid "-35"
msgstr "-35"
+#: ppdc/sample.c:316
msgid "-4"
msgstr "-4"
+#: ppdc/sample.c:414
msgid "-40"
msgstr "-40"
+#: ppdc/sample.c:413
msgid "-45"
msgstr "-45"
+#: ppdc/sample.c:315
msgid "-5"
msgstr "-5"
+#: ppdc/sample.c:412
msgid "-50"
msgstr "-50"
+#: ppdc/sample.c:411
msgid "-55"
msgstr "-55"
+#: ppdc/sample.c:314
msgid "-6"
msgstr "-6"
+#: ppdc/sample.c:410
msgid "-60"
msgstr "-60"
+#: ppdc/sample.c:409
msgid "-65"
msgstr "-65"
+#: ppdc/sample.c:313
msgid "-7"
msgstr "-7"
+#: ppdc/sample.c:408
msgid "-70"
msgstr "-70"
+#: ppdc/sample.c:407
msgid "-75"
msgstr "-75"
+#: ppdc/sample.c:312
msgid "-8"
msgstr "-8"
+#: ppdc/sample.c:406
msgid "-80"
msgstr "-80"
+#: ppdc/sample.c:405
msgid "-85"
msgstr "-85"
+#: ppdc/sample.c:311
msgid "-9"
msgstr "-9"
+#: ppdc/sample.c:404
msgid "-90"
msgstr "-90"
+#: ppdc/sample.c:403
msgid "-95"
msgstr "-95"
+#: ppdc/sample.c:320
msgid "0"
msgstr "0"
+#: ppdc/sample.c:321
msgid "1"
msgstr "1"
+#: ppdc/sample.c:393
msgid "1 inch/sec."
msgstr "1 pulg./seg"
+#: ppdc/sample.c:181
msgid "1.25x0.25\""
msgstr "1.25x0.25 pulg."
+#: ppdc/sample.c:182
msgid "1.25x2.25\""
msgstr "1.25x2.25 pulg."
+#: ppdc/sample.c:441
msgid "1.5 inch/sec."
msgstr "1.5 pulg./seg"
+#: ppdc/sample.c:183
msgid "1.50x0.25\""
msgstr "1.50x0.25 pulg."
+#: ppdc/sample.c:184
msgid "1.50x0.50\""
msgstr "1.50x0.50 pulg."
+#: ppdc/sample.c:185
msgid "1.50x1.00\""
msgstr "1.50x1.00 pulg."
+#: ppdc/sample.c:186
msgid "1.50x2.00\""
msgstr "1.50x2.00 pulg."
+#: ppdc/sample.c:330
msgid "10"
msgstr "10"
+#: ppdc/sample.c:452
msgid "10 inches/sec."
msgstr "10 pulg./seg"
-msgid "10 x 11\""
-msgstr "10 x 11 pulg."
+#: ppdc/sample.c:6
+msgid "10 x 11"
+msgstr "10 x 11"
-msgid "10 x 13\""
-msgstr "10 x 13 pulg."
+#: ppdc/sample.c:7
+msgid "10 x 13"
+msgstr "10 x 13"
-msgid "10 x 14\""
-msgstr "10 x 14 pulg."
+#: ppdc/sample.c:8
+msgid "10 x 14"
+msgstr "10 x 14"
+#: ppdc/sample.c:432
msgid "100"
msgstr "100"
+#: ppdc/sample.c:343
msgid "100 mm/sec."
msgstr "100 mm/seg"
+#: ppdc/sample.c:433
msgid "105"
msgstr "105"
+#: ppdc/sample.c:331
msgid "11"
msgstr "11"
+#: ppdc/sample.c:453
msgid "11 inches/sec."
msgstr "11 pulg./seg"
+#: ppdc/sample.c:434
msgid "110"
msgstr "110"
+#: ppdc/sample.c:435
msgid "115"
msgstr "115"
+#: ppdc/sample.c:332
msgid "12"
msgstr "12"
+#: ppdc/sample.c:454
msgid "12 inches/sec."
msgstr "12 pulg./seg"
-msgid "12 x 11\""
-msgstr "12 x 11 pulg."
+#: ppdc/sample.c:9
+msgid "12 x 11"
+msgstr "12 x 11"
+#: ppdc/sample.c:436
msgid "120"
msgstr "120"
+#: ppdc/sample.c:344
msgid "120 mm/sec."
msgstr "120 mm/seg"
+#: ppdc/sample.c:252
msgid "120x60dpi"
msgstr "120x60ppp"
+#: ppdc/sample.c:258
msgid "120x72dpi"
msgstr "120x72ppp"
+#: ppdc/sample.c:333
msgid "13"
msgstr "13"
+#: ppdc/sample.c:241
msgid "136dpi"
msgstr "136ppp"
+#: ppdc/sample.c:334
msgid "14"
msgstr "14"
+#: ppdc/sample.c:335
msgid "15"
msgstr "15"
+#: ppdc/sample.c:337
msgid "15 mm/sec."
msgstr "15 mm/seg"
-msgid "15 x 11\""
-msgstr "15 x 11 pulg."
+#: ppdc/sample.c:10
+msgid "15 x 11"
+msgstr "15 x 11"
+#: ppdc/sample.c:345
msgid "150 mm/sec."
msgstr "150 mm/seg"
+#: ppdc/sample.c:292
msgid "150dpi"
msgstr "150ppp"
+#: ppdc/sample.c:377
msgid "16"
msgstr "16"
+#: ppdc/sample.c:378
msgid "17"
msgstr "17"
+#: ppdc/sample.c:379
msgid "18"
msgstr "18"
+#: ppdc/sample.c:253
msgid "180dpi"
msgstr "180ppp"
+#: ppdc/sample.c:380
msgid "19"
msgstr "19"
+#: ppdc/sample.c:322
msgid "2"
msgstr "2"
+#: ppdc/sample.c:394
msgid "2 inches/sec."
msgstr "2 pulg./seg"
+#: ppdc/sample.c:279
msgid "2-Sided Printing"
msgstr "Dúplex"
+#: ppdc/sample.c:187
msgid "2.00x0.37\""
msgstr "2.00x0.37 pulg."
+#: ppdc/sample.c:188
msgid "2.00x0.50\""
msgstr "2.00x0.50 pulg."
+#: ppdc/sample.c:189
msgid "2.00x1.00\""
msgstr "2.00x1.00 pulg."
+#: ppdc/sample.c:190
msgid "2.00x1.25\""
msgstr "2.00x1.25 pulg."
+#: ppdc/sample.c:191
msgid "2.00x2.00\""
msgstr "2.00x2.00 pulg."
+#: ppdc/sample.c:192
msgid "2.00x3.00\""
msgstr "2.00x3.00 pulg."
+#: ppdc/sample.c:193
msgid "2.00x4.00\""
msgstr "2.00x4.00 pulg."
+#: ppdc/sample.c:194
msgid "2.00x5.50\""
msgstr "2.00x5.50 pulg."
+#: ppdc/sample.c:195
msgid "2.25x0.50\""
msgstr "2.25x0.50 pulg."
+#: ppdc/sample.c:196
msgid "2.25x1.25\""
msgstr "2.25x1.25 pulg."
+#: ppdc/sample.c:197
msgid "2.25x4.00\""
msgstr "2.25x4.00 pulg."
+#: ppdc/sample.c:198
msgid "2.25x5.50\""
msgstr "2.25x5.50 pulg."
+#: ppdc/sample.c:199
msgid "2.38x5.50\""
msgstr "2.38x5.50 pulg."
+#: ppdc/sample.c:442
msgid "2.5 inches/sec."
msgstr "2.5 pulg./seg"
+#: ppdc/sample.c:200
msgid "2.50x1.00\""
msgstr "2.50x1.00 pulg."
+#: ppdc/sample.c:201
msgid "2.50x2.00\""
msgstr "2.50x2.00 pulg."
+#: ppdc/sample.c:202
msgid "2.75x1.25\""
msgstr "2.75x1.25 pulg."
+#: ppdc/sample.c:203
msgid "2.9 x 1\""
msgstr "2.9 x 1 pulg."
+#: ppdc/sample.c:381
msgid "20"
msgstr "20"
+#: ppdc/sample.c:338
msgid "20 mm/sec."
msgstr "20 mm/seg"
+#: ppdc/sample.c:346
msgid "200 mm/sec."
msgstr "200 mm/seg"
+#: ppdc/sample.c:242
msgid "203dpi"
msgstr "203ppp"
+#: ppdc/sample.c:382
msgid "21"
msgstr "21"
+#: ppdc/sample.c:383
msgid "22"
msgstr "22"
+#: ppdc/sample.c:384
msgid "23"
msgstr "23"
+#: ppdc/sample.c:385
msgid "24"
msgstr "24"
+#: ppdc/sample.c:250
msgid "24-Pin Series"
msgstr "24-Pin Series"
+#: ppdc/sample.c:259
msgid "240x72dpi"
msgstr "240x72ppp"
+#: ppdc/sample.c:386
msgid "25"
msgstr "25"
+#: ppdc/sample.c:347
msgid "250 mm/sec."
msgstr "250 mm/seg"
+#: ppdc/sample.c:387
msgid "26"
msgstr "26"
+#: ppdc/sample.c:388
msgid "27"
msgstr "27"
+#: ppdc/sample.c:389
msgid "28"
msgstr "28"
+#: ppdc/sample.c:390
msgid "29"
msgstr "29"
+#: ppdc/sample.c:323
msgid "3"
msgstr "3"
+#: ppdc/sample.c:395
msgid "3 inches/sec."
msgstr "3 pulg./seg"
+#: ppdc/sample.c:3
+msgid "3 x 5"
+msgstr "3 x 5"
+
+#: ppdc/sample.c:204
msgid "3.00x1.00\""
msgstr "3.00x1.00 pulg."
+#: ppdc/sample.c:205
msgid "3.00x1.25\""
msgstr "3.00x1.25 pulg."
+#: ppdc/sample.c:206
msgid "3.00x2.00\""
msgstr "3.00x2.00 pulg."
+#: ppdc/sample.c:207
msgid "3.00x3.00\""
msgstr "3.00x3.00 pulg."
+#: ppdc/sample.c:208
msgid "3.00x5.00\""
msgstr "3.00x5.00 pulg."
+#: ppdc/sample.c:209
msgid "3.25x2.00\""
msgstr "3.25x2.00 pulg."
+#: ppdc/sample.c:210
msgid "3.25x5.00\""
msgstr "3.25x5.00 pulg."
+#: ppdc/sample.c:211
msgid "3.25x5.50\""
msgstr "3.25x5.50 pulg."
+#: ppdc/sample.c:212
msgid "3.25x5.83\""
msgstr "3.25x5.83 pulg."
+#: ppdc/sample.c:213
msgid "3.25x7.83\""
msgstr "3.25x7.83 pulg."
+#: ppdc/sample.c:4
+msgid "3.5 x 5"
+msgstr "3.5 x 5"
+
+#: ppdc/sample.c:171
msgid "3.5\" Disk"
msgstr "Disco de 3.5 pulg."
+#: ppdc/sample.c:180
msgid "3.5\" Disk - 2 1/8 x 2 3/4\""
msgstr "Disco de 3.5 pulg. - 2 1/8 x 2 3/4 pulg."
+#: ppdc/sample.c:214
msgid "3.50x1.00\""
msgstr "3.50x1.00 pulg."
+#: ppdc/sample.c:391
msgid "30"
msgstr "30"
+#: ppdc/sample.c:339
msgid "30 mm/sec."
msgstr "30 mm/seg"
+#: ppdc/sample.c:348
msgid "300 mm/sec."
msgstr "300 mm/seg"
+#: ppdc/sample.c:243
msgid "300dpi"
msgstr "300ppp"
+#: ppdc/sample.c:419
msgid "35"
msgstr "35"
+#: ppdc/sample.c:255
msgid "360dpi"
msgstr "360ppp"
+#: ppdc/sample.c:254
msgid "360x180dpi"
msgstr "360x180ppp"
+#: ppdc/sample.c:324
msgid "4"
msgstr "4"
+#: ppdc/sample.c:396
msgid "4 inches/sec."
msgstr "4 pulg./seg"
+#: ppdc/sample.c:215
msgid "4.00x1.00\""
msgstr "4.00x1.00 pulg."
+#: ppdc/sample.c:223
msgid "4.00x13.00\""
msgstr "4.00x13.00 pulg."
+#: ppdc/sample.c:216
msgid "4.00x2.00\""
msgstr "4.00x2.00 pulg."
+#: ppdc/sample.c:217
msgid "4.00x2.50\""
msgstr "4.00x2.50 pulg."
+#: ppdc/sample.c:218
msgid "4.00x3.00\""
msgstr "4.00x3.00 pulg."
+#: ppdc/sample.c:219
msgid "4.00x4.00\""
msgstr "4.00x4.00 pulg."
+#: ppdc/sample.c:220
msgid "4.00x5.00\""
msgstr "4.00x5.00 pulg."
+#: ppdc/sample.c:221
msgid "4.00x6.00\""
msgstr "4.00x6.00 pulg."
+#: ppdc/sample.c:222
msgid "4.00x6.50\""
msgstr "4.00x6.50 pulg."
+#: ppdc/sample.c:420
msgid "40"
msgstr "40"
+#: ppdc/sample.c:340
msgid "40 mm/sec."
msgstr "40 mm/seg"
+#: ppdc/sample.c:421
msgid "45"
msgstr "45"
+#: ppdc/sample.c:325
msgid "5"
msgstr "5"
+#: ppdc/sample.c:446
msgid "5 inches/sec."
msgstr "5 pulg./seg"
+#: ppdc/sample.c:5
+msgid "5 x 7"
+msgstr "5 x 7"
+
+#: ppdc/sample.c:422
msgid "50"
msgstr "50"
+#: ppdc/sample.c:423
msgid "55"
msgstr "55"
+#: ppdc/sample.c:326
msgid "6"
msgstr "6"
+#: ppdc/sample.c:447
msgid "6 inches/sec."
msgstr "6 pulg./seg"
+#: ppdc/sample.c:224
msgid "6.00x1.00\""
msgstr "6.00x1.00 pulg."
+#: ppdc/sample.c:225
msgid "6.00x2.00\""
msgstr "6.00x2.00 pulg."
+#: ppdc/sample.c:226
msgid "6.00x3.00\""
msgstr "6.00x3.00 pulg."
+#: ppdc/sample.c:227
msgid "6.00x4.00\""
msgstr "6.00x4.00 pulg."
+#: ppdc/sample.c:228
msgid "6.00x5.00\""
msgstr "6.00x5.00 pulg."
+#: ppdc/sample.c:229
msgid "6.00x6.00\""
msgstr "6.00x6.00 pulg."
+#: ppdc/sample.c:230
msgid "6.00x6.50\""
msgstr "6.00x6.50 pulg."
+#: ppdc/sample.c:424
msgid "60"
msgstr "60"
+#: ppdc/sample.c:341
msgid "60 mm/sec."
msgstr "60 mm/seg"
+#: ppdc/sample.c:270
msgid "600dpi"
msgstr "600ppp"
+#: ppdc/sample.c:251
msgid "60dpi"
msgstr "60ppp"
-msgid "60x720dpi"
-msgstr "60x720ppp"
+#: ppdc/sample.c:257
+msgid "60x72dpi"
+msgstr "60x72ppp"
+#: ppdc/sample.c:425
msgid "65"
msgstr "65"
+#: ppdc/sample.c:327
msgid "7"
msgstr "7"
+#: ppdc/sample.c:449
msgid "7 inches/sec."
msgstr "7 pulg./seg"
-msgid "7 x 9\""
-msgstr "7 x 9 pulg."
+#: ppdc/sample.c:11
+msgid "7 x 9"
+msgstr "7 x 9"
+#: ppdc/sample.c:426
msgid "70"
msgstr "70"
+#: ppdc/sample.c:261
msgid "720dpi"
msgstr "720ppp"
+#: ppdc/sample.c:427
msgid "75"
msgstr "75"
+#: ppdc/sample.c:328
msgid "8"
msgstr "8"
+#: ppdc/sample.c:450
msgid "8 inches/sec."
msgstr "8 pulg./seg"
-msgid "8 x 10\""
-msgstr "8 x 10 pulg."
+#: ppdc/sample.c:12
+msgid "8 x 10"
+msgstr "8 x 10"
+#: ppdc/sample.c:231
msgid "8.00x1.00\""
msgstr "8.00x1.00 pulg."
+#: ppdc/sample.c:232
msgid "8.00x2.00\""
msgstr "8.00x2.00 pulg."
+#: ppdc/sample.c:233
msgid "8.00x3.00\""
msgstr "8.00x3.00 pulg."
+#: ppdc/sample.c:234
msgid "8.00x4.00\""
msgstr "8.00x4.00 pulg."
+#: ppdc/sample.c:235
msgid "8.00x5.00\""
msgstr "8.00x5.00 pulg."
+#: ppdc/sample.c:236
msgid "8.00x6.00\""
msgstr "8.00x6.00 pulg."
+#: ppdc/sample.c:237
msgid "8.00x6.50\""
msgstr "8.00x6.50 pulg."
+#: ppdc/sample.c:428
msgid "80"
msgstr "80"
+#: ppdc/sample.c:342
msgid "80 mm/sec."
msgstr "80 mm/seg"
+#: ppdc/sample.c:429
msgid "85"
msgstr "85"
+#: ppdc/sample.c:329
msgid "9"
msgstr "9"
+#: ppdc/sample.c:451
msgid "9 inches/sec."
msgstr "9 pulg./seg"
-msgid "9 x 11\""
-msgstr "9 x 11 pulg."
+#: ppdc/sample.c:13
+msgid "9 x 11"
+msgstr "9 x 11"
-msgid "9 x 12\""
-msgstr "9 x 12 pulg."
+#: ppdc/sample.c:14
+msgid "9 x 12"
+msgstr "9 x 12"
+#: ppdc/sample.c:256
msgid "9-Pin Series"
msgstr "9-Pin Series"
+#: ppdc/sample.c:430
msgid "90"
msgstr "90"
+#: ppdc/sample.c:431
msgid "95"
msgstr "95"
-msgid "?Invalid help command unknown\n"
-msgstr "?Comando de ayuda inválido desconocido\n"
+#: berkeley/lpc.c:213
+msgid "?Invalid help command unknown."
+msgstr "?Comando de ayuda no válido desconocido."
+#: cgi-bin/admin.c:2443
msgid "A Samba password is required to export printer drivers"
-msgstr ""
+msgstr "Se requiere una contraseña Samba para exportar los controladores de impresora"
+#: cgi-bin/admin.c:2439
msgid "A Samba username is required to export printer drivers"
-msgstr ""
+msgstr "Se requiere un nombre de usuario Samba para exportar los controladores de impresora"
+#: scheduler/ipp.c:2430
#, c-format
-msgid "A class named \"%s\" already exists"
-msgstr ""
+msgid "A class named \"%s\" already exists."
+msgstr "Ya existe una clase llamada \"%s\"."
+#: scheduler/ipp.c:1034
#, c-format
-msgid "A printer named \"%s\" already exists"
-msgstr ""
+msgid "A printer named \"%s\" already exists."
+msgstr "Ya existe una impresora llamada \"%s\"."
+#: ppdc/sample.c:15
msgid "A0"
msgstr "A0"
+#: ppdc/sample.c:16
+msgid "A0 Long Edge"
+msgstr "A0 lado largo"
+
+#: ppdc/sample.c:17
msgid "A1"
msgstr "A1"
+#: ppdc/sample.c:18
+msgid "A1 Long Edge"
+msgstr "A1 lado largo"
+
+#: ppdc/sample.c:37
msgid "A10"
msgstr "A10"
+#: ppdc/sample.c:19
msgid "A2"
msgstr "A2"
+#: ppdc/sample.c:20
+msgid "A2 Long Edge"
+msgstr "A2 lado largo"
+
+#: ppdc/sample.c:21
msgid "A3"
msgstr "A3"
-msgid "A3 (Oversize)"
-msgstr "A3 (extragrande)"
+#: ppdc/sample.c:22
+msgid "A3 Long Edge"
+msgstr "A3 lado largo"
+
+#: ppdc/sample.c:23
+msgid "A3 Oversize"
+msgstr "A3 Extragrande"
+
+#: ppdc/sample.c:24
+msgid "A3 Oversize Long Edge"
+msgstr "A3 Extragrande lado largo"
+#: ppdc/sample.c:25
msgid "A4"
msgstr "A4"
-msgid "A4 (Oversize)"
-msgstr "A4 (extragrande)"
+#: ppdc/sample.c:27
+msgid "A4 Long Edge"
+msgstr "A4 lado largo"
-msgid "A4 (Small)"
-msgstr "A4 (pequeño)"
+#: ppdc/sample.c:26
+msgid "A4 Oversize"
+msgstr "A4 Extragrande"
+#: ppdc/sample.c:28
+msgid "A4 Small"
+msgstr "A4 Pequeño"
+
+#: ppdc/sample.c:29
msgid "A5"
msgstr "A5"
-msgid "A5 (Oversize)"
-msgstr "A5 (extragrande)"
+#: ppdc/sample.c:31
+msgid "A5 Long Edge"
+msgstr "A5 lado largo"
+
+#: ppdc/sample.c:30
+msgid "A5 Oversize"
+msgstr "A5 Extragrande"
+#: ppdc/sample.c:32
msgid "A6"
msgstr "A6"
+#: ppdc/sample.c:33
+msgid "A6 Long Edge"
+msgstr "A6 lado largo"
+
+#: ppdc/sample.c:34
msgid "A7"
msgstr "A7"
+#: ppdc/sample.c:35
msgid "A8"
msgstr "A8"
+#: ppdc/sample.c:36
msgid "A9"
msgstr "A9"
+#: ppdc/sample.c:38
msgid "ANSI A"
msgstr "ANSI A"
+#: ppdc/sample.c:39
msgid "ANSI B"
msgstr "ANSI B"
+#: ppdc/sample.c:40
msgid "ANSI C"
msgstr "ANSI C"
+#: ppdc/sample.c:41
msgid "ANSI D"
msgstr "ANSI D"
+#: ppdc/sample.c:42
msgid "ANSI E"
msgstr "ANSI E"
-msgid "ARCH A"
-msgstr "ARCH A"
-
-msgid "ARCH B"
-msgstr "ARCH B"
-
+#: ppdc/sample.c:47
msgid "ARCH C"
msgstr "ARCH C"
+#: ppdc/sample.c:48
+msgid "ARCH C Long Edge"
+msgstr "ARCH C lado largo"
+
+#: ppdc/sample.c:49
msgid "ARCH D"
msgstr "ARCH D"
+#: ppdc/sample.c:50
+msgid "ARCH D Long Edge"
+msgstr "ARCH D lado largo"
+
+#: ppdc/sample.c:51
msgid "ARCH E"
msgstr "ARCH E"
+#: ppdc/sample.c:52
+msgid "ARCH E Long Edge"
+msgstr "ARCH E lado largo"
+
+#: cgi-bin/classes.c:169
+#: cgi-bin/printers.c:172
msgid "Accept Jobs"
msgstr "Aceptar trabajos"
+#: cups/http-support.c:1254
msgid "Accepted"
msgstr "Aceptado"
+#: cgi-bin/admin.c:570
msgid "Add Class"
msgstr "Añadir clase"
+#: cgi-bin/admin.c:883
msgid "Add Printer"
msgstr "Añadir impresora"
+#: cgi-bin/admin.c:444
+#: cgi-bin/admin.c:477
+#: cgi-bin/admin.c:525
+#: cgi-bin/admin.c:535
msgid "Add RSS Subscription"
msgstr "Añadir subscripción RSS"
+#: ppdc/sample.c:163
msgid "Address"
msgstr "Dirección"
+#: ppdc/sample.c:172
msgid "Address - 1 1/8 x 3 1/2\""
msgstr "Dirección - 1 1/8 x 3 1/2 pulg."
+#: cgi-bin/admin.c:210
+#: cgi-bin/admin.c:284
+#: cgi-bin/admin.c:2864
msgid "Administration"
msgstr "Administración"
+#: ppdc/sample.c:438
msgid "Always"
msgstr "Siempre"
+#: backend/socket.c:129
msgid "AppSocket/HP JetDirect"
msgstr "AppSocket/HP JetDirect"
+#: ppdc/sample.c:459
msgid "Applicator"
msgstr "Aplicador"
+#: scheduler/ipp.c:1159
#, c-format
-msgid "Attempt to set %s printer-state to bad value %d"
-msgstr ""
+msgid "Attempt to set %s printer-state to bad value %d."
+msgstr "Se ha intentado cambiar el valor printer-state de %s a un valor incorrecto %d."
+#: scheduler/ipp.c:352
#, c-format
-msgid "Attribute groups are out of order (%x < %x)"
-msgstr ""
+msgid "Attribute groups are out of order (%x < %x)."
+msgstr "Los grupos de atributos están desordenados (%x < %x)."
+#: ppdc/sample.c:126
msgid "B0"
msgstr "B0"
+#: ppdc/sample.c:127
msgid "B1"
msgstr "B1"
+#: ppdc/sample.c:137
msgid "B10"
msgstr "B10"
+#: ppdc/sample.c:128
msgid "B2"
msgstr "B2"
+#: ppdc/sample.c:129
msgid "B3"
msgstr "B3"
+#: ppdc/sample.c:130
msgid "B4"
msgstr "B4"
+#: ppdc/sample.c:131
msgid "B5"
msgstr "B5"
+#: ppdc/sample.c:132
+msgid "B5 Oversize"
+msgstr "A5 Extragrande"
+
+#: ppdc/sample.c:133
msgid "B6"
msgstr "B6"
+#: ppdc/sample.c:134
msgid "B7"
msgstr "B7"
+#: ppdc/sample.c:135
msgid "B8"
msgstr "B8"
+#: ppdc/sample.c:136
msgid "B9"
msgstr "B9"
+#: cups/dest.c:827
msgid "Bad NULL dests pointer"
msgstr "Puntero destino NULLincorrecto"
+#: cups/ppd.c:345
msgid "Bad OpenGroup"
msgstr "OpenGroup incorrecto"
+#: cups/ppd.c:347
msgid "Bad OpenUI/JCLOpenUI"
msgstr "OpenUI/JCLOpenUI incorrecto"
+#: cups/ppd.c:349
msgid "Bad OrderDependency"
msgstr "OrderDependency incorrecto"
+#: cups/ppd-cache.c:144
+#: cups/ppd-cache.c:189
+#: cups/ppd-cache.c:227
+#: cups/ppd-cache.c:233
+#: cups/ppd-cache.c:249
+#: cups/ppd-cache.c:265
+#: cups/ppd-cache.c:274
+#: cups/ppd-cache.c:282
+#: cups/ppd-cache.c:299
+#: cups/ppd-cache.c:307
+#: cups/ppd-cache.c:322
+#: cups/ppd-cache.c:330
+#: cups/ppd-cache.c:348
+#: cups/ppd-cache.c:360
+#: cups/ppd-cache.c:375
+#: cups/ppd-cache.c:387
+#: cups/ppd-cache.c:409
+#: cups/ppd-cache.c:417
+#: cups/ppd-cache.c:435
+#: cups/ppd-cache.c:443
+#: cups/ppd-cache.c:458
+#: cups/ppd-cache.c:466
+#: cups/ppd-cache.c:484
+#: cups/ppd-cache.c:492
+#: cups/ppd-cache.c:519
+#: cups/ppd-cache.c:546
+#: cups/ppd-cache.c:554
+#: cups/ppd-cache.c:562
+msgid "Bad PPD cache file."
+msgstr "Archivo de caché PPD incorrecto."
+
+#: cups/http-support.c:1269
msgid "Bad Request"
msgstr "Petición incorrecta"
+#: cups/snmp.c:1002
msgid "Bad SNMP version number"
msgstr "Número de versión SNMP incorrecto"
+#: cups/ppd.c:350
msgid "Bad UIConstraints"
msgstr "UIConstraints incorrecto"
+#: filter/pstext.c:278
+#: filter/texttops.c:297
+#: filter/texttops.c:309
+#, c-format
+msgid "Bad charset file \"%s\"."
+msgstr "Archivo de juego de caracteres incorrecto \"%s\"."
+
+#: filter/texttops.c:472
+#, c-format
+msgid "Bad charset type: %s"
+msgstr "Tipo de juego de caracteres incorrecto: %s"
+
+#: filter/textcommon.c:613
+#, c-format
+msgid "Bad columns value %d."
+msgstr "Valor de número de columnas %d incorrecto."
+
+#: scheduler/ipp.c:1460
#, c-format
msgid "Bad copies value %d."
msgstr "Valor de copias %d incorrecto."
+#: filter/textcommon.c:625
+#, c-format
+msgid "Bad cpi value %f."
+msgstr "Valor de cpi %f incorrecto."
+
+#: cups/ppd.c:358
msgid "Bad custom parameter"
msgstr "Parámetro a medida incorrecto"
+#: cups/http-support.c:1421
+#: scheduler/ipp.c:2549
#, c-format
-msgid "Bad device URI \"%s\"\n"
-msgstr ""
+msgid "Bad device-uri \"%s\"."
+msgstr "device-uri \"%s\" incorrecto."
+#: scheduler/ipp.c:2590
#, c-format
-msgid "Bad device-uri \"%s\""
-msgstr ""
+msgid "Bad device-uri scheme \"%s\"."
+msgstr "Esquema device-uri \"%s\" incorrecto."
+#: scheduler/ipp.c:9402
+#: scheduler/ipp.c:9418
+#: scheduler/ipp.c:10604
+#: scheduler/ipp.c:12111
#, c-format
-msgid "Bad device-uri scheme \"%s\""
-msgstr ""
+msgid "Bad document-format \"%s\"."
+msgstr "document-format \"%s\" incorrecto."
+#: scheduler/ipp.c:10620
#, c-format
-msgid "Bad document-format \"%s\""
-msgstr ""
+msgid "Bad document-format-default \"%s\"."
+msgstr "document-format-default \"%s\" incorrecto."
+#: cups/util.c:927
msgid "Bad filename buffer"
-msgstr ""
+msgstr "Nombre de archivo del búfer incorrecto"
+#: filter/pstext.c:324
+#: filter/pstext.c:362
#, c-format
-msgid "Bad font attribute: %s\n"
-msgstr "Atributo de fuente: %s incorrecto\n"
+msgid "Bad font description line \"%s\"."
+msgstr "LÃnea de descripción tipográfica incorrecta: \"%s\"."
-msgid "Bad job-priority value"
-msgstr ""
+#: filter/texttops.c:364
+#: filter/texttops.c:402
+#, c-format
+msgid "Bad font description line: %s"
+msgstr "LÃnea de descripción tipográfica incorrecta: %s"
+#: scheduler/ipp.c:11203
+msgid "Bad job-priority value."
+msgstr "Valor job-priority incorrecto."
+
+#: scheduler/ipp.c:1490
#, c-format
-msgid "Bad job-sheets value \"%s\""
-msgstr ""
+msgid "Bad job-sheets value \"%s\"."
+msgstr "Valor de job-sheets \"%s\" incorrecto."
-msgid "Bad job-sheets value type"
-msgstr ""
+#: scheduler/ipp.c:1474
+msgid "Bad job-sheets value type."
+msgstr "Tipo de valor de job-sheets incorrecto."
-msgid "Bad job-state value"
-msgstr ""
+#: scheduler/ipp.c:11233
+msgid "Bad job-state value."
+msgstr "Valor job-state incorrecto."
+#: scheduler/ipp.c:4058
+#: scheduler/ipp.c:4511
+#: scheduler/ipp.c:7262
+#: scheduler/ipp.c:7409
+#: scheduler/ipp.c:8852
+#: scheduler/ipp.c:9105
+#: scheduler/ipp.c:9953
+#: scheduler/ipp.c:10178
+#: scheduler/ipp.c:10505
+#: scheduler/ipp.c:11095
#, c-format
-msgid "Bad job-uri attribute \"%s\""
-msgstr ""
+msgid "Bad job-uri \"%s\"."
+msgstr "job-uri \"%s\" incorrecto."
+#: filter/textcommon.c:637
#, c-format
-msgid "Bad notify-pull-method \"%s\""
-msgstr ""
+msgid "Bad lpi value %f."
+msgstr "Valor de lpi %f incorrecto."
+#: scheduler/ipp.c:2194
+#: scheduler/ipp.c:6804
#, c-format
-msgid "Bad notify-recipient-uri URI \"%s\""
-msgstr ""
+msgid "Bad notify-pull-method \"%s\"."
+msgstr "notify-pull-method \"%s\" incorrecto."
+
+#: scheduler/ipp.c:2158
+#: scheduler/ipp.c:6768
+#, c-format
+msgid "Bad notify-recipient-uri \"%s\"."
+msgstr "notify-recipient-uri \"%s\" incorrecto."
+#: scheduler/ipp.c:1506
#, c-format
msgid "Bad number-up value %d."
msgstr "Valor number-up (páginas por hoja) %d incorrecto."
+#: cups/adminutil.c:292
#, c-format
-msgid "Bad option + choice on line %d"
-msgstr ""
+msgid "Bad option + choice on line %d."
+msgstr "Opción + preferencia incorrectas en lÃnea %d."
+#: scheduler/ipp.c:1523
#, c-format
msgid "Bad page-ranges values %d-%d."
msgstr "Valores de page-ranges %d-%d incorrectos."
+#: scheduler/ipp.c:2633
#, c-format
-msgid "Bad port-monitor \"%s\""
-msgstr ""
+msgid "Bad port-monitor \"%s\"."
+msgstr "port-monitor \"%s\" incorrecto."
+#: scheduler/ipp.c:2694
#, c-format
-msgid "Bad printer-state value %d"
-msgstr ""
+msgid "Bad printer-state value %d."
+msgstr "Valor printer-state %d incorrecto."
+#: scheduler/ipp.c:320
#, c-format
-msgid "Bad request ID %d"
-msgstr ""
+msgid "Bad request ID %d."
+msgstr "Petición incorrecta de ID %d."
+#: scheduler/ipp.c:305
#, c-format
-msgid "Bad request version number %d.%d"
-msgstr ""
+msgid "Bad request version number %d.%d."
+msgstr "Petición incorrecta de número de versión %d.%d."
+#: cgi-bin/admin.c:1485
msgid "Bad subscription ID"
-msgstr ""
+msgstr "ID de subscripción incorrecto"
+
+#: filter/pstext.c:337
+#, c-format
+msgid "Bad text direction \"%s\"."
+msgstr "Dirección de texto incorrecta \"%s\"."
+
+#: filter/texttops.c:377
+#, c-format
+msgid "Bad text direction: %s"
+msgstr "Dirección de texto incorrecta: %s"
+
+#: filter/pstext.c:375
+#, c-format
+msgid "Bad text width \"%s\"."
+msgstr "Anchura de texto incorrecta \"%s\"."
+
+#: filter/texttops.c:416
+#, c-format
+msgid "Bad text width: %s"
+msgstr "Anchura de texto incorrecta: %s"
+#: cups/ppd.c:360
msgid "Bad value string"
-msgstr ""
+msgstr "Cadena de valores incorrecta"
+#: cgi-bin/admin.c:3409
+#: cgi-bin/admin.c:3655
msgid "Banners"
msgstr "Rótulos"
+#: filter/bannertops.c:666
msgid "Billing Information: "
msgstr "Información de facturación: "
+#: ppdc/sample.c:296
msgid "Bond Paper"
msgstr "Papel de cartas"
-msgid "C0 Envelope"
-msgstr "Sobre C0"
+#: backend/usb-darwin.c:1874
+#, c-format
+msgid "Boolean expected for waiteof option \"%s\"."
+msgstr "Se esperaba un valor lógico para la opción waiteof \"%s\"."
-msgid "C1 Envelope"
-msgstr "Sobre C1"
-
-msgid "C2 Envelope"
-msgstr "Sobre C2"
-
-msgid "C3 Envelope"
-msgstr "Sobre C3"
-
-msgid "C4"
-msgstr "C4"
-
-msgid "C4 Envelope"
-msgstr "Sobre C4"
-
-msgid "C5"
-msgstr "C5"
-
-msgid "C5 Envelope"
-msgstr "Sobre C5"
-
-msgid "C6"
-msgstr "C6"
-
-msgid "C6 Envelope"
-msgstr "Sobre C6"
-
-msgid "C65 Envelope"
-msgstr "Sobre C65"
-
-msgid "C7 Envelope"
-msgstr "Sobre C7"
+#: filter/pstops.c:2075
+msgid "Buffer overflow detected, aborting."
+msgstr "Se ha detectado un desbordamiento de buffer, cancelando."
+#: ppdc/sample.c:263
msgid "CMYK"
msgstr "CMYK"
+#: ppdc/sample.c:372
msgid "CPCL Label Printer"
msgstr "Impresora de etiquetas CPCL"
+#: cgi-bin/admin.c:1486
+#: cgi-bin/admin.c:1525
+#: cgi-bin/admin.c:1535
msgid "Cancel RSS Subscription"
msgstr "Cancelar subscripción RSS"
+#: backend/ipp.c:1795
+msgid "Canceling print job."
+msgstr "Cancelando trabajo de impresión."
+
+#: scheduler/ipp.c:2674
+msgid "Cannot share a remote Kerberized printer."
+msgstr "No se puede compartir una impresora remota Kerberizada."
+
+#: ppdc/sample.c:288
+msgid "Cassette"
+msgstr "Casete"
+
+#: cgi-bin/admin.c:1708
+#: cgi-bin/admin.c:1872
+#: cgi-bin/admin.c:1884
+#: cgi-bin/admin.c:1895
msgid "Change Settings"
msgstr "Cambiar configuración"
+#: scheduler/ipp.c:2206
+#: scheduler/ipp.c:6816
#, c-format
-msgid "Character set \"%s\" not supported"
-msgstr ""
-
-msgid "Chou3 Envelope"
-msgstr "Sobre Chou3"
-
-msgid "Chou4 Envelope"
-msgstr "Sobre Chou4"
+msgid "Character set \"%s\" not supported."
+msgstr "No se admite el juego de caracteres \"%s\"."
+#: cgi-bin/classes.c:195
+#: cgi-bin/classes.c:322
msgid "Classes"
msgstr "Clases"
+#: cgi-bin/printers.c:182
msgid "Clean Print Heads"
msgstr "Limpiar cabezales de impresión"
+#: scheduler/ipp.c:4960
+msgid "Close-Job doesn't support the job-uri attribute."
+msgstr "Close-Job no admite el atributo job-uri."
+
+#: ppdc/sample.c:291
msgid "Color"
msgstr "Color"
+#: ppdc/sample.c:262
msgid "Color Mode"
msgstr "Modo de color"
+#: berkeley/lpc.c:204
msgid ""
"Commands may be abbreviated. Commands are:\n"
"\n"
-"exit help quit status ?\n"
+"exit help quit status ?"
msgstr ""
"Los comandos se pueden abreviar. Los comandos son:\n"
"\n"
-"exit help quit status ?\n"
+"exit help quit status ?"
+#: cups/snmp.c:1006
msgid "Community name uses indefinite length"
msgstr "Nombre de comunidad usa una longitud indefinida"
+#: backend/ipp.c:764
+#: backend/lpd.c:868
+#: backend/socket.c:395
+msgid "Connected to printer."
+msgstr "Conectado a la impresora."
+
+#: backend/ipp.c:671
+#: backend/lpd.c:708
+#: backend/socket.c:314
+msgid "Connecting to printer."
+msgstr "Conectando a la impresora."
+
+#: cups/http-support.c:1242
msgid "Continue"
msgstr "Continuar"
+#: ppdc/sample.c:374
msgid "Continuous"
msgstr "Continuo"
-#, c-format
-msgid "Could not scan type \"%s\""
-msgstr ""
+#: backend/lpd.c:1019
+#: backend/lpd.c:1161
+msgid "Control file sent successfully."
+msgstr "Archivo de control enviado correctamente."
+
+#: backend/ipp.c:1188
+#: backend/lpd.c:462
+msgid "Copying print data."
+msgstr "Copiando datos de impresión."
+#: cups/http-support.c:1251
msgid "Created"
msgstr "Creado"
+#: filter/bannertops.c:854
msgid "Created On: "
msgstr "Creado en: "
+#: cups/ppd.c:1073
+#: cups/ppd.c:1113
+#: cups/ppd.c:1358
+#: cups/ppd.c:1461
msgid "Custom"
msgstr "A medida"
+#: ppdc/sample.c:368
msgid "CustominCutInterval"
msgstr "CustominCutInterval"
+#: ppdc/sample.c:366
msgid "CustominTearInterval"
msgstr "CustominTearInterval"
+#: ppdc/sample.c:352
msgid "Cut"
msgstr "Cortar"
+#: ppdc/sample.c:460
msgid "Cutter"
msgstr "Cortadora"
-msgid "DL"
-msgstr "DL"
-
-msgid "DL Envelope"
-msgstr "Sobre DL"
-
+#: ppdc/sample.c:248
msgid "Dark"
msgstr "Oscuro"
+#: ppdc/sample.c:244
msgid "Darkness"
msgstr "Oscuridad"
+#: backend/lpd.c:1109
+msgid "Data file sent successfully."
+msgstr "Archivo de datos enviado correctamente."
+
+#: cgi-bin/admin.c:2168
+#: cgi-bin/admin.c:2179
+#: cgi-bin/admin.c:2224
msgid "Delete Class"
msgstr "Borrar clase"
+#: cgi-bin/admin.c:2253
+#: cgi-bin/admin.c:2264
+#: cgi-bin/admin.c:2309
msgid "Delete Printer"
msgstr "Borrar impresora"
+#: filter/bannertops.c:735
msgid "Description: "
msgstr "Descripción: "
+#: ppdc/sample.c:290
msgid "DeskJet Series"
msgstr "DeskJet Series"
+#: scheduler/ipp.c:1426
#, c-format
msgid "Destination \"%s\" is not accepting jobs."
msgstr "El destino %s no acepta trabajos."
+#: systemv/lpinfo.c:300
#, c-format
msgid ""
"Device: uri = %s\n"
" info = %s\n"
" make-and-model = %s\n"
" device-id = %s\n"
-" location = %s\n"
+" location = %s"
msgstr ""
"Dispositivo: uri = %s\n"
" clase = %s\n"
" info = %s\n"
" marca y modelo = %s\n"
" id dispositivo= %s\n"
-" ubicación = %s\n"
+" ubicación = %s"
+#: ppdc/sample.c:445
msgid "Direct Thermal Media"
msgstr "Soporte térmico directo"
+#: cups/file.c:305
+#, c-format
+msgid "Directory \"%s\" contains a relative path."
+msgstr "El directorio \"%s\" contiene una ruta relativa."
+
+#: cups/file.c:277
+#, c-format
+msgid "Directory \"%s\" has insecure permissions (0%o/uid=%d/gid=%d)."
+msgstr "El directorio \"%s\" tiene permisos no seguros (0%o/uid=%d/gid=%d)."
+
+#: cups/file.c:294
+#, c-format
+msgid "Directory \"%s\" is a file."
+msgstr "El directorio \"%s\" es un archivo."
+
+#: cups/file.c:265
+#, c-format
+msgid "Directory \"%s\" not available: %s"
+msgstr "Directorio \"%s\" no disponible: %s"
+
+#: cups/file.c:250
+#, c-format
+msgid "Directory \"%s\" permissions OK (0%o/uid=%d/gid=%d)."
+msgstr "Permisos del directorio \"%s\" OK (0%o/uid=%d/gid=%d)."
+
+#: ppdc/sample.c:354
msgid "Disabled"
msgstr "Deshabilitado"
+#: scheduler/ipp.c:7311
#, c-format
-msgid "Document %d not found in job %d."
-msgstr "No se encuentra el documento %d en el trabajo %d."
-
-msgid "Double Postcard"
-msgstr "Postal doble"
+msgid "Document #%d does not exist in job #%d."
+msgstr "El documento #%d no existe en el trabajo #%d."
+#: filter/bannertops.c:820
msgid "Driver Name: "
msgstr "Nombre del controlador: "
+#: filter/bannertops.c:831
msgid "Driver Version: "
msgstr "Versión del controlador: "
+#: ppdc/sample.c:284
msgid "Duplexer"
msgstr "Unidad de impresión dúplex"
+#: ppdc/sample.c:238
msgid "Dymo"
msgstr "Dymo"
-#, c-format
-msgid "EMERG: Unable to allocate memory for page info: %s\n"
-msgstr ""
-"EMERG: No se ha podido asignar memoria para la información de página: %s\n"
-
-#, c-format
-msgid "EMERG: Unable to allocate memory for pages array: %s\n"
-msgstr ""
-"EMERG: No se ha podido asignar memoria para la secuencia de páginas: %s\n"
-
+#: ppdc/sample.c:440
msgid "EPL1 Label Printer"
msgstr "Impresora de etiquetas EPL1"
+#: ppdc/sample.c:443
msgid "EPL2 Label Printer"
msgstr "Impresora de etiquetas EPL2"
-#, c-format
-msgid "ERROR: %s job-id user title copies options [file]\n"
-msgstr "ERROR: %s job-id usuario tÃtulo copias opciones [archivo]\n"
-
-#, c-format
-msgid "ERROR: Bad %%BoundingBox: comment seen\n"
-msgstr ""
-
-#, c-format
-msgid "ERROR: Bad %%IncludeFeature: comment\n"
-msgstr ""
-
-#, c-format
-msgid "ERROR: Bad %%Page: comment in file\n"
-msgstr ""
-
-#, c-format
-msgid "ERROR: Bad %%PageBoundingBox: comment in file\n"
-msgstr ""
-
-#, c-format
-msgid "ERROR: Bad charset file %s\n"
-msgstr "ERROR: Archivo de juego de caracteres incorrecto %s\n"
-
-#, c-format
-msgid "ERROR: Bad charset type %s\n"
-msgstr "ERROR: Tipo de juego de caracteres incorrecto %s\n"
+#: cgi-bin/admin.c:1923
+#: cgi-bin/admin.c:1935
+#: cgi-bin/admin.c:1989
+#: cgi-bin/admin.c:1996
+#: cgi-bin/admin.c:2031
+#: cgi-bin/admin.c:2044
+#: cgi-bin/admin.c:2068
+#: cgi-bin/admin.c:2141
+msgid "Edit Configuration File"
+msgstr "Editar archivo de configuración"
-#, c-format
-msgid "ERROR: Bad columns value %d\n"
-msgstr ""
+#: cups/adminutil.c:337
+msgid "Empty PPD file."
+msgstr "Archivo PPD vacÃo."
-#, c-format
-msgid "ERROR: Bad cpi value %f\n"
-msgstr ""
+#. TRANSLATORS: Banner/cover sheet after the print job.
+#: cgi-bin/admin.c:3680
+msgid "Ending Banner"
+msgstr "Rótulo final"
-#, c-format
-msgid "ERROR: Bad font description line: %s\n"
-msgstr "ERROR: LÃnea de descripción tipográfica incorrecta: %s\n"
+#: ppdc/sample.c:2
+msgid "English"
+msgstr "Spanish"
-#, c-format
-msgid "ERROR: Bad lpi value %f\n"
-msgstr ""
+#: systemv/lppasswd.c:193
+msgid "Enter old password:"
+msgstr "Introduzca la contraseña antigua:"
-msgid "ERROR: Bad page setup\n"
-msgstr ""
+#: systemv/lppasswd.c:224
+msgid "Enter password again:"
+msgstr "Introduzca nuevamente la contraseña:"
-#, c-format
-msgid "ERROR: Bad text direction %s\n"
-msgstr "ERROR: Dirección de texto incorrecta %s\n"
+#: systemv/lppasswd.c:212
+msgid "Enter password:"
+msgstr "Introduzca la contraseña:"
-#, c-format
-msgid "ERROR: Bad text width %s\n"
-msgstr "ERROR: Anchura de texto incorrecta %s\n"
+#: scheduler/client.c:2439
+msgid "Enter your username and password or the root username and password to access this page. If you are using Kerberos authentication, make sure you have a valid Kerberos ticket."
+msgstr "Introduzca su nombre de usuario y contraseña o el nombre de usuario y contraseña de root para poder acceder a esta página. Si está usando autentificación Kerberos, asegúrese de que tiene un ticket Kerberos válido."
-msgid "ERROR: Destination printer does not exist\n"
-msgstr ""
+#: ppdc/sample.c:73
+msgid "Envelope #10 "
+msgstr "Sobre #10"
-#, c-format
-msgid "ERROR: Duplicate %%BoundingBox: comment seen\n"
-msgstr ""
+#: ppdc/sample.c:74
+msgid "Envelope #11"
+msgstr "Sobre #11"
-#, c-format
-msgid "ERROR: Duplicate %%Pages: comment seen\n"
-msgstr ""
+#: ppdc/sample.c:75
+msgid "Envelope #12"
+msgstr "Sobre #12"
-msgid "ERROR: Empty print file\n"
-msgstr ""
+#: ppdc/sample.c:76
+msgid "Envelope #14"
+msgstr "Sobre #14"
-#, c-format
-msgid "ERROR: Error %d sending PAPSendData request: %s\n"
-msgstr "ERROR: Error %d enviando petición PAPSendData: %s\n"
+#: ppdc/sample.c:77
+msgid "Envelope #9"
+msgstr "Sobre #9"
-#, c-format
-msgid "ERROR: Expected quoted string on line %d of %s\n"
-msgstr ""
+#: ppdc/sample.c:89
+msgid "Envelope B4"
+msgstr "Sobre B4"
-msgid "ERROR: Fatal USB error\n"
-msgstr ""
+#: ppdc/sample.c:90
+msgid "Envelope B5"
+msgstr "Sobre B5"
-#, c-format
-msgid "ERROR: Missing %%EndProlog\n"
-msgstr ""
+#: ppdc/sample.c:91
+msgid "Envelope B6"
+msgstr "Sobre B6"
-#, c-format
-msgid "ERROR: Missing %%EndSetup\n"
-msgstr ""
+#: ppdc/sample.c:78
+msgid "Envelope C0"
+msgstr "Sobre C0"
-#, c-format
-msgid "ERROR: Missing value on line %d of banner file\n"
-msgstr ""
+#: ppdc/sample.c:79
+msgid "Envelope C1"
+msgstr "Sobre C1"
-#, c-format
-msgid ""
-"ERROR: Need a msgid line before any translation strings on line %d of %s\n"
-msgstr ""
+#: ppdc/sample.c:80
+msgid "Envelope C2"
+msgstr "Sobre C2"
-#, c-format
-msgid "ERROR: No %%BoundingBox: comment in header\n"
-msgstr ""
+#: ppdc/sample.c:81
+msgid "Envelope C3"
+msgstr "Sobre C3"
-#, c-format
-msgid "ERROR: No %%Pages: comment in header\n"
-msgstr ""
+#: ppdc/sample.c:67
+msgid "Envelope C4"
+msgstr "Sobre C4"
-msgid ""
-"ERROR: No device URI found in argv[0] or in DEVICE_URI environment variable\n"
-msgstr ""
+#: ppdc/sample.c:68
+msgid "Envelope C5"
+msgstr "Sobre C5"
-#, c-format
-msgid "ERROR: No fonts in charset file %s\n"
-msgstr "ERROR: No hay fuentes en el archivo de juego de caracteres %s\n"
+#: ppdc/sample.c:69
+msgid "Envelope C6"
+msgstr "Sobre C6"
-msgid "ERROR: No pages found\n"
-msgstr ""
+#: ppdc/sample.c:82
+msgid "Envelope C65"
+msgstr "Sobre C65"
-msgid "ERROR: Out of paper\n"
-msgstr ""
+#: ppdc/sample.c:83
+msgid "Envelope C7"
+msgstr "Sobre C7"
-msgid "ERROR: PRINTER environment variable not defined\n"
-msgstr ""
+#: ppdc/sample.c:84
+msgid "Envelope Choukei 3"
+msgstr "Sobre Choukei 3"
-#, c-format
-msgid "ERROR: Print file was not accepted (%s)\n"
-msgstr ""
+#: ppdc/sample.c:85
+msgid "Envelope Choukei 3 Long Edge"
+msgstr "Sobre Choukei 3 lado largo"
-msgid "ERROR: Printer not responding\n"
-msgstr "ERROR: La impresora no responde\n"
+#: ppdc/sample.c:86
+msgid "Envelope Choukei 4"
+msgstr "Sobre Choukei 4"
-msgid "ERROR: Printer sent unexpected EOF\n"
-msgstr "ERROR: La impresora envió un inesperado EOF\n"
+#: ppdc/sample.c:87
+msgid "Envelope Choukei 4 Long Edge"
+msgstr "Sobre Choukei 4 lado largo"
-#, c-format
-msgid "ERROR: Remote host did not accept control file (%d)\n"
-msgstr "ERROR: El ordenador remoto no ha aceptado el archivo de control (%d)\n"
+#: ppdc/sample.c:70
+msgid "Envelope DL"
+msgstr "Sobre DL"
-#, c-format
-msgid "ERROR: Remote host did not accept data file (%d)\n"
-msgstr "ERROR: El ordenador remoto no ha aceptado el archivo de datos (%d)\n"
+#: ppdc/sample.c:278
+msgid "Envelope Feed"
+msgstr "Alimentador de sobre"
-msgid "ERROR: There was a timeout error while sending data to the printer\n"
-msgstr ""
-"ERROR: Hay un error de tiempo de espera mientras se enviaban datos a la "
-"impresora\n"
+#: ppdc/sample.c:88
+msgid "Envelope Invite"
+msgstr "Sobre Invitación"
-#, c-format
-msgid "ERROR: Unable to add file %d to job: %s\n"
-msgstr "ERROR: No se ha podido añadir el archivo %d al trabajo: %s\n"
+#: ppdc/sample.c:92
+msgid "Envelope Italian"
+msgstr "Sobre Italiano"
-#, c-format
-msgid "ERROR: Unable to cancel job %d: %s\n"
-msgstr "ERROR: No se ha podido cancelar el trabajo %d: %s\n"
+#: ppdc/sample.c:93
+msgid "Envelope Kaku2"
+msgstr "Sobre Kaku2"
-msgid "ERROR: Unable to connect to printer; will retry in 30 seconds...\n"
-msgstr ""
+#: ppdc/sample.c:94
+msgid "Envelope Kaku2 Long Edge"
+msgstr "Sobre Kaku2 lado largo"
-msgid "ERROR: Unable to copy PDF file"
-msgstr "ERROR: No se ha podido copiar el archivo PDF"
+#: ppdc/sample.c:95
+msgid "Envelope Kaku3"
+msgstr "Sobre Kaku3"
-msgid "ERROR: Unable to create pipe"
-msgstr "ERROR: No se ha podido crear el canal (pipe)"
+#: ppdc/sample.c:96
+msgid "Envelope Kaku3 Long Edge"
+msgstr "Sobre Kaku3 lado largo"
-msgid "ERROR: Unable to create socket"
-msgstr "ERROR: No se ha podido crear socket"
+#: ppdc/sample.c:97
+msgid "Envelope Monarch"
+msgstr "Sobre Monarch"
-#, c-format
-msgid "ERROR: Unable to create temporary compressed print file: %s\n"
-msgstr ""
-"ERROR: No se ha podido crear el archivo de impresión temporal comprimido: %"
-"s\n"
+#: ppdc/sample.c:99
+msgid "Envelope PRC1 "
+msgstr "Sobre PRC1"
-msgid "ERROR: Unable to create temporary file"
-msgstr "ERROR: No se ha podido crear el archivo temporal"
+#: ppdc/sample.c:100
+msgid "Envelope PRC1 Long Edge"
+msgstr "Sobre PRC1 lado largo"
-#, c-format
-msgid "ERROR: Unable to exec pictwpstops: %s\n"
-msgstr "ERROR: No se ha podido ejecutar pictwpstops: %s\n"
+#: ppdc/sample.c:117
+msgid "Envelope PRC10"
+msgstr "Sobre PRC10"
-msgid "ERROR: Unable to execute gs program"
-msgstr "ERROR: No se ha podido ejecutar el programa gs"
+#: ppdc/sample.c:118
+msgid "Envelope PRC10 Long Edge"
+msgstr "Sobre PRC10 lado largo"
-msgid "ERROR: Unable to execute pdftops program"
-msgstr "ERROR: No se ha podido ejecutar el programa pdftops"
+#: ppdc/sample.c:101
+msgid "Envelope PRC2"
+msgstr "Sobre PRC2"
-msgid "ERROR: Unable to execute pstops program"
-msgstr "ERROR: No se ha podido ejecutar el programa pstops"
+#: ppdc/sample.c:102
+msgid "Envelope PRC2 Long Edge"
+msgstr "Sobre PRC2 lado largo"
-#, c-format
-msgid "ERROR: Unable to fork pictwpstops: %s\n"
-msgstr "ERROR: No se ha podido bifurcar (fork) pictwpstops: %s\n"
+#: ppdc/sample.c:103
+msgid "Envelope PRC3"
+msgstr "Sobre PRC3"
-msgid "ERROR: Unable to get PAP request"
-msgstr "ERROR: No se ha podido obtener una petición PAP"
+#: ppdc/sample.c:104
+msgid "Envelope PRC3 Long Edge"
+msgstr "Sobre PRC3 lado largo"
-msgid "ERROR: Unable to get PAP response"
-msgstr "ERROR: No se ha podido obtener una respuesta PAP"
+#: ppdc/sample.c:105
+msgid "Envelope PRC4"
+msgstr "Sobre PRC4"
-#, c-format
-msgid "ERROR: Unable to get PPD file for printer \"%s\" - %s.\n"
-msgstr ""
-"ERROR: No se ha podido obtener el archivo PPD para la impresora \"%s\" - %"
-"s.\n"
+#: ppdc/sample.c:106
+msgid "Envelope PRC4 Long Edge"
+msgstr "Sobre PRC4 lado largo"
-msgid "ERROR: Unable to get default AppleTalk zone"
-msgstr "ERROR: No se ha podido conseguir la zona AppleTalk predeterminada"
+#: ppdc/sample.c:108
+msgid "Envelope PRC5 Long Edge"
+msgstr "Sobre PRC5 lado largo"
-#, c-format
-msgid "ERROR: Unable to get job %d attributes (%s)\n"
-msgstr ""
+#: ppdc/sample.c:107
+msgid "Envelope PRC5PRC5"
+msgstr "Sobre PRC5PRC5"
-#, c-format
-msgid "ERROR: Unable to get printer status (%s)\n"
-msgstr ""
+#: ppdc/sample.c:109
+msgid "Envelope PRC6"
+msgstr "Sobre PRC6"
-#, c-format
-msgid "ERROR: Unable to locate printer '%s'\n"
-msgstr ""
+#: ppdc/sample.c:110
+msgid "Envelope PRC6 Long Edge"
+msgstr "Sobre PRC6 lado largo"
-msgid "ERROR: Unable to look for PAP response"
-msgstr "ERROR: No se ha podido buscar una respuesta PAP"
+#: ppdc/sample.c:111
+msgid "Envelope PRC7"
+msgstr "Sobre PRC7"
-msgid "ERROR: Unable to lookup AppleTalk printers"
-msgstr "ERROR: No se han podido mirar las impresoras AppleTalk"
+#: ppdc/sample.c:112
+msgid "Envelope PRC7 Long Edge"
+msgstr "Sobre PRC7 lado largo"
-msgid "ERROR: Unable to make AppleTalk address"
-msgstr "ERROR: No se ha podido crear la dirección AppleTalk"
+#: ppdc/sample.c:113
+msgid "Envelope PRC8"
+msgstr "Sobre PRC8"
-#, c-format
-msgid "ERROR: Unable to open \"%s\" - %s\n"
-msgstr "ERROR: No se ha podido abrir \"%s\" - %s\n"
+#: ppdc/sample.c:114
+msgid "Envelope PRC8 Long Edge"
+msgstr "Sobre PRC8 lado largo"
-#, c-format
-msgid "ERROR: Unable to open %s: %s\n"
-msgstr "ERROR: No se ha podido abrir %s: %s\n"
+#: ppdc/sample.c:115
+msgid "Envelope PRC9"
+msgstr "Sobre PRC9"
-msgid "ERROR: Unable to open PPD file\n"
-msgstr ""
+#: ppdc/sample.c:116
+msgid "Envelope PRC9 Long Edge"
+msgstr "Sobre PRC9 lado largo"
-#, c-format
-msgid "ERROR: Unable to open banner file \"%s\" - %s\n"
-msgstr "ERROR: No se ha podido abrir el archivo de rótulo \"%s\" - %s\n"
+#: ppdc/sample.c:98
+msgid "Envelope Personal"
+msgstr "Sobre Personal"
-#, c-format
-msgid "ERROR: Unable to open device file \"%s\": %s\n"
-msgstr "ERROR: No se ha podido abrir el archivo de dispositivo \"%s\": %s\n"
+#: ppdc/sample.c:119
+msgid "Envelope You4"
+msgstr "Sobre You4"
-#, c-format
-msgid "ERROR: Unable to open file \"%s\" - %s\n"
-msgstr "ERROR: No se ha podido abrir el archivo \"%s\" - %s\n"
+#: ppdc/sample.c:120
+msgid "Envelope You4 Long Edge"
+msgstr "Sobre You4 lado largo"
-#, c-format
-msgid "ERROR: Unable to open file \"%s\": %s\n"
-msgstr "ERROR: No se ha podido abrir el archivo \"%s\": %s\n"
+#: ppdc/sample.c:249
+msgid "Epson"
+msgstr "Epson"
-msgid "ERROR: Unable to open image file for printing\n"
-msgstr ""
+#: cgi-bin/admin.c:3723
+msgid "Error Policy"
+msgstr "Directiva de error"
-#, c-format
-msgid "ERROR: Unable to open print file \"%s\": %s\n"
-msgstr "ERROR: No se ha podido abrir el archivo de impresión \"%s\": %s\n"
+#: filter/rastertopwg.c:160
+#: filter/rastertopwg.c:175
+#: filter/rastertopwg.c:186
+#: filter/rastertopwg.c:197
+msgid "Error sending raster data."
+msgstr "Error enviando trama de datos (raster)."
-#, c-format
-msgid "ERROR: Unable to open print file %s - %s\n"
-msgstr "ERROR: No se ha podido abrir el archivo de impresión %s - %s\n"
+#: systemv/lpinfo.c:103
+#: systemv/lpmove.c:88
+msgid "Error: need hostname after \"-h\" option."
+msgstr "Error: se necesita un nombre de ordenador tras la opción \"-h\"."
-#, c-format
-msgid "ERROR: Unable to open print file %s: %s\n"
-msgstr "ERROR: No se ha podido abrir el archivo de impresión %s: %s\n"
+#: ppdc/sample.c:364
+msgid "Every 10 Labels"
+msgstr "Cada 10 etiquetas"
-#, c-format
-msgid "ERROR: Unable to open raster file - %s\n"
-msgstr "ERROR: No se ha podido abrir el archivo de trama de datos - %s\n"
+#: ppdc/sample.c:356
+msgid "Every 2 Labels"
+msgstr "Cada 2 etiquetas"
-#, c-format
-msgid "ERROR: Unable to open temporary compressed print file: %s\n"
-msgstr ""
-"ERROR: No se ha podido abrir el archivo de impresión temporal comprimido: %"
-"s\n"
+#: ppdc/sample.c:357
+msgid "Every 3 Labels"
+msgstr "Cada 3 etiquetas"
-#, c-format
-msgid "ERROR: Unable to print %d text columns\n"
-msgstr ""
+#: ppdc/sample.c:358
+msgid "Every 4 Labels"
+msgstr "Cada 4 etiquetas"
-#, c-format
-msgid "ERROR: Unable to print %dx%d text page\n"
-msgstr ""
+#: ppdc/sample.c:359
+msgid "Every 5 Labels"
+msgstr "Cada 5 etiquetas"
-msgid "ERROR: Unable to read print data"
-msgstr "ERROR: No se han podido leer los datos de impresión"
+#: ppdc/sample.c:360
+msgid "Every 6 Labels"
+msgstr "Cada 6 etiquetas"
-msgid "ERROR: Unable to read print data\n"
-msgstr ""
+#: ppdc/sample.c:361
+msgid "Every 7 Labels"
+msgstr "Cada 7 etiquetas"
-msgid "ERROR: Unable to reserve port"
-msgstr "ERROR: No se ha podido reservar puerto"
+#: ppdc/sample.c:362
+msgid "Every 8 Labels"
+msgstr "Cada 8 etiquetas"
-#, c-format
-msgid "ERROR: Unable to seek to offset %ld in file - %s\n"
-msgstr "ERROR: No se ha podido alcanzar la posición %ld en el archivo - %s\n"
+#: ppdc/sample.c:363
+msgid "Every 9 Labels"
+msgstr "Cada 9 etiquetas"
-#, c-format
-msgid "ERROR: Unable to seek to offset %lld in file - %s\n"
-msgstr "ERROR: No se ha podido alcanzar la posición %lld en el archivo - %s\n"
+#: ppdc/sample.c:355
+msgid "Every Label"
+msgstr "Cada etiqueta"
-msgid "ERROR: Unable to send LPD command"
-msgstr "ERROR: No se ha podido enviar comando LPD"
+#: ppdc/sample.c:121
+msgid "Executive"
+msgstr "Ejecutivo"
-msgid "ERROR: Unable to send PAP tickle request"
-msgstr "ERROR: No se ha podido enviar una petición PAP"
+#: cups/http-support.c:1297
+msgid "Expectation Failed"
+msgstr "Lo que se esperaba, falló."
-msgid "ERROR: Unable to send initial PAP send data request"
-msgstr ""
-"ERROR: No se ha podido enviar la petición inicial de datos de envÃo PAP"
+#: cgi-bin/admin.c:2431
+#: cgi-bin/admin.c:2450
+msgid "Export Printers to Samba"
+msgstr "Exportar impresoras a Samba"
-msgid "ERROR: Unable to send print data\n"
-msgstr ""
+#: systemv/cupstestdsc.c:172
+#: systemv/cupstestdsc.c:189
+#: systemv/cupstestdsc.c:214
+#: systemv/cupstestdsc.c:231
+#: systemv/cupstestdsc.c:255
+#: systemv/cupstestdsc.c:273
+#: systemv/cupstestdsc.c:302
+#: systemv/cupstestdsc.c:339
+#: systemv/cupstestdsc.c:349
+#: systemv/cupstestdsc.c:359
+#: systemv/cupstestdsc.c:369
+#: systemv/cupstestdsc.c:379
+#: systemv/cupstestdsc.c:387
+msgid "FAIL"
+msgstr "FALLO"
+
+#: ppdc/sample.c:122
+msgid "FanFold German"
+msgstr "FanFold alemán"
-msgid "ERROR: Unable to send print file to printer"
-msgstr "ERROR: No se ha podido imprimir el archivo en la impresora"
+#: ppdc/sample.c:123
+msgid "FanFold Legal German"
+msgstr "FanFold Legal alemán"
-msgid "ERROR: Unable to send trailing nul to printer"
-msgstr "ERROR: No se ha podido enviar carácter nulo del final a la impresora"
+#: ppdc/sample.c:124
+msgid "Fanfold US"
+msgstr "FanFold de EE.UU"
+#: cups/file.c:309
#, c-format
-msgid "ERROR: Unable to wait for pictwpstops: %s\n"
-msgstr "ERROR: No se puede esperar por pictwpstops: %s\n"
+msgid "File \"%s\" contains a relative path."
+msgstr "El archivo \"%s\" contiene una ruta relativa."
+#: cups/file.c:284
#, c-format
-msgid "ERROR: Unable to write %d bytes to \"%s\": %s\n"
-msgstr "ERROR: No se han podido escribir %d bytes a \"%s\": %s\n"
+msgid "File \"%s\" has insecure permissions (0%o/uid=%d/gid=%d)."
+msgstr "El archivo \"%s\" tiene permisos no seguros (0%o/uid=%d/gid=%d)."
+#: cups/file.c:298
#, c-format
-msgid "ERROR: Unable to write %d bytes to printer\n"
-msgstr ""
-
-msgid "ERROR: Unable to write control file"
-msgstr "ERROR: No se ha podido escribir el archivo de control"
-
-msgid "ERROR: Unable to write print data"
-msgstr "ERROR: No se han podido escribir los datos de impresión"
+msgid "File \"%s\" is a directory."
+msgstr "El archivo \"%s\" es un directorio."
+#: cups/file.c:270
#, c-format
-msgid "ERROR: Unable to write print data: %s\n"
-msgstr "ERROR: No se han podido escribir los datos de impresión: %s\n"
-
-msgid "ERROR: Unable to write raster data to driver\n"
-msgstr ""
+msgid "File \"%s\" not available: %s"
+msgstr "Archivo \"%s\" no disponible: %s"
+#: cups/file.c:256
#, c-format
-msgid "ERROR: Unable to write uncompressed document data: %s\n"
-msgstr ""
-"ERROR: No se han podido escribir los datos de documento sin comprimir: %s\n"
+msgid "File \"%s\" permissions OK (0%o/uid=%d/gid=%d)."
+msgstr "Permisos del archivo \"%s\" OK (0%o/uid=%d/gid=%d)."
-#, c-format
-msgid "ERROR: Unexpected text on line %d of %s\n"
-msgstr ""
+#: ppdc/sample.c:169
+msgid "File Folder"
+msgstr "Carpeta de archivos"
-#, c-format
-msgid "ERROR: Unknown encryption option value \"%s\"\n"
-msgstr ""
+#: ppdc/sample.c:178
+msgid "File Folder - 9/16 x 3 7/16\""
+msgstr "Carpeta de archivosr - 9/16 x 3 7/16 pulg."
+#: scheduler/ipp.c:2569
#, c-format
-msgid "ERROR: Unknown file order \"%s\"\n"
-msgstr "ERROR: Orden de archivos \"%s\" desconocido\n"
+msgid "File device URIs have been disabled. To enable, see the FileDevice directive in \"%s/cupsd.conf\"."
+msgstr "Los URIs del dispositivo de archivo han sido deshabilitados. Para habilitarlos, vea la directiva FileDevice en \"%s/cupsd.conf\"."
+#: driver/rastertoescpx.c:1899
+#: driver/rastertopclx.c:1924
+#: filter/rastertoepson.c:1117
+#: filter/rastertohp.c:845
+#: filter/rastertolabel.c:1273
#, c-format
-msgid "ERROR: Unknown format character \"%c\"\n"
-msgstr "ERROR: Carácter de formato \"%c\" desconocido\n"
+msgid "Finished page %d."
+msgstr "Acabada la página %d."
-#, c-format
-msgid "ERROR: Unknown message catalog format for \"%s\"\n"
-msgstr ""
+#: ppdc/sample.c:125
+msgid "Folio"
+msgstr "Folio"
-#, c-format
-msgid "ERROR: Unknown option \"%s\" with value \"%s\"\n"
-msgstr ""
+#: cups/http-support.c:1276
+msgid "Forbidden"
+msgstr "Prohibido"
+#: filter/imagetoraster.c:1187
#, c-format
-msgid "ERROR: Unknown print mode \"%s\"\n"
-msgstr "ERROR: Modo de impresión \"%s\" desconocido\n"
+msgid "Formatting page %d."
+msgstr "Formateando página %d."
-#, c-format
-msgid "ERROR: Unknown version option value \"%s\"\n"
-msgstr ""
+#: cups/ppd.c:701
+#: cups/ppd.c:1262
+msgid "General"
+msgstr "General"
-#, c-format
-msgid "ERROR: Unsupported brightness value %s, using brightness=100\n"
-msgstr ""
+#: ppdc/sample.c:268
+msgid "Generic"
+msgstr "Genérico"
-#, c-format
-msgid "ERROR: Unsupported gamma value %s, using gamma=1000\n"
-msgstr ""
-
-#, c-format
-msgid "ERROR: Unsupported number-up value %d, using number-up=1\n"
-msgstr ""
-
-#, c-format
-msgid ""
-"ERROR: Unsupported number-up-layout value %s, using number-up-layout=lrtb\n"
-msgstr ""
-
-#, c-format
-msgid "ERROR: Unsupported page-border value %s, using page-border=none\n"
-msgstr ""
-
-#, c-format
-msgid "ERROR: doc_printf overflow (%d bytes) detected, aborting\n"
-msgstr ""
-
-#, c-format
-msgid "ERROR: pictwpstops exited on signal %d\n"
-msgstr ""
-
-#, c-format
-msgid "ERROR: pictwpstops exited with status %d\n"
-msgstr ""
-
-msgid "ERROR: select() failed"
-msgstr "ERROR: select() ha fallado"
-
-msgid "ERROR: unable to stat print file"
-msgstr "ERROR: no se ha podido ejecutar 'stat' sobre el archivo de impresión"
-
-msgid "Edit Configuration File"
-msgstr "Editar archivo de configuración"
-
-msgid "Empty PPD file"
-msgstr ""
-
-msgid "Ending Banner"
-msgstr "Rótulo final"
-
-msgid "English"
-msgstr "Spanish"
-
-msgid "Enter old password:"
-msgstr "Introduzca la contraseña antigua:"
-
-msgid "Enter password again:"
-msgstr "Introduzca nuevamente la contraseña:"
-
-msgid "Enter password:"
-msgstr "Introduzca la contraseña:"
-
-msgid ""
-"Enter your username and password or the root username and password to access "
-"this page. If you are using Kerberos authentication, make sure you have a "
-"valid Kerberos ticket."
-msgstr ""
-"Introduzca su nombre de usuario y contraseña o el nombre de usuario y "
-"contraseña de root para poder acceder a esta página. Si está usando "
-"autentificación Kerberos, asegúrese de que tiene un ticket Kerberos válido."
-
-msgid "Envelope Feed"
-msgstr "Alimentador de sobre"
-
-msgid "Epson"
-msgstr "Epson"
-
-msgid "Error Policy"
-msgstr "Directiva de error"
-
-msgid "Error: need hostname after '-h' option\n"
-msgstr ""
-
-msgid "Every 10 Labels"
-msgstr "Cada 10 etiquetas"
-
-msgid "Every 2 Labels"
-msgstr "Cada 2 etiquetas"
-
-msgid "Every 3 Labels"
-msgstr "Cada 3 etiquetas"
-
-msgid "Every 4 Labels"
-msgstr "Cada 4 etiquetas"
-
-msgid "Every 5 Labels"
-msgstr "Cada 5 etiquetas"
-
-msgid "Every 6 Labels"
-msgstr "Cada 6 etiquetas"
-
-msgid "Every 7 Labels"
-msgstr "Cada 7 etiquetas"
-
-msgid "Every 8 Labels"
-msgstr "Cada 8 etiquetas"
-
-msgid "Every 9 Labels"
-msgstr "Cada 9 etiquetas"
-
-msgid "Every Label"
-msgstr "Cada etiqueta"
-
-msgid "Expectation Failed"
-msgstr "Lo que se esperaba, falló."
-
-msgid "Export Printers to Samba"
-msgstr "Exportar impresoras a Samba"
-
-msgid "FAIL\n"
-msgstr "FALLO\n"
-
-msgid "File Folder"
-msgstr "Carpeta de archivos"
-
-msgid "File Folder - 9/16 x 3 7/16\""
-msgstr "Carpeta de archivosr - 9/16 x 3 7/16 pulg."
-
-#, c-format
-msgid ""
-"File device URIs have been disabled! To enable, see the FileDevice directive "
-"in \"%s/cupsd.conf\"."
-msgstr ""
-"Los URIs del dispositivo de archivo han sido deshabilitados. Para "
-"habilitarlos, vea la directiva FileDevice en \"%s/cupsd.conf\"."
-
-msgid "Folio"
-msgstr "Folio"
-
-msgid "Forbidden"
-msgstr "Prohibido"
-
-msgid "General"
-msgstr "General"
-
-msgid "Generic"
-msgstr "Genérico"
-
-msgid "German FanFold"
-msgstr "FanFold alemán"
-
-msgid "German FanFold Legal"
-msgstr "FanFold Legal alemán"
-
-msgid "Get-Response-PDU uses indefinite length"
-msgstr "Get-Response-PDU usa una longitud indefinida"
+#: cups/snmp.c:1016
+msgid "Get-Response-PDU uses indefinite length"
+msgstr "Get-Response-PDU usa una longitud indefinida"
+#: ppdc/sample.c:299
msgid "Glossy Paper"
msgstr "Papel satinado"
-msgid "Got a printer-uri attribute but no job-id"
-msgstr ""
-
+#: scheduler/ipp.c:4036
+#: scheduler/ipp.c:4437
+#: scheduler/ipp.c:4972
+#: scheduler/ipp.c:7240
+#: scheduler/ipp.c:7387
+#: scheduler/ipp.c:8829
+#: scheduler/ipp.c:9931
+#: scheduler/ipp.c:10156
+#: scheduler/ipp.c:10483
+#: scheduler/ipp.c:11073
+msgid "Got a printer-uri attribute but no job-id."
+msgstr "Se ha obtenido el atributo printer-uri pero no el job-id."
+
+#: ppdc/sample.c:264
msgid "Grayscale"
msgstr "Escale de grises"
+#: ppdc/sample.c:289
msgid "HP"
msgstr "HP"
+#: ppdc/sample.c:170
msgid "Hanging Folder"
msgstr "Carpeta colgante"
+#: ppdc/sample.c:179
msgid "Hanging Folder - 9/16 x 2\""
msgstr "Carpeta colgante - 9/16 x 2 pulg."
-msgid "INFO: AppleTalk disabled in System Preferences\n"
-msgstr "INFO: AppleTalk desactivado en Preferencias del sistema\n"
-
-msgid "INFO: AppleTalk disabled in System Preferences.\n"
-msgstr "INFO: AppleTalk desactivado en Preferencias del sistema.\n"
-
-msgid "INFO: Canceling print job...\n"
-msgstr "INFO: Cancelando trabajo de impresión...\n"
-
-msgid "INFO: Connected to printer...\n"
-msgstr "INFO: Conectado a la impresora...\n"
-
-msgid "INFO: Connecting to printer...\n"
-msgstr "INFO: Conectando a la impresora...\n"
-
-msgid "INFO: Control file sent successfully\n"
-msgstr "INFO: Archivo de control enviado correctamente\n"
-
-msgid "INFO: Copying print data...\n"
-msgstr "INFO: Copiando datos de impresión...\n"
-
-msgid "INFO: Data file sent successfully\n"
-msgstr "INFO: Archivo de datos enviado correctamente\n"
-
-#, c-format
-msgid "INFO: Finished page %d...\n"
-msgstr "INFO: Acabada la página %d...\n"
-
-#, c-format
-msgid "INFO: Formatting page %d...\n"
-msgstr "INFO: Formateando página %d...\n"
-
-msgid "INFO: Loading image file...\n"
-msgstr "INFO: Cargando archivo de imagen...\n"
-
-msgid "INFO: Looking for printer...\n"
-msgstr "INFO: Buscando impresora...\n"
-
-msgid "INFO: Opening connection\n"
-msgstr "INFO: Abriendo la conexión\n"
-
-msgid "INFO: Print file sent, waiting for printer to finish...\n"
-msgstr ""
-"INFO: Archivo de impresión enviado; esperando a que finalice la "
-"impresora...\n"
-
-msgid "INFO: Printer busy; will retry in 10 seconds...\n"
-msgstr "INFO: Impresora ocupada; reintento en 10 segundos...\n"
-
-msgid "INFO: Printer busy; will retry in 30 seconds...\n"
-msgstr "INFO: Impresora ocupada; reintento en 30 segundos...\n"
-
-msgid "INFO: Printer busy; will retry in 5 seconds...\n"
-msgstr "INFO: Impresora ocupada; reintento en 5 segundos...\n"
-
-#, c-format
-msgid "INFO: Printer does not support IPP/%d.%d, trying IPP/1.0...\n"
-msgstr ""
-"INFO: La impresora no es compatible con IPP/%d.%d, probando IPP/1.0...\n"
-
-msgid "INFO: Printer is busy; will retry in 5 seconds...\n"
-msgstr "INFO: La impresora está ocupada; reintento en 5 segundos...\n"
-
-msgid "INFO: Printer is currently off-line.\n"
-msgstr "INFO: La impresora está actualmente fuera de lÃnea.\n"
-
-msgid "INFO: Printer is currently offline.\n"
-msgstr "INFO: La impresora está sin conexión en estos momentos.\n"
-
-msgid "INFO: Printer is now online.\n"
-msgstr "INFO: La impresora ya tiene conexión.\n"
-
-msgid "INFO: Printer is offline.\n"
-msgstr "INFO: La impresora está sin conexión.\n"
-
-msgid "INFO: Printer not connected; will retry in 30 seconds...\n"
-msgstr "INFO: Impresora no conectada; reintento en 30 segundos...\n"
-
-#, c-format
-msgid "INFO: Printing page %d, %d%% complete...\n"
-msgstr "INFO: Imprimiendo página %d, %d%% completado...\n"
-
-#, c-format
-msgid "INFO: Printing page %d...\n"
-msgstr "INFO: Imprimiendo página %d...\n"
-
-msgid "INFO: Ready to print.\n"
-msgstr "INFO: Lista para imprimir.\n"
-
-#, c-format
-msgid "INFO: Sending control file (%lu bytes)\n"
-msgstr "INFO: Enviando archivo de control (%lu bytes)\n"
-
-#, c-format
-msgid "INFO: Sending control file (%u bytes)\n"
-msgstr "INFO: Enviando archivo de control (%u bytes)\n"
-
-msgid "INFO: Sending data\n"
-msgstr "INFO: Enviando datos\n"
-
-#, c-format
-msgid "INFO: Sending data file (%ld bytes)\n"
-msgstr "INFO: Enviando archivo de datos (%ld bytes)\n"
-
-#, c-format
-msgid "INFO: Sending data file (%lld bytes)\n"
-msgstr "INFO: Enviando archivo de datos (%lld bytes)\n"
-
-msgid "INFO: Sending print data...\n"
-msgstr "INFO: Enviando datos de impresión...\n"
-
-#, c-format
-msgid "INFO: Sent print file, %ld bytes...\n"
-msgstr "INFO: Archivo de impresión enviado, %ld bytes...\n"
-
-#, c-format
-msgid "INFO: Sent print file, %lld bytes...\n"
-msgstr "INFO: Archivo de impresión enviado, %lld bytes...\n"
-
-#, c-format
-msgid "INFO: Spooling LPR job, %.0f%% complete...\n"
-msgstr "INFO: Guardando trabajo LPR en cola, %.0f%% completado...\n"
-
-#, c-format
-msgid "INFO: Starting page %d...\n"
-msgstr "INFO: Iniciando página %d...\n"
-
-msgid "INFO: Unable to contact printer, queuing on next printer in class...\n"
-msgstr ""
-"INFO: No se ha podido contactar con la impresora; poniendo en cola en la "
-"siguiente impresora de la clase...\n"
-
-#, c-format
-msgid "INFO: Using default AppleTalk zone \"%s\"\n"
-msgstr "INFO: Usando zona AppleTalk predeterminada \"%s\"\n"
-
-msgid "INFO: Waiting for job to complete...\n"
-msgstr "INFO: Esperando a que finalice el trabajo...\n"
-
-msgid "INFO: Waiting for printer to become available...\n"
-msgstr "INFO: Esperando a que la impresora esté disponible...\n"
-
-msgid "ISO B0"
-msgstr "ISO B0"
-
-msgid "ISO B1"
-msgstr "ISO B1"
-
-msgid "ISO B10"
-msgstr "ISO B10"
-
-msgid "ISO B2"
-msgstr "ISO B2"
-
-msgid "ISO B3"
-msgstr "ISO B3"
-
-msgid "ISO B4"
-msgstr "ISO B4"
-
-msgid "ISO B4 Envelope"
-msgstr "Sobre ISO B4"
-
-msgid "ISO B5"
-msgstr "ISO B5"
-
-msgid "ISO B5 (Oversize)"
-msgstr "ISO B5 (extragrande)"
-
-msgid "ISO B5 Envelope"
-msgstr "Sobre ISO B5"
-
-msgid "ISO B6"
-msgstr "ISO B6"
-
-msgid "ISO B6 Envelope"
-msgstr "Sobre ISO B6"
-
-msgid "ISO B7"
-msgstr "ISO B7"
-
-msgid "ISO B8"
-msgstr "ISO B8"
-
-msgid "ISO B9"
-msgstr "ISO B9"
-
+#: ppdc/sample.c:1
msgid "ISOLatin1"
msgstr "UTF-8"
+#: cups/ppd.c:353
msgid "Illegal control character"
msgstr "Carácter de control ilegal"
+#: cups/ppd.c:354
msgid "Illegal main keyword string"
msgstr "Cadena de clave principal ilegal"
+#: cups/ppd.c:355
msgid "Illegal option keyword string"
msgstr "Cadena de clave de opción ilegal"
+#: cups/ppd.c:356
msgid "Illegal translation string"
msgstr "Cadena de traducción ilegal"
+#: cups/ppd.c:357
msgid "Illegal whitespace character"
msgstr "Carácter de espacio en blanco ilegal"
+#: ppdc/sample.c:283
msgid "Installable Options"
msgstr "Opciones instalables"
+#: ppdc/sample.c:286
msgid "Installed"
msgstr "Instalada"
+#: ppdc/sample.c:302
msgid "IntelliBar Label Printer"
msgstr "Impresora de etiquetas IntelliBar"
+#: ppdc/sample.c:301
msgid "Intellitech"
msgstr "Intellitech"
+#: cups/http-support.c:1303
msgid "Internal Server Error"
msgstr "Error interno del servidor"
+#: cups/ppd.c:344
msgid "Internal error"
msgstr "Error interno"
+#: ppdc/sample.c:167
msgid "Internet Postage 2-Part"
msgstr "Correo por Internet Parte-2"
+#: ppdc/sample.c:176
msgid "Internet Postage 2-Part - 2 1/4 x 7 1/2\""
msgstr "Correo por Internet Parte-2 - 2 1/4 x 7 1/2 pulg."
+#: ppdc/sample.c:168
msgid "Internet Postage 3-Part"
msgstr "Correo por Internet Parte-3"
+#: ppdc/sample.c:177
msgid "Internet Postage 3-Part - 2 1/4 x 7\""
msgstr "Correo por Internet Parte-3 - 2 1/4 x 7 pulg."
+#: backend/ipp.c:294
msgid "Internet Printing Protocol"
msgstr "Protocolo de Impresión de Internet IPP"
-msgid "Invite Envelope"
-msgstr "Sobre de invitación"
-
-msgid "Italian Envelope"
-msgstr "Sobre Italiano"
-
+#: cups/ppd.c:1380
msgid "JCL"
msgstr "JCL"
-#, c-format
-msgid "Job #%d cannot be restarted - no files"
-msgstr ""
-
-#, c-format
-msgid "Job #%d does not exist"
-msgstr ""
-
+#: ppdc/sample.c:53
+msgid "JIS B0"
+msgstr "JIS B0"
+
+#: ppdc/sample.c:55
+msgid "JIS B1"
+msgstr "JIS B1"
+
+#: ppdc/sample.c:54
+msgid "JIS B10"
+msgstr "JIS B10"
+
+#: ppdc/sample.c:56
+msgid "JIS B2"
+msgstr "JIS B2"
+
+#: ppdc/sample.c:57
+msgid "JIS B3"
+msgstr "JIS B3"
+
+#: ppdc/sample.c:58
+msgid "JIS B4"
+msgstr "JIS B4"
+
+#: ppdc/sample.c:59
+msgid "JIS B4 Long Edge"
+msgstr "JIS B4 lado largo"
+
+#: ppdc/sample.c:60
+msgid "JIS B5"
+msgstr "JIS B5"
+
+#: ppdc/sample.c:61
+msgid "JIS B5 Long Edge"
+msgstr "JIS B5 lado largo"
+
+#: ppdc/sample.c:62
+msgid "JIS B6"
+msgstr "JIS B6"
+
+#: ppdc/sample.c:63
+msgid "JIS B6 Long Edge"
+msgstr "JIS B6 lado largo"
+
+#: ppdc/sample.c:64
+msgid "JIS B7"
+msgstr "JIS B7"
+
+#: ppdc/sample.c:65
+msgid "JIS B8"
+msgstr "JIS B8"
+
+#: ppdc/sample.c:66
+msgid "JIS B9"
+msgstr "JIS B9"
+
+#: scheduler/ipp.c:10228
+#, c-format
+msgid "Job #%d cannot be restarted - no files."
+msgstr "El trabajo #%d no puede ser reiniciado - no hay archivos."
+
+#: scheduler/ipp.c:4076
+#: scheduler/ipp.c:4307
+#: scheduler/ipp.c:4362
+#: scheduler/ipp.c:4539
+#: scheduler/ipp.c:4982
+#: scheduler/ipp.c:6902
+#: scheduler/ipp.c:7280
+#: scheduler/ipp.c:7427
+#: scheduler/ipp.c:7727
+#: scheduler/ipp.c:8676
+#: scheduler/ipp.c:8698
+#: scheduler/ipp.c:8870
+#: scheduler/ipp.c:9079
+#: scheduler/ipp.c:9122
+#: scheduler/ipp.c:9971
+#: scheduler/ipp.c:10196
+#: scheduler/ipp.c:10523
+#: scheduler/ipp.c:11113
+#, c-format
+msgid "Job #%d does not exist."
+msgstr "El trabajo #%d no existe."
+
+#: scheduler/ipp.c:4571
#, c-format
msgid "Job #%d is already aborted - can't cancel."
msgstr "El trabajo #%d ya está anulado - no se puede cancelar."
+#: scheduler/ipp.c:4565
#, c-format
msgid "Job #%d is already canceled - can't cancel."
msgstr "El trabajo #%d ya está cancelado - no se puede cancelar."
+#: scheduler/ipp.c:4577
#, c-format
msgid "Job #%d is already completed - can't cancel."
msgstr "El trabajo #%d ya ha sido completado - no se puede cancelar."
+#: scheduler/ipp.c:9164
+#: scheduler/ipp.c:11128
#, c-format
-msgid "Job #%d is finished and cannot be altered"
-msgstr ""
-
-#, c-format
-msgid "Job #%d is not complete"
-msgstr ""
-
-#, c-format
-msgid "Job #%d is not held"
-msgstr ""
+msgid "Job #%d is finished and cannot be altered."
+msgstr "El trabajo #%d ha terminado y no puede ser modificado."
+#: scheduler/ipp.c:10210
#, c-format
-msgid "Job #%d is not held for authentication"
-msgstr ""
+msgid "Job #%d is not complete."
+msgstr "El trabajo #%d no ha sido completado."
+#: scheduler/ipp.c:4091
#, c-format
-msgid "Job #%s does not exist"
-msgstr ""
+msgid "Job #%d is not held for authentication."
+msgstr "El trabajo #%d no está retenido para autentificación."
+#: scheduler/ipp.c:9985
#, c-format
-msgid "Job %d not found"
-msgstr ""
+msgid "Job #%d is not held."
+msgstr "El trabajo #%d no está retenido."
+#: cgi-bin/ipp-var.c:1055
msgid "Job Completed"
msgstr "Trabajo completado"
+#: cgi-bin/ipp-var.c:1053
msgid "Job Created"
msgstr "Trabajo creado"
+#: filter/bannertops.c:623
msgid "Job ID: "
msgstr "ID del trabajo: "
+#: cgi-bin/ipp-var.c:1059
msgid "Job Options Changed"
msgstr "Opciones de trabajo cambiadas"
+#: cgi-bin/ipp-var.c:1057
msgid "Job Stopped"
msgstr "Trabajo detenido"
+#: filter/bannertops.c:631
msgid "Job UUID: "
msgstr "UUID del trabajo: "
+#: scheduler/ipp.c:11211
msgid "Job is completed and cannot be changed."
msgstr "El trabajo está terminado y no puede ser cambiado."
+#: cgi-bin/jobs.c:198
msgid "Job operation failed:"
msgstr "La operación del trabajo ha fallado:"
+#: scheduler/ipp.c:11247
+#: scheduler/ipp.c:11266
+#: scheduler/ipp.c:11277
msgid "Job state cannot be changed."
msgstr "No se puede cambiar el estado del trabajo."
-msgid "Job subscriptions cannot be renewed"
-msgstr ""
+#: scheduler/ipp.c:10076
+msgid "Job subscriptions cannot be renewed."
+msgstr "Las suscripciones de trabajos no han podido ser renovadas."
+#: cgi-bin/jobs.c:103
+#: cgi-bin/jobs.c:114
+#: cgi-bin/jobs.c:195
msgid "Jobs"
msgstr "Trabajos"
-msgid "Kaku2 Envelope"
-msgstr "Sobre Kaku2"
-
-msgid "Kaku3 Envelope"
-msgstr "Sobre Kaku3"
-
+#: backend/lpd.c:185
msgid "LPD/LPR Host or Printer"
msgstr "Equipo o impresora LPD/LPR"
+#: ppdc/sample.c:239
msgid "Label Printer"
msgstr "Impresora de etiquetas"
+#: ppdc/sample.c:455
msgid "Label Top"
msgstr "Parte superior de la etiqueta"
+#: scheduler/ipp.c:2215
+#: scheduler/ipp.c:6825
#, c-format
-msgid "Language \"%s\" not supported"
-msgstr ""
+msgid "Language \"%s\" not supported."
+msgstr "No se admite el uso del idioma \"%s\"."
+#: ppdc/sample.c:164
msgid "Large Address"
msgstr "Dirección grande"
+#: ppdc/sample.c:173
msgid "Large Address - 1 4/10 x 3 1/2\""
msgstr "Dirección grande - 1 4/10 x 3 1/2 pulg."
+#: ppdc/sample.c:300
msgid "LaserJet Series PCL 4/5"
msgstr "LaserJet Series PCL 4/5"
+#: ppdc/sample.c:43
+msgid "Letter Oversize"
+msgstr "Carta Extragrande"
+
+#: ppdc/sample.c:44
+msgid "Letter Oversize Long Edge"
+msgstr "Carta Extragrande lado largo"
+
+#: ppdc/sample.c:245
msgid "Light"
msgstr "Ligero"
+#: cups/ppd.c:352
msgid "Line longer than the maximum allowed (255 characters)"
msgstr "LÃnea más larga que el máximo permitido (255 caracteres)"
+#: cgi-bin/admin.c:2468
msgid "List Available Printers"
msgstr "Listar impresoras disponibles"
+#: filter/imagetoraster.c:667
+msgid "Loading print file."
+msgstr "Cargando archivo de impresión."
+
+#: filter/bannertops.c:744
msgid "Location: "
msgstr "Ubicación: "
+#: ppdc/sample.c:281
msgid "Long-Edge (Portrait)"
msgstr "Lado largo (retrato)"
+#: cups/http-support.c:1518
+msgid "Looking for printer."
+msgstr "Buscando impresora."
+
+#: filter/bannertops.c:753
msgid "Make and Model: "
msgstr "Marca y modelo: "
+#: ppdc/sample.c:277
msgid "Manual Feed"
msgstr "Alimentación manual"
+#: filter/bannertops.c:780
msgid "Media Dimensions: "
msgstr "Dimensiones del papel: "
+#: filter/bannertops.c:800
msgid "Media Limits: "
msgstr "LÃmites del papel: "
+#: filter/bannertops.c:769
msgid "Media Name: "
msgstr "Nombre del soporte: "
+#: cups/ppd.c:748
+#: cups/ppd.c:1317
msgid "Media Size"
msgstr "Tamaño de papel"
+#: cups/ppd.c:752
+#: cups/ppd.c:1321
+#: ppdc/sample.c:271
msgid "Media Source"
msgstr "Fuente del papel"
+#: ppdc/sample.c:373
msgid "Media Tracking"
msgstr "Seguimiento del medio"
+#: cups/ppd.c:750
+#: cups/ppd.c:1319
+#: ppdc/sample.c:294
msgid "Media Type"
msgstr "Tipo de papel"
+#: ppdc/sample.c:246
msgid "Medium"
msgstr "Media"
+#: cups/ppd.c:341
msgid "Memory allocation error"
msgstr "Error de reserva de memoria"
+#: cups/ppd.c:361
+msgid "Missing CloseGroup"
+msgstr "Falta CloseGroup"
+
+#: cups/ppd.c:342
msgid "Missing PPD-Adobe-4.x header"
msgstr "Falta cabecera PPD-Adobe-4.x"
+#: cups/ppd.c:351
msgid "Missing asterisk in column 1"
msgstr "Falta un asterisco en la columna 1"
-msgid "Missing document-number attribute"
-msgstr ""
+#: scheduler/ipp.c:7303
+msgid "Missing document-number attribute."
+msgstr "Falta el atributo document-number."
+#: cups/adminutil.c:273
#, c-format
-msgid "Missing double quote on line %d"
-msgstr ""
+msgid "Missing double quote on line %d."
+msgstr "Faltan dobles comillas en lÃnea %d."
+#: cgi-bin/admin.c:737
+#: cgi-bin/admin.c:2180
+#: cgi-bin/admin.c:2265
+#: cgi-bin/admin.c:2904
+#: cgi-bin/admin.c:3158
+#: cgi-bin/admin.c:3269
+#: cgi-bin/admin.c:3979
msgid "Missing form variable"
-msgstr ""
+msgstr "Falta una variable de formulario"
-msgid "Missing notify-subscription-ids attribute"
-msgstr ""
+#: cups/pwg-media.c:473
+msgid "Missing media or media-col."
+msgstr "Falta media o media-col."
+#: cups/pwg-media.c:392
+msgid "Missing media-size in media-col."
+msgstr "Falta media-size en media-col."
+
+#: scheduler/ipp.c:7857
+msgid "Missing notify-subscription-ids attribute."
+msgstr "Falta el atributo notify-subscription-ids."
+
+#: cups/ppd.c:359
msgid "Missing option keyword"
-msgstr ""
+msgstr "Falta cadena de clave de opción"
-msgid "Missing requesting-user-name attribute"
-msgstr ""
+#: scheduler/ipp.c:4218
+#: scheduler/ipp.c:4243
+msgid "Missing requesting-user-name attribute."
+msgstr "Falta el atributo requesting-user-name."
-msgid "Missing required attributes"
-msgstr ""
+#: scheduler/ipp.c:488
+msgid "Missing required attributes."
+msgstr "Faltan atributos necesarios."
+#: filter/bannertops.c:222
#, c-format
-msgid "Missing value on line %d"
-msgstr ""
+msgid "Missing value on line %d of banner file."
+msgstr "Falta un valor en la lÃnea %d del archivo de rótulo."
+
+#: cups/adminutil.c:254
+#, c-format
+msgid "Missing value on line %d."
+msgstr "Falta un valor en la lÃnea %d."
+#: cups/ppd.c:343
msgid "Missing value string"
msgstr "Falta cadena de valores"
+#: cups/pwg-media.c:380
+msgid "Missing x-dimension in media-size."
+msgstr "Falta x-dimension en media-size."
+
+#: cups/pwg-media.c:386
+msgid "Missing y-dimension in media-size."
+msgstr "Falta y-dimension en media-size."
+
+#: systemv/lpinfo.c:470
#, c-format
msgid ""
"Model: name = %s\n"
" natural_language = %s\n"
" make-and-model = %s\n"
-" device-id = %s\n"
+" device-id = %s"
msgstr ""
"Modelo: nombre = %s\n"
" natural_language = %s\n"
" make-and-model = %s\n"
-" device-id = %s\n"
+" device-id = %s"
+#: cgi-bin/admin.c:570
msgid "Modify Class"
msgstr "Modificar clase"
+#: cgi-bin/admin.c:883
msgid "Modify Printer"
msgstr "Modificar impresora"
-msgid "Monarch"
-msgstr "Monarch"
-
-msgid "Monarch Envelope"
-msgstr "Sobre Monarch"
-
+#: cgi-bin/ipp-var.c:425
+#: cgi-bin/ipp-var.c:516
msgid "Move All Jobs"
msgstr "Mover todos los trabajos"
+#: cgi-bin/ipp-var.c:364
+#: cgi-bin/ipp-var.c:423
+#: cgi-bin/ipp-var.c:514
msgid "Move Job"
msgstr "Mover trabajo"
+#: cups/http-support.c:1260
msgid "Moved Permanently"
msgstr "Movido permanentemente"
-#, c-format
-msgid "NOTICE: Print file accepted - job ID %d.\n"
-msgstr "NOTICE: Archivo de impresión aceptado: ID de trabajo %d.\n"
-
-msgid "NOTICE: Print file accepted - job ID unknown.\n"
-msgstr "NOTICE: Archivo de impresión aceptado: ID de trabajo desconocido.\n"
-
+#: cups/ppd.c:340
msgid "NULL PPD file pointer"
msgstr "Puntero de archivo PPD NULO"
+#: cups/snmp.c:1053
msgid "Name OID uses indefinite length"
msgstr "Nombre OID usa una longitud indefinida"
-msgid "Nested classes are not allowed"
-msgstr ""
+#: scheduler/ipp.c:1222
+msgid "Nested classes are not allowed."
+msgstr "No se permiten clases anidadas."
+#: ppdc/sample.c:439
msgid "Never"
msgstr "Nunca"
+#: ppdc/sample.c:265
msgid "New Stylus Color Series"
msgstr "Nueva Stylus Color Series"
+#: ppdc/sample.c:267
msgid "New Stylus Photo Series"
msgstr "Nueva Stylus Photo Series"
+#: cups/ppd.c:1909
msgid "No"
msgstr "No"
+#: cups/http-support.c:1257
msgid "No Content"
msgstr "No hay contenido"
+#: cups/util.c:1286
msgid "No PPD name"
-msgstr ""
+msgstr "No hay nombre de PPD"
+#: cups/snmp.c:1047
msgid "No VarBind SEQUENCE"
msgstr "No hay Varbind SEQUENCE"
-msgid "No Windows printer drivers are installed"
-msgstr ""
+#: cups/adminutil.c:788
+msgid "No Windows printer drivers are installed."
+msgstr "No está instalado ningún controlador de impresora de Windows."
+#: cups/request.c:577
+#: cups/request.c:871
msgid "No active connection"
msgstr "No hay conexión activa"
+#: scheduler/ipp.c:4488
#, c-format
-msgid "No active jobs on %s"
-msgstr ""
+msgid "No active jobs on %s."
+msgstr "No hay trabajos activos en %s."
-msgid "No attributes in request"
-msgstr ""
+#: scheduler/ipp.c:329
+msgid "No attributes in request."
+msgstr "No hay atributos en la solicitud."
-msgid "No authentication information provided"
-msgstr ""
+#: scheduler/ipp.c:4119
+msgid "No authentication information provided."
+msgstr "No se ha proporcionado información de autentificación."
+#: cups/snmp.c:1004
msgid "No community name"
msgstr "No hay nombre de comunidad"
-msgid "No default printer"
-msgstr "No hay impresora predeterminada"
+#: scheduler/ipp.c:7103
+msgid "No default printer."
+msgstr "No hay impresora predeterminada."
+#: cgi-bin/ipp-var.c:436
+#: scheduler/ipp.c:8433
msgid "No destinations added."
msgstr "No se han añadido destinos."
+#: backend/usb.c:200
+msgid "No device URI found in argv[0] or in DEVICE_URI environment variable."
+msgstr "No se ha encontrado el URI del dispositivo en argv[0] o en la variable de entorno DEVICE_URI."
+
+#: cups/snmp.c:1034
msgid "No error-index"
msgstr "No hay error-index"
+#: cups/snmp.c:1026
msgid "No error-status"
msgstr "No hay error-status"
-msgid "No file!?"
-msgstr ""
+#: scheduler/ipp.c:9368
+#: scheduler/ipp.c:10586
+msgid "No file in print request."
+msgstr "No hay ningún archivo en la petición de impresión."
+#: filter/pstext.c:438
+msgid "No fonts in charset file."
+msgstr "No hay fuentes en el archivo de juego de caracteres."
+
+#: cups/util.c:921
msgid "No modification time"
-msgstr ""
+msgstr "No hay tiempo de modificación"
+#: cups/snmp.c:1051
msgid "No name OID"
msgstr "No hay nombre OID"
+#: driver/rastertoescpx.c:1918
+#: driver/rastertopclx.c:1943
+#: filter/rastertoepson.c:1147
+#: filter/rastertohp.c:876
+#: filter/rastertolabel.c:1302
+msgid "No pages were found."
+msgstr "No se han encontrado páginas."
+
+#: cups/util.c:915
msgid "No printer name"
-msgstr ""
+msgstr "No hay nombre de impresora"
+#: cups/util.c:1789
msgid "No printer-uri found"
-msgstr ""
+msgstr "No se encontró printer-uri"
+#: cups/util.c:1774
msgid "No printer-uri found for class"
-msgstr ""
+msgstr "No se encontró printer-uri para la clase"
-msgid "No printer-uri in request"
-msgstr ""
+#: scheduler/ipp.c:7506
+msgid "No printer-uri in request."
+msgstr "No hay printer-uri en la petición."
+#: cups/snmp.c:1018
msgid "No request-id"
msgstr "No hay request-id"
-msgid "No subscription attributes in request"
-msgstr ""
+#: scheduler/ipp.c:6710
+msgid "No subscription attributes in request."
+msgstr "No hay atributos de subscripción en la solicitud."
+#: scheduler/ipp.c:8769
msgid "No subscriptions found."
msgstr "No se han encontrado subscripciones."
+#: cups/snmp.c:1042
msgid "No variable-bindings SEQUENCE"
msgstr "No hay variable-bindings SEQUENCE"
+#: cups/snmp.c:997
msgid "No version number"
msgstr "No hay número de versión"
+#: ppdc/sample.c:376
msgid "Non-continuous (Mark sensing)"
msgstr "No continuo (sensible a señal)"
+#: ppdc/sample.c:375
msgid "Non-continuous (Web sensing)"
msgstr "No continuo (sensible a web)"
+#: ppdc/sample.c:247
msgid "Normal"
msgstr "Normal"
+#: cups/http-support.c:1279
msgid "Not Found"
msgstr "No encontrado"
+#: cups/http-support.c:1291
msgid "Not Implemented"
msgstr "No implementado"
+#: ppdc/sample.c:285
msgid "Not Installed"
msgstr "No instalado"
+#: cups/http-support.c:1266
msgid "Not Modified"
msgstr "No modificado"
+#: cups/http-support.c:1294
msgid "Not Supported"
msgstr "No permitido"
+#: scheduler/ipp.c:1598
+#: scheduler/ipp.c:11809
msgid "Not allowed to print."
msgstr "No se permite imprimir."
+#: ppdc/sample.c:146
msgid "Note"
msgstr "Nota"
+#: systemv/cupstestdsc.c:433
+msgid "Note: this program only validates the DSC comments, not the PostScript itself."
+msgstr "Nota: este programa sólo valida los comentarios DSC, no los PostScript."
+
+#: cups/http-support.c:1248
+#: cups/ppd.c:338
msgid "OK"
msgstr "OK"
+#: ppdc/sample.c:280
msgid "Off (1-Sided)"
msgstr "Desactivado (1 cara)"
+#: ppdc/sample.c:370
msgid "Oki"
msgstr "Oki"
+#: cgi-bin/help.c:90
+#: cgi-bin/help.c:131
+#: cgi-bin/help.c:141
+#: cgi-bin/help.c:172
msgid "Online Help"
msgstr "Ayuda en lÃnea"
+#: cups/adminutil.c:955
#, c-format
msgid "Open of %s failed: %s"
msgstr "La apertura de %s ha fallado: %s"
+#: cups/ppd.c:346
msgid "OpenGroup without a CloseGroup first"
msgstr "OpenGroup sin un CloseGroup previo"
+#: cups/ppd.c:348
msgid "OpenUI/JCLOpenUI without a CloseUI/JCLCloseUI first"
msgstr "OpenUI/JCLOpenUI sin un CloseUI/JCLCloseUI previo"
+#: cgi-bin/admin.c:3750
msgid "Operation Policy"
msgstr "Directiva de operación"
+#: filter/pstops.c:2223
+#, c-format
+msgid "Option \"%s\" cannot be included via %%%%IncludeFeature."
+msgstr "La opción \"%s\" no puede incluirse via %%%%IncludeFeature."
+
+#: cgi-bin/admin.c:3400
+#: cgi-bin/admin.c:3484
msgid "Options Installed"
msgstr "Opciones instaladas"
+#: scheduler/cupsfilter.c:1440
+#: scheduler/cupsfilter.c:1467
+#: scheduler/main.c:2058
+#: systemv/cupsaddsmb.c:284
+#: systemv/cupsctl.c:209
+#: systemv/cupstestdsc.c:429
+#: systemv/cupstestppd.c:3616
+#: test/ipptool.c:3921
+#: ppdc/ppdc.cxx:437
+#: ppdc/ppdhtml.cxx:174
+#: ppdc/ppdi.cxx:130
+#: ppdc/ppdmerge.cxx:369
+#: ppdc/ppdpo.cxx:254
+msgid "Options:"
+msgstr "Opciones: "
+
+#: filter/bannertops.c:674
msgid "Options: "
msgstr "Opciones: "
+#: cups/ppd-cache.c:152
+msgid "Out of date PPD cache file."
+msgstr "Archivo de caché PPD obsoleto."
+
+#: cups/ppd-cache.c:1313
+msgid "Out of memory."
+msgstr "Sin memoria."
+
+#: cups/ppd.c:754
+#: cups/ppd.c:1323
msgid "Output Mode"
msgstr "Modo de salida"
+#: systemv/lpstat.c:1188
+#: systemv/lpstat.c:1192
#, c-format
-msgid "Output for printer %s is sent to %s\n"
-msgstr "La salida de la impresora %s se ha enviado a %s\n"
+msgid "Output for printer %s is sent to %s"
+msgstr "La salida de la impresora %s se ha enviado a %s"
+#: systemv/lpstat.c:1182
#, c-format
-msgid "Output for printer %s is sent to remote printer %s on %s\n"
-msgstr ""
-"La salida de la impresora %s se ha enviado a la impresora remota %s en %s\n"
+msgid "Output for printer %s is sent to remote printer %s on %s"
+msgstr "La salida de la impresora %s se ha enviado a la impresora remota %s en %s"
+#: systemv/lpstat.c:1206
+#: systemv/lpstat.c:1210
#, c-format
-msgid "Output for printer %s/%s is sent to %s\n"
-msgstr "La salida de la impresora %s/%s se ha enviado a %s\n"
+msgid "Output for printer %s/%s is sent to %s"
+msgstr "La salida de la impresora %s/%s se ha enviado a %s"
+#: systemv/lpstat.c:1200
#, c-format
-msgid "Output for printer %s/%s is sent to remote printer %s on %s\n"
-msgstr ""
-"La salida de la impresora %s/%s se ha enviado a la impresora remota %s en %"
-"s\n"
+msgid "Output for printer %s/%s is sent to remote printer %s on %s"
+msgstr "La salida de la impresora %s/%s se ha enviado a la impresora remota %s en %s"
-msgid "PASS\n"
-msgstr "PASA\n"
+#: systemv/cupstestdsc.c:399
+msgid "PASS"
+msgstr "PASA"
+#: ppdc/sample.c:269
msgid "PCL Laser Printer"
msgstr "Impresora Laser PCL"
-msgid "PRC1 Envelope"
-msgstr "Sobre PRC1"
-
-msgid "PRC10 Envelope"
-msgstr "Sobre PRC10"
-
+#: ppdc/sample.c:149
msgid "PRC16K"
msgstr "PRC16K"
-msgid "PRC2 Envelope"
-msgstr "Sobre PRC2"
-
-msgid "PRC3 Envelope"
-msgstr "Sobre PRC3"
+#: ppdc/sample.c:150
+msgid "PRC16K Long Edge"
+msgstr "PRC16K lado largo"
+#: ppdc/sample.c:151
msgid "PRC32K"
msgstr "PRC32K"
-msgid "PRC32K (Oversize)"
-msgstr "PRC32K (extragrande)"
-
-msgid "PRC4 Envelope"
-msgstr "Sobre PRC4"
-
-msgid "PRC5 Envelope"
-msgstr "Sobre PRC5"
-
-msgid "PRC6 Envelope"
-msgstr "Sobre PRC6"
-
-msgid "PRC7 Envelope"
-msgstr "Sobre PRC7"
+#: ppdc/sample.c:154
+msgid "PRC32K Long Edge"
+msgstr "PRC32K lado largo"
-msgid "PRC8 Envelope"
-msgstr "Sobre PRC8"
+#: ppdc/sample.c:152
+msgid "PRC32K Oversize"
+msgstr "PRC32K Extragrande"
-msgid "PRC9 Envelope"
-msgstr "Sobre PRC9"
+#: ppdc/sample.c:153
+msgid "PRC32K Oversize Long Edge"
+msgstr "PRC32K Extragrande lado largo"
+#: cups/snmp.c:1014
msgid "Packet does not contain a Get-Response-PDU"
msgstr "El paquete no contiene un Get-Response-PDU"
+#: cups/snmp.c:993
msgid "Packet does not start with SEQUENCE"
msgstr "El paquete no empieza por SEQUENCE"
+#: ppdc/sample.c:369
msgid "ParamCustominCutInterval"
msgstr "ParamCustominCutInterval"
+#: ppdc/sample.c:367
msgid "ParamCustominTearInterval"
msgstr "ParamCustominTearInterval"
+#: cups/auth.c:194
+#: cups/auth.c:363
#, c-format
msgid "Password for %s on %s? "
msgstr "¿Contraseña de %s en %s? "
+#: systemv/cupsaddsmb.c:252
#, c-format
msgid "Password for %s required to access %s via SAMBA: "
msgstr "Se requiere la contraseña de %s para acceder a %s vÃa SAMBA: "
+#: cgi-bin/classes.c:167
msgid "Pause Class"
msgstr "Pausar clase"
+#: cgi-bin/printers.c:170
msgid "Pause Printer"
msgstr "Pausar impresora"
+#: ppdc/sample.c:457
msgid "Peel-Off"
msgstr "Despegar"
-msgid "Personal Envelope"
-msgstr "Sobre personal"
-
+#: ppdc/sample.c:160
msgid "Photo"
msgstr "Foto"
+#: ppdc/sample.c:161
msgid "Photo Labels"
msgstr "Foto pequeña"
+#: ppdc/sample.c:295
msgid "Plain Paper"
msgstr "Papel normal"
+#: cgi-bin/admin.c:3418
+#: cgi-bin/admin.c:3699
msgid "Policies"
msgstr "Reglas"
+#: cgi-bin/admin.c:3425
+#: cgi-bin/admin.c:3768
+#: cgi-bin/admin.c:3781
msgid "Port Monitor"
msgstr "Monitor de puerto"
+#: ppdc/sample.c:287
msgid "PostScript Printer"
msgstr "Impresora PostScript"
+#: ppdc/sample.c:147
msgid "Postcard"
msgstr "Postal"
+#: ppdc/sample.c:71
+msgid "Postcard Double "
+msgstr "Postal doble"
+
+#: ppdc/sample.c:72
+msgid "Postcard Double Long Edge"
+msgstr "Postal doble lado largo"
+
+#: ppdc/sample.c:148
+msgid "Postcard Long Edge"
+msgstr "Postal lado largo"
+
+#: ppdc/sample.c:304
msgid "Print Density"
msgstr "Densidad de impresión"
+#: cups/notify.c:82
msgid "Print Job:"
msgstr "Imprimir trabajo:"
+#: ppdc/sample.c:349
msgid "Print Mode"
msgstr "Modo de impresión"
+#: ppdc/sample.c:392
msgid "Print Rate"
msgstr "Tasa de impresión"
+#: cgi-bin/printers.c:179
msgid "Print Self-Test Page"
msgstr "Imprimir página de auto-prueba"
+#: ppdc/sample.c:336
msgid "Print Speed"
msgstr "Velocidad de impresión"
+#: cgi-bin/ipp-var.c:792
msgid "Print Test Page"
msgstr "Imprimir página de prueba"
+#: ppdc/sample.c:365
msgid "Print and Cut"
msgstr "Imprimir y cortar"
+#: ppdc/sample.c:353
msgid "Print and Tear"
msgstr "Imprimir y romper"
+#: backend/ipp.c:1461
+#, c-format
+msgid "Print file accepted - job ID %d."
+msgstr "Archivo de impresión aceptado: ID de trabajo %d."
+
+#: backend/ipp.c:1452
+msgid "Print file accepted - job ID unknown."
+msgstr "Archivo de impresión aceptado: ID de trabajo desconocido."
+
+#: backend/parallel.c:286
+#: backend/socket.c:424
+#: backend/usb-unix.c:195
+msgid "Print file sent."
+msgstr "Archivo de impresión enviado."
+
+#: backend/ipp.c:1416
+msgid "Print file was not accepted."
+msgstr "No se ha aceptado el archivo de impresión."
+
+#: filter/bannertops.c:648
msgid "Printed For: "
msgstr "Impreso para: "
+#: filter/bannertops.c:656
msgid "Printed From: "
msgstr "Impreso desde: "
+#: filter/bannertops.c:876
msgid "Printed On: "
msgstr "Impreso en: "
+#: cgi-bin/ipp-var.c:1047
msgid "Printer Added"
msgstr "Impresora añadida"
+#: ppdc/sample.c:272
msgid "Printer Default"
msgstr "Predeterminado de la impresora"
+#: cgi-bin/ipp-var.c:1051
msgid "Printer Deleted"
msgstr "Impresora borrada"
+#: cgi-bin/ipp-var.c:1049
msgid "Printer Modified"
msgstr "Impresora modificada"
+#: filter/bannertops.c:614
msgid "Printer Name: "
msgstr "Nombre de la impresora: "
+#: cgi-bin/ipp-var.c:1045
msgid "Printer Paused"
msgstr "Impresora en pausa"
+#: ppdc/sample.c:303
msgid "Printer Settings"
msgstr "Configuración de la impresora"
+#: backend/usb-unix.c:132
+msgid "Printer busy, will retry in 10 seconds."
+msgstr "Impresora ocupada; reintento en 10 segundos."
+
+#: backend/parallel.c:234
+#: backend/serial.c:256
+msgid "Printer busy; will retry in 30 seconds."
+msgstr "Impresora ocupada; reintento en 30 segundos."
+
+#: backend/lpd.c:617
+#: backend/lpd.c:1005
+#: backend/lpd.c:1092
+#: backend/lpd.c:1147
+#, c-format
+msgid "Printer did not respond after %d seconds."
+msgstr "La impresora no respondió tras %d segundos."
+
+#: backend/ipp.c:869
+#: backend/ipp.c:876
+#, c-format
+msgid "Printer does not support IPP/%d.%d, trying IPP/%s."
+msgstr "La impresora no es compatible con IPP/%d.%d, probando IPP/%s."
+
+#: backend/usb-unix.c:429
+#: backend/usb-unix.c:513
+msgid "Printer is busy, will retry in 5 seconds."
+msgstr "La impresora está ocupada, reintento en 5 segundos."
+
+#: backend/runloop.c:253
+#: backend/runloop.c:371
+msgid "Printer is not currently connected."
+msgstr "La impresora está sin conexión en estos momentos."
+
+#: backend/runloop.c:392
+msgid "Printer is now connected."
+msgstr "La impresora ya tiene conexión."
+
+#: backend/usb-darwin.c:1314
+msgid "Printer is now online."
+msgstr "La impresora ya está en lÃnea."
+
+#: backend/usb-darwin.c:1335
+msgid "Printer is offline."
+msgstr "La impresora está fuera de lÃnea."
+
+#: backend/usb-unix.c:139
+msgid "Printer not connected, will retry in 30 seconds."
+msgstr "Impresora no conectada, reintento en 30 segundos."
+
+#: backend/parallel.c:240
+msgid "Printer not connected; will retry in 30 seconds."
+msgstr "Impresora no conectada; reintento en 30 segundos."
+
+#: cups/notify.c:126
msgid "Printer:"
msgstr "Impresora:"
+#: cgi-bin/printers.c:204
+#: cgi-bin/printers.c:332
msgid "Printers"
msgstr "Impresoras"
+#: driver/rastertoescpx.c:1882
+#: driver/rastertopclx.c:1904
+#: filter/rastertoepson.c:1093
+#: filter/rastertohp.c:817
+#: filter/rastertolabel.c:1249
+#, c-format
+msgid "Printing page %d, %d%% complete."
+msgstr "Imprimiendo página %d, %d%% completado."
+
+#: filter/imagetops.c:817
+#, c-format
+msgid "Printing page %d."
+msgstr "Imprimiendo página %d."
+
+#: cgi-bin/classes.c:173
+#: cgi-bin/printers.c:176
msgid "Purge Jobs"
msgstr "Purgar trabajos"
+#: ppdc/sample.c:155
msgid "Quarto"
msgstr "Quarto"
+#: scheduler/ipp.c:1593
+#: scheduler/ipp.c:11804
msgid "Quota limit reached."
msgstr "Se ha alcanzado el lÃmite de cuota."
-msgid "Rank Owner Job File(s) Total Size\n"
-msgstr "Rango Propiet. Trabajo Archivo(s) Tamaño total\n"
-
-msgid ""
-"Rank Owner Pri Job Files Total Size\n"
-msgstr ""
-"Rango Propiet. Pri Trabajo Archivos Tamaño total\n"
-
+#: berkeley/lpq.c:515
+msgid "Rank Owner Job File(s) Total Size"
+msgstr "Rango Propiet. Trabajo Archivo(s) Tamaño total"
+
+#. TRANSLATORS: Pri is job priority.
+#: berkeley/lpq.c:511
+msgid "Rank Owner Pri Job Files Total Size"
+msgstr "Rango Propiet. Pri Trabajo Archivos Tamaño total"
+
+#: backend/ipp.c:1774
+#: backend/socket.c:475
+#: driver/rastertoescpx.c:1923
+#: driver/rastertopclx.c:1948
+#: filter/rastertoepson.c:1152
+#: filter/rastertohp.c:881
+#: filter/rastertolabel.c:1307
+msgid "Ready to print."
+msgstr "Lista para imprimir."
+
+#: cgi-bin/classes.c:171
+#: cgi-bin/printers.c:174
msgid "Reject Jobs"
msgstr "Rechazar trabajos"
+#: backend/lpd.c:1015
+#: backend/lpd.c:1157
+#, c-format
+msgid "Remote host did not accept control file (%d)."
+msgstr "El ordenador remoto no ha aceptado el archivo de control (%d)."
+
+#: backend/lpd.c:1105
+#, c-format
+msgid "Remote host did not accept data file (%d)."
+msgstr "El ordenador remoto no ha aceptado el archivo de datos (%d)."
+
+#: ppdc/sample.c:437
msgid "Reprint After Error"
msgstr "Volver a imprimir tras un error"
+#: cups/http-support.c:1282
msgid "Request Entity Too Large"
msgstr "La entidad requerida es demasiado larga"
+#: cups/ppd.c:756
+#: cups/ppd.c:1325
+#: ppdc/sample.c:240
msgid "Resolution"
msgstr "Resolución"
+#: cgi-bin/classes.c:165
msgid "Resume Class"
msgstr "Reanudar clase"
+#: cgi-bin/printers.c:167
msgid "Resume Printer"
msgstr "Reanudar impresora"
+#: ppdc/sample.c:165
msgid "Return Address"
msgstr "Remite"
+#: ppdc/sample.c:174
msgid "Return Address - 3/4 x 2\""
msgstr "Remite - 3/4 x 2 pulg."
+#: ppdc/sample.c:458
msgid "Rewind"
msgstr "Rebobinar"
+#: cups/adminutil.c:2169
#, c-format
-msgid "Running command: %s %s -N -A %s -c '%s'\n"
-msgstr "Ejecutando comando: %s %s -N -A '%s -c '%s'\n"
+msgid "Running command: %s %s -N -A %s -c '%s'"
+msgstr "Ejecutando comando: %s %s -N -A %s -c '%s'"
+#: cups/snmp.c:995
msgid "SEQUENCE uses indefinite length"
msgstr "SEQUENCE usa una longitud indefinida"
+#: cups/http-support.c:1306
+msgid "SSL/TLS Negotiation Error"
+msgstr "Error en negociación SSL/TLS"
+
+#: cups/http-support.c:1263
msgid "See Other"
msgstr "Ver otros"
+#: backend/usb-darwin.c:543
+msgid "Sending data to printer."
+msgstr "Enviando datos a la impresora."
+
+#: backend/serial.c:783
+#: backend/serial.c:942
+#: backend/serial.c:1064
+#: backend/serial.c:1158
#, c-format
msgid "Serial Port #%d"
msgstr "Puerto serie #%d"
+#: cgi-bin/ipp-var.c:1061
msgid "Server Restarted"
msgstr "Servidor reiniciado"
+#: cgi-bin/ipp-var.c:1067
msgid "Server Security Auditing"
msgstr "AuditorÃa de seguridad del servidor"
+#: cgi-bin/ipp-var.c:1063
msgid "Server Started"
msgstr "Servidor iniciado"
+#: cgi-bin/ipp-var.c:1065
msgid "Server Stopped"
msgstr "Servidor parado"
+#: cups/http-support.c:1300
msgid "Service Unavailable"
msgstr "Servicio no disponible"
+#: cgi-bin/admin.c:2905
+#: cgi-bin/admin.c:2951
+#: cgi-bin/admin.c:3108
+#: cgi-bin/admin.c:3127
msgid "Set Allowed Users"
msgstr "Establecer usuarios permitidos"
+#: cgi-bin/admin.c:3154
msgid "Set As Server Default"
msgstr "Establecer como predeterminada del servidor"
+#: cgi-bin/admin.c:3254
msgid "Set Class Options"
msgstr "Cambiar opciones clase"
+#: cgi-bin/admin.c:3254
+#: cgi-bin/admin.c:3428
+#: cgi-bin/admin.c:3810
msgid "Set Printer Options"
msgstr "Cambiar opciones impresora"
+#: cgi-bin/admin.c:3980
+#: cgi-bin/admin.c:4024
+#: cgi-bin/admin.c:4042
msgid "Set Publishing"
msgstr "Hacer pública"
+#: ppdc/sample.c:166
msgid "Shipping Address"
msgstr "Dirección de envÃo"
+#: ppdc/sample.c:175
msgid "Shipping Address - 2 5/16 x 4\""
msgstr "Dirección de envÃo - 2 5/16 x 4 pulg."
+#: ppdc/sample.c:282
msgid "Short-Edge (Landscape)"
msgstr "Lado corto (apaisado)"
+#: ppdc/sample.c:297
msgid "Special Paper"
msgstr "Papel especial"
+#: backend/lpd.c:1056
+#, c-format
+msgid "Spooling job, %.0f%% complete."
+msgstr "Guardando trabajo en cola, %.0f%% completado."
+
+#: ppdc/sample.c:350
msgid "Standard"
msgstr "Estándar"
+#. TRANSLATORS: Banner/cover sheet before the print job.
+#: cgi-bin/admin.c:3671
msgid "Starting Banner"
msgstr "Rótulo inicial"
+#: driver/rastertoescpx.c:1866
+#: driver/rastertopclx.c:1887
+#: filter/rastertoepson.c:1069
+#: filter/rastertohp.c:793
+#: filter/rastertolabel.c:1225
+#, c-format
+msgid "Starting page %d."
+msgstr "Iniciando página %d."
+
+#: ppdc/sample.c:156
msgid "Statement"
msgstr "Declaración"
+#: ppdc/sample.c:260
msgid "Stylus Color Series"
msgstr "Stylus Color Series"
+#: ppdc/sample.c:266
msgid "Stylus Photo Series"
msgstr "Stylus Photo Series"
+#: scheduler/ipp.c:4634
+#: scheduler/ipp.c:7873
+#: scheduler/ipp.c:8582
+#: scheduler/ipp.c:10064
+#, c-format
+msgid "Subscription #%d does not exist."
+msgstr "Subscripción #%d no existe."
+
+#: ppdc/sample.c:157
msgid "Super A"
msgstr "Super A"
+#: ppdc/sample.c:158
msgid "Super B"
msgstr "Super B (13 x 19 pulg.)"
+#: ppdc/sample.c:162
msgid "Super B/A3"
msgstr "Super B/A3"
+#: cups/http-support.c:1245
msgid "Switching Protocols"
msgstr "Protocolos de conexión"
+#: ppdc/sample.c:159
msgid "Tabloid"
msgstr "Tabloide"
-msgid "Tabloid (Oversize)"
-msgstr "Tabloide (extragrande)"
+#: ppdc/sample.c:45
+msgid "Tabloid Oversize"
+msgstr "Tabloide Extragrande"
+#: ppdc/sample.c:46
+msgid "Tabloid Oversize Long Edge"
+msgstr "Tabloide Extragrande lado largo"
+
+#: ppdc/sample.c:351
msgid "Tear"
msgstr "Pestaña"
+#: ppdc/sample.c:456
msgid "Tear-Off"
msgstr "Pestaña desprendible"
+#: ppdc/sample.c:397
msgid "Tear-Off Adjust Position"
msgstr "Ajuste de posición de la pestaña desprendible"
+#: scheduler/ipp.c:7577
+#: scheduler/ipp.c:7655
+#: scheduler/ipp.c:7671
+#: scheduler/ipp.c:7689
+#, c-format
+msgid "The %s attribute cannot be provided with job-ids."
+msgstr "El atributo %s no puede ser usado con jobs-ids."
+
+#: scheduler/ipp.c:8104
#, c-format
msgid "The PPD file \"%s\" could not be found."
msgstr "No se ha podido encontrar el archivo PPD \"%s\"."
+#: scheduler/ipp.c:8091
#, c-format
msgid "The PPD file \"%s\" could not be opened: %s"
msgstr "No se ha podido abrir el archivo PPD \"%s\": %s"
-msgid ""
-"The class name may only contain up to 127 printable characters and may not "
-"contain spaces, slashes (/), or the pound sign (#)."
-msgstr ""
-"El nombre de la clase sólo puede contener hasta 127 caracteres imprimibles y "
-"no puede contener espacios, barras (/), o la almohadilla (#)."
+#: driver/rastertoescpx.c:1794
+#: driver/rastertopclx.c:1819
+#: filter/rastertoepson.c:1038
+#: filter/rastertohp.c:764
+#: filter/rastertolabel.c:1189
+msgid "The PPD file could not be opened."
+msgstr "No se ha podido abrir el archivo PPD."
+
+#: cgi-bin/admin.c:750
+msgid "The class name may only contain up to 127 printable characters and may not contain spaces, slashes (/), or the pound sign (#)."
+msgstr "El nombre de la clase sólo puede contener hasta 127 caracteres imprimibles y no puede contener espacios, barras (/), o la almohadilla (#)."
+#: cups/localize.c:353
msgid "The developer unit needs to be replaced."
-msgstr ""
+msgstr "La unidad de revelado debe ser reemplazada"
+#: cups/localize.c:351
msgid "The developer unit will need to be replaced soon."
-msgstr ""
+msgstr "La unidad de revelado necesitará ser cambiada pronto."
+#: cups/localize.c:343
msgid "The fuser's temperature is high."
-msgstr ""
+msgstr "Temperatura del fusor alta"
+#: cups/localize.c:345
msgid "The fuser's temperature is low."
-msgstr ""
+msgstr "Temperatura del fusor baja"
-msgid ""
-"The notify-lease-duration attribute cannot be used with job subscriptions."
-msgstr ""
-"El atributo notify-lease-duration no puede ser usado con subscripciones de "
-"trabajos."
+#: scheduler/ipp.c:2242
+msgid "The notify-lease-duration attribute cannot be used with job subscriptions."
+msgstr "El atributo notify-lease-duration no puede ser usado con subscripciones de trabajos."
+#: scheduler/ipp.c:2225
+#: scheduler/ipp.c:6835
#, c-format
-msgid "The notify-user-data value is too large (%d > 63 octets)"
-msgstr ""
+msgid "The notify-user-data value is too large (%d > 63 octets)."
+msgstr "El valor notify-user-data es demasiado grande (%d > 63 octetos)."
+#: cups/localize.c:349
msgid "The optical photoconductor needs to be replaced."
-msgstr ""
+msgstr "El fotoconductor óptico necesita ser cambiado."
+#: cups/localize.c:347
msgid "The optical photoconductor will need to be replaced soon."
-msgstr ""
+msgstr "El fotoconductor óptico necesitará ser cambiado pronto."
+#: cups/localize.c:331
msgid "The output bin is almost full."
-msgstr ""
+msgstr "Recipiente de salida casi lleno"
+#: cups/localize.c:333
msgid "The output bin is full."
-msgstr ""
+msgstr "Bandeja de salida llena."
+#: cups/localize.c:329
msgid "The output bin is missing."
-msgstr ""
+msgstr "Falta la bandeja de salida."
+#: filter/imagetoraster.c:466
+msgid "The page setup information was not valid."
+msgstr "La información de configuración de página no era válida."
+
+#: cups/localize.c:325
msgid "The paper tray is almost empty."
-msgstr ""
+msgstr "Bandeja de papel casi vacÃa."
+#: cups/localize.c:327
msgid "The paper tray is empty."
-msgstr ""
+msgstr "Bandeja de papel vacÃa."
+#: cups/localize.c:323
msgid "The paper tray is missing."
-msgstr ""
+msgstr "Falta la bandeja de papel."
+#: cups/localize.c:306
msgid "The paper tray needs to be filled."
-msgstr ""
-
-msgid "The printer is almost out of ink."
-msgstr ""
+msgstr "Hay que poner papel en la bandeja."
-msgid "The printer is low on toner."
-msgstr ""
+#: filter/imagetops.c:322
+#: filter/imagetoraster.c:682
+msgid "The print file could not be opened."
+msgstr "No se ha podido abrir el archivo de impresión."
-msgid "The printer is offline."
-msgstr ""
+#: backend/ipp.c:886
+msgid "The printer URI is incorrect or no longer exists."
+msgstr "El URI de la impresora es incorrecto o ya no existe."
+#: cups/localize.c:335
+msgid "The printer is almost out of ink."
+msgstr "La impresora casi no tiene tinta."
+
+#: backend/ipp.c:737
+#: backend/ipp.c:851
+#: backend/ipp.c:952
+#: backend/ipp.c:1247
+#: backend/ipp.c:1396
+#: backend/lpd.c:842
+#: backend/socket.c:374
+msgid "The printer is busy."
+msgstr "La impresora está ocupada."
+
+#: cups/localize.c:313
+msgid "The printer is low on toner."
+msgstr "La impresora tiene poco tóner."
+
+#: cups/localize.c:311
+msgid "The printer is not connected."
+msgstr "La impresora no está conectada."
+
+#: backend/ipp.c:715
+#: backend/ipp.c:748
+#: backend/ipp.c:847
+#: backend/lpd.c:821
+#: backend/lpd.c:862
+#: backend/socket.c:353
+#: backend/socket.c:386
+msgid "The printer is not responding."
+msgstr "La impresora no responde."
+
+#: cups/localize.c:337
msgid "The printer is out of ink."
-msgstr ""
+msgstr "La impresora no tiene tinta."
+#: cups/localize.c:315
msgid "The printer is out of toner."
-msgstr ""
-
-msgid ""
-"The printer name may only contain up to 127 printable characters and may not "
-"contain spaces, slashes (/), or the pound sign (#)."
-msgstr ""
-"El nombre de la impresora sólo puede contener hasta 127 caracteres "
-"imprimibles y no puede contener espacios, barras (/), o la almohadilla (#)."
-
-msgid "The printer or class is not shared"
-msgstr ""
-
-msgid "The printer or class was not found."
-msgstr "No se ha encontrado la impresora o la clase."
-
+msgstr "La impresora no tiene tóner."
+
+#: backend/ipp.c:730
+#: backend/lpd.c:835
+#: backend/socket.c:367
+msgid "The printer is unreachable at this time."
+msgstr "La impresora es inalcanzable en este momento."
+
+#: backend/ipp.c:724
+#: backend/lpd.c:829
+#: backend/socket.c:361
+msgid "The printer may not exist or is unavailable at this time."
+msgstr "La impresora puede no existir o no estar disponible en este momento."
+
+#: cgi-bin/admin.c:932
+msgid "The printer name may only contain up to 127 printable characters and may not contain spaces, slashes (/), or the pound sign (#)."
+msgstr "El nombre de la impresora sólo puede contener hasta 127 caracteres imprimibles y no puede contener espacios, barras (/), o la almohadilla (#)."
+
+#: scheduler/ipp.c:904
+#: scheduler/ipp.c:1216
+#: scheduler/ipp.c:4283
+#: scheduler/ipp.c:4454
+#: scheduler/ipp.c:6366
+#: scheduler/ipp.c:6669
+#: scheduler/ipp.c:6983
+#: scheduler/ipp.c:7543
+#: scheduler/ipp.c:8309
+#: scheduler/ipp.c:8365
+#: scheduler/ipp.c:8688
+#: scheduler/ipp.c:8938
+#: scheduler/ipp.c:9027
+#: scheduler/ipp.c:9060
+#: scheduler/ipp.c:9383
+#: scheduler/ipp.c:9776
+#: scheduler/ipp.c:9857
+#: scheduler/ipp.c:10982
+#: scheduler/ipp.c:11437
+#: scheduler/ipp.c:11767
+#: scheduler/ipp.c:11849
+#: scheduler/ipp.c:12141
+msgid "The printer or class does not exist."
+msgstr "La impresora o clase no existe."
+
+#: scheduler/ipp.c:1384
+msgid "The printer or class is not shared."
+msgstr "La impresora o clase no está compartida."
+
+#: cups/localize.c:317
msgid "The printer's cover is open."
-msgstr ""
+msgstr "La tapa de la impresora está abierta."
+#: cups/localize.c:321
msgid "The printer's door is open."
-msgstr ""
+msgstr "La puerta de la impresora está abierta."
+#: cups/localize.c:319
msgid "The printer's interlock is open."
-msgstr ""
+msgstr "El dispositivo de seguridad de la impresora está abierto."
+#: cups/localize.c:339
msgid "The printer's waste bin is almost full."
-msgstr ""
+msgstr "Recipiente de residuos de la impresora está casi lleno."
+#: cups/localize.c:341
msgid "The printer's waste bin is full."
-msgstr ""
+msgstr "Recipiente de residuos de la impresora está lleno."
+#: scheduler/ipp.c:1011
+#: scheduler/ipp.c:2407
#, c-format
msgid "The printer-uri \"%s\" contains invalid characters."
-msgstr "El printer-uri \"%s\" contiene caracteres incorrectos."
+msgstr "El printer-uri \"%s\" contiene caracteres no válidos."
-msgid "The printer-uri attribute is required"
-msgstr ""
+#: scheduler/ipp.c:4260
+msgid "The printer-uri attribute is required."
+msgstr "Se necesita el atributo printer-uri."
-msgid ""
-"The printer-uri must be of the form \"ipp://HOSTNAME/classes/CLASSNAME\"."
-msgstr ""
-"El printer-uri debe ser de la forma \"ipp://NOMBRE_ORDENADOR/classes/"
-"NOMBRE_CLASE\"."
+#: scheduler/ipp.c:995
+msgid "The printer-uri must be of the form \"ipp://HOSTNAME/classes/CLASSNAME\"."
+msgstr "El printer-uri debe ser de la forma \"ipp://NOMBRE_ORDENADOR/classes/NOMBRE_CLASE\"."
-msgid ""
-"The printer-uri must be of the form \"ipp://HOSTNAME/printers/PRINTERNAME\"."
-msgstr ""
-"El printer-uri debe ser de la forma \"ipp://NOMBRE_ORDENADOR/printers/"
-"NOMBRE_IMPRESORA\"."
+#: scheduler/ipp.c:2391
+msgid "The printer-uri must be of the form \"ipp://HOSTNAME/printers/PRINTERNAME\"."
+msgstr "El printer-uri debe ser de la forma \"ipp://NOMBRE_ORDENADOR/printers/NOMBRE_IMPRESORA\"."
-msgid ""
-"The subscription name may not contain spaces, slashes (/), question marks "
-"(?), or the pound sign (#)."
-msgstr ""
-"El nombre de la subscripción no puede contener espacios, barras (/), signos "
-"de interrogación (?), o la almohadilla (#)."
+#: cgi-bin/admin.c:474
+msgid "The subscription name may not contain spaces, slashes (/), question marks (?), or the pound sign (#)."
+msgstr "El nombre de la subscripción no puede contener espacios, barras (/), signos de interrogación (?), o la almohadilla (#)."
+
+#: scheduler/client.c:2462
+msgid "The web interface is currently disabled. Run \"cupsctl WebInterface=yes\" to enable it."
+msgstr "La interfaz web está desactivada en este momento. Ejecute \"cupsctl WebInterface=yes\" para activarla."
+
+#: scheduler/ipp.c:7638
+#, c-format
+msgid "The which-jobs value \"%s\" is not supported."
+msgstr "No se admite el uso del valor which-jobs \"%s\"."
+#: scheduler/ipp.c:6913
msgid "There are too many subscriptions."
msgstr "Hay demasiadas subscripciones."
+#: cups/localize.c:308
msgid "There is a paper jam."
-msgstr ""
+msgstr "Hay un atasco de papel."
+#: backend/usb-darwin.c:379
+#: backend/usb-darwin.c:438
+#: backend/usb-darwin.c:505
+#: backend/usb-darwin.c:526
+msgid "There was an unrecoverable USB error."
+msgstr "Ha habido un error USB irrecuperable."
+
+#: ppdc/sample.c:444
msgid "Thermal Transfer Media"
msgstr "Soporte de transferencia térmica"
+#: filter/bannertops.c:640
msgid "Title: "
msgstr "TÃtulo: "
+#: scheduler/ipp.c:1587
msgid "Too many active jobs."
msgstr "Demasiados trabajos activos."
+#: scheduler/ipp.c:1481
#, c-format
-msgid "Too many job-sheets values (%d > 2)"
-msgstr ""
+msgid "Too many job-sheets values (%d > 2)."
+msgstr "Demasiados valores de job-sheets (%d > 2)."
+#: scheduler/ipp.c:2728
#, c-format
-msgid "Too many printer-state-reasons values (%d > %d)"
-msgstr ""
+msgid "Too many printer-state-reasons values (%d > %d)."
+msgstr "Demasiados valores printer-state-reasons (%d > %d)."
+#: ppdc/sample.c:298
msgid "Transparency"
msgstr "Transparencia"
+#: ppdc/sample.c:293
msgid "Tray"
msgstr "Bandeja"
+#: ppdc/sample.c:273
msgid "Tray 1"
msgstr "Bandeja 1"
+#: ppdc/sample.c:274
msgid "Tray 2"
msgstr "Bandeja 2"
+#: ppdc/sample.c:275
msgid "Tray 3"
msgstr "Bandeja 3"
+#: ppdc/sample.c:276
msgid "Tray 4"
msgstr "Bandeja 4"
+#: cups/http-support.c:1285
msgid "URI Too Long"
msgstr "URI demasiado largo"
-msgid "US Executive"
-msgstr "Ejecutivo de EE.UU"
-
-msgid "US Fanfold"
-msgstr "FanFold de EE.UU"
-
+#: ppdc/sample.c:138
msgid "US Ledger"
msgstr "Libro Mayor, 17 x 11 pulg."
+#: ppdc/sample.c:139
msgid "US Legal"
msgstr "Legal EE.UU."
-msgid "US Legal (Oversize)"
-msgstr "Legal EE.UU. (extragrande)"
+#: ppdc/sample.c:140
+msgid "US Legal Oversize"
+msgstr "Legal EE.UU. Extragrande"
+#: ppdc/sample.c:141
msgid "US Letter"
msgstr "Carta EE.UU."
-msgid "US Letter (Oversize)"
-msgstr "Carta EE.UU. (extragrande)"
+#: ppdc/sample.c:142
+msgid "US Letter Long Edge"
+msgstr "Carta EE.UU. lado largo"
-msgid "US Letter (Small)"
-msgstr "Carta EE.UU. (pequeña)"
+#: ppdc/sample.c:143
+msgid "US Letter Oversize"
+msgstr "Carta EE.UU. Extragrande"
+#: ppdc/sample.c:144
+msgid "US Letter Oversize Long Edge"
+msgstr "Carta EE.UU. Extragrande lado largo"
+
+#: ppdc/sample.c:145
+msgid "US Letter Small"
+msgstr "Carta EE.UU. Pequeña"
+
+#: backend/serial.c:796
#, c-format
msgid "USB Serial Port #%d"
msgstr "Puerto serie USB #%d"
+#: cgi-bin/admin.c:2033
+#: cgi-bin/admin.c:2046
+#: cgi-bin/admin.c:2070
msgid "Unable to access cupsd.conf file:"
msgstr "No se ha podido acceder al archivo cupsd.conf"
+#: cgi-bin/admin.c:526
msgid "Unable to add RSS subscription:"
msgstr "No se ha podido añadir la subscripción RSS:"
+#: cgi-bin/admin.c:815
msgid "Unable to add class:"
msgstr "No se ha podido añadir la clase:"
+#: backend/ipp.c:1536
+msgid "Unable to add document to print job."
+msgstr "No se ha podido añadir el documento al trabajo de impresión."
+
+#: scheduler/ipp.c:1628
#, c-format
-msgid "Unable to add job for destination \"%s\""
-msgstr ""
+msgid "Unable to add job for destination \"%s\"."
+msgstr "No se ha podido añadir el trabajo para el destino \"%s\"."
+#: cgi-bin/admin.c:1060
+#: cgi-bin/admin.c:1420
msgid "Unable to add printer:"
msgstr "No se ha podido añadir la impresora:"
-msgid "Unable to allocate memory for file types"
-msgstr ""
+#: scheduler/ipp.c:1326
+msgid "Unable to allocate memory for file types."
+msgstr "No se ha podido reservar memoria para tipos de archivo."
+
+#: filter/pstops.c:456
+msgid "Unable to allocate memory for page info"
+msgstr "No se ha podido reservar memoria para la información de página."
+#: filter/pstops.c:450
+msgid "Unable to allocate memory for pages array"
+msgstr "No se ha podido reservar memoria para la secuencia de páginas"
+
+#: cgi-bin/admin.c:1526
msgid "Unable to cancel RSS subscription:"
msgstr "No se ha podido cancelar la subscripción RSS:"
+#: backend/ipp.c:1816
+msgid "Unable to cancel print job."
+msgstr "No se ha podido cancelar el trabajo de impresión."
+
+#: cgi-bin/admin.c:4025
msgid "Unable to change printer-is-shared attribute:"
msgstr "No se ha podido cambiar el atributo printer-is-shared:"
+#: cgi-bin/admin.c:3109
msgid "Unable to change printer:"
msgstr "No se ha podido cambiar la impresora:"
+#: cgi-bin/admin.c:1710
+#: cgi-bin/admin.c:1874
msgid "Unable to change server settings:"
msgstr "No se ha podido cambiar la configuración del servidor:"
+#: cups/adminutil.c:911
+#: cups/request.c:972
msgid "Unable to connect to host."
msgstr "No se ha podido conectar al servidor."
-#, c-format
-msgid "Unable to copy 64-bit CUPS printer driver files (%d)"
-msgstr ""
+#: cups/http-addrlist.c:172
+msgid "Unable to connect to server"
+msgstr "No se ha podido conectar al servidor"
+#: backend/ipp.c:693
+#: backend/ipp.c:1092
+#: backend/lpd.c:801
+#: backend/parallel.c:219
+#: backend/serial.c:241
+#: backend/socket.c:333
+#: backend/usb-unix.c:117
+msgid "Unable to contact printer, queuing on next printer in class."
+msgstr "No se ha podido contactar con la impresora; poniendo en cola en la siguiente impresora de la clase."
+
+#: cups/adminutil.c:726
#, c-format
-msgid "Unable to copy 64-bit Windows printer driver files (%d)"
-msgstr ""
+msgid "Unable to copy 64-bit CUPS printer driver files (%d)."
+msgstr "No se han podido copiar los archivos del controlador de impresora de 64-bit de CUPS (%d)."
+#: cups/adminutil.c:691
#, c-format
-msgid "Unable to copy CUPS printer driver files (%d)"
-msgstr ""
+msgid "Unable to copy 64-bit Windows printer driver files (%d)."
+msgstr "No se han podido copiar los archivos del controlador de impresora de 64-bit de Windows (%d)."
-msgid "Unable to copy PPD file"
-msgstr ""
+#: cups/adminutil.c:522
+#, c-format
+msgid "Unable to copy CUPS printer driver files (%d)."
+msgstr "No se han podido copiar los archivos del controlador de impresora de CUPS (%d)."
+#: scheduler/ipp.c:2848
#, c-format
msgid "Unable to copy PPD file - %s"
-msgstr ""
+msgstr "No se ha podido copiar el archivo PPD - %s"
+#: scheduler/ipp.c:2903
+msgid "Unable to copy PPD file."
+msgstr "No se ha podido copiar el archivo PPD."
+
+#: cups/adminutil.c:487
#, c-format
-msgid "Unable to copy Windows 2000 printer driver files (%d)"
-msgstr ""
+msgid "Unable to copy Windows 2000 printer driver files (%d)."
+msgstr "No se han podido copiar los archivos del controlador de impresora de Windows 2000 (%d)."
+#: cups/adminutil.c:610
#, c-format
-msgid "Unable to copy Windows 9x printer driver files (%d)"
-msgstr ""
+msgid "Unable to copy Windows 9x printer driver files (%d)."
+msgstr "No se han podido copiar los archivos del controlador de impresora de Windows 9x (%d)."
+#: scheduler/ipp.c:2825
#, c-format
msgid "Unable to copy interface script - %s"
-msgstr ""
+msgstr "No se ha podido copiar el script de interfaz - %s"
+#: filter/imagetops.c:141
+#: filter/imagetoraster.c:301
+msgid "Unable to copy print file"
+msgstr "No se ha podido copiar el archivo de impresión"
+
+#: backend/ipp.c:1905
+msgid "Unable to create compressed print file"
+msgstr "No se ha podido crear el archivo de impresión comprimido"
+
+#: filter/imagetoraster.c:242
+msgid "Unable to create pipes for filters"
+msgstr "No se han podido crear tuberÃas (pipes) para filtros"
+
+#: cups/util.c:601
+#: cups/util.c:1644
msgid "Unable to create printer-uri"
-msgstr ""
+msgstr "No se ha podido crear printer-uri"
+#: scheduler/cupsfilter.c:1244
+msgid "Unable to create temporary file"
+msgstr "No se ha podido crear el archivo temporal"
+
+#: cgi-bin/admin.c:1924
+#: cgi-bin/admin.c:1936
msgid "Unable to create temporary file:"
msgstr "No se ha podido crear el archivo temporal:"
+#: cgi-bin/admin.c:2227
msgid "Unable to delete class:"
msgstr "No se ha podido borrar la clase:"
+#: cgi-bin/admin.c:2312
msgid "Unable to delete printer:"
msgstr "No se ha podido borrar la impresora:"
+#: cgi-bin/classes.c:260
+#: cgi-bin/printers.c:269
msgid "Unable to do maintenance command:"
msgstr "No se ha podido realizar el comando de mantenimiento:"
+#: cgi-bin/admin.c:2048
msgid "Unable to edit cupsd.conf files larger than 1MB"
-msgstr ""
+msgstr "No se pueden editar archivos cupsd.conf mayores de 1MB"
+
+#: cups/http.c:4080
+msgid "Unable to establish a secure connection to host (certificate chain invalid)."
+msgstr "No se ha podido establecer una conexión segura con el servidor (cadena certificado incorrecta)."
+
+#: cups/http.c:4070
+msgid "Unable to establish a secure connection to host (certificate not yet valid)."
+msgstr "No se ha podido establecer una conexión segura con el servidor (el certificado aún no es válido)."
+
+#: cups/http.c:4065
+msgid "Unable to establish a secure connection to host (expired certificate)."
+msgstr "No se ha podido establecer una conexión segura con el servidor (certificado caducado)."
+
+#: cups/http.c:4075
+msgid "Unable to establish a secure connection to host (host name mismatch)."
+msgstr "No se ha podido establecer una conexión segura con el servidor (el nombre de ordenador no coincide)."
+
+#: cups/http.c:4085
+msgid "Unable to establish a secure connection to host (peer dropped connection before responding)."
+msgstr "No se ha podido establecer una conexión segura con el servidor (el par cortó la conexión antes de responder)."
+
+#: cups/http.c:4060
+msgid "Unable to establish a secure connection to host (self-signed certificate)."
+msgstr "No se ha podido establecer una conexión segura con el servidor (certificado auto-firmado)."
+#: cups/http.c:4055
+msgid "Unable to establish a secure connection to host (untrusted certificate)."
+msgstr "No se ha podido establecer una conexión segura con el servidor (certificado no seguro)."
+
+#: cups/http.c:4112
+msgid "Unable to establish a secure connection to host."
+msgstr "No se ha podido establecer una conexión segura al servidor."
+
+#: cgi-bin/ipp-var.c:365
msgid "Unable to find destination for job"
-msgstr ""
+msgstr "No se ha podido encontrar destino para el trabajo"
-msgid "Unable to find printer\n"
-msgstr ""
+#: cups/http-support.c:1631
+msgid "Unable to find printer."
+msgstr "No se ha podido encontrar la impresora."
+#: filter/imagetoraster.c:266
+msgid "Unable to fork filter"
+msgstr "No se ha podido bifurcar (fork) el filtro"
+
+#: backend/ipp.c:1927
+msgid "Unable to generate compressed print file"
+msgstr "No se ha podido crear el archivo de impresión comprimido"
+
+#: backend/ipp.c:2713
+msgid "Unable to get backend exit status."
+msgstr "No se ha podido obtener el estado de salida del programa backend"
+
+#: cgi-bin/classes.c:450
msgid "Unable to get class list:"
msgstr "No se ha podido obtener la lista de clases:"
+#: cgi-bin/classes.c:549
msgid "Unable to get class status:"
msgstr "No se ha podido obtener el estado de la clase:"
+#: cgi-bin/admin.c:1321
msgid "Unable to get list of printer drivers:"
msgstr "No se ha podido obtener la lista de controladores de impresora:"
+#: backend/ipp.c:1625
+msgid "Unable to get print job status."
+msgstr "No se ha podido obtener el estado del trabajo de impresión."
+
+#: cgi-bin/admin.c:2959
msgid "Unable to get printer attributes:"
msgstr "No se han podido obtener los atributos de la impresora:"
+#: cgi-bin/printers.c:467
msgid "Unable to get printer list:"
msgstr "No se ha podido obtener la lista de impresoras:"
+#: backend/ipp.c:905
+msgid "Unable to get printer status."
+msgstr "No se ha podido obtener el estado de la impresora."
+
+#: cgi-bin/printers.c:569
msgid "Unable to get printer status:"
msgstr "No se ha podido obtener el estado de la impresora"
+#: cups/adminutil.c:565
+#: cups/adminutil.c:769
#, c-format
-msgid "Unable to install Windows 2000 printer driver files (%d)"
-msgstr ""
+msgid "Unable to install Windows 2000 printer driver files (%d)."
+msgstr "No se han podido instalar los archivos del controlador de impresora de Windows 2000 (%d)."
+#: cups/adminutil.c:639
#, c-format
-msgid "Unable to install Windows 9x printer driver files (%d)"
-msgstr ""
+msgid "Unable to install Windows 9x printer driver files (%d)."
+msgstr "No se han podido instalar los archivos del controlador de impresora de Windows 9x (%d)."
+
+#: backend/ipp.c:625
+#: backend/lpd.c:419
+#: backend/socket.c:275
+#, c-format
+msgid "Unable to locate printer \"%s\"."
+msgstr "No se ha podido localizar la impresora \"%s\"."
+
+#: backend/dnssd.c:497
+#: backend/ipp.c:311
+#: backend/lpd.c:202
+#: backend/socket.c:171
+msgid "Unable to locate printer."
+msgstr "No se ha podido localizar la impresora."
+#: cgi-bin/admin.c:814
msgid "Unable to modify class:"
msgstr "No se ha podido modificar la clase:"
+#: cgi-bin/admin.c:1059
+#: cgi-bin/admin.c:1419
msgid "Unable to modify printer:"
msgstr "No se ha podido modificar la impresora:"
+#: cgi-bin/ipp-var.c:432
+#: cgi-bin/ipp-var.c:521
msgid "Unable to move job"
msgstr "No se ha podido mover el trabajo"
+#: cgi-bin/ipp-var.c:434
+#: cgi-bin/ipp-var.c:523
msgid "Unable to move jobs"
msgstr "No se han podido mover los trabajos"
+#: cups/ppd.c:339
msgid "Unable to open PPD file"
msgstr "No se ha podido abrir el archivo PPD"
+#: cgi-bin/admin.c:3305
msgid "Unable to open PPD file:"
msgstr "No se ha podido abrir el archivo PPD:"
+#: filter/texttops.c:282
+msgid "Unable to open charset file"
+msgstr "No se ha podido abrir el archivo del juego de caracteres"
+
+#: backend/ipp.c:1911
+msgid "Unable to open compressed print file"
+msgstr "No se ha podido abrir el archivo de impresión comprimido"
+
+#: cgi-bin/admin.c:2683
msgid "Unable to open cupsd.conf file:"
msgstr "No se ha podido abrir el archivo cupsd.conf:"
-#, c-format
-msgid "Unable to open document %d in job %d"
-msgstr ""
-
+#: backend/parallel.c:246
+#: backend/serial.c:261
+#: backend/usb-unix.c:145
+msgid "Unable to open device file"
+msgstr "No se ha podido abrir el archivo de dispositivo"
+
+#: scheduler/ipp.c:7324
+#, c-format
+msgid "Unable to open document #%d in job #%d."
+msgstr "No se ha podido abrir el documento #%d del trabajo #%d."
+
+#: backend/ipp.c:352
+#: backend/ipp.c:1917
+#: backend/lpd.c:486
+#: backend/parallel.c:150
+#: backend/serial.c:190
+#: backend/socket.c:158
+#: backend/usb.c:237
+#: filter/bannertops.c:183
+#: filter/gziptoany.c:71
+#: filter/pstext.c:89
+#: filter/pstext.c:249
+#: filter/pstext.c:266
+#: filter/pstops.c:305
+msgid "Unable to open print file"
+msgstr "No se ha podido abrir el archivo de impresión"
+
+#: filter/texttops.c:263
+msgid "Unable to open psglyphs"
+msgstr "No se ha podido abrir psglyphs"
+
+#: driver/rastertoescpx.c:1814
+#: driver/rastertopclx.c:1839
+#: filter/rastertoepson.c:998
+#: filter/rastertohp.c:724
+#: filter/rastertolabel.c:1147
+msgid "Unable to open raster file"
+msgstr "No se ha podido abrir el archivo de trama de datos (raster)"
+
+#: filter/texttops.c:216
+#, c-format
+msgid "Unable to print %d text columns."
+msgstr "No se han podido imprimir %d columnas de texto."
+
+#: filter/texttops.c:180
+#: filter/texttops.c:188
+#: filter/texttops.c:196
+#, c-format
+msgid "Unable to print %dx%d text page."
+msgstr "No se han podido imprimir %dx%d páginas de texto."
+
+#: cgi-bin/ipp-var.c:795
msgid "Unable to print test page:"
msgstr "No se ha podido imprimir la página de prueba:"
+#: backend/runloop.c:95
+#: backend/runloop.c:322
+msgid "Unable to read print data"
+msgstr "No se han podido leer los datos de impresión"
+
+#: backend/usb-darwin.c:613
+#: backend/usb-darwin.c:657
+msgid "Unable to read print data."
+msgstr "No se han podido leer los datos de impresión."
+
+#: cups/adminutil.c:2205
#, c-format
-msgid "Unable to run \"%s\": %s\n"
-msgstr "No se ha podido ejecutar \"%s\": %s\n"
+msgid "Unable to run \"%s\": %s"
+msgstr "No se ha podido ejecutar \"%s\": %s"
+
+#: filter/pstops.c:568
+msgid "Unable to see in file"
+msgstr "No se ha podido mirar en el archivo"
+#: cgi-bin/ipp-var.c:598
+#: cgi-bin/ipp-var.c:618
msgid "Unable to send command to printer driver"
-msgstr ""
+msgstr "No se ha podido enviar un comando al controlador de la impresora"
+
+#: backend/usb-darwin.c:735
+#: backend/usb-libusb.c:179
+#: backend/usb-libusb.c:781
+msgid "Unable to send data to printer."
+msgstr "No se han podido enviar datos a la impresora."
+#: filter/imagetoraster.c:1245
+#: filter/imagetoraster.c:1342
+#: filter/imagetoraster.c:1383
+msgid "Unable to send raster data to the driver."
+msgstr "No se ha podido enviar la trama de datos (raster) al controlador."
+
+#: cups/adminutil.c:821
#, c-format
-msgid "Unable to set Windows printer driver (%d)"
-msgstr ""
+msgid "Unable to set Windows printer driver (%d)."
+msgstr "No se ha podido configurar el controlador de impresora de Windows (%d)."
+#: cgi-bin/admin.c:3926
msgid "Unable to set options:"
msgstr "No se han podido cambiar las opciones:"
+#: cgi-bin/admin.c:3196
msgid "Unable to set server default:"
msgstr "No se han podido cambiar los ajustes predeterminados del servidor:"
+#: backend/ipp.c:2572
+#: backend/ipp.c:2649
+#: backend/ipp.c:2657
+msgid "Unable to start backend process."
+msgstr "No se ha podido iniciar el proceso backend."
+
+#: cgi-bin/admin.c:1986
msgid "Unable to upload cupsd.conf file:"
msgstr "No se ha podido copiar el archivo cupsd.conf:"
-msgid "Unable to use legacy USB class driver\n"
-msgstr ""
+#: backend/usb-darwin.c:2013
+#: backend/usb-darwin.c:2037
+msgid "Unable to use legacy USB class driver."
+msgstr "No se ha podido usar el controlador de dispositivo de clase USB obsoleto."
+#: backend/runloop.c:124
+#: backend/runloop.c:377
+msgid "Unable to write print data"
+msgstr "No se han podido escribir los datos de impresión"
+
+#: filter/gziptoany.c:90
+#, c-format
+msgid "Unable to write uncompressed print data: %s"
+msgstr "No se han podido escribir los datos de impresión sin comprimir: %s"
+
+#: cups/http-support.c:1273
msgid "Unauthorized"
msgstr "No autorizado"
+#: cgi-bin/admin.c:3622
msgid "Units"
msgstr "Unidades"
+#: cups/http-support.c:1313
+#: cups/ppd.c:366
msgid "Unknown"
msgstr "Desconocido"
+#: filter/pstops.c:2231
#, c-format
-msgid "Unknown printer-error-policy \"%s\"."
-msgstr "printer-error-policy \"%s\" incorrecto."
-
-#, c-format
-msgid "Unknown printer-op-policy \"%s\"."
-msgstr "printer-op-policy \"%s\" incorrecto."
-
-#, c-format
-msgid "Unsupported character set \"%s\""
-msgstr ""
-
-#, c-format
-msgid "Unsupported compression \"%s\""
-msgstr ""
-
-#, c-format
-msgid "Unsupported compression attribute %s"
-msgstr ""
-
-#, c-format
-msgid "Unsupported format \"%s\""
-msgstr ""
-
-#, c-format
-msgid "Unsupported format '%s'"
-msgstr ""
-
-#, c-format
-msgid "Unsupported format '%s/%s'"
-msgstr ""
-
-msgid "Unsupported value type"
-msgstr "Tipo de valor no permitido"
-
-msgid "Upgrade Required"
-msgstr "Se requiere actualización"
-
-msgid ""
-"Usage:\n"
-"\n"
-" lpadmin [-h server] -d destination\n"
-" lpadmin [-h server] -x destination\n"
-" lpadmin [-h server] -p printer [-c add-class] [-i interface] [-m model]\n"
-" [-r remove-class] [-v device] [-D description]\n"
-" [-P ppd-file] [-o name=value]\n"
-" [-u allow:user,user] [-u deny:user,user]\n"
-"\n"
-msgstr ""
-"Uso:\n"
-"\n"
-" lpadmin [-h servidor] -d destino\n"
-" lpadmin [-h servidor] -x destino\n"
-" lpadmin [-h servidor] -p impresora [-c clase] [-i interfaz] [-m modelo]\n"
-" [-r clase] [-v dispositivo] [-D descripción]\n"
-" [-P archivo_ppd] [-o nombre=valor]\n"
-" [-u allow:usuario,usuario] [-u deny:usuario,usuario]\n"
-"\n"
-
-#, c-format
-msgid "Usage: %s job user title copies options [filename]\n"
-msgstr "Uso: %s trabajo usuario tÃtulo copias opciones [archivo]\n"
+msgid "Unknown choice \"%s\" for option \"%s\"."
+msgstr "Preferencia \"%s\" desconocida para la opción \"%s\"."
+#: backend/ipp.c:494
#, c-format
-msgid "Usage: %s job-id user title copies options [file]\n"
-msgstr "Uso: %s job-id usuario tÃtulo copias opciones [archivo]\n"
+msgid "Unknown encryption option value: \"%s\"."
+msgstr "Valor de opción de cifrado \"%s\" desconocida."
+#: backend/lpd.c:348
#, c-format
-msgid "Usage: %s job-id user title copies options file\n"
-msgstr "Uso: %s job-id usuario tÃtulo copias opciones archivo\n"
-
-msgid ""
-"Usage: convert [ options ]\n"
-"\n"
-"Options:\n"
-"\n"
-" -e Use every filter from the PPD file\n"
-" -f filename Set file to be converted (otherwise stdin)\n"
-" -o filename Set file to be generated (otherwise stdout)\n"
-" -i mime/type Set input MIME type (otherwise auto-typed)\n"
-" -j mime/type Set output MIME type (otherwise application/pdf)\n"
-" -P filename.ppd Set PPD file\n"
-" -a 'name=value ...' Set option(s)\n"
-" -U username Set username for job\n"
-" -J title Set title\n"
-" -c copies Set number of copies\n"
-" -u Remove the PPD file when finished\n"
-" -D Remove the input file when finished\n"
-msgstr ""
-"Uso: convert [ opciones ]\n"
-"\n"
-"Opciones:\n"
-"\n"
-" -e Usar cada filtro del archivo PPD\n"
-" -f nombre_archivo Establecer el archivo a convertir (de lo "
-"contrario, stdin)\n"
-" -o nombre_archivo Establecer el archivo a generar (de lo "
-"contrario, stdout)\n"
-" -i tipo/mime Establecer el tipo MIME de entrada (de lo contrario, "
-"auto-typed)\n"
-" -j tipo/mime Establecer el tipo MIME de salida (de lo contrario, "
-"application/pdf)\n"
-" -P nombre_archivo.ppd Establecer el archivo PPD\n"
-" -a 'nombre=valor ...' Establecer opciones\n"
-" -U nombre_usuario Establecer un nombre de usuario para el "
-"trabajo\n"
-" -J tÃtulo Establecer el tÃtulo\n"
-" -c copias Establecer el número de copias\n"
-" -u Borrar el archivo PPD al finalizar\n"
-" -D Borrar el archivo de entrada al finalizar\n"
-
-msgid ""
-"Usage: cupsaddsmb [options] printer1 ... printerN\n"
-" cupsaddsmb [options] -a\n"
-"\n"
-"Options:\n"
-" -E Encrypt the connection to the server\n"
-" -H samba-server Use the named SAMBA server\n"
-" -U samba-user Authenticate using the named SAMBA user\n"
-" -a Export all printers\n"
-" -h cups-server Use the named CUPS server\n"
-" -v Be verbose (show commands)\n"
-msgstr ""
-"Uso: cupsaddsmb [opciones] impresora1 ... impresoraN\n"
-" cupsaddsmb [opciones] -a\n"
-"\n"
-"Opciones:\n"
-" -E Hace que se use encriptación en la conexión con el "
-"servidor\n"
-" -H servidor_samba Usa el servidor SAMBA especificado\n"
-" -U usuario_samba Autentifica usando el usuario SAMBA especificado\n"
-" -a Exporta todas las impresoras\n"
-" -h servidor_cups Usa el servidor CUPS especificado\n"
-" -v Ser detallado (mostrar comandos)\n"
-
-msgid ""
-"Usage: cupsctl [options] [param=value ... paramN=valueN]\n"
-"\n"
-"Options:\n"
-"\n"
-" -E Enable encryption\n"
-" -U username Specify username\n"
-" -h server[:port] Specify server address\n"
-"\n"
-" --[no-]debug-logging Turn debug logging on/off\n"
-" --[no-]remote-admin Turn remote administration on/off\n"
-" --[no-]remote-any Allow/prevent access from the Internet\n"
-" --[no-]remote-printers Show/hide remote printers\n"
-" --[no-]share-printers Turn printer sharing on/off\n"
-" --[no-]user-cancel-any Allow/prevent users to cancel any job\n"
-msgstr ""
-"Uso: cupsctl [opciones] [param=valor ... paramN=valorN]\n"
-"\n"
-"Opciones:\n"
-"\n"
-" -E Activar encriptación\n"
-" -U nombre_usuario Especificar nombre de usuario\n"
-" -h servidor[:puerto] Especificar la dirección del servidor\n"
-"\n"
-" --[no-]debug-logging Activar o desactivar el registro de depuración\n"
-" --[no-]remote-admin Activar o desactivar la administración remota\n"
-" --[no-]remote-any Permitir o impedir el acceso desde Internet\n"
-" --[no-]remote-printers Mostrar u ocultar las impresoras remotas\n"
-" --[no-]share-printers Activar o desactivar la compartición de "
-"impresoras\n"
-" --[no-]user-cancel-any Permitir o impedir a los usuarios cancelar "
-"cualquier trabajo\n"
-
-msgid ""
-"Usage: cupsd [-c config-file] [-f] [-F] [-h] [-l]\n"
-"\n"
-"-c config-file Load alternate configuration file\n"
-"-f Run in the foreground\n"
-"-F Run in the foreground but detach\n"
-"-h Show this usage message\n"
-"-l Run cupsd from launchd(8)\n"
-msgstr ""
-"Uso: cupsd (-c archivo-configuración) (-f) (-F) (-h) (-l)\n"
-"\n"
-"-c archivo-configuración Carga un archivo de configuración alternativo\n"
-"-f Se ejecuta en primer plano\n"
-"-F Se ejecuta en primer plano pero separado\n"
-"-h Muestra este mensaje de cómo se usa\n"
-"-l Ejecuta cupsd desde launchd(8)\n"
-
-msgid ""
-"Usage: cupsfilter -m mime/type [ options ] filename\n"
-"\n"
-"Options:\n"
-"\n"
-" -c cupsd.conf Set cupsd.conf file to use\n"
-" -e Use every filter from the PPD file\n"
-" -j job-id[,N] Filter file N from the specified job (default is file 1)\n"
-" -n copies Set number of copies\n"
-" -o name=value Set option(s)\n"
-" -p filename.ppd Set PPD file\n"
-" -t title Set title\n"
-msgstr ""
-"Uso: cupsfilter -m tipo/mime [ opciones ] nombre_archivo\n"
-"\n"
-"Opciones:\n"
-"\n"
-" -c cupsd.conf Establecer el archivo cupsd.conf a usar\n"
-" -e Usar cada filtro del archivo PPD\n"
-" -j job-id[,N] Filtrar el archivo N del trabajo especificado (el valor "
-"predeterminado es el archivo 1)\n"
-" -n copias Establecer el número de copias\n"
-" -o nombre=valor Establecer opciones\n"
-" -p nombre_archivo.ppd Establecer el archivo PPD\n"
-" -t tÃtulo Establecer el tÃtulo\n"
-
-msgid ""
-"Usage: cupstestdsc [options] filename.ps [... filename.ps]\n"
-" cupstestdsc [options] -\n"
-"\n"
-"Options:\n"
-"\n"
-" -h Show program usage\n"
-"\n"
-" Note: this program only validates the DSC comments, not the PostScript "
-"itself.\n"
-msgstr ""
-"Uso: cupstestdsc [opciones] nombre_archivo.ps [... nombre_archivo.ps]\n"
-" cupstestdsc [opciones] -\n"
-"\n"
-"Opciones:\n"
-"\n"
-" -h Muestra cómo se usa el programa\n"
-"\n"
-" Nota: este programa sólo valida los comentarios DSC, no el PostScript en "
-"sà mismo.\n"
-
-msgid ""
-"Usage: cupstestppd [options] filename1.ppd[.gz] [... filenameN.ppd[.gz]]\n"
-" program | cupstestppd [options] -\n"
-"\n"
-"Options:\n"
-"\n"
-" -I {filename,filters,none,profiles}\n"
-" Ignore specific warnings\n"
-" -R root-directory Set alternate root\n"
-" -W {all,none,constraints,defaults,duplex,filters,profiles,sizes,"
-"translations}\n"
-" Issue warnings instead of errors\n"
-" -q Run silently\n"
-" -r Use 'relaxed' open mode\n"
-" -v Be slightly verbose\n"
-" -vv Be very verbose\n"
-msgstr ""
-
-msgid ""
-"Usage: ipptest [options] URI filename.test [ ... filenameN.test ]\n"
-"\n"
-"Options:\n"
-"\n"
-"-E Test with encryption.\n"
-"-V version Set default IPP version.\n"
-"-X Produce XML instead of plain text.\n"
-"-c Send requests using chunking (default)\n"
-"-d name=value Define variable.\n"
-"-f filename Set default test file.\n"
-"-i seconds Repeat the last test file with the given interval.\n"
-"-l Send requests using content-length\n"
-"-v Show all attributes sent and received.\n"
-msgstr ""
-
-msgid "Usage: lpmove job/src dest\n"
-msgstr "Uso: lpmove trabajo/fuente destino\n"
-
-msgid ""
-"Usage: lpoptions [-h server] [-E] -d printer\n"
-" lpoptions [-h server] [-E] [-p printer] -l\n"
-" lpoptions [-h server] [-E] -p printer -o option[=value] ...\n"
-" lpoptions [-h server] [-E] -x printer\n"
-msgstr ""
-"Uso: lpoptions [-h servidor] [-E] -d impresora\n"
-" lpoptions [-h servidor] [-E] [-p impresora] -l\n"
-" lpoptions [-h servidor] [-E] -p impresora -o opción[=valor] ...\n"
-" lpoptions [-h servidor] [-E] -x impresora\n"
-
-msgid "Usage: lppasswd [-g groupname]\n"
-msgstr "Usage: lppasswd [-g nombre_grupo]\n"
-
-msgid ""
-"Usage: lppasswd [-g groupname] [username]\n"
-" lppasswd [-g groupname] -a [username]\n"
-" lppasswd [-g groupname] -x [username]\n"
-msgstr ""
-"Usage: lppasswd [-g nombre_grupo] [nombre_usuario]\n"
-" lppasswd [-g nombre_grupo] -a [nombre_usuario]\n"
-" lppasswd [-g nombre_grupo] -x [nombre_usuario]\n"
-
-msgid ""
-"Usage: lpq [-P dest] [-U username] [-h hostname[:port]] [-l] [+interval]\n"
-msgstr ""
-"Uso: lpq (-P dest) (-U nombre_usuario) (-h nombre_ordenador(:puerto)) (-l) "
-"(+intervalo)\n"
-
-msgid ""
-"Usage: ppdc [options] filename.drv [ ... filenameN.drv ]\n"
-"Options:\n"
-" -D name=value Set named variable to value.\n"
-" -I include-dir Add include directory to search path.\n"
-" -c catalog.po Load the specified message catalog.\n"
-" -d output-dir Specify the output directory.\n"
-" -l lang[,lang,...] Specify the output language(s) (locale).\n"
-" -m Use the ModelName value as the filename.\n"
-" -t Test PPDs instead of generating them.\n"
-" -v Be verbose (more v's for more verbosity).\n"
-" -z Compress PPD files using GNU zip.\n"
-" --cr End lines with CR (Mac OS 9).\n"
-" --crlf End lines with CR + LF (Windows).\n"
-" --lf End lines with LF (UNIX/Linux/Mac OS X).\n"
-msgstr ""
-"Uso: ppdc [opciones] nombre_archivo.drv [ ... nombre_archivoN.drv ]\n"
-"Options:\n"
-" -D nombre=valor Establecer la variable nombre al valor.\n"
-" -I include-dir Añadir el directorio include a la ruta de búsqueda.\n"
-" -c catálogo.po Cargar el catálogo de mensajes especificado.\n"
-" -d dir-salida Especificar el directorio de salida.\n"
-" -l idioma[,idioma,...] Especificar el/los idioma(s) de salida.\n"
-" -m Usar el valor ModelName como nombre de archivo.\n"
-" -t Chequear el PPDs en vez de generarlo.\n"
-" -v Ser detallado (más v's para más detalle).\n"
-" -z Comprimir los archivos PPD usando GNU zip.\n"
-" --cr Terminar las lÃneas con CR (Mac OS 9).\n"
-" --crlf Terminar las lÃneas con CR + LF (Windows).\n"
-" --lf Terminar las lÃneas con LF (UNIX/Linux/Mac OS X).\n"
-
-msgid ""
-"Usage: ppdhtml [options] filename.drv >filename.html\n"
-" -D name=value Set named variable to value.\n"
-"Options:\n"
-" -I include-dir Add include directory to search path.\n"
-msgstr ""
-"Uso: ppdhtml [opciones] nombre_archivo.drv >nombre_archivo.html\n"
-"Opciones:\n"
-" -D nombre=valor Establecer la variable nombre al valor.\n"
-" -I include-dir Añadir el directorio include a la ruta de búsqueda.\n"
-
-msgid ""
-"Usage: ppdi [options] filename.ppd [ ... filenameN.ppd ]\n"
-"Options:\n"
-" -I include-dir\n"
-" -o filename.drv\n"
-msgstr ""
-"Uso: ppdi [opciones] nombre_archivo.ppd [ ... nombre_archivoN.ppd ]\n"
-"Opciones:\n"
-" -I include-dir\n"
-" -o nombre_archivo.drv\n"
-
-msgid ""
-"Usage: ppdmerge [options] filename.ppd [ ... filenameN.ppd ]\n"
-"Options:\n"
-" -o filename.ppd[.gz]\n"
-msgstr ""
-"Uso: ppdmerge [opciones] nombre_archivo.ppd [ ... nombre_archivoN.ppd ]\n"
-"Opciones:\n"
-" -o nombre_archivo.ppd[.gz]\n"
-
-msgid ""
-"Usage: ppdpo [options] -o filename.po filename.drv [ ... filenameN.drv ]\n"
-"Options:\n"
-" -D name=value Set named variable to value.\n"
-" -I include-dir Add include directory to search path.\n"
-" -v Be verbose (more v's for more verbosity).\n"
-msgstr ""
-"Uso: ppdpo [opciones] -o nombre_archivo.po nombre_archivo.drv [ ... "
-"nombre_archivoN.drv ]\n"
-"Opciones:\n"
-" -D nombre=valor Establecer la variable nombre al valor.\n"
-" -I include-dir Añadir el directorio include a la ruta de búsqueda.\n"
-" -v Ser detallado (más v's para más detalle).\n"
-
-msgid "Usage: snmp [host-or-ip-address]\n"
-msgstr "Uso: snmp [ordenador-o-dirección-ip]\n"
-
-msgid "Value uses indefinite length"
-msgstr "Valor usa una longitud indefinida"
-
-msgid "VarBind uses indefinite length"
-msgstr "VarBind usa una longitud indefinida"
-
-msgid "Version uses indefinite length"
-msgstr "Versión usa una longitud indefinida"
-
-#, c-format
-msgid "WARNING: Adding only the first %d printers found"
-msgstr "WARNING: Añadiendo sólo las primeras %d impresoras encontradas"
-
-#, c-format
-msgid "WARNING: Boolean expected for waiteof option \"%s\"\n"
-msgstr ""
-"WARNING: Se esperaba un valor booleano para la opción waiteof \"%s\".\n"
-
-#, c-format
-msgid "WARNING: Network host '%s' is busy; will retry in %d seconds...\n"
-msgstr ""
-
-#, c-format
-msgid "WARNING: Option \"%s\" cannot be included via IncludeFeature\n"
-msgstr ""
-
-msgid "WARNING: Printer not responding\n"
-msgstr "WARNING: La impresora no responde\n"
-
-msgid "WARNING: Printer sent unexpected EOF\n"
-msgstr "WARNING: La impresora envió un EOF inesperado\n"
-
-#, c-format
-msgid ""
-"WARNING: Remote host did not respond with command status byte after %d "
-"seconds\n"
-msgstr ""
-
-#, c-format
-msgid ""
-"WARNING: Remote host did not respond with control status byte after %d "
-"seconds\n"
-msgstr ""
-
-#, c-format
-msgid ""
-"WARNING: Remote host did not respond with data status byte after %d seconds\n"
-msgstr ""
-
-msgid ""
-"WARNING: This document does not conform to the Adobe Document Structuring "
-"Conventions and may not print correctly\n"
-msgstr ""
-
-#, c-format
-msgid "WARNING: Unable to open \"%s:%s\": %s\n"
-msgstr "WARNING: No se ha podido abrir \"%s:%s\": %s\n"
-
-msgid "WARNING: Unable to send PAP status request"
-msgstr "WARNING: No se ha podido enviar la petición de estado PAP"
-
-#, c-format
-msgid "WARNING: Unexpected PAP packet of type %d\n"
-msgstr "WARNING: Paquete PAP de tipo %d no esperado\n"
-
-#, c-format
-msgid "WARNING: Unknown PAP packet of type %d\n"
-msgstr "WARNING: Paquete PAP de tipo %d desconocido\n"
-
-#, c-format
-msgid "WARNING: Unknown choice \"%s\" for option \"%s\"\n"
-msgstr ""
-
-#, c-format
-msgid "WARNING: Unknown option \"%s\"\n"
-msgstr ""
-
-#, c-format
-msgid "WARNING: Unsupported baud rate %s\n"
-msgstr ""
-
-#, c-format
-msgid "WARNING: number expected for status option \"%s\"\n"
-msgstr "WARNING: se esperaba un número para la opción de estado \"%s\"\n"
-
-msgid "Warning, no Windows 2000 printer drivers are installed"
-msgstr ""
-
-msgid "Yes"
-msgstr "Si"
-
-#, c-format
-msgid ""
-"You must access this page using the URL <A HREF=\"https://%s:%d%s\">https://%"
-"s:%d%s</A>."
-msgstr ""
-"Debe acceder a esta página usando el URL <A HREF=\"https://%s:%d%s\">https://"
-"%s:%d%s</A>."
-
-msgid "You4 Envelope"
-msgstr "Sobre You4"
-
-msgid "ZPL Label Printer"
-msgstr "Impresora de etiquetas ZPL"
-
-msgid "Zebra"
-msgstr "Zebra"
-
-msgid "aborted"
-msgstr "cancelado"
-
-msgid "canceled"
-msgstr "cancelado"
-
-msgid "completed"
-msgstr "completado"
-
-msgid "convert: Use the -f option to specify a file to convert.\n"
-msgstr "convert: Use la opción -f para especificar el fichero a convertir.\n"
-
-msgid "cups-deviced failed to execute."
-msgstr "Ha fallado al ejecutarse cups-deviced."
-
-msgid "cups-driverd failed to execute."
-msgstr "Ha fallado al ejecutarse cups-driverd."
-
-#, c-format
-msgid "cupsaddsmb: No PPD file for printer \"%s\" - %s\n"
-msgstr "cupsaddsmb: No hay archivo PPD para la impresora \"%s\" - %s\n"
-
-#, c-format
-msgid "cupsctl: Unable to connect to server: %s\n"
-msgstr "cupsctl: No se ha podido conectar al servidor: %s\n"
-
-#, c-format
-msgid "cupsctl: Unknown option \"%s\"\n"
-msgstr ""
-
-#, c-format
-msgid "cupsctl: Unknown option \"-%c\"\n"
-msgstr ""
-
-msgid "cupsd: Expected config filename after \"-c\" option\n"
-msgstr ""
-
-msgid "cupsd: Unable to get current directory\n"
-msgstr ""
-
-#, c-format
-msgid "cupsd: Unknown argument \"%s\" - aborting\n"
-msgstr ""
-
-#, c-format
-msgid "cupsd: Unknown option \"%c\" - aborting\n"
-msgstr ""
-
-msgid "cupsd: launchd(8) support not compiled in, running in normal mode.\n"
-msgstr ""
-"cupsd: el uso de launchd(8) no ha sido compilado, ejecutándose en modo "
-"normal.\n"
-
-#, c-format
-msgid "cupsfilter: Invalid document number %d\n"
-msgstr ""
-
-#, c-format
-msgid "cupsfilter: Invalid job ID %d\n"
-msgstr ""
-
-msgid "cupsfilter: Only one filename can be specified\n"
-msgstr ""
-
-#, c-format
-msgid "cupsfilter: Unable to get job file - %s\n"
-msgstr "cupsfilter: No se ha podido obtener el archivo del trabajo - %s\n"
-
-msgid "cupstestppd: The -q option is incompatible with the -v option.\n"
-msgstr "cupstestppd: La opción -q es incompatible con la opción -v.\n"
-
-msgid "cupstestppd: The -v option is incompatible with the -q option.\n"
-msgstr "cupstestppd: La opción -v es incompatible con la opción -q.\n"
-
-#, c-format
-msgid "device for %s/%s: %s\n"
-msgstr "tipo de conexión para %s/%s: %s\n"
-
-#, c-format
-msgid "device for %s: %s\n"
-msgstr "tipo de conexión para %s: %s\n"
-
-msgid "error-index uses indefinite length"
-msgstr "error-index usa una longitud indefinida"
-
-msgid "error-status uses indefinite length"
-msgstr "error-status usa una longitud indefinida"
-
-msgid "held"
-msgstr "retenido"
-
-msgid "help\t\tget help on commands\n"
-msgstr "help\t\tproporciona ayuda sobre los comandos\n"
-
-msgid "idle"
-msgstr "inactiva"
-
-msgid "ipptest: \"-i\" is incompatible with \"-x\".\n"
-msgstr ""
-
-#, c-format
-msgid "ipptest: Bad URI - %s.\n"
-msgstr ""
-
-#, c-format
-msgid "ipptest: Bad version %s for \"-V\".\n"
-msgstr ""
-
-msgid "ipptest: May only specify a single URI.\n"
-msgstr ""
-
-msgid "ipptest: Missing filename for \"-f\".\n"
-msgstr ""
-
-msgid "ipptest: Missing name=value for \"-d\".\n"
-msgstr ""
-
-msgid "ipptest: Missing seconds for \"-i\".\n"
-msgstr ""
-
-msgid "ipptest: Missing version for \"-V\".\n"
-msgstr ""
-
-msgid "ipptest: Only http, https, and ipp URIs are supported."
-msgstr ""
-
-msgid "ipptest: URI required before test file."
-msgstr ""
-
-#, c-format
-msgid "ipptest: Unknown option \"-%c\".\n"
-msgstr ""
-
-msgid "job-printer-uri attribute missing"
-msgstr ""
-
-msgid "lpadmin: Class name can only contain printable characters\n"
-msgstr ""
-
-msgid "lpadmin: Expected PPD after '-P' option\n"
-msgstr ""
-
-msgid "lpadmin: Expected allow/deny:userlist after '-u' option\n"
-msgstr ""
-
-msgid "lpadmin: Expected class after '-r' option\n"
-msgstr ""
-
-msgid "lpadmin: Expected class name after '-c' option\n"
-msgstr ""
-
-msgid "lpadmin: Expected description after '-D' option\n"
-msgstr ""
-
-msgid "lpadmin: Expected device URI after '-v' option\n"
-msgstr ""
-
-msgid "lpadmin: Expected file type(s) after '-I' option\n"
-msgstr ""
-
-msgid "lpadmin: Expected hostname after '-h' option\n"
-msgstr ""
-
-msgid "lpadmin: Expected interface after '-i' option\n"
-msgstr ""
-
-msgid "lpadmin: Expected location after '-L' option\n"
-msgstr ""
-
-msgid "lpadmin: Expected model after '-m' option\n"
-msgstr ""
-
-msgid "lpadmin: Expected name=value after '-o' option\n"
-msgstr ""
-
-msgid "lpadmin: Expected printer after '-p' option\n"
-msgstr ""
-
-msgid "lpadmin: Expected printer name after '-d' option\n"
-msgstr ""
-
-msgid "lpadmin: Expected printer or class after '-x' option\n"
-msgstr ""
-
-msgid "lpadmin: No member names were seen\n"
-msgstr ""
-
-#, c-format
-msgid "lpadmin: Printer %s is already a member of class %s.\n"
-msgstr "lpadmin: La impresora %s ya es miembro de la clase %s.\n"
-
-#, c-format
-msgid "lpadmin: Printer %s is not a member of class %s.\n"
-msgstr "lpadmin: La impresora %s no es miembro de la clase %s.\n"
-
-msgid "lpadmin: Printer name can only contain printable characters\n"
-msgstr ""
-
-msgid ""
-"lpadmin: Unable to add a printer to the class:\n"
-" You must specify a printer name first\n"
-msgstr ""
-
-#, c-format
-msgid "lpadmin: Unable to connect to server: %s\n"
-msgstr "lpadmin: No se ha podido conectar al servidor: %s\n"
-
-#, c-format
-msgid "lpadmin: Unable to open PPD file \"%s\" - %s\n"
-msgstr "lpadmin: No se ha podido abrir el archivo PPD \"%s\" - %s\n"
-
-#, c-format
-msgid "lpadmin: Unable to open file \"%s\": %s\n"
-msgstr "lpadmin: No se ha podido abrir el archivo \"%s\": %s\n"
-
-msgid ""
-"lpadmin: Unable to remove a printer from the class:\n"
-" You must specify a printer name first\n"
-msgstr ""
-
-msgid ""
-"lpadmin: Unable to set the PPD file:\n"
-" You must specify a printer name first\n"
-msgstr ""
-
-msgid ""
-"lpadmin: Unable to set the device URI:\n"
-" You must specify a printer name first\n"
-msgstr ""
-
-msgid ""
-"lpadmin: Unable to set the interface script or PPD file:\n"
-" You must specify a printer name first\n"
-msgstr ""
-
-msgid ""
-"lpadmin: Unable to set the interface script:\n"
-" You must specify a printer name first\n"
-msgstr ""
-
-msgid ""
-"lpadmin: Unable to set the printer description:\n"
-" You must specify a printer name first\n"
-msgstr ""
-
-msgid ""
-"lpadmin: Unable to set the printer location:\n"
-" You must specify a printer name first\n"
-msgstr ""
-
-msgid ""
-"lpadmin: Unable to set the printer options:\n"
-" You must specify a printer name first\n"
-msgstr ""
-
-#, c-format
-msgid "lpadmin: Unknown allow/deny option \"%s\"\n"
-msgstr ""
-
-#, c-format
-msgid "lpadmin: Unknown argument '%s'\n"
-msgstr ""
-
-#, c-format
-msgid "lpadmin: Unknown option '%c'\n"
-msgstr ""
-
-msgid "lpadmin: Warning - content type list ignored\n"
-msgstr ""
-
-msgid "lpc> "
-msgstr "lpc> "
-
-msgid "lpinfo: Expected 1284 device ID string after --device-id\n"
-msgstr ""
-
-msgid "lpinfo: Expected language after --language\n"
-msgstr ""
-
-msgid "lpinfo: Expected make and model after --make-and-model\n"
-msgstr ""
-
-msgid "lpinfo: Expected product string after --product\n"
-msgstr ""
-
-msgid "lpinfo: Expected scheme list after --exclude-schemes\n"
-msgstr ""
-
-msgid "lpinfo: Expected scheme list after --include-schemes\n"
-msgstr ""
-
-msgid "lpinfo: Expected timeout after --timeout\n"
-msgstr ""
-
-#, c-format
-msgid "lpinfo: Unknown argument '%s'\n"
-msgstr ""
-
-#, c-format
-msgid "lpinfo: Unknown option '%c'\n"
-msgstr ""
-
-#, c-format
-msgid "lpinfo: Unknown option '%s'\n"
-msgstr ""
-
-#, c-format
-msgid "lpmove: Unable to connect to server: %s\n"
-msgstr "lpmove: No se ha podido conectar al servidor: %s\n"
-
-#, c-format
-msgid "lpmove: Unknown argument '%s'\n"
-msgstr ""
-
-#, c-format
-msgid "lpmove: Unknown option '%c'\n"
-msgstr ""
-
-msgid "lpoptions: No printers\n"
-msgstr ""
-
-#, c-format
-msgid "lpoptions: Unable to add printer or instance: %s\n"
-msgstr "lpoptions: No se ha podido añadir la impresora o la instancia: %s\n"
-
-#, c-format
-msgid "lpoptions: Unable to get PPD file for %s: %s\n"
-msgstr "lpoptions: No se ha podido obtener el archivo PPD para %s: %s\n"
-
-#, c-format
-msgid "lpoptions: Unable to open PPD file for %s\n"
-msgstr ""
-
-msgid "lpoptions: Unknown printer or class\n"
-msgstr ""
-
-msgid "lppasswd: Only root can add or delete passwords\n"
-msgstr ""
-
-msgid "lppasswd: Password file busy\n"
-msgstr ""
-
-msgid "lppasswd: Password file not updated\n"
-msgstr ""
-
-msgid "lppasswd: Sorry, password doesn't match\n"
-msgstr ""
-
-msgid ""
-"lppasswd: Sorry, password rejected.\n"
-"Your password must be at least 6 characters long, cannot contain\n"
-"your username, and must contain at least one letter and number.\n"
-msgstr ""
-"lppasswd: Lo siento, se ha rechazado la contraseña.\n"
-"Su contraseña debe tener al menos 6 caracteres, no puede contener\n"
-"su nombre de usuario, y debe tener al menos una letra y un número.\n"
-
-msgid "lppasswd: Sorry, passwords don't match\n"
-msgstr ""
-
-#, c-format
-msgid "lppasswd: Unable to copy password string: %s\n"
-msgstr "lppasswd: No se ha podido copiar la cadena de contraseña: %s\n"
-
-#, c-format
-msgid "lppasswd: Unable to open password file: %s\n"
-msgstr "lppasswd: No se ha podido abrir el archivo de contraseñas: %s\n"
-
-#, c-format
-msgid "lppasswd: Unable to write to password file: %s\n"
-msgstr "lppasswd: No se ha podido escribir en el archivo de contraseñas: %s\n"
-
-#, c-format
-msgid "lppasswd: failed to backup old password file: %s\n"
-msgstr ""
-"lppasswd: falló al hacer una copia de seguridad del antiguo archivo de "
-"contraseñas: %s\n"
-
-#, c-format
-msgid "lppasswd: failed to rename password file: %s\n"
-msgstr "lppasswd: falló al cambiar de nombre al archivo de contraseñas: %s\n"
-
-#, c-format
-msgid "lppasswd: user \"%s\" and group \"%s\" do not exist.\n"
-msgstr "lppasswd: el usuario \"%s\" y el grupo \"%s\" no existen.\n"
-
-#, c-format
-msgid ""
-"lpstat: error - %s environment variable names non-existent destination \"%s"
-"\"\n"
-msgstr ""
-
-#, c-format
-msgid "members of class %s:\n"
-msgstr "miembros de la clase %s:\n"
-
-msgid "no entries\n"
-msgstr "no hay entradas\n"
-
-msgid "no system default destination\n"
-msgstr "no hay un destino predeterminado del sistema\n"
-
-msgid "notify-events not specified"
-msgstr ""
-
-#, c-format
-msgid "notify-recipient-uri URI \"%s\" is already used"
-msgstr ""
-
-#, c-format
-msgid "notify-recipient-uri URI \"%s\" uses unknown scheme"
-msgstr ""
-
-#, c-format
-msgid "notify-subscription-id %d no good"
-msgstr ""
-
-msgid "pending"
-msgstr "pendiente"
-
-#, c-format
-msgid "ppdc: Adding include directory \"%s\"...\n"
-msgstr "ppdc: Añadiendo directorio include \"%s\"...\n"
-
-#, c-format
-msgid "ppdc: Adding/updating UI text from %s...\n"
-msgstr "ppdc: Añadiendo/actualizando texto UI desde %s...\n"
-
-#, c-format
-msgid "ppdc: Bad boolean value (%s) on line %d of %s.\n"
-msgstr "ppdc: Valor lógico (%s) incorrecto en lÃnea %d de %s.\n"
-
-#, c-format
-msgid "ppdc: Bad resolution name \"%s\" on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Bad status keyword %s on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Bad variable substitution ($%c) on line %d of %s.\n"
-msgstr "ppdc: Sustitución de variable ($%c) errónea en la lÃnea %d de %s.\n"
-
-#, c-format
-msgid "ppdc: Choice found on line %d of %s with no Option\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Duplicate #po for locale %s on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected a filter definition on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected a program name on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected boolean value on line %d of %s.\n"
-msgstr "ppdc: Se esperaba un valor lógico en la lÃnea %d de %s.\n"
-
-#, c-format
-msgid "ppdc: Expected charset after Font on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected choice code on line %d of %s.\n"
-msgstr "ppdc: Se esperaba un código apropiado en la lÃnea %d de %s.\n"
-
-#, c-format
-msgid "ppdc: Expected choice name/text on line %d of %s.\n"
-msgstr "ppdc: Se esperaba un nombre/texto apropiado en la lÃnea %d de %s.\n"
-
-#, c-format
-msgid "ppdc: Expected color order for ColorModel on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected colorspace for ColorModel on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected compression for ColorModel on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected constraints string for UIConstraints on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid ""
-"ppdc: Expected driver type keyword following DriverType on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected duplex type after Duplex on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected encoding after Font on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected filename after #po %s on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected group name/text on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected include filename on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected integer on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected locale after #po on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected name after %s on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected name after FileName on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected name after Font on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected name after Manufacturer on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected name after MediaSize on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected name after ModelName on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected name after PCFileName on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected name/text after %s on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected name/text after Installable on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected name/text after Resolution on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected name/text combination for ColorModel on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected option name/text on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected option section on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected option type on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected override field after Resolution on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected real number on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid ""
-"ppdc: Expected resolution/mediatype following ColorProfile on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid ""
-"ppdc: Expected resolution/mediatype following SimpleColorProfile on line %d "
-"of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected selector after %s on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected status after Font on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected string after Copyright on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected string after Version on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected two option names on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected value after %s on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Expected version after Font on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Invalid #include/#po filename \"%s\"\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Invalid cost for filter on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Invalid empty MIME type for filter on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Invalid empty program name for filter on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Invalid option section \"%s\" on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Invalid option type \"%s\" on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Loading driver information file \"%s\"...\n"
-msgstr "ppdc: Cargando archivo de información de controlador \"%s\"...\n"
-
-#, c-format
-msgid "ppdc: Loading messages for locale \"%s\"...\n"
-msgstr "ppdc: Cargando mensajes del idioma \"%s\"...\n"
-
-#, c-format
-msgid "ppdc: Loading messages from \"%s\"...\n"
-msgstr "ppdc: Cargando mensajes desde \"%s\"...\n"
-
-#, c-format
-msgid "ppdc: Missing #endif at end of \"%s\"\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Missing #if on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: No message catalog provided for locale %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Option %s defined in two different groups on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Option %s redefined with a different type on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Option constraint must *name on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Too many nested #if's on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Unable to create PPD file \"%s\" - %s.\n"
-msgstr "ppdc: No se ha podido crear el archivo PPD \"%s\" - %s.\n"
-
-#, c-format
-msgid "ppdc: Unable to create output directory %s: %s\n"
-msgstr "ppdc: No se ha podido crear el directorio de salida %s: %s\n"
-
-#, c-format
-msgid "ppdc: Unable to create output pipes: %s\n"
-msgstr "ppdc: No se han podido crear canales (pipes) de salida: %s\n"
-
-#, c-format
-msgid "ppdc: Unable to execute cupstestppd: %s\n"
-msgstr "ppdc: No se ha podido ejecutar cupstestppd: %s\n"
-
-#, c-format
-msgid "ppdc: Unable to find #po file %s on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Unable to find include file \"%s\" on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Unable to find localization for \"%s\" - %s\n"
-msgstr "ppdc: No se ha podido encontrar localización para \"%s\" - %s\n"
-
-#, c-format
-msgid "ppdc: Unable to load localization file \"%s\" - %s\n"
-msgstr "ppdc: No se ha podido cargar el archivo de localización \"%s\" - %s\n"
-
-#, c-format
-msgid "ppdc: Undefined variable (%s) on line %d of %s.\n"
-msgstr "ppdc: Variable no definida (%s) en la lÃnea %d de %s.\n"
-
-#, c-format
-msgid "ppdc: Unknown driver type %s on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Unknown duplex type \"%s\" on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Unknown media size \"%s\" on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Unknown token \"%s\" seen on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid ""
-"ppdc: Unknown trailing characters in real number \"%s\" on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Unterminated string starting with %c on line %d of %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Warning - overlapping filename \"%s\".\n"
-msgstr ""
-
-#, c-format
-msgid "ppdc: Writing %s...\n"
-msgstr "ppdc: Escribiendo %s...\n"
-
-#, c-format
-msgid "ppdc: Writing PPD files to directory \"%s\"...\n"
-msgstr "ppdc: Escribiendo archivos PPD al directorio \"%s\"...\n"
-
-#, c-format
-msgid "ppdmerge: Bad LanguageVersion \"%s\" in %s\n"
-msgstr ""
-
-#, c-format
-msgid "ppdmerge: Ignoring PPD file %s...\n"
-msgstr "ppdmerge: Ignorando archivo PPD %s...\n"
-
-#, c-format
-msgid "ppdmerge: Unable to backup %s to %s- %s\n"
-msgstr "ppdmerge: No se ha podido hacer copia de seguridad de %s a %s- %s\n"
-
-#, c-format
-msgid "printer %s disabled since %s -\n"
-msgstr "la impresora %s está deshabilitada desde %s -\n"
-
-#, c-format
-msgid "printer %s is idle. enabled since %s\n"
-msgstr "la impresora %s está inactiva. activada desde %s\n"
-
-#, c-format
-msgid "printer %s now printing %s-%d. enabled since %s\n"
-msgstr "la impresora %s está imprimiendo %s-%d. activada desde %s\n"
-
-#, c-format
-msgid "printer %s/%s disabled since %s -\n"
-msgstr "la impresora %s/%s está desactivada desde %s -\n"
-
-#, c-format
-msgid "printer %s/%s is idle. enabled since %s\n"
-msgstr "la impresora %s/%s está inactiva. activada desde %s\n"
-
-#, c-format
-msgid "printer %s/%s now printing %s-%d. enabled since %s\n"
-msgstr "la impresora %s/%s está imprimiendo %s-%d. activada desde %s\n"
-
-msgid "processing"
-msgstr "en proceso"
-
-#, c-format
-msgid "request id is %s-%d (%d file(s))\n"
-msgstr "la id solicitada es %s-%d (%d archivo(s))\n"
-
-msgid "request-id uses indefinite length"
-msgstr "request-id usa una longitud indefinida"
-
-msgid "scheduler is not running\n"
-msgstr "el planificador de tareas no se está ejecutando\n"
-
-msgid "scheduler is running\n"
-msgstr "el planificador de tareas se está ejecutando\n"
-
-#, c-format
-msgid "stat of %s failed: %s"
-msgstr "estado de %s ha fallado: %s"
-
-msgid "status\t\tshow status of daemon and queue\n"
-msgstr "status\t\tmuestra el estado del demonio y la cola\n"
-
-msgid "stopped"
-msgstr "parada"
-
-#, c-format
-msgid "system default destination: %s\n"
-msgstr "destino predeterminado del sistema: %s\n"
-
-#, c-format
-msgid "system default destination: %s/%s\n"
-msgstr "destino predeterminado del sistema: %s/%s\n"
-
-msgid "unknown"
-msgstr "desconocido"
-
-msgid "untitled"
-msgstr "sin tÃtulo"
-
-msgid "variable-bindings uses indefinite length"
-msgstr "variable-bindings usa una longitud indefinida"
-
-#~ msgid " WARN %s has no corresponding options!\n"
-#~ msgstr " ADVERTENCIA %s tiene opciones que no corresponden.\n"
-
-#~ msgid " WARN Default choices conflicting!\n"
-#~ msgstr ""
-#~ " ADVERTENCIA Las preferencias predeterminadas están en "
-#~ "conflicto.\n"
-
-#~ msgid ""
-#~ " WARN Duplex option keyword %s may not work as expected and "
-#~ "should be named Duplex!\n"
-#~ " REF: Page 122, section 5.17\n"
-#~ msgstr ""
-#~ " ADVERTENCIA La clave de opción Duplex %s puede que no funcione "
-#~ "como se espera y deberÃa llamarse Duplex.\n"
-#~ " REF: Página 122, sección 5.17\n"
-
-#~ msgid ""
-#~ " WARN File contains a mix of CR, LF, and CR LF line endings!\n"
-#~ msgstr ""
-#~ " ADVERTENCIA El archivo contiene una mezcla de lÃneas acabadas "
-#~ "en CR, LF y CR LF.\n"
-
-#~ msgid " WARN Line %d only contains whitespace!\n"
-#~ msgstr ""
-#~ " ADVERTENCIA La lÃnea %d solo contiene espacios en blanco.\n"
-
-#~ msgid ""
-#~ " WARN Non-Windows PPD files should use lines ending with only "
-#~ "LF, not CR LF!\n"
-#~ msgstr ""
-#~ " ADVERTENCIA Los archivos PPD que no sean de Windows deben "
-#~ "tener lÃneas que acaben sólo en LF, no en CR LF.\n"
-
-#~ msgid ""
-#~ " WARN Obsolete PPD version %.1f!\n"
-#~ " REF: Page 42, section 5.2.\n"
-#~ msgstr ""
-#~ " ADVERTENCIA Versión de PPD %.1f anticuada.\n"
-#~ " REF: Página 42, sección 5.2.\n"
-
-#~ msgid " %s %s %s does not exist!\n"
-#~ msgstr " %s %s %s no existe.\n"
-
-#~ msgid " %s %s file \"%s\" has the wrong capitalization!\n"
-#~ msgstr " %s archivo %s \"%s\" tiene las mayúsculas equivocadas.\n"
-
-#~ msgid ""
-#~ " %s Bad %s choice %s!\n"
-#~ " REF: Page 122, section 5.17\n"
-#~ msgstr ""
-#~ " %s Preferencia %s incorrecta %s.\n"
-#~ " REF: Página 122, sección 5.17\n"
-
-#~ msgid " %s Bad UTF-8 \"%s\" translation string for option %s!\n"
-#~ msgstr ""
-#~ " %s Cadena de traducción UTF-8 \"%s\" incorrecta para opción %s.\n"
-
-#~ msgid ""
-#~ " %s Bad UTF-8 \"%s\" translation string for option %s, choice %s!\n"
-#~ msgstr ""
-#~ " %s Cadena de traducción UTF-8 \"%s\" incorrecta para opción %s, "
-#~ "preferencia %s.\n"
-
-#~ msgid " %s Bad cupsFilter value \"%s\"!\n"
-#~ msgstr " %s Valor cupsFilter \"%s\" incorrecto.\n"
-
-#~ msgid " %s Bad cupsICCProfile %s!\n"
-#~ msgstr " %s cupsICCProfile %s incorrecto.\n"
-
-#~ msgid " %s Bad cupsPreFilter value \"%s\"!\n"
-#~ msgstr " %s Valor cupsPreFilter \"%s\" incorrecto.\n"
-
-#~ msgid " %s Bad cupsUIConstraints %s: \"%s\"!\n"
-#~ msgstr " %s cupsUIConstraints %s: \"%s\" incorrecto.\n"
-
-#~ msgid " %s Bad language \"%s\"!\n"
-#~ msgstr " %s Idioma incorrecto \"%s\".\n"
-
-#~ msgid " %s Bad spelling of %s - should be %s!\n"
-#~ msgstr " %s %s mal escrito - deberÃa ser %s.\n"
-
-#~ msgid " %s Cannot provide both APScanAppPath and APScanAppBundleID!\n"
-#~ msgstr ""
-#~ " %s No puede proporcionar APScanAppPath y APScanAppBundleID.\n"
-
-#~ msgid " %s Empty cupsUIConstraints %s!\n"
-#~ msgstr " %s cupsUIConstraints %s vacÃo.\n"
-
-#~ msgid " %s Missing \"%s\" translation string for option %s!\n"
-#~ msgstr " %s Falta cadena de traducción \"%s\" para opción %s.\n"
-
-#~ msgid ""
-#~ " %s Missing \"%s\" translation string for option %s, choice %s!\n"
-#~ msgstr ""
-#~ " %s Falta cadena de traducción \"%s\" para opción %s, preferencia %"
-#~ "s.\n"
-
-#~ msgid ""
-#~ " %s Missing REQUIRED PageRegion option!\n"
-#~ " REF: Page 100, section 5.14.\n"
-#~ msgstr ""
-#~ " %s Falta la opción NECESARIA PageRegion.\n"
-#~ " REF: Página 100, sección 5.14.\n"
-
-#~ msgid ""
-#~ " %s Missing REQUIRED PageSize option!\n"
-#~ " REF: Page 99, section 5.14.\n"
-#~ msgstr ""
-#~ " %s Falta la opción NECESARIA PageSize.\n"
-#~ " REF: Página 99, sección 5.14.\n"
-
-#~ msgid ""
-#~ " %s Missing choice *%s %s in UIConstraints \"*%s %s *%s %s\"!\n"
-#~ msgstr ""
-#~ " %s Falta la preferencia *%s %s en UIConstraint \"*%s %s *%s %s\".\n"
-
-#~ msgid " %s Missing choice *%s %s in cupsUIConstraints %s: \"%s\"!\n"
-#~ msgstr ""
-#~ " %s Falta la preferencia *%s %s en cupsUIConstraints %s: \"%s\".\n"
-
-#~ msgid " %s Missing cupsICCProfile file \"%s\"!\n"
-#~ msgstr " %s Falta el archivo cupsICCProfile \"%s\".\n"
-
-#~ msgid " %s Missing cupsUIResolver %s!\n"
-#~ msgstr " %s Falta cupsUIResolver %s.\n"
-
-#~ msgid " %s Missing option %s in UIConstraints \"*%s %s *%s %s\"!\n"
-#~ msgstr " %s Falta la opción %s en UIConstraints \"*%s %s *%s %s\".\n"
-
-#~ msgid " %s Missing option %s in cupsUIConstraints %s: \"%s\"!\n"
-#~ msgstr " %s Falta la opción %s en cupsUIConstraints %s: \"%s\".\n"
-
-#~ msgid " %s No base translation \"%s\" is included in file!\n"
-#~ msgstr " %s No hay traducción base \"%s\" incluida en el archivo.\n"
-
-#~ msgid ""
-#~ " %s Non-standard size name \"%s\"!\n"
-#~ " REF: Page 187, section B.2.\n"
-#~ msgstr ""
-#~ " %s Tamaño de nombre \"%s\" no estándar.\n"
-#~ " REF: Página 187, sección B.2.\n"
-
-#~ msgid ""
-#~ " %s REQUIRED %s does not define choice None!\n"
-#~ " REF: Page 122, section 5.17\n"
-#~ msgstr ""
-#~ " %s NECESARIA %s no define la opción None.\n"
-#~ " REF: Página 122, sección 5.17\n"
-
-#~ msgid " %s Size \"%s\" defined for %s but not for %s!\n"
-#~ msgstr " %s Tamaño \"%s\" definido para %s pero no para %s.\n"
-
-#~ msgid " %s Size \"%s\" has unexpected dimensions (%gx%g)!\n"
-#~ msgstr " %s El tamaño \"%s\" tiene inesperadas dimensiones (%gx%g).\n"
-
-#~ msgid " %s cupsICCProfile %s hash value collides with %s!\n"
-#~ msgstr " %s valor hash de cupsICCProfile %s colisiona con %s!\n"
-
-#~ msgid " %s cupsUIResolver %s causes a loop!\n"
-#~ msgstr " %s cupsUIResolver %s genera un bucle.\n"
-
-#~ msgid ""
-#~ " %s cupsUIResolver %s does not list at least two different "
-#~ "options!\n"
-#~ msgstr ""
-#~ " %s cupsUIResolver %s no lista al menos dos opciones diferentes.\n"
-
-#~ msgid " **FAIL** %s choice names %s and %s differ only by case!\n"
-#~ msgstr ""
-#~ " **FALLO** %s nombres de opción %s y %s se diferencian sólo en la "
-#~ "capitalización.\n"
-
-#~ msgid ""
-#~ " **FAIL** %s must be 1284DeviceID!\n"
-#~ " REF: Page 72, section 5.5\n"
-#~ msgstr ""
-#~ " **FALLO** %s debe ser 1284DeviceID.\n"
-#~ " REF: Página 72, sección 5.5\n"
-
-#~ msgid ""
-#~ " **FAIL** BAD DefaultImageableArea %s!\n"
-#~ " REF: Page 102, section 5.15.\n"
-#~ msgstr ""
-#~ " **FALLO** DefaultImageableArea %s INCORRECTO\n"
-#~ " REF: Página 102, sección 5.15.\n"
-
-#~ msgid ""
-#~ " **FAIL** BAD DefaultPaperDimension %s!\n"
-#~ " REF: Page 103, section 5.15.\n"
-#~ msgstr ""
-#~ " **FALLO** DefaultPaperDimension %s INCORRECTO.\n"
-#~ " REF: Página 103, sección 5.15.\n"
-
-#~ msgid ""
-#~ " **FAIL** Bad %s choice %s!\n"
-#~ " REF: Page 84, section 5.9\n"
-#~ msgstr ""
-#~ " **FALLO** Preferencia %s incorrecta %s.\n"
-#~ " REF: Página 84, sección 5.9\n"
-
-#~ msgid " **FAIL** Bad LanguageEncoding %s - must be ISOLatin1!\n"
-#~ msgstr ""
-#~ " **FALLO** LanguageEncoding %s incorrecto: deberÃa ser ISOLatin1.\n"
-
-#~ msgid " **FAIL** Bad LanguageVersion %s - must be English!\n"
-#~ msgstr ""
-#~ " **FALLO** LanguageVersion %s incorrecto: deberÃa ser Inglés.\n"
-
-#~ msgid ""
-#~ " **FAIL** Default translation string for option %s choice %s "
-#~ "contains 8-bit characters!\n"
-#~ msgstr ""
-#~ " **FALLO** Cadena de traducción predeterminada para opción %s "
-#~ "preferencia %s contiene caracteres de 8-bits.\n"
-
-#~ msgid ""
-#~ " **FAIL** Default translation string for option %s contains 8-bit "
-#~ "characters!\n"
-#~ msgstr ""
-#~ " **FALLO** Cadena de traducción predeterminada para opción %s "
-#~ "contiene caracteres de 8-bits.\n"
-
-#~ msgid " **FAIL** Group names %s and %s differ only by case!\n"
-#~ msgstr ""
-#~ " **FALLO** Nombres de grupo %s y %s se diferencian sólo en la "
-#~ "capitalización.\n"
-
-#~ msgid " **FAIL** Multiple occurrences of %s choice name %s!\n"
-#~ msgstr " **FALLO** Múltiples apariciones de %s nombre de opción %s.\n"
-
-#~ msgid " **FAIL** Option names %s and %s differ only by case!\n"
-#~ msgstr ""
-#~ " **FALLO** Nombres de opción %s y %s se diferencian sólo en la "
-#~ "capitalización.\n"
-
-#~ msgid ""
-#~ " Bad %%%%BoundingBox: on line %d!\n"
-#~ " REF: Page 39, %%%%BoundingBox:\n"
-#~ msgstr ""
-#~ " %%%%BoundingBox: incorrecto en lÃnea %d.\n"
-#~ " REF: Página 39, %%%%BoundingBox:\n"
-
-#~ msgid ""
-#~ " Bad %%%%Page: on line %d!\n"
-#~ " REF: Page 53, %%%%Page:\n"
-#~ msgstr ""
-#~ " %%%%Page: incorrecto en lÃnea %d.\n"
-#~ " REF: Página 53, %%%%Page:\n"
-
-#~ msgid ""
-#~ " Bad %%%%Pages: on line %d!\n"
-#~ " REF: Page 43, %%%%Pages:\n"
-#~ msgstr ""
-#~ " %%%%Pages: incorrecto en lÃnea %d.\n"
-#~ " REF: Página 43, %%%%Pages:\n"
-
-#~ msgid ""
-#~ " Line %d is longer than 255 characters (%d)!\n"
-#~ " REF: Page 25, Line Length\n"
-#~ msgstr ""
-#~ " La lÃnea %d es más larga de 255 caracteres (%d).\n"
-#~ " REF: Página 25, Longitud de LÃnea\n"
-
-#~ msgid ""
-#~ " Missing %!PS-Adobe-3.0 on first line!\n"
-#~ " REF: Page 17, 3.1 Conforming Documents\n"
-#~ msgstr ""
-#~ " Falta %!PS-Adobe-3.0 en la primera lÃnea.\n"
-#~ " REF: Página 17, 3.1 Conformidad de documentos\n"
-
-#~ msgid ""
-#~ " Missing %%EndComments comment!\n"
-#~ " REF: Page 41, %%EndComments\n"
-#~ msgstr ""
-#~ " Falta comentario %%EndComments.\n"
-#~ " REF: Página 41, %%EndComments\n"
-
-#~ msgid ""
-#~ " Missing or bad %%BoundingBox: comment!\n"
-#~ " REF: Page 39, %%BoundingBox:\n"
-#~ msgstr ""
-#~ " Falta comentario %%BoundingBox: o incorrecto.\n"
-#~ " REF: Página 39, %%BoundingBox:\n"
-
-#~ msgid ""
-#~ " Missing or bad %%Page: comments!\n"
-#~ " REF: Page 53, %%Page:\n"
-#~ msgstr ""
-#~ " Falta comentario %%Page: o incorrecto.\n"
-#~ " REF: Página 53, %%Page:\n"
-
-#~ msgid ""
-#~ " Missing or bad %%Pages: comment!\n"
-#~ " REF: Page 43, %%Pages:\n"
-#~ msgstr ""
-#~ " Falta comentario %%Pages: o incorrecto.\n"
-#~ " REF: Página 43, %%Pages:\n"
-
-#~ msgid " Saw %d lines that exceeded 255 characters!\n"
-#~ msgstr " Se han visto %d lÃneas que exceden de 255 caracteres.\n"
-
-#~ msgid " Too many %%BeginDocument comments!\n"
-#~ msgstr " Demasiados comentarios %%BeginDocument.\n"
-
-#~ msgid " Too many %%EndDocument comments!\n"
-#~ msgstr " Demasiados comentarios %%EndDocument.\n"
-
-#~ msgid " Warning: file contains binary data!\n"
-#~ msgstr " Advertencia: el archivo contiene datos binarios.\n"
-
-#~ msgid " Warning: no %%EndComments comment in file!\n"
-#~ msgstr " Advertencia: no hay comentario %%EndComments en el archivo.\n"
-
-#~ msgid " Warning: obsolete DSC version %.1f in file!\n"
-#~ msgstr " Advertencia: versión DSC %.1f obsoleta en el archivo.\n"
-
-#~ msgid "%s not supported!"
-#~ msgstr "No se admite el uso de %s."
-
-#~ msgid "%s: Don't know what to do!\n"
-#~ msgstr "%s: No sé que hay que hacer.\n"
-
-#~ msgid ""
-#~ "%s: Error - %s environment variable names non-existent destination \"%s"
-#~ "\"!\n"
-#~ msgstr ""
-#~ "%s: Error - %s nombres de variables de entorno no existen en destino \"%s"
-#~ "\".\n"
-
-#~ msgid "%s: Error - bad job ID!\n"
-#~ msgstr "%s: Error - ID de trabajo incorrecta.\n"
-
-#~ msgid "%s: Error - cannot print files and alter jobs simultaneously!\n"
-#~ msgstr ""
-#~ "%s: Error - no se pueden imprimir archivos y alterar trabajos al mismo "
-#~ "tiempo.\n"
-
-#~ msgid ""
-#~ "%s: Error - cannot print from stdin if files or a job ID are provided!\n"
-#~ msgstr ""
-#~ "%s: Error - no se puede imprimir desde stdin si se proporcionan archivos "
-#~ "o una ID de trabajo.\n"
-
-#~ msgid "%s: Error - expected character set after '-S' option!\n"
-#~ msgstr ""
-#~ "%s: Error - se esperaba un juego de caracteres tras la opción '-S'.\n"
-
-#~ msgid "%s: Error - expected content type after '-T' option!\n"
-#~ msgstr "%s: Error - se esperaba un tipo de contenido tras la opción '-T'.\n"
-
-#~ msgid "%s: Error - expected copies after '-n' option!\n"
-#~ msgstr "%s: Error - se esperaba número de copias tras la opción '-n'.\n"
-
-#~ msgid "%s: Error - expected copy count after '-#' option!\n"
-#~ msgstr "%s: Error - se esperaba un número de copias tras la opción '-#'.\n"
-
-#~ msgid "%s: Error - expected destination after '-P' option!\n"
-#~ msgstr "%s: Error - se esperaba un destino tras la opción '-P'.\n"
-
-#~ msgid "%s: Error - expected destination after '-b' option!\n"
-#~ msgstr "%s: Error - se esperaba un destino tras la opción '-b'.\n"
-
-#~ msgid "%s: Error - expected destination after '-d' option!\n"
-#~ msgstr "%s: Error - se esperaba un destino tras la opción '-d'.\n"
-
-#~ msgid "%s: Error - expected form after '-f' option!\n"
-#~ msgstr "%s: Error - se esperaba un formulario tras la opción '-f'.\n"
-
-#~ msgid "%s: Error - expected hold name after '-H' option!\n"
-#~ msgstr ""
-#~ "%s: Error - se esperaba un nombre de retención tras la opción '-H'.\n"
-
-#~ msgid "%s: Error - expected hostname after '-H' option!\n"
-#~ msgstr ""
-#~ "%s: Error - se esperaba un nombre de ordenador tras la opción '-H'.\n"
-
-#~ msgid "%s: Error - expected hostname after '-h' option!\n"
-#~ msgstr ""
-#~ "%s: Error - se esperaba un nombre de ordenador tras la opción '-h'.\n"
-
-#~ msgid "%s: Error - expected mode list after '-y' option!\n"
-#~ msgstr "%s: Error - se esperaba una lista de modos tras la opción '-y'.\n"
-
-#~ msgid "%s: Error - expected name after '-%c' option!\n"
-#~ msgstr "%s: Error - se esperaba un nombre tras la opción '%c'.\n"
-
-#~ msgid "%s: Error - expected option string after '-o' option!\n"
-#~ msgstr ""
-#~ "%s: Error - se esperaba una cadena de opciones tras la opción '-o'.\n"
-
-#~ msgid "%s: Error - expected page list after '-P' option!\n"
-#~ msgstr "%s: Error - se esperaba una lista de páginas tras la opción '-P'.\n"
-
-#~ msgid "%s: Error - expected priority after '-%c' option!\n"
-#~ msgstr ""
-#~ "%s: Error - se esperaba un valor de prioridad tras la opción '-%c'.\n"
-
-#~ msgid "%s: Error - expected reason text after '-r' option!\n"
-#~ msgstr ""
-#~ "%s: Error - se esperaba un texto con una razón tras la opción '-r'.\n"
-
-#~ msgid "%s: Error - expected title after '-t' option!\n"
-#~ msgstr "%s: Error - se esperaba un tÃtulo tras la opción '-t'.\n"
-
-#~ msgid "%s: Error - expected username after '-U' option!\n"
-#~ msgstr "%s: Error - se esperaba un nombre de usuario tras la opción '-U'.\n"
-
-#~ msgid "%s: Error - expected username after '-u' option!\n"
-#~ msgstr "%s: Error - se esperaba un nombre de usuario tras la opción '-u'.\n"
-
-#~ msgid "%s: Error - expected value after '-%c' option!\n"
-#~ msgstr "%s: Error - se esperaba un valor tras la opción '%c'.\n"
-
-#~ msgid ""
-#~ "%s: Error - need \"completed\", \"not-completed\", or \"all\" after '-W' "
-#~ "option!\n"
-#~ msgstr ""
-#~ "%s: Error - se necesita \"completed\", \"not completed\", o \"all\" tras "
-#~ "la opción '-W'.\n"
-
-#~ msgid "%s: Error - scheduler not responding!\n"
-#~ msgstr "%s: Error - el programa planificador de tareas no responde.\n"
-
-#~ msgid "%s: Error - unknown destination \"%s\"!\n"
-#~ msgstr "%s: Error - destino \"%s\" desconocido.\n"
-
-#~ msgid "%s: Error - unknown destination \"%s/%s\"!\n"
-#~ msgstr "%s: Error - destino \"%s/%s\" desconocido.\n"
-
-#~ msgid "%s: Error - unknown option '%c'!\n"
-#~ msgstr "%s: Error - opción '%c' desconocida.\n"
-
-#~ msgid "%s: Error - unknown option '%s'!\n"
-#~ msgstr "%s: Error: opción '%s' desconocida.\n"
+msgid "Unknown file order: \"%s\"."
+msgstr "Orden de archivos \"%s\" desconocido."
-#~ msgid "%s: Expected job ID after '-i' option!\n"
-#~ msgstr "%s : Se esperaba una ID de trabajo tras la opción '-i'.\n"
+#: backend/lpd.c:319
+#, c-format
+msgid "Unknown format character: \"%c\"."
+msgstr "Carácter de formato \"%c\" desconocido."
-#~ msgid "%s: Invalid destination name in list \"%s\"!\n"
-#~ msgstr "%s: Nombre de destino no válido en la lista \"%s\".\n"
+#: backend/ipp.c:541
+#, c-format
+msgid "Unknown option \"%s\" with value \"%s\"."
+msgstr "Opción \"%s\" con valor \"%s\" desconocida."
-#~ msgid "%s: Need job ID ('-i jobid') before '-H restart'!\n"
-#~ msgstr ""
-#~ "%s: Se necesita un ID de trabajo ('-i id_trabajo') antes de '-H "
-#~ "restart'.\n"
+#: filter/pstops.c:2214
+#, c-format
+msgid "Unknown option \"%s\"."
+msgstr "Opción \"%s\" desconocida"
-#~ msgid "%s: No filter to convert from %s/%s to %s/%s!\n"
-#~ msgstr "%s: No hay ningún filtro que convertir de %s/%s a %s/%s.\n"
+#: backend/lpd.c:334
+#, c-format
+msgid "Unknown print mode: \"%s\"."
+msgstr "Modo de impresión \"%s\" desconocido."
-#~ msgid "%s: Sorry, no encryption support compiled in!\n"
-#~ msgstr "%s: Lo siento, no está compilado con la opción de encriptación.\n"
+#: scheduler/ipp.c:11639
+#, c-format
+msgid "Unknown printer-error-policy \"%s\"."
+msgstr "printer-error-policy \"%s\" incorrecto."
-#~ msgid "%s: Unable to contact server!\n"
-#~ msgstr "%s: No se ha podido contactar con el servidor.\n"
+#: scheduler/ipp.c:11622
+#, c-format
+msgid "Unknown printer-op-policy \"%s\"."
+msgstr "printer-op-policy \"%s\" incorrecto."
-#~ msgid "%s: Unable to determine MIME type of \"%s\"!\n"
-#~ msgstr "%s: No se ha podido determinar el tipo MIME de \"%s\".\n"
+#: backend/ipp.c:513
+#, c-format
+msgid "Unknown version option value: \"%s\"."
+msgstr "Valor de opción de versión \"%s\" desconocida."
-#~ msgid "%s: Unable to read MIME database from \"%s\" or \"%s\"!\n"
-#~ msgstr "%s: No se pudo leer base de datos MIME desde \"%s\" o \"%s\".\n"
+#: backend/serial.c:379
+#, c-format
+msgid "Unsupported baud rate: %s"
+msgstr "Velocidad en baudios %s no permitida."
-#~ msgid "%s: Unknown destination \"%s\"!\n"
-#~ msgstr "%s: Destino \"%s\" desconocido.\n"
+#: filter/pstops.c:2422
+#, c-format
+msgid "Unsupported brightness value %s, using brightness=100."
+msgstr "Valor de brillo %s no permitido; usando brillo=100."
-#~ msgid "%s: Unknown destination MIME type %s/%s!\n"
-#~ msgstr "%s: Tipo MIME de destino %s/%s desconocido.\n"
+#: scheduler/ipp.c:429
+#, c-format
+msgid "Unsupported character set \"%s\"."
+msgstr "Juego de caracteres \"%s\" no permitido."
-#~ msgid "%s: Unknown option '%c'!\n"
-#~ msgstr "%s: Opción '%c' desconocida.\n"
+#: scheduler/ipp.c:9349
+#: scheduler/ipp.c:10556
+#: scheduler/ipp.c:12093
+#, c-format
+msgid "Unsupported compression \"%s\"."
+msgstr "Compresión \"%s\" no permitida."
-#~ msgid "%s: Unknown source MIME type %s/%s!\n"
-#~ msgstr "%s: Tipo MIME de origen %s/%s desconocido.\n"
+#: scheduler/ipp.c:9483
+#: scheduler/ipp.c:10701
+#: scheduler/ipp.c:12122
+#, c-format
+msgid "Unsupported document-format \"%s\"."
+msgstr "document-format \"%s\" no permitido."
-#~ msgid ""
-#~ "%s: Warning - '%c' format modifier not supported - output may not be "
-#~ "correct!\n"
-#~ msgstr ""
-#~ "%s: Advertencia - no se admite el uso del modificador de formato '%c' - "
-#~ "la salida puede no ser correcta.\n"
+#: scheduler/ipp.c:10684
+#, c-format
+msgid "Unsupported document-format \"%s/%s\"."
+msgstr "document-format \"%s/%s\" no permitido."
-#~ msgid "%s: Warning - character set option ignored!\n"
-#~ msgstr ""
-#~ "%s: Advertencia - opción de juego de caracteres no tenida en cuenta.\n"
+#: scheduler/ipp.c:1447
+#, c-format
+msgid "Unsupported format \"%s\"."
+msgstr "Formato \"%s\" no permitido."
-#~ msgid "%s: Warning - content type option ignored!\n"
-#~ msgstr ""
-#~ "%s: Advertencia - opción de tipo de contenido no tenida en cuenta.\n"
+#: filter/pstops.c:2504
+#, c-format
+msgid "Unsupported gamma value %s, using gamma=1000."
+msgstr "Valor gamma %s no permitido; usando gamma=1000."
-#~ msgid "%s: Warning - form option ignored!\n"
-#~ msgstr "%s: Advertencia - opción de formulario no tenida en cuenta.\n"
+#: scheduler/ipp.c:1545
+msgid "Unsupported margins."
+msgstr "Márgenes no permitidos."
-#~ msgid "%s: Warning - mode option ignored!\n"
-#~ msgstr "%s: Advertencia - opción de modo no tenida en cuenta.\n"
+#: cups/pwg-media.c:467
+msgid "Unsupported media value."
+msgstr "Valor del medio no permitido."
-#~ msgid ""
-#~ "%s: error - %s environment variable names non-existent destination \"%s"
-#~ "\"!\n"
-#~ msgstr ""
-#~ "%s: error - %s nombres de variables de entorno no existen en destino \"%s"
-#~ "\".\n"
+#: filter/pstops.c:2548
+#, c-format
+msgid "Unsupported number-up value %d, using number-up=1."
+msgstr "Valor de number-up (páginas por hoja) %d no permitido; usando number-up=1."
-#~ msgid "%s: error - expected option=value after '-o' option!\n"
-#~ msgstr "%s: error - se esperaba opción=valor tras la opción '-o'.\n"
+#: filter/pstops.c:2582
+#, c-format
+msgid "Unsupported number-up-layout value %s, using number-up-layout=lrtb."
+msgstr "Valor de number-up-layout (disposición de páginas por hoja) %s no permitido; usando number-up-layout=lrtb."
-#~ msgid "A Samba password is required to export printer drivers!"
-#~ msgstr ""
-#~ "Se requiere una contraseña Samba para exportar los controladores de "
-#~ "impresora."
+#: filter/pstops.c:2633
+#, c-format
+msgid "Unsupported page-border value %s, using page-border=none."
+msgstr "Valor de page-border (borde de página) %s no permitido; usando page-border=none (ninguno)."
-#~ msgid "A Samba username is required to export printer drivers!"
-#~ msgstr ""
-#~ "Se requiere un nombre de usuario Samba para exportar los controladores de "
-#~ "impresora."
+#: filter/rastertopwg.c:130
+#: filter/rastertopwg.c:138
+#: filter/rastertopwg.c:147
+msgid "Unsupported raster data."
+msgstr "Trama de datos no permitidos."
-#~ msgid "A class named \"%s\" already exists!"
-#~ msgstr "Ya existe una clase llamada \"%s\"."
+#: cups/snmp.c:1112
+msgid "Unsupported value type"
+msgstr "Tipo de valor no permitido"
-#~ msgid "A printer named \"%s\" already exists!"
-#~ msgstr "Ya existe una impresora llamada \"%s\"."
+#: cups/http-support.c:1288
+msgid "Upgrade Required"
+msgstr "Se requiere actualización"
-#~ msgid "Attempt to set %s printer-state to bad value %d!"
-#~ msgstr ""
-#~ "Se ha intentado cambiar el valor printer-state de %s a un valor "
-#~ "incorrecto %d."
+#: systemv/lpadmin.c:668
+msgid ""
+"Usage:\n"
+"\n"
+" lpadmin [-h server] -d destination\n"
+" lpadmin [-h server] -x destination\n"
+" lpadmin [-h server] -p printer [-c add-class] [-i interface] [-m model]\n"
+" [-r remove-class] [-v device] [-D description]\n"
+" [-P ppd-file] [-o name=value]\n"
+" [-u allow:user,user] [-u deny:user,user]"
+msgstr ""
+"Uso:\n"
+"\n"
+" lpadmin [-h servidor] -d destino\n"
+" lpadmin [-h servidor] -x destino\n"
+" lpadmin [-h servidor] -p impresora [-c clase] [-i interfaz] [-m modelo]\n"
+" [-r clase] [-v dispositivo] [-D descripción]\n"
+" [-P archivo_ppd] [-o nombre=valor]\n"
+" [-u allow:usuario,usuario] [-u deny:usuario,usuario]"
+
+#: filter/pdftops.c:109
+#, c-format
+msgid "Usage: %s job user title copies options [filename]"
+msgstr "Uso: %s trabajo usuario tÃtulo copias opciones [archivo]"
+
+#: backend/dnssd.c:171
+#: backend/ipp.c:300
+#: backend/lpd.c:191
+#: backend/parallel.c:127
+#: backend/serial.c:167
+#: backend/socket.c:135
+#: backend/usb.c:183
+#: driver/commandtoescpx.c:57
+#: driver/commandtopclx.c:57
+#: filter/textcommon.c:518
+#: monitor/bcp.c:62
+#: monitor/tbcp.c:61
+#, c-format
+msgid "Usage: %s job-id user title copies options [file]"
+msgstr "Uso: %s job-id usuario tÃtulo copias opciones [archivo]"
+
+#: filter/bannertops.c:118
+#: filter/commandtops.c:73
+#: filter/gziptoany.c:50
+#: filter/imagetops.c:123
+#: filter/imagetoraster.c:215
+#: filter/pstops.c:269
+#, c-format
+msgid "Usage: %s job-id user title copies options file"
+msgstr "Uso: %s job-id usuario tÃtulo copias opciones archivo"
+
+#: scheduler/cupsfilter.c:1466
+msgid "Usage: convert [ options ]"
+msgstr "Uso: convert ( opciones )"
+
+#: systemv/cupsaddsmb.c:281
+msgid "Usage: cupsaddsmb [options] printer1 ... printerN"
+msgstr "Uso: cupsaddsmb [opciones] impresora1 ... impresoraN"
+
+#: systemv/cupsctl.c:206
+msgid "Usage: cupsctl [options] [param=value ... paramN=valueN]"
+msgstr "Uso: cupsctl [opciones] [param=valor ... paramN=valorN]"
+
+#: scheduler/main.c:2057
+msgid "Usage: cupsd [options]"
+msgstr "Uso: cupsd [opciones)"
+
+#: scheduler/cupsfilter.c:1439
+msgid "Usage: cupsfilter [ options ] filename"
+msgstr "Uso: cupsfilter ( opciones ) archivo"
+
+#: systemv/cupstestdsc.c:425
+msgid "Usage: cupstestdsc [options] filename.ps [... filename.ps]"
+msgstr "Uso: cupstestdsc [opciones] nombre_archivo.ps [... nombre_archivo.ps]"
+
+#: systemv/cupstestppd.c:3612
+msgid "Usage: cupstestppd [options] filename1.ppd[.gz] [... filenameN.ppd[.gz]]"
+msgstr "Uso: cupstestppd [opciones] nombre_archivo1.ppd[.gz] [... nombre_archivoN.ppd[.gz]]"
+
+#: test/ipptool.c:3919
+msgid "Usage: ipptool [options] URI filename [ ... filenameN ]"
+msgstr "Uso: ipptool [opciones] URI nombre_archivo [ ... nombre_archivoN ]"
+
+#: systemv/lpmove.c:125
+msgid "Usage: lpmove job/src dest"
+msgstr "Uso: lpmove trabajo/fuente destino"
+
+#: systemv/lpoptions.c:553
+msgid ""
+"Usage: lpoptions [-h server] [-E] -d printer\n"
+" lpoptions [-h server] [-E] [-p printer] -l\n"
+" lpoptions [-h server] [-E] -p printer -o option[=value] ...\n"
+" lpoptions [-h server] [-E] -x printer"
+msgstr ""
+"Uso: lpoptions [-h servidor] [-E] -d impresora\n"
+" lpoptions [-h servidor] [-E] [-p impresora] -l\n"
+" lpoptions [-h servidor] [-E] -p impresora -o opción[=valor] ...\n"
+" lpoptions [-h servidor] [-E] -x impresora"
-#~ msgid "Attribute groups are out of order (%x < %x)!"
-#~ msgstr "Los grupos de atributos están desordenados (%x < %x)."
+#: systemv/lppasswd.c:476
+msgid "Usage: lppasswd [-g groupname]"
+msgstr "Uso: lppasswd [-g nombre_grupo]"
-#~ msgid "Bad device URI \"%s\"!\n"
-#~ msgstr "URI de dispositivoi \"%s\" incorrecto.\n"
+#: systemv/lppasswd.c:479
+msgid ""
+"Usage: lppasswd [-g groupname] [username]\n"
+" lppasswd [-g groupname] -a [username]\n"
+" lppasswd [-g groupname] -x [username]"
+msgstr ""
+"Uso: lppasswd [-g nombre_grupo] [nombre_usuario]\n"
+" lppasswd [-g nombre_grupo] -a [nombre_usuario]\n"
+" lppasswd [-g nombre_grupo] -x [nombre_usuario]"
-#~ msgid "Bad device-uri \"%s\"!"
-#~ msgstr "device-uri \"%s\" incorrecto."
+#: berkeley/lpq.c:670
+msgid "Usage: lpq [-P dest] [-U username] [-h hostname[:port]] [-l] [+interval]"
+msgstr "Uso: lpq (-P dest) (-U nombre_usuario) (-h nombre_ordenador(:puerto)) (-l) (+intervalo)"
-#~ msgid "Bad device-uri scheme \"%s\"!"
-#~ msgstr "Esquema device-uri \"%s\" incorrecto."
+#: ppdc/ppdc.cxx:435
+msgid "Usage: ppdc [options] filename.drv [ ... filenameN.drv ]"
+msgstr "Uso: ppdc [opciones] nombre_archivo.drv [ ... nombre_archivoN.drv ]"
-#~ msgid "Bad document-format \"%s\"!"
-#~ msgstr "document-format \"%s\" incorrecto."
+#: ppdc/ppdhtml.cxx:172
+msgid "Usage: ppdhtml [options] filename.drv >filename.html"
+msgstr "Uso: ppdhtml [opciones] nombre_archivo.drv >nombre_archivo.html"
-#~ msgid "Bad filename buffer!"
-#~ msgstr "Nombre de archivo del búfer incorrecto."
+#: ppdc/ppdi.cxx:128
+msgid "Usage: ppdi [options] filename.ppd [ ... filenameN.ppd ]"
+msgstr "Uso: ppdi [opciones] nombre_archivo.ppd [ ... nombre_archivoN.ppd ]"
-#~ msgid "Bad job-priority value!"
-#~ msgstr "Valor job-priority incorrecto."
+#: ppdc/ppdmerge.cxx:367
+msgid "Usage: ppdmerge [options] filename.ppd [ ... filenameN.ppd ]"
+msgstr "Uso: ppdmerge [opciones] nombre_archivo.ppd [ ... nombre_archivoN.ppd ]"
-#~ msgid "Bad job-sheets value \"%s\"!"
-#~ msgstr "Valor de job-sheets \"%s\" incorrecto."
+#: ppdc/ppdpo.cxx:252
+msgid "Usage: ppdpo [options] -o filename.po filename.drv [ ... filenameN.drv ]"
+msgstr "Uso: ppdpo [opciones] -o nombre_archivo.po nombre_archivo.drv [ ... nombre_archivoN.drv ]"
-#~ msgid "Bad job-sheets value type!"
-#~ msgstr "Tipo de valor de job-sheets incorrecto."
+#: backend/snmp.c:218
+msgid "Usage: snmp [host-or-ip-address]"
+msgstr "Uso: snmp [ordenador-o-dirección-ip]"
-#~ msgid "Bad job-state value!"
-#~ msgstr "Valor job-state incorrecto."
+#: cups/snmp.c:1064
+msgid "Value uses indefinite length"
+msgstr "Valor usa una longitud indefinida"
-#~ msgid "Bad job-uri attribute \"%s\"!"
-#~ msgstr "Atributo job-uri \"%s\" incorrecto."
+#: cups/snmp.c:1049
+msgid "VarBind uses indefinite length"
+msgstr "VarBind usa una longitud indefinida"
-#~ msgid "Bad notify-pull-method \"%s\"!"
-#~ msgstr "notify-pull-method \"%s\" incorrecto."
+#: cups/snmp.c:999
+msgid "Version uses indefinite length"
+msgstr "Versión usa una longitud indefinida"
-#~ msgid "Bad notify-recipient-uri URI \"%s\"!"
-#~ msgstr "URI notify-recipient-uri \"%s\" incorrecto."
+#: backend/ipp.c:1560
+msgid "Waiting for job to complete."
+msgstr "Esperando a que finalice el trabajo."
-#~ msgid "Bad option + choice on line %d!"
-#~ msgstr "Opción + preferencia incorrectas en lÃnea %d."
+#: backend/usb-darwin.c:457
+#: backend/usb-libusb.c:118
+msgid "Waiting for printer to become available."
+msgstr "Esperando a que la impresora esté disponible."
-#~ msgid "Bad port-monitor \"%s\"!"
-#~ msgstr "port-monitor \"%s\" incorrecto."
+#: backend/socket.c:444
+msgid "Waiting for printer to finish."
+msgstr "Esperando a que finalice la impresora."
-#~ msgid "Bad printer-state value %d!"
-#~ msgstr "Valor printer-state %d incorrecto."
+#: cups/adminutil.c:793
+msgid "Warning, no Windows 2000 printer drivers are installed."
+msgstr "Advertencia, no está instalado ningún controlador de impresora de Windows 2000."
-#~ msgid "Bad request ID %d!"
-#~ msgstr "ID %d de petición incorrecta."
+#: cups/http-support.c:1309
+msgid "Web Interface is Disabled"
+msgstr "La interfaz web está desactivada."
-#~ msgid "Bad request version number %d.%d!"
-#~ msgstr "Petición incorrecta de número de versión %d.%d."
+#: cups/ppd.c:1907
+msgid "Yes"
+msgstr "Si"
-#~ msgid "Bad subscription ID!"
-#~ msgstr "ID de subscripción incorrecto."
+#: scheduler/client.c:2449
+#, c-format
+msgid "You must access this page using the URL <A HREF=\"https://%s:%d%s\">https://%s:%d%s</A>."
+msgstr "Debe acceder a esta página usando el URL <A HREF=\"https://%s:%d%s\">https://%s:%d%s</A>."
-#~ msgid "Character set \"%s\" not supported!"
-#~ msgstr "No se admite el uso del juego de caracteres \"%s\"."
+#: systemv/lppasswd.c:254
+msgid "Your password must be at least 6 characters long, cannot contain your username, and must contain at least one letter and number."
+msgstr "Su contraseña debe tener al menos 6 caracteres, no puede contener su nombre de usuario, y debe tener al menos una letra y un número."
-#~ msgid "Could not scan type \"%s\"!"
-#~ msgstr "No se puede analizar el tipo \"%s\"."
+#: ppdc/sample.c:448
+msgid "ZPL Label Printer"
+msgstr "Impresora de etiquetas ZPL"
-#~ msgid "Cover open."
-#~ msgstr "Cubierta abierta."
+#: ppdc/sample.c:371
+msgid "Zebra"
+msgstr "Zebra"
-#~ msgid "Developer almost empty."
-#~ msgstr "Revelador casi vacÃo."
+#: cups/notify.c:102
+msgid "aborted"
+msgstr "cancelado"
-#~ msgid "Developer empty!"
-#~ msgstr "Revelador vacÃo."
+#: cups/notify.c:99
+msgid "canceled"
+msgstr "cancelado"
-#~ msgid "Door open."
-#~ msgstr "Puerta abierta."
+#: cups/notify.c:105
+msgid "completed"
+msgstr "completado"
-#~ msgid "ERROR: Bad %%BoundingBox: comment seen!\n"
-#~ msgstr "ERROR: Se ha detectado un comentario %%BoundingBox: incorrecto.\n"
+#: scheduler/cupsfilter.c:355
+msgid "convert: Use the -f option to specify a file to convert."
+msgstr "convert: Use la opción -f para especificar el archivo a convertir."
-#~ msgid "ERROR: Bad %%IncludeFeature: comment!\n"
-#~ msgstr "ERROR: Comentario %%IncludeFeature: incorrecto.\n"
+#: scheduler/ipp.c:7196
+msgid "cups-deviced failed to execute."
+msgstr "Ha fallado al ejecutarse cups-deviced."
-#~ msgid "ERROR: Bad %%Page: comment in file!\n"
-#~ msgstr "ERROR: Comentario %%Page: incorrecto en el archivo.\n"
+#: scheduler/ipp.c:8026
+#: scheduler/ipp.c:8276
+msgid "cups-driverd failed to execute."
+msgstr "Ha fallado al ejecutarse cups-driverd."
-#~ msgid "ERROR: Bad %%PageBoundingBox: comment in file!\n"
-#~ msgstr "ERROR: Comentario %%PageBoundingBox: incorrecto en el archivo.\n"
+#: systemv/cupsaddsmb.c:233
+#, c-format
+msgid "cupsaddsmb: No PPD file for printer \"%s\" - %s"
+msgstr "cupsaddsmb: No hay archivo PPD para la impresora \"%s\" - %s"
-#~ msgid "ERROR: Bad SCSI device file \"%s\"!\n"
-#~ msgstr "ERROR: archivo de dispositivo SCSI \"%s\" incorrecto.\n"
+#: systemv/cupsctl.c:147
+msgid "cupsctl: Cannot set Listen or Port directly."
+msgstr "cupsctl: No se puede establecer Listen o Port directamente."
-#~ msgid "ERROR: Bad columns value %d!\n"
-#~ msgstr "ERROR: Valor de columnas %d incorrecto.\n"
+#: systemv/cupsctl.c:158
+#, c-format
+msgid "cupsctl: Unable to connect to server: %s"
+msgstr "cupsctl: No se ha podido conectar al servidor: %s"
-#~ msgid "ERROR: Bad cpi value %f!\n"
-#~ msgstr "ERROR: Valor de cpi %f incorrecto.\n"
+#: systemv/cupsctl.c:201
+#, c-format
+msgid "cupsctl: Unknown option \"%s\""
+msgstr "cupsctl: Opción \"%s\" desconocida"
-#~ msgid "ERROR: Bad lpi value %f!\n"
-#~ msgstr "ERROR: Valor de lpi %f incorrecto.\n"
+#: systemv/cupsctl.c:203
+#, c-format
+msgid "cupsctl: Unknown option \"-%c\""
+msgstr "cupsctl: Opción \"-%c\" desconocida"
-#~ msgid "ERROR: Bad page setup!\n"
-#~ msgstr "ERROR: Ajuste de página incorrecto.\n"
+#: scheduler/main.c:190
+msgid "cupsd: Expected config filename after \"-c\" option."
+msgstr "cupsd: Se esperaba un nombre de archivo de configuración tras la opción \"-c\"."
-#~ msgid "ERROR: Destination printer does not exist!\n"
-#~ msgstr "ERROR: La impresora destino no existe.\n"
+#: scheduler/main.c:222
+#: scheduler/main.c:229
+msgid "cupsd: Unable to get current directory."
+msgstr "cupsd: No se ha podido obtener el directorio actual."
-#~ msgid "ERROR: Duplicate %%BoundingBox: comment seen!\n"
-#~ msgstr "ERROR: Se ha detectado un comentario %%BoundingBox: duplicado.\n"
+#: scheduler/main.c:296
+#, c-format
+msgid "cupsd: Unknown argument \"%s\" - aborting."
+msgstr "cupsd: Argumento \"%s\" desconocido - cancelando."
-#~ msgid "ERROR: Duplicate %%Pages: comment seen!\n"
-#~ msgstr "ERROR: Se ha detectado un comentario %%Pages: duplicado.\n"
+#: scheduler/main.c:289
+#, c-format
+msgid "cupsd: Unknown option \"%c\" - aborting."
+msgstr "cupsd: Opción \"%c\" desconocida - cancelando."
-#~ msgid "ERROR: Empty print file!\n"
-#~ msgstr "ERROR: Archivo de impresión vacÃo.\n"
+#: scheduler/main.c:256
+msgid "cupsd: launchd(8) support not compiled in, running in normal mode."
+msgstr "cupsd: el uso de launchd(8) no ha sido compilado, ejecutándose en modo normal."
-#~ msgid "ERROR: Expected quoted string on line %d of %s!\n"
-#~ msgstr ""
-#~ "ERROR: Se esperaba una cadena entrecomillada en la lÃnea %d de %s.\n"
+#: scheduler/cupsfilter.c:1217
+#, c-format
+msgid "cupsfilter: Invalid document number %d."
+msgstr "cupsfilter: Número de documento %d no válido."
-#~ msgid "ERROR: Fatal USB error!\n"
-#~ msgstr "ERROR: Error fatal de USB.\n"
+#: scheduler/cupsfilter.c:1211
+#, c-format
+msgid "cupsfilter: Invalid job ID %d."
+msgstr "cupsfilter: ID de trabajo %d no válida."
-#~ msgid "ERROR: Invalid HP-GL/2 command seen, unable to print file!\n"
-#~ msgstr ""
-#~ "ERROR: Se ha detectado un comando HP-GL/2 no válido; no se puede imprimir "
-#~ "el archivo.\n"
+#: scheduler/cupsfilter.c:363
+msgid "cupsfilter: Only one filename can be specified."
+msgstr "cupsfilter: Solo se puede especificar un nombre de archivo."
-#~ msgid "ERROR: Missing %%EndProlog!\n"
-#~ msgstr "ERROR: Falta %%EndProlog.\n"
+#: scheduler/cupsfilter.c:1259
+#, c-format
+msgid "cupsfilter: Unable to get job file - %s"
+msgstr "cupsfilter: No se ha podido obtener el archivo del trabajo - %s"
-#~ msgid "ERROR: Missing %%EndSetup!\n"
-#~ msgstr "ERROR: Falta %%EndSetup.\n"
+#: systemv/cupstestppd.c:260
+msgid "cupstestppd: The -q option is incompatible with the -v option."
+msgstr "cupstestppd: La opción -q es incompatible con la opción -v."
-#~ msgid "ERROR: Missing value on line %d of banner file!\n"
-#~ msgstr "ERROR: Falta el valor en la lÃnea %d del archivo de rótulo.\n"
+#: systemv/cupstestppd.c:276
+msgid "cupstestppd: The -v option is incompatible with the -q option."
+msgstr "cupstestppd: La opción -v es incompatible con la opción -q."
-#~ msgid ""
-#~ "ERROR: Need a msgid line before any translation strings on line %d of %"
-#~ "s!\n"
-#~ msgstr ""
-#~ "ERROR: Se necesita una lÃnea msgid antes de cualquier cadena de "
-#~ "traducción en lÃnea %d de %s.\n"
+#: systemv/lpstat.c:1228
+#: systemv/lpstat.c:1231
+#: systemv/lpstat.c:1234
+#, c-format
+msgid "device for %s/%s: %s"
+msgstr "dispositivo para %s/%s: %s"
-#~ msgid "ERROR: No %%BoundingBox: comment in header!\n"
-#~ msgstr "ERROR: No hay comentario %%BoundingBox: en la cabecera.\n"
+#: systemv/lpstat.c:1215
+#: systemv/lpstat.c:1218
+#: systemv/lpstat.c:1221
+#, c-format
+msgid "device for %s: %s"
+msgstr "dispositivo para %s: %s"
-#~ msgid "ERROR: No %%Pages: comment in header!\n"
-#~ msgstr "ERROR: No hay comentario %%Pages: en la cabecera.\n"
+#: cups/snmp.c:1036
+msgid "error-index uses indefinite length"
+msgstr "error-index usa una longitud indefinida"
-#~ msgid ""
-#~ "ERROR: No device URI found in argv[0] or in DEVICE_URI environment "
-#~ "variable!\n"
-#~ msgstr ""
-#~ "ERROR: No se ha encontrado el URI del dispositivo en argv[0] o en la "
-#~ "variable de entorno DEVICE_URI.\n"
+#: cups/snmp.c:1028
+msgid "error-status uses indefinite length"
+msgstr "error-status usa una longitud indefinida"
-#~ msgid "ERROR: No pages found!\n"
-#~ msgstr "ERROR: No se han encontrado páginas.\n"
+#: cups/notify.c:90
+msgid "held"
+msgstr "retenido"
-#~ msgid "ERROR: Out of paper!\n"
-#~ msgstr "ERROR: No hay papel.\n"
+#: berkeley/lpc.c:209
+msgid "help\t\tGet help on commands."
+msgstr "help\t\tProporciona ayuda sobre los comandos."
-#~ msgid "ERROR: PRINTER environment variable not defined!\n"
-#~ msgstr "ERROR: Variable de entorno PRINTER no definida.\n"
+#: cups/notify.c:131
+msgid "idle"
+msgstr "inactiva"
-#~ msgid "ERROR: Print file was not accepted (%s)!\n"
-#~ msgstr "ERROR: No se ha aceptado la impresión del archivo (%s).\n"
+#: test/ipptool.c:347
+msgid "ipptool: \"-i\" and \"-n\" are incompatible with -X\"."
+msgstr "ipptool: \"-i\" y \"-n\" son incompatibles with -X\"."
-#~ msgid "ERROR: Printer not responding!\n"
-#~ msgstr "ERROR: La impresora no responde.\n"
+#: test/ipptool.c:422
+msgid "ipptool: \"-i\" is incompatible with \"-X\"."
+msgstr "ipptool: \"-i\" es incompatible with \"-X\"."
-#~ msgid "ERROR: Unable to get job %d attributes (%s)!\n"
-#~ msgstr ""
-#~ "ERROR: No se han podido obtener los atributos del trabajo %d (%s).\n"
+#: test/ipptool.c:446
+msgid "ipptool: \"-n\" is incompatible with \"-X\"."
+msgstr "ipptool: \"-n\" es incompatible with \"-X\"."
-#~ msgid "ERROR: Unable to get printer status (%s)!\n"
-#~ msgstr "ERROR: No se ha podido obtener el estado de la impresora (%s).\n"
+#: test/ipptool.c:504
+#, c-format
+msgid "ipptool: Bad URI - %s."
+msgstr "ipptool: URI - %s incorrecto."
-#~ msgid "ERROR: Unable to locate printer '%s'!\n"
-#~ msgstr "ERROR: No se ha podido localizar la impresora '%s'.\n"
+#: test/ipptool.c:336
+#, c-format
+msgid "ipptool: Bad version %s for \"-V\"."
+msgstr "ipptool: Versión %s para \"-V\" incorrecta."
-#~ msgid "ERROR: Unable to open PPD file!\n"
-#~ msgstr "ERROR: No se ha podido abrir el archivo PPD.\n"
+#: test/ipptool.c:415
+msgid "ipptool: Invalid seconds for \"-i\"."
+msgstr "ipptool: Número de segundos no válido para \"-i\"."
-#~ msgid "ERROR: Unable to open image file for printing!\n"
-#~ msgstr ""
-#~ "ERROR: No se ha podido abrir el archivo de imagen para imprimirlo.\n"
+#: test/ipptool.c:485
+msgid "ipptool: May only specify a single URI."
+msgstr "ipptool: Sólo se puede especificar un URI."
-#~ msgid "ERROR: Unable to print %d text columns!\n"
-#~ msgstr "ERROR: No se ha podido imprimir %d columnas de texto.\n"
+#: test/ipptool.c:438
+msgid "ipptool: Missing count for \"-n\"."
+msgstr "ipptool: Falta el contador para \"-n\"."
-#~ msgid "ERROR: Unable to print %dx%d text page!\n"
-#~ msgstr "ERROR: No se ha podido imprimir %dx%d páginas de texto.\n"
+#: test/ipptool.c:382
+msgid "ipptool: Missing filename for \"-f\"."
+msgstr "ipptool: Falta el nombre del archivo para \"-f\"."
-#~ msgid "ERROR: Unable to read print data!\n"
-#~ msgstr "ERROR: No se han podido leer los datos de impresión.\n"
+#: test/ipptool.c:363
+msgid "ipptool: Missing name=value for \"-d\"."
+msgstr "ipptool: Falta un nombre=valor para \"-d\"."
-#~ msgid "ERROR: Unable to send print data (%d)\n"
-#~ msgstr "ERROR: No se han podido enviar los datos de impresión (%d)\n"
+#: test/ipptool.c:405
+msgid "ipptool: Missing seconds for \"-i\"."
+msgstr "ipptool: Falta el número de segundos para \"-i\"."
-#~ msgid "ERROR: Unable to send print data!\n"
-#~ msgstr "ERROR: No se han podido enviar los datos de impresión.\n"
+#: test/ipptool.c:306
+msgid "ipptool: Missing timeout for \"-T\"."
+msgstr "ipptool: Falta un tiempo de espera para \"-T\"."
-#~ msgid "ERROR: Unable to write %d bytes to printer!\n"
-#~ msgstr "ERROR: No se han podido escribir %d bytes a la impresora.\n"
+#: test/ipptool.c:319
+msgid "ipptool: Missing version for \"-V\"."
+msgstr "ipptool: Falta la versión para \"-V\"."
-#~ msgid "ERROR: Unable to write raster data to driver!\n"
-#~ msgstr ""
-#~ "ERROR: No se ha podido escribir la trama de datos (raster) al "
-#~ "controlador.\n"
+#: test/ipptool.c:527
+msgid "ipptool: URI required before test file."
+msgstr "ipptool: Se requiere un URI antes del archivo de prueba."
-#~ msgid "ERROR: Unable to write to temporary file"
-#~ msgstr "ERROR: No se ha podido escribir al archivo temporal"
+#: test/ipptool.c:465
+#, c-format
+msgid "ipptool: Unknown option \"-%c\"."
+msgstr "ipptool: Opción \"-%c\" desconocida."
-#~ msgid "ERROR: Unexpected text on line %d of %s!\n"
-#~ msgstr "ERROR: Texto inesperado en la lÃnea %d del %s.\n"
+#: scheduler/ipp.c:9016
+msgid "job-printer-uri attribute missing."
+msgstr "Falta el atributo job-printer-uri."
-#~ msgid "ERROR: Unknown encryption option value \"%s\"!\n"
-#~ msgstr "ERROR: Valor de opción de encriptación \"%s\" desconocida.\n"
+#: systemv/lpadmin.c:131
+#: systemv/lpadmin.c:375
+msgid "lpadmin: Class name can only contain printable characters."
+msgstr "lpadmin: El nombre de la clase sólo puede contener caracteres imprimibles."
-#~ msgid "ERROR: Unknown message catalog format for \"%s\"!\n"
-#~ msgstr "ERROR: Formato del catálogo de mensajes para \"%s\" desconocido.\n"
+#: systemv/lpadmin.c:614
+msgid "lpadmin: Expected PPD after \"-P\" option."
+msgstr "lpadmin: Se esperaba un PPD tras la opción \"-P\"."
-#~ msgid "ERROR: Unknown option \"%s\" with value \"%s\"!\n"
-#~ msgstr "ERROR: Opción \"%s\" con valor \"%s\" desconocida.\n"
+#: systemv/lpadmin.c:457
+msgid "lpadmin: Expected allow/deny:userlist after \"-u\" option."
+msgstr "lpadmin: Se esperaba allow/deny:lista_usuarios tras la opción \"-u\"."
-#~ msgid "ERROR: Unknown version option value \"%s\"!\n"
-#~ msgstr "ERROR: Valor de opción de versión \"%s\" desconocida.\n"
+#: systemv/lpadmin.c:364
+msgid "lpadmin: Expected class after \"-r\" option."
+msgstr "lpadmin: Se esperaba una clase tras la opción \"-r\"."
-#~ msgid "ERROR: Unsupported brightness value %s, using brightness=100!\n"
-#~ msgstr "ERROR: Valor de brillo %s no permitido; usando brillo=100.\n"
+#: systemv/lpadmin.c:120
+msgid "lpadmin: Expected class name after \"-c\" option."
+msgstr "lpadmin: Se esperaba un nombre de clase tras la opción \"-c\"."
-#~ msgid "ERROR: Unsupported gamma value %s, using gamma=1000!\n"
-#~ msgstr "ERROR: Valor gamma %s no permitido; usando gamma=1000.\n"
+#: systemv/lpadmin.c:558
+msgid "lpadmin: Expected description after \"-D\" option."
+msgstr "lpadmin: Se esperaba una descripción tras la opción \"-D\"."
-#~ msgid "ERROR: Unsupported number-up value %d, using number-up=1!\n"
-#~ msgstr ""
-#~ "ERROR: Valor de number-up (páginas por hoja) %d no permitido; usando "
-#~ "number-up=1.\n"
+#: systemv/lpadmin.c:491
+msgid "lpadmin: Expected device URI after \"-v\" option."
+msgstr "lpadmin: Se esperaba un URI de dispositivo tras la opción \"-v\"."
-#~ msgid ""
-#~ "ERROR: Unsupported number-up-layout value %s, using number-up-"
-#~ "layout=lrtb!\n"
-#~ msgstr ""
-#~ "ERROR: Valor de number-up-layout (disposición de páginas por hoja) %s no "
-#~ "permitido; usando number-up-layout=lrtb.\n"
+#: systemv/lpadmin.c:574
+msgid "lpadmin: Expected file type(s) after \"-I\" option."
+msgstr "lpadmin: Se esperaba(n) tipo(s) de archivo(s) tras la opción \"-l\"."
-#~ msgid "ERROR: Unsupported page-border value %s, using page-border=none!\n"
-#~ msgstr ""
-#~ "ERROR: Valor de page-border (borde de página) %s no permitido; usando "
-#~ "page-border=none (ninguno).\n"
+#: systemv/lpadmin.c:202
+msgid "lpadmin: Expected hostname after \"-h\" option."
+msgstr "lpadmin: Se esperaba un nombre de ordenador tras la opción \"-h\"."
-#~ msgid "ERROR: doc_printf overflow (%d bytes) detected, aborting!\n"
-#~ msgstr ""
-#~ "ERROR: Se ha detectado un desbordamiento de doc_printf (%d bytes); "
-#~ "cancelando.\n"
+#: systemv/lpadmin.c:221
+msgid "lpadmin: Expected interface after \"-i\" option."
+msgstr "lpadmin: Se esperaba una interfaz tras la opción \"-i\"."
-#~ msgid "ERROR: pictwpstops exited on signal %d!\n"
-#~ msgstr "ERROR: pictwpstops se ha cerrado con la señal %d.\n"
+#: systemv/lpadmin.c:594
+msgid "lpadmin: Expected location after \"-L\" option."
+msgstr "lpadmin: Se esperaba una ubicación tras la opción \"-L\"."
-#~ msgid "ERROR: pictwpstops exited with status %d!\n"
-#~ msgstr "ERROR: pictwpstops se ha cerrado con el estado %d.\n"
+#: systemv/lpadmin.c:274
+msgid "lpadmin: Expected model after \"-m\" option."
+msgstr "lpadmin: Se esperaba un modelo tras la opción \"-m\"."
-#~ msgid ""
-#~ "ERROR: recoverable: Unable to connect to printer; will retry in 30 "
-#~ "seconds...\n"
-#~ msgstr ""
-#~ "ERROR: recuperable: No se ha podido establecer conexión con la impresora; "
-#~ "reintento en 30 segundos...\n"
+#: systemv/lpadmin.c:417
+msgid "lpadmin: Expected name after \"-R\" option."
+msgstr "lpadmin: Se esperaba un nombre tras la opción \"-R\"."
-#~ msgid "Empty PPD file!"
-#~ msgstr "Archivo PPD vacÃo."
+#: systemv/lpadmin.c:294
+msgid "lpadmin: Expected name=value after \"-o\" option."
+msgstr "lpadmin: Se esperaba un nombre=valor tras la opción \"-o\"."
-#~ msgid "Error: need hostname after '-h' option!\n"
-#~ msgstr "Error: se necesita un nombre de ordenador tras la opción '-h'.\n"
+#: systemv/lpadmin.c:313
+msgid "lpadmin: Expected printer after \"-p\" option."
+msgstr "lpadmin: Se esperaba una impresora tras la opción \"-p\"."
-#~ msgid "Fuser temperature high!"
-#~ msgstr "Temperatura del fusor alta."
+#: systemv/lpadmin.c:164
+msgid "lpadmin: Expected printer name after \"-d\" option."
+msgstr "lpadmin: Se esperaba un nombre de impresora tras la opción \"-d\"."
-#~ msgid "Fuser temperature low!"
-#~ msgstr "Temperatura del fusor baja."
+#: systemv/lpadmin.c:525
+msgid "lpadmin: Expected printer or class after \"-x\" option."
+msgstr "lpadmin: Se esperaba una impresora o clase tras la opción \"-x\"."
-#~ msgid "Got a printer-uri attribute but no job-id!"
-#~ msgstr "Se ha obtenido el atributo printer-uri pero no el job-id."
+#: systemv/lpadmin.c:975
+msgid "lpadmin: No member names were seen."
+msgstr "lpadmin: No se han visto nombres de miembros"
-#~ msgid "Ink/toner almost empty."
-#~ msgstr "Tinta/toner casi vacÃos."
+#: systemv/lpadmin.c:762
+#, c-format
+msgid "lpadmin: Printer %s is already a member of class %s."
+msgstr "lpadmin: La impresora %s ya es miembro de la clase %s."
-#~ msgid "Ink/toner empty!"
-#~ msgstr "Tinta/toner vacÃos."
+#: systemv/lpadmin.c:989
+#, c-format
+msgid "lpadmin: Printer %s is not a member of class %s."
+msgstr "lpadmin: La impresora %s no es miembro de la clase %s."
-#~ msgid "Ink/toner waste bin almost full."
-#~ msgstr "Recipiente de residuos de tinta/tóner casi lleno."
+#: systemv/lpadmin.c:175
+#: systemv/lpadmin.c:324
+#: systemv/lpadmin.c:536
+msgid "lpadmin: Printer name can only contain printable characters."
+msgstr "lpadmin: El nombre de la impresora sólo puede contener caracteres imprimibles."
-#~ msgid "Ink/toner waste bin full!"
-#~ msgstr "Recipiente de residuos de tinta/tóner lleno."
+#: systemv/lpadmin.c:105
+msgid ""
+"lpadmin: Unable to add a printer to the class:\n"
+" You must specify a printer name first."
+msgstr ""
+"lpadmin: No se ha podido añadir una impresora a la clase:\n"
+" Debe especificar un nombre de impresora primero."
-#~ msgid "Interlock open."
-#~ msgstr "Dispositivo de seguridad abierto."
+#: systemv/lpadmin.c:96
+#: systemv/lpadmin.c:149
+#: systemv/lpadmin.c:253
+#: systemv/lpadmin.c:339
+#: systemv/lpadmin.c:393
+#: systemv/lpadmin.c:510
+#: systemv/lpadmin.c:647
+#, c-format
+msgid "lpadmin: Unable to connect to server: %s"
+msgstr "lpadmin: No se ha podido conectar al servidor: %s"
-#~ msgid "Job #%d cannot be restarted - no files!"
-#~ msgstr "El trabajo #%d no puede ser reiniciado - no hay archivos."
+#: systemv/lpadmin.c:1332
+msgid "lpadmin: Unable to create temporary file"
+msgstr "lpadmin: No se ha podido crear el archivo temporal"
-#~ msgid "Job #%d does not exist!"
-#~ msgstr "El trabajo #%d no existe."
+#: systemv/lpadmin.c:402
+msgid ""
+"lpadmin: Unable to delete option:\n"
+" You must specify a printer name first."
+msgstr ""
+"lpadmin: No se ha podido borrar la opción:\n"
+" Primero debe especificar un nombre de impresora."
-#~ msgid "Job #%d is finished and cannot be altered!"
-#~ msgstr "El trabajo #%d ha terminado y no puede ser modificado."
+#: systemv/lpadmin.c:1342
+#, c-format
+msgid "lpadmin: Unable to open PPD file \"%s\" - %s"
+msgstr "lpadmin: No se ha podido abrir el archivo PPD \"%s\" - %s"
-#~ msgid "Job #%d is not complete!"
-#~ msgstr "El trabajo #%d no ha sido completado."
+#: systemv/lpadmin.c:348
+msgid ""
+"lpadmin: Unable to remove a printer from the class:\n"
+" You must specify a printer name first."
+msgstr ""
+"lpadmin: No se ha podido quitar una impresora de la clase:\n"
+" Primero debe especificar un nombre de impresora."
-#~ msgid "Job #%d is not held for authentication!"
-#~ msgstr "El trabajo #%d no está retenido para autentificación."
+#: systemv/lpadmin.c:656
+msgid ""
+"lpadmin: Unable to set the printer options:\n"
+" You must specify a printer name first."
+msgstr ""
+"lpadmin: No se han podido establecer las opciones de impresora:\n"
+" Primero debe especificar un nombre de impresora."
-#~ msgid "Job #%d is not held!"
-#~ msgstr "El trabajo #%d no está retenido."
+#: systemv/lpadmin.c:474
+#, c-format
+msgid "lpadmin: Unknown allow/deny option \"%s\"."
+msgstr "lpadmin: Opción allow/deny desconocida \"%s\"."
-#~ msgid "Job #%s does not exist!"
-#~ msgstr "El trabajo #%s no existe."
+#: systemv/lpadmin.c:629
+#, c-format
+msgid "lpadmin: Unknown argument \"%s\"."
+msgstr "lpadmin: Argumento \"%s\" desconocido."
-#~ msgid "Job %d not found!"
-#~ msgstr "No se ha encontrado el trabajo %d."
+#: systemv/lpadmin.c:624
+#, c-format
+msgid "lpadmin: Unknown option \"%c\"."
+msgstr "lpadmin: Opción \"%c\" desconocida."
-#~ msgid "Job subscriptions cannot be renewed!"
-#~ msgstr "Las suscripciones de trabajos no han podido ser renovadas."
+#: systemv/lpadmin.c:580
+msgid "lpadmin: Warning - content type list ignored."
+msgstr "lpadmin: Advertencia - lista de tipo de contenido no tenida en cuenta."
-#~ msgid "Language \"%s\" not supported!"
-#~ msgstr "No se admite el uso del idioma \"%s\"."
+#: berkeley/lpc.c:76
+#: berkeley/lpc.c:104
+#: berkeley/lpc.c:140
+msgid "lpc> "
+msgstr "lpc> "
-#~ msgid "Media jam!"
-#~ msgstr "Atasco de papel."
+#: systemv/lpinfo.c:137
+msgid "lpinfo: Expected 1284 device ID string after \"--device-id\"."
+msgstr "lpinfo: Se esperaba una cadena ID de dispositivo 1284 tras \"--device-id\"."
-#~ msgid "Media tray almost empty."
-#~ msgstr "Bandeja de papel casi vacÃa."
+#: systemv/lpinfo.c:190
+msgid "lpinfo: Expected language after \"--language\"."
+msgstr "lpinfo: Se esperaba un idioma tras \"--language\"."
-#~ msgid "Media tray empty!"
-#~ msgstr "Bandeja de papel vacÃa."
+#: systemv/lpinfo.c:207
+msgid "lpinfo: Expected make and model after \"--make-and-model\"."
+msgstr "lpinfo: Se esperaba marca y modelo tras \"--make-and-model\"."
-#~ msgid "Media tray missing!"
-#~ msgstr "Falta la bandeja de papel."
+#: systemv/lpinfo.c:224
+msgid "lpinfo: Expected product string after \"--product\"."
+msgstr "lpinfo: Se esperaba una cadena de producto tras \"--product\"."
-#~ msgid "Media tray needs to be filled."
-#~ msgstr "Hay que poner papel en la bandeja."
+#: systemv/lpinfo.c:155
+msgid "lpinfo: Expected scheme list after \"--exclude-schemes\"."
+msgstr "lpinfo: Se esperaba una lista de esquemas tras \"--exclude-schemes\"."
-#~ msgid "Missing document-number attribute!"
-#~ msgstr "Falta el atributo document-number."
+#: systemv/lpinfo.c:173
+msgid "lpinfo: Expected scheme list after \"--include-schemes\"."
+msgstr "lpinfo: Se esperaba una lista de esquemas tras \"--include-schemes\"."
-#~ msgid "Missing double quote on line %d!"
-#~ msgstr "Faltan dobles comillas en lÃnea %d."
+#: systemv/lpinfo.c:241
+msgid "lpinfo: Expected timeout after \"--timeout\"."
+msgstr "lpinfo: Se esperaba un tiempo de espera tras \"--timeout\"."
-#~ msgid "Missing form variable!"
-#~ msgstr "Variable de formulario desaparecida."
+#: systemv/lpinfo.c:265
+#, c-format
+msgid "lpinfo: Unknown argument \"%s\"."
+msgstr "lpinfo: Argumento \"%s\" desconocido."
-#~ msgid "Missing notify-subscription-ids attribute!"
-#~ msgstr "Atributo notify-subscription-ids desaparecido."
+#: systemv/lpinfo.c:259
+#, c-format
+msgid "lpinfo: Unknown option \"%c\"."
+msgstr "lpinfo: Opción \"%c\" desconocida."
-#~ msgid "Missing requesting-user-name attribute!"
-#~ msgstr "Falta el atributo requesting-user-name."
+#: systemv/lpinfo.c:252
+#, c-format
+msgid "lpinfo: Unknown option \"%s\"."
+msgstr "lpinfo: Opción \"%s\" desconocida."
-#~ msgid "Missing required attributes!"
-#~ msgstr "Faltan atributos necesarios."
+#: systemv/lpmove.c:133
+#, c-format
+msgid "lpmove: Unable to connect to server: %s"
+msgstr "lpmove: No se ha podido conectar al servidor: %s"
-#~ msgid "Missing value on line %d!"
-#~ msgstr "Falta un valor en la lÃnea %d."
+#: systemv/lpmove.c:119
+#, c-format
+msgid "lpmove: Unknown argument \"%s\"."
+msgstr "lpmove: Argumento \"%s\" desconocido."
-#~ msgid "Nested classes are not allowed!"
-#~ msgstr "No se permiten clases anidadas."
+#: systemv/lpmove.c:97
+#, c-format
+msgid "lpmove: Unknown option \"%c\"."
+msgstr "lpmove: Opción \"%c\" desconocida."
-#~ msgid "No PPD name!"
-#~ msgstr "No hay nombre de PPD."
+#: systemv/lpoptions.c:150
+#: systemv/lpoptions.c:168
+#: systemv/lpoptions.c:244
+msgid "lpoptions: No printers."
+msgstr "lpoptions: No hay impresoras."
-#~ msgid "No Windows printer drivers are installed!"
-#~ msgstr "No está instalado ningún controlador de impresora de Windows."
+#: systemv/lpoptions.c:219
+#, c-format
+msgid "lpoptions: Unable to add printer or instance: %s"
+msgstr "lpoptions: No se ha podido añadir la impresora o la instancia: %s"
-#~ msgid "No active jobs on %s!"
-#~ msgstr "No hay trabajos activos en %s."
+#: systemv/lpoptions.c:521
+#, c-format
+msgid "lpoptions: Unable to get PPD file for %s: %s"
+msgstr "lpoptions: No se ha podido obtener el archivo PPD para %s: %s"
-#~ msgid "No attributes in request!"
-#~ msgstr "No hay atributos en la solicitud."
+#: systemv/lpoptions.c:529
+#, c-format
+msgid "lpoptions: Unable to open PPD file for %s."
+msgstr "lpoptions: No se ha podido abrir el archivo PPD para %s."
-#~ msgid "No authentication information provided!"
-#~ msgstr "No se ha proporcionado información de autentificación."
+#: systemv/lpoptions.c:99
+msgid "lpoptions: Unknown printer or class."
+msgstr "lpoptions: Impresora o clase desconocida."
-#~ msgid "No file!?!"
-#~ msgstr "¡¿¡No hay archivo!?!"
+#: systemv/lppasswd.c:173
+msgid "lppasswd: Only root can add or delete passwords."
+msgstr "lppasswd: Solo el usuario root puede añadir o borrar contraseñas."
-#~ msgid "No modification time!"
-#~ msgstr "No hay tiempo de modificación."
+#: systemv/lppasswd.c:302
+msgid "lppasswd: Password file busy."
+msgstr "lppasswd: Archivo de contraseñas ocupado."
-#~ msgid "No printer name!"
-#~ msgstr "No hay nombre de impresora."
+#: systemv/lppasswd.c:431
+msgid "lppasswd: Password file not updated."
+msgstr "lppasswd: Archivo de contraseñas no actualizado."
-#~ msgid "No printer-uri found for class!"
-#~ msgstr "No se encontró printer-uri para la clase."
+#: systemv/lppasswd.c:398
+msgid "lppasswd: Sorry, password doesn't match."
+msgstr "lppasswd: Lo siento, la contraseña no coincide."
-#~ msgid "No printer-uri found!"
-#~ msgstr "No se encontró printer-uri."
+#: systemv/lppasswd.c:253
+msgid "lppasswd: Sorry, password rejected."
+msgstr "lppasswd: Lo siento, la contraseña ha sido rechazada."
-#~ msgid "No printer-uri in request!"
-#~ msgstr "No hay printer-uri en la petición."
+#: systemv/lppasswd.c:230
+msgid "lppasswd: Sorry, passwords don't match."
+msgstr "lppasswd: Lo siento, las contraseñas no coinciden."
-#~ msgid "No subscription attributes in request!"
-#~ msgstr "No hay atributos de subscripción en la solicitud."
+#: systemv/lppasswd.c:199
+#: systemv/lppasswd.c:218
+#, c-format
+msgid "lppasswd: Unable to copy password string: %s"
+msgstr "lppasswd: No se ha podido copiar la cadena de contraseña: %s"
-#~ msgid "OPC almost at end-of-life."
-#~ msgstr "OPC prácticamente agotado."
+#: systemv/lppasswd.c:304
+#: systemv/lppasswd.c:312
+#: systemv/lppasswd.c:329
+#, c-format
+msgid "lppasswd: Unable to open password file: %s"
+msgstr "lppasswd: No se ha podido abrir el archivo de contraseñas: %s"
-#~ msgid "OPC at end-of-life!"
-#~ msgstr "OPC agotado."
+#: systemv/lppasswd.c:364
+#: systemv/lppasswd.c:377
+#: systemv/lppasswd.c:408
+#, c-format
+msgid "lppasswd: Unable to write to password file: %s"
+msgstr "lppasswd: No se ha podido escribir en el archivo de contraseñas: %s"
-#~ msgid "Out of toner!"
-#~ msgstr "No hay toner."
+#: systemv/lppasswd.c:446
+#, c-format
+msgid "lppasswd: failed to backup old password file: %s"
+msgstr "lppasswd: falló al hacer una copia de seguridad del antiguo archivo de contraseñas: %s"
-#~ msgid "Output bin almost full."
-#~ msgstr "Recipiente de salida casi lleno."
+#: systemv/lppasswd.c:458
+#, c-format
+msgid "lppasswd: failed to rename password file: %s"
+msgstr "lppasswd: falló al cambiar de nombre al archivo de contraseñas: %s"
-#~ msgid "Output bin full!"
-#~ msgstr "Recipiente de salida lleno."
+#: systemv/lppasswd.c:389
+#, c-format
+msgid "lppasswd: user \"%s\" and group \"%s\" do not exist."
+msgstr "lppasswd: el usuario \"%s\" y el grupo \"%s\" no existen."
-#~ msgid "Output tray missing!"
-#~ msgstr "Falta la bandeja de salida."
+#: systemv/lpstat.c:1036
+#, c-format
+msgid "lpstat: error - %s environment variable names non-existent destination \"%s\"."
+msgstr "lpstat: error - Los nombre de variable de entorno %s no existen en el destino \"%s\"."
-#~ msgid "Printer offline."
-#~ msgstr "Impresora desconectada."
+#: systemv/lpstat.c:967
+#, c-format
+msgid "members of class %s:"
+msgstr "miembros de la clase %s:"
-#~ msgid "SCSI Printer"
-#~ msgstr "Impresora SCSI"
+#: berkeley/lpq.c:582
+msgid "no entries"
+msgstr "no hay entradas"
-#~ msgid "The notify-user-data value is too large (%d > 63 octets)!"
-#~ msgstr "El valor notify-user-data es demasiado grande (%d > 63 octetos)."
+#: systemv/lpstat.c:1040
+msgid "no system default destination"
+msgstr "no hay un destino predeterminado del sistema"
-#~ msgid "The printer or class is not shared!"
-#~ msgstr "La impresora o clase no está compartida."
+#: scheduler/ipp.c:6884
+msgid "notify-events not specified."
+msgstr "notify-events no especificado."
-#~ msgid "The printer-uri attribute is required!"
-#~ msgstr "Se necesita el atributo printer-uri."
+#: scheduler/ipp.c:2179
+#: scheduler/ipp.c:6789
+#, c-format
+msgid "notify-recipient-uri URI \"%s\" is already used."
+msgstr "El URI notify-recipient-uri \"%s\" ya está usado."
-#~ msgid "Toner low."
-#~ msgstr "Toner bajo."
+#: scheduler/ipp.c:2169
+#: scheduler/ipp.c:6779
+#, c-format
+msgid "notify-recipient-uri URI \"%s\" uses unknown scheme."
+msgstr "El URI notify-recipient-uri \"%s\" usa un esquema desconocido."
-#~ msgid "Too many job-sheets values (%d > 2)!"
-#~ msgstr "Demasiados valores de job-sheets (%d > 2)."
+#: cups/notify.c:87
+msgid "pending"
+msgstr "pendiente"
-#~ msgid "Too many printer-state-reasons values (%d > %d)!"
-#~ msgstr "Demasiados valores printer-state-reasons (%d > %d)."
+#: ppdc/ppdc.cxx:113
+#: ppdc/ppdpo.cxx:93
+#, c-format
+msgid "ppdc: Adding include directory \"%s\"."
+msgstr "ppdc: Añadiendo directorio include \"%s\"."
-#~ msgid "Unable to add job for destination \"%s\"!"
-#~ msgstr "No se ha podido añadir el trabajo para el destino \"%s\"."
+#: ppdc/ppdpo.cxx:134
+#, c-format
+msgid "ppdc: Adding/updating UI text from %s."
+msgstr "ppdc: Añadiendo/actualizando texto UI desde %s."
-#~ msgid "Unable to allocate memory for file types!"
-#~ msgstr "No se ha podido reservar memoria para tipos de archivo."
+#: ppdc/ppdc-source.cxx:412
+#, c-format
+msgid "ppdc: Bad boolean value (%s) on line %d of %s."
+msgstr "ppdc: Valor lógico (%s) incorrecto en lÃnea %d de %s."
-#~ msgid "Unable to copy 64-bit CUPS printer driver files (%d)!"
-#~ msgstr ""
-#~ "No se han podido copiar los archivos del controlador de impresora de 64-"
-#~ "bit de CUPS (%d)."
+#: ppdc/ppdc-import.cxx:264
+#, c-format
+msgid "ppdc: Bad font attribute: %s"
+msgstr "ppdc: Atributo de fuente: %s incorrecto"
-#~ msgid "Unable to copy 64-bit Windows printer driver files (%d)!"
-#~ msgstr ""
-#~ "No se han podido copiar los archivos del controlador de impresora de 64-"
-#~ "bit de Windows (%d)."
+#: ppdc/ppdc-source.cxx:1797
+#, c-format
+msgid "ppdc: Bad resolution name \"%s\" on line %d of %s."
+msgstr "ppdc: Resolución de nombre \"%s\" incorrecta en lÃnea %d de %s."
-#~ msgid "Unable to copy CUPS printer driver files (%d)!"
-#~ msgstr ""
-#~ "No se han podido copiar los archivos del controlador de impresora de CUPS "
-#~ "(%d)."
+#: ppdc/ppdc-source.cxx:1115
+#, c-format
+msgid "ppdc: Bad status keyword %s on line %d of %s."
+msgstr "ppdc: Clave de estado %s incorrecta en lÃnea %d de %s."
-#~ msgid "Unable to copy PPD file - %s!"
-#~ msgstr "No se ha podido copiar el archivo PPD - %s."
+#: ppdc/ppdc-source.cxx:2034
+#, c-format
+msgid "ppdc: Bad variable substitution ($%c) on line %d of %s."
+msgstr "ppdc: Sustitución de variable ($%c) errónea en la lÃnea %d de %s."
-#~ msgid "Unable to copy PPD file!"
-#~ msgstr "No se ha podido copiar el archivo PPD."
+#: ppdc/ppdc-source.cxx:2710
+#, c-format
+msgid "ppdc: Choice found on line %d of %s with no Option."
+msgstr "ppdc: Selección encontrada en lÃnea %d de %s sin opciones."
-#~ msgid "Unable to copy Windows 2000 printer driver files (%d)!"
-#~ msgstr ""
-#~ "No se han podido copiar los archivos del controlador de impresora de "
-#~ "Windows 2000 (%d)."
+#: ppdc/ppdc-source.cxx:1699
+#, c-format
+msgid "ppdc: Duplicate #po for locale %s on line %d of %s."
+msgstr "ppdc: #po duplicado para código regional %s en lÃnea %d de %s."
-#~ msgid "Unable to copy Windows 9x printer driver files (%d)!"
-#~ msgstr ""
-#~ "No se han podido copiar los archivos del controlador de impresora de "
-#~ "Windows 9x (%d)."
+#: ppdc/ppdc-source.cxx:934
+#, c-format
+msgid "ppdc: Expected a filter definition on line %d of %s."
+msgstr "ppdc: Se esperaba una definición de filtro en la lÃnea %d de %s."
-#~ msgid "Unable to copy interface script - %s!"
-#~ msgstr "No se ha podido copiar el script de interfaz - %s."
+#: ppdc/ppdc-source.cxx:957
+#, c-format
+msgid "ppdc: Expected a program name on line %d of %s."
+msgstr "ppdc: Se esperaba un nombre de programa en la lÃnea %d de %s."
-#~ msgid "Unable to create printer-uri!"
-#~ msgstr "No se ha podido crear printer-uri."
+#: ppdc/ppdc-source.cxx:396
+#, c-format
+msgid "ppdc: Expected boolean value on line %d of %s."
+msgstr "ppdc: Se esperaba un valor lógico en la lÃnea %d de %s."
-#~ msgid "Unable to edit cupsd.conf files larger than 1MB!"
-#~ msgstr "No se pueden editar archivos cupsd.conf mayores de 1MB."
+#: ppdc/ppdc-source.cxx:1095
+#, c-format
+msgid "ppdc: Expected charset after Font on line %d of %s."
+msgstr "ppdc: Se esperaba un juego de caracteres tras Font en la lÃnea %d de %s."
-#~ msgid "Unable to find destination for job!"
-#~ msgstr "No se ha podido encontrar destino para el trabajo."
-
-#~ msgid "Unable to find printer!\n"
-#~ msgstr "No se ha podido encontrar la impresora.\n"
-
-#~ msgid "Unable to install Windows 2000 printer driver files (%d)!"
-#~ msgstr ""
-#~ "No se han podido instalar los archivos del controlador de impresora de "
-#~ "Windows 2000 (%d)."
-
-#~ msgid "Unable to install Windows 9x printer driver files (%d)!"
-#~ msgstr ""
-#~ "No se han podido instalar los archivos del controlador de impresora de "
-#~ "Windows 9x (%d)."
-
-#~ msgid "Unable to open document %d in job %d!"
-#~ msgstr "No se ha podido abrir el documento %d del trabajo %d."
-
-#~ msgid "Unable to send command to printer driver!"
-#~ msgstr "No se ha podido enviar un comando al controlador de la impresora."
-
-#~ msgid "Unable to set Windows printer driver (%d)!"
-#~ msgstr ""
-#~ "No se ha podido configurar el controlador de impresora de Windows (%d)."
-
-#~ msgid "Unable to use legacy USB class driver!\n"
-#~ msgstr "No se ha podido usar el controlador de dispositivo USB obsoleto.\n"
-
-#~ msgid "Unsupported character set \"%s\"!"
-#~ msgstr "Juego de caracteres \"%s\" no permitido."
-
-#~ msgid "Unsupported compression \"%s\"!"
-#~ msgstr "No se admite el uso de la compresión \"%s\"."
-
-#~ msgid "Unsupported compression attribute %s!"
-#~ msgstr "No se admite el uso del atributo de compresión %s."
-
-#~ msgid "Unsupported format \"%s\"!"
-#~ msgstr "No se admite el uso del formato \"%s\"."
-
-#~ msgid "Unsupported format '%s'!"
-#~ msgstr "No se admite el uso del formato '%s'."
-
-#~ msgid "Unsupported format '%s/%s'!"
-#~ msgstr "No se admite el uso del formato '%s/%s'."
-
-#~ msgid ""
-#~ "Usage: cupstestppd [options] filename1.ppd[.gz] [... filenameN.ppd[.gz]]\n"
-#~ " program | cupstestppd [options] -\n"
-#~ "\n"
-#~ "Options:\n"
-#~ "\n"
-#~ " -R root-directory Set alternate root\n"
-#~ " -W {all,none,constraints,defaults,duplex,filters,profiles,sizes,"
-#~ "translations}\n"
-#~ " Issue warnings instead of errors\n"
-#~ " -q Run silently\n"
-#~ " -r Use 'relaxed' open mode\n"
-#~ " -v Be slightly verbose\n"
-#~ " -vv Be very verbose\n"
-#~ msgstr ""
-#~ "Uso: cupstestppd [opciones] nombre_archivo1.ppd[.gz] [... nombre_archivoN."
-#~ "ppd[.gz]]\n"
-#~ " programa | cupstestppd [opciones] -\n"
-#~ "\n"
-#~ "Opciones:\n"
-#~ "\n"
-#~ " -R directorio-raÃz Establecer directorio raÃz alternativo\n"
-#~ " -W {all,none,constraints,defaults,duplex,filters,profiles,sizes,"
-#~ "translations}\n"
-#~ " Emitir avisos (warnings) en vez de errores\n"
-#~ " -q Ejecución silenciosa\n"
-#~ " -r Usar modo abierto 'relajado'\n"
-#~ " -v Ser ligeramente detallado\n"
-#~ " -vv Ser muy detallado\n"
-
-#~ msgid "WARNING: Failed to read side-channel request!\n"
-#~ msgstr "WARNING: No se ha podido leer la petición del canal lateral.\n"
-
-#~ msgid "WARNING: Option \"%s\" cannot be included via IncludeFeature!\n"
-#~ msgstr "WARNING: La opción \"%s\" no puede incluirse con IncludeFeature.\n"
-
-#~ msgid ""
-#~ "WARNING: Remote host did not respond with command status byte after %d "
-#~ "seconds!\n"
-#~ msgstr ""
-#~ "WARNING: El ordenador remoto no ha respondido con el byte de estado del "
-#~ "comando después de %d segundos.\n"
-
-#~ msgid ""
-#~ "WARNING: Remote host did not respond with control status byte after %d "
-#~ "seconds!\n"
-#~ msgstr ""
-#~ "WARNING: El ordenador remoto no ha respondido con el byte de estado de "
-#~ "control después de %d segundos.\n"
-
-#~ msgid ""
-#~ "WARNING: Remote host did not respond with data status byte after %d "
-#~ "seconds!\n"
-#~ msgstr ""
-#~ "WARNING: El ordenador remoto no ha respondido con el byte de estado de "
-#~ "los datos después de %d segundos.\n"
-
-#~ msgid "WARNING: SCSI command timed out (%d); retrying...\n"
-#~ msgstr ""
-#~ "WARNING: Agotado el tiempo de espera para el comando SCSI (%d); "
-#~ "reintentando...\n"
-
-#~ msgid ""
-#~ "WARNING: This document does not conform to the Adobe Document Structuring "
-#~ "Conventions and may not print correctly!\n"
-#~ msgstr ""
-#~ "WARNING: Este documento no se ajusta a las Convenciones de Estructuración "
-#~ "de Documentos de Adobe y puede que no se imprima correctamente.\n"
-
-#~ msgid "WARNING: Unknown choice \"%s\" for option \"%s\"!\n"
-#~ msgstr "WARNING: Preferencia \"%s\" desconocida para la opción \"%s\".\n"
-
-#~ msgid "WARNING: Unknown option \"%s\"!\n"
-#~ msgstr "WARNING: Opción \"%s\" desconocida.\n"
-
-#~ msgid "WARNING: Unsupported baud rate %s!\n"
-#~ msgstr "WARNING: No se admite el uso de la velocidad en baudios %s.\n"
-
-#~ msgid ""
-#~ "WARNING: recoverable: Network host '%s' is busy; will retry in %d "
-#~ "seconds...\n"
-#~ msgstr ""
-#~ "WARNING: recuperable: El ordenador de red '%s' está ocupado; reintento en "
-#~ "%d segundos...\n"
-
-#~ msgid "Warning, no Windows 2000 printer drivers are installed!"
-#~ msgstr ""
-#~ "Advertencia, no está instalado ningún controlador de impresora de Windows "
-#~ "2000."
-
-#~ msgid "cupsctl: Unknown option \"%s\"!\n"
-#~ msgstr "cupsctl: Opción \"%s\" desconocida.\n"
-
-#~ msgid "cupsctl: Unknown option \"-%c\"!\n"
-#~ msgstr "cupsctl: Opción \"-%c\" desconocida.\n"
-
-#~ msgid "cupsd: Expected config filename after \"-c\" option!\n"
-#~ msgstr ""
-#~ "cupsd: Se esperaba un nombre de archivo de configuración tras la opción "
-#~ "\"-c\".\n"
-
-#~ msgid "cupsd: Unable to get current directory!\n"
-#~ msgstr "cupsd: No se ha podido obtener el directorio actual.\n"
-
-#~ msgid "cupsd: Unknown argument \"%s\" - aborting!\n"
-#~ msgstr "cupsd: Argumento \"%s\" desconocido - cancelando.\n"
-
-#~ msgid "cupsd: Unknown option \"%c\" - aborting!\n"
-#~ msgstr "cupsd: Opción \"%c\" desconocida - cancelando.\n"
-
-#~ msgid "cupsfilter: Invalid document number %d!\n"
-#~ msgstr "cupsfilter: Número de documento %d inválido.\n"
-
-#~ msgid "cupsfilter: Invalid job ID %d!\n"
-#~ msgstr "cupsfilter: ID de trabajo %d inválida.\n"
-
-#~ msgid "cupsfilter: Only one filename can be specified!\n"
-#~ msgstr "cupsfilter: Solo se puede especificar un nombre de archivo.\n"
-
-#~ msgid "job-printer-uri attribute missing!"
-#~ msgstr "Falta el atributo job-printer-uri."
-
-#~ msgid "lpadmin: Class name can only contain printable characters!\n"
-#~ msgstr ""
-#~ "lpadmin: El nombre de la clase sólo puede contener caracteres "
-#~ "imprimibles.\n"
-
-#~ msgid "lpadmin: Expected PPD after '-P' option!\n"
-#~ msgstr "lpadmin: Se esperaba un PPD tras la opción '-P'.\n"
-
-#~ msgid "lpadmin: Expected allow/deny:userlist after '-u' option!\n"
-#~ msgstr ""
-#~ "lpadmin: Se esperaba allow/deny:lista_usuarios tras la opción '-u'.\n"
-
-#~ msgid "lpadmin: Expected class after '-r' option!\n"
-#~ msgstr "lpadmin: Se esperaba una clase tras la opción '-r'\n"
-
-#~ msgid "lpadmin: Expected class name after '-c' option!\n"
-#~ msgstr "lpadmin: Se esperaba un nombre de clase tras la opción '-c'\n"
-
-#~ msgid "lpadmin: Expected description after '-D' option!\n"
-#~ msgstr "lpadmin: Se esperaba una descripción tras la opción '-D'.\n"
-
-#~ msgid "lpadmin: Expected device URI after '-v' option!\n"
-#~ msgstr "lpadmin: Se esperaba un URI de dispositivo tras la opción '-v'.\n"
-
-#~ msgid "lpadmin: Expected file type(s) after '-I' option!\n"
-#~ msgstr "lpadmin: Se esperaba tipo(s) de archivo(s) tras la opción '-l'.\n"
-
-#~ msgid "lpadmin: Expected hostname after '-h' option!\n"
-#~ msgstr "lpadmin: Se esperaba un nombre de ordenador tras la opción '-h'.\n"
-
-#~ msgid "lpadmin: Expected interface after '-i' option!\n"
-#~ msgstr "lpadmin: Se esperaba una interfaz tras la opción '-i'.\n"
-
-#~ msgid "lpadmin: Expected location after '-L' option!\n"
-#~ msgstr "lpadmin: Se esperaba una ubicación tras la opción '-L'.\n"
-
-#~ msgid "lpadmin: Expected model after '-m' option!\n"
-#~ msgstr "lpadmin: Se esperaba un modelo tras la opción '-m'.\n"
-
-#~ msgid "lpadmin: Expected name=value after '-o' option!\n"
-#~ msgstr "lpadmin: Se esperaba un nombre=valor tras la opción '-o'.\n"
-
-#~ msgid "lpadmin: Expected printer after '-p' option!\n"
-#~ msgstr "lpadmin: Se esperaba una impresora tras la opción '-p'.\n"
-
-#~ msgid "lpadmin: Expected printer name after '-d' option!\n"
-#~ msgstr "lpadmin: Se esperaba un nombre de impresora tras la opción '-d'\n"
-
-#~ msgid "lpadmin: Expected printer or class after '-x' option!\n"
-#~ msgstr "lpadmin: Se esperaba una impresora o clase tras la opción '-x'.\n"
-
-#~ msgid "lpadmin: No member names were seen!\n"
-#~ msgstr "lpadmin: No se han visto nombres de miembros.\n"
-
-#~ msgid "lpadmin: Printer name can only contain printable characters!\n"
-#~ msgstr ""
-#~ "lpadmin: El nombre de la impresora sólo puede contener caracteres "
-#~ "imprimibles.\n"
+#: ppdc/ppdc-source.cxx:449
+#, c-format
+msgid "ppdc: Expected choice code on line %d of %s."
+msgstr "ppdc: Se esperaba un código apropiado en la lÃnea %d de %s."
-#~ msgid ""
-#~ "lpadmin: Unable to add a printer to the class:\n"
-#~ " You must specify a printer name first!\n"
-#~ msgstr ""
-#~ "lpadmin: No se ha podido añadir una impresora a la clase:\n"
-#~ " Debe especificar un nombre de impresora primero.\n"
+#: ppdc/ppdc-source.cxx:437
+#, c-format
+msgid "ppdc: Expected choice name/text on line %d of %s."
+msgstr "ppdc: Se esperaba un nombre/texto apropiado en la lÃnea %d de %s."
-#~ msgid ""
-#~ "lpadmin: Unable to remove a printer from the class:\n"
-#~ " You must specify a printer name first!\n"
-#~ msgstr ""
-#~ "lpadmin: No se ha podido quitar una impresora de la clase:\n"
-#~ " Primero debe especificar un nombre de impresora.\n"
+#: ppdc/ppdc-source.cxx:505
+#, c-format
+msgid "ppdc: Expected color order for ColorModel on line %d of %s."
+msgstr "ppdc: Se esperaba un orden de color para ColorModel en la lÃnea %d de %s."
-#~ msgid ""
-#~ "lpadmin: Unable to set the PPD file:\n"
-#~ " You must specify a printer name first!\n"
-#~ msgstr ""
-#~ "lpadmin: No se ha podido establecer el archivo PPD:\n"
-#~ " Primero debe especificar un nombre de impresora.\n"
+#: ppdc/ppdc-source.cxx:494
+#, c-format
+msgid "ppdc: Expected colorspace for ColorModel on line %d of %s."
+msgstr "ppdc: Se esperaba colorspace para ColorModel en la lÃnea %d de %s."
-#~ msgid ""
-#~ "lpadmin: Unable to set the device URI:\n"
-#~ " You must specify a printer name first!\n"
-#~ msgstr ""
-#~ "lpadmin: No se ha podido ajustar el URI de dispositivo:\n"
-#~ " Primero debe especificar un nombre de impresora.\n"
+#: ppdc/ppdc-source.cxx:516
+#, c-format
+msgid "ppdc: Expected compression for ColorModel on line %d of %s."
+msgstr "ppdc: Se esperaba compresión para ColorModel en la lÃnea %d de %s."
-#~ msgid ""
-#~ "lpadmin: Unable to set the interface script or PPD file:\n"
-#~ " You must specify a printer name first!\n"
-#~ msgstr ""
-#~ "lpadmin: No se ha podido establecer el script de interfaz o el archivo "
-#~ "PPD:\n"
-#~ " Primero debe especificar un nombre de impresora.\n"
+#: ppdc/ppdc-source.cxx:697
+#, c-format
+msgid "ppdc: Expected constraints string for UIConstraints on line %d of %s."
+msgstr "ppdc: Se esperaba una cadena de restricciones para UIConstraints en la lÃnea %d de %s."
-#~ msgid ""
-#~ "lpadmin: Unable to set the interface script:\n"
-#~ " You must specify a printer name first!\n"
-#~ msgstr ""
-#~ "lpadmin: No se ha podido establecer el script de interfaz:\n"
-#~ " Primero debe especificar un nombre de impresora.\n"
+#: ppdc/ppdc-source.cxx:2896
+#, c-format
+msgid "ppdc: Expected driver type keyword following DriverType on line %d of %s."
+msgstr "ppdc: Se esperaba una clave de tipo de controlador tras DriverType en la lÃnea %d de %s."
-#~ msgid ""
-#~ "lpadmin: Unable to set the printer description:\n"
-#~ " You must specify a printer name first!\n"
-#~ msgstr ""
-#~ "lpadmin: No se ha podido establecer la descripción de la impresora:\n"
-#~ " Primero debe especificar un nombre de impresora.\n"
+#: ppdc/ppdc-source.cxx:828
+#, c-format
+msgid "ppdc: Expected duplex type after Duplex on line %d of %s."
+msgstr "ppdc: Se esperaba un tipo dúplex tras Duplex en la lÃnea %d de %s."
-#~ msgid ""
-#~ "lpadmin: Unable to set the printer location:\n"
-#~ " You must specify a printer name first!\n"
-#~ msgstr ""
-#~ "lpadmin: No se ha podido establecer la ubicación de la impresora:\n"
-#~ " Primero debe especificar un nombre de impresora.\n"
+#: ppdc/ppdc-source.cxx:1079
+#, c-format
+msgid "ppdc: Expected encoding after Font on line %d of %s."
+msgstr "ppdc: Se esperaba una codificación tras Font en la lÃnea %d de %s."
-#~ msgid ""
-#~ "lpadmin: Unable to set the printer options:\n"
-#~ " You must specify a printer name first!\n"
-#~ msgstr ""
-#~ "lpadmin: No se han podido establecer las opciones de impresora:\n"
-#~ " Primero debe especificar un nombre de impresora.\n"
+#: ppdc/ppdc-source.cxx:1690
+#, c-format
+msgid "ppdc: Expected filename after #po %s on line %d of %s."
+msgstr "ppdc: Se esperaba un nombre de archivo tras #po %s en la lÃnea %d de %s."
-#~ msgid "lpadmin: Unknown allow/deny option \"%s\"!\n"
-#~ msgstr "lpadmin: Opción allow/deny desconocida \"%s\".\n"
+#: ppdc/ppdc-source.cxx:1207
+#, c-format
+msgid "ppdc: Expected group name/text on line %d of %s."
+msgstr "ppdc: Se esperaba un nombre/texto de grupo en la lÃnea %d de %s."
-#~ msgid "lpadmin: Unknown argument '%s'!\n"
-#~ msgstr "lpadmin: Argumento '%s' desconocido.\n"
+#: ppdc/ppdc-source.cxx:2610
+#, c-format
+msgid "ppdc: Expected include filename on line %d of %s."
+msgstr "ppdc: Se esperaba un nombre de archivo include en la lÃnea %d de %s."
-#~ msgid "lpadmin: Unknown option '%c'!\n"
-#~ msgstr "lpadmin: Opción '%c' desconocida.\n"
+#: ppdc/ppdc-source.cxx:1503
+#, c-format
+msgid "ppdc: Expected integer on line %d of %s."
+msgstr "ppdc: Se esperaba un número entero en la lÃnea %d de %s."
-#~ msgid "lpadmin: Warning - content type list ignored!\n"
-#~ msgstr ""
-#~ "lpadmin: Advertencia - lista de tipo de contenido no tenida en cuenta.\n"
+#: ppdc/ppdc-source.cxx:1682
+#, c-format
+msgid "ppdc: Expected locale after #po on line %d of %s."
+msgstr "ppdc: Se esperaba un código regional tras #po en la lÃnea %d de %s."
-#~ msgid "lpinfo: Expected 1284 device ID string after --device-id!\n"
-#~ msgstr ""
-#~ "lpinfo: Se esperaba una cadena ID de dispositivo 1284 tras --device-id.\n"
+#: ppdc/ppdc-source.cxx:355
+#, c-format
+msgid "ppdc: Expected name after %s on line %d of %s."
+msgstr "ppdc: Se esperaba un nombre tras %s en la lÃnea %d de %s."
-#~ msgid "lpinfo: Expected language after --language!\n"
-#~ msgstr "lpinfo: Se esperaba un idioma tras --language.\n"
+#: ppdc/ppdc-source.cxx:3268
+#, c-format
+msgid "ppdc: Expected name after FileName on line %d of %s."
+msgstr "ppdc: Se esperaba un nombre tras FileName en la lÃnea %d de %s."
-#~ msgid "lpinfo: Expected make and model after --make-and-model!\n"
-#~ msgstr "lpinfo: Se esperaba marca y modelo tras --make-and-model.\n"
+#: ppdc/ppdc-source.cxx:1060
+#, c-format
+msgid "ppdc: Expected name after Font on line %d of %s."
+msgstr "ppdc: Se esperaba un nombre tras Font en la lÃnea %d de %s."
-#~ msgid "lpinfo: Expected product string after --product!\n"
-#~ msgstr "lpinfo: Se esperaba una cadena de producto tras --product.\n"
+#: ppdc/ppdc-source.cxx:3099
+#, c-format
+msgid "ppdc: Expected name after Manufacturer on line %d of %s."
+msgstr "ppdc: Se esperaba un nombre tras Manufacturer en la lÃnea %d de %s."
-#~ msgid "lpinfo: Expected scheme list after --exclude-schemes!\n"
-#~ msgstr "lpinfo: Se esperaba una lista de esquemas tras --exclude-schemes.\n"
+#: ppdc/ppdc-source.cxx:3132
+#, c-format
+msgid "ppdc: Expected name after MediaSize on line %d of %s."
+msgstr "ppdc: Se esperaba un nombre tras MediaSize en la lÃnea %d de %s."
-#~ msgid "lpinfo: Expected scheme list after --include-schemes!\n"
-#~ msgstr "lpinfo: Se esperaba una lista de esquemas tras --include-schemes.\n"
-
-#~ msgid "lpinfo: Expected timeout after --timeout!\n"
-#~ msgstr "lpinfo: Se esperaba un tiempo tras --timeout.\n"
+#: ppdc/ppdc-source.cxx:3222
+#, c-format
+msgid "ppdc: Expected name after ModelName on line %d of %s."
+msgstr "ppdc: Se esperaba un nombre tras ModelName en la lÃnea %d de %s."
-#~ msgid "lpinfo: Unknown argument '%s'!\n"
-#~ msgstr "lpinfo Argumento '%s' desconocido.\n"
-
-#~ msgid "lpinfo: Unknown option '%c'!\n"
-#~ msgstr "lpinfo: Opción '%c' desconocida.\n"
+#: ppdc/ppdc-source.cxx:3285
+#, c-format
+msgid "ppdc: Expected name after PCFileName on line %d of %s."
+msgstr "ppdc: Se esperaba un nombre tras PCFileName en la lÃnea %d de %s."
-#~ msgid "lpinfo: Unknown option '%s'!\n"
-#~ msgstr "lpinfo: Opción desconocida '%s'.\n"
-
-#~ msgid "lpmove: Unknown argument '%s'!\n"
-#~ msgstr "lpmove: Argumento '%s' desconocido.\n"
+#: ppdc/ppdc-source.cxx:1158
+#, c-format
+msgid "ppdc: Expected name/text after %s on line %d of %s."
+msgstr "ppdc: Se esperaba un nombre/texto tras %s en la lÃnea %d de %s."
-#~ msgid "lpmove: Unknown option '%c'!\n"
-#~ msgstr "lpmove: Opción '%c' desconocida.\n"
+#: ppdc/ppdc-source.cxx:1247
+#, c-format
+msgid "ppdc: Expected name/text after Installable on line %d of %s."
+msgstr "ppdc: Se esperaba un nombre/texto tras Installable en la lÃnea %d de %s."
-#~ msgid "lpoptions: No printers!?!\n"
-#~ msgstr "lpoptions: ¡¿¡No hay impresoras!?!\n"
+#: ppdc/ppdc-source.cxx:1783
+#, c-format
+msgid "ppdc: Expected name/text after Resolution on line %d of %s."
+msgstr "ppdc: Se esperaba un nombre/texto tras Resolution en la lÃnea %d de %s."
-#~ msgid "lpoptions: Unable to open PPD file for %s!\n"
-#~ msgstr "lpoptions: No se ha podido abrir el archivo PPD para %s.\n"
+#: ppdc/ppdc-source.cxx:481
+#, c-format
+msgid "ppdc: Expected name/text combination for ColorModel on line %d of %s."
+msgstr "ppdc: Se esperaba una combinación nombre/texto para ColorModel en la lÃnea %d de %s."
-#~ msgid "lpoptions: Unknown printer or class!\n"
-#~ msgstr "lpoptions: Impresora o clase desconocida.\n"
+#: ppdc/ppdc-source.cxx:1575
+#, c-format
+msgid "ppdc: Expected option name/text on line %d of %s."
+msgstr "ppdc: Se esperaba una opción de nombre/texto en la lÃnea %d de %s."
-#~ msgid "lppasswd: Only root can add or delete passwords!\n"
-#~ msgstr "lppasswd: Solo el usuario root puede añadir o borrar contraseñas.\n"
+#: ppdc/ppdc-source.cxx:1609
+#, c-format
+msgid "ppdc: Expected option section on line %d of %s."
+msgstr "ppdc: Se esperaba una sección de opciones en la lÃnea %d de %s."
-#~ msgid "lppasswd: Password file busy!\n"
-#~ msgstr "lppasswd: Archivo de contraseñas ocupado.\n"
+#: ppdc/ppdc-source.cxx:1587
+#, c-format
+msgid "ppdc: Expected option type on line %d of %s."
+msgstr "ppdc: Se esperaba un tipo de opción en la lÃnea %d de %s."
-#~ msgid "lppasswd: Password file not updated!\n"
-#~ msgstr "lppasswd: Archivo de contraseñas no actualizado.\n"
+#: ppdc/ppdc-source.cxx:1766
+#, c-format
+msgid "ppdc: Expected override field after Resolution on line %d of %s."
+msgstr "ppdc: Se esperaba un campo de anulación tras Resolution en la lÃnea %d de %s."
-#~ msgid "lppasswd: Sorry, password doesn't match!\n"
-#~ msgstr "lppasswd: Lo siento, las contraseñas no coinciden.\n"
+#: ppdc/ppdc-catalog.cxx:341
+#: ppdc/ppdc-catalog.cxx:353
+#, c-format
+msgid "ppdc: Expected quoted string on line %d of %s."
+msgstr "ppdc: Se esperaba una cadena entrecomillada en la lÃnea %d de %s."
-#~ msgid "lppasswd: Sorry, passwords don't match!\n"
-#~ msgstr "lppasswd: Lo siento, las contraseñas no coinciden.\n"
+#: ppdc/ppdc-source.cxx:1006
+#, c-format
+msgid "ppdc: Expected real number on line %d of %s."
+msgstr "ppdc: Se esperaba un número real en la lÃnea %d de %s."
-#~ msgid ""
-#~ "lpstat: error - %s environment variable names non-existent destination \"%"
-#~ "s\"!\n"
-#~ msgstr ""
-#~ "lpstat: error - Los nombre de variable de entorno %s no existen en el "
-#~ "destino \"%s\".\n"
+#: ppdc/ppdc-source.cxx:574
+#, c-format
+msgid "ppdc: Expected resolution/mediatype following ColorProfile on line %d of %s."
+msgstr "ppdc: Se esperaba resolución/tipo de soporte tras ColorProfile en la lÃnea %d de %s."
-#~ msgid "notify-events not specified!"
-#~ msgstr "notify-events no especificado."
+#: ppdc/ppdc-source.cxx:1864
+#, c-format
+msgid "ppdc: Expected resolution/mediatype following SimpleColorProfile on line %d of %s."
+msgstr "ppdc: Se esperaba resolución/tipo de soporte tras SimpleColorProfile en la lÃnea %d de %s."
-#~ msgid "notify-recipient-uri URI \"%s\" is already used!"
-#~ msgstr "El URI notify-recipient-uri \"%s\" ya está usado."
+#: ppdc/ppdc-source.cxx:363
+#, c-format
+msgid "ppdc: Expected selector after %s on line %d of %s."
+msgstr "ppdc: Se esperaba un selector tras %s en la lÃnea %d de %s."
-#~ msgid "notify-recipient-uri URI \"%s\" uses unknown scheme!"
-#~ msgstr "El URI notify-recipient-uri \"%s\" usa un esquema desconocido."
+#: ppdc/ppdc-source.cxx:1103
+#, c-format
+msgid "ppdc: Expected status after Font on line %d of %s."
+msgstr "ppdc: Se esperaba un estado tras Font en la lÃnea %d de %s."
-#~ msgid "notify-subscription-id %d no good!"
-#~ msgstr "notify-subscription-id %d incorrecto."
+#: ppdc/ppdc-source.cxx:2785
+#, c-format
+msgid "ppdc: Expected string after Copyright on line %d of %s."
+msgstr "ppdc: Se esperaba una cadena tras Copyright en la lÃnea %d de %s."
-#~ msgid "ppdc: Bad resolution name \"%s\" on line %d of %s!\n"
-#~ msgstr "ppdc: Resolución de nombre \"%s\" incorrecta en lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:3388
+#, c-format
+msgid "ppdc: Expected string after Version on line %d of %s."
+msgstr "ppdc: Se esperaba una cadena tras Version en la lÃnea %d de %s."
-#~ msgid "ppdc: Bad status keyword %s on line %d of %s!\n"
-#~ msgstr "ppdc: Clave de estado %s incorrecta en lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:730
+#, c-format
+msgid "ppdc: Expected two option names on line %d of %s."
+msgstr "ppdc: Se esperaban dos nombres de opciones en la lÃnea %d de %s."
-#~ msgid "ppdc: Choice found on line %d of %s with no Option!\n"
-#~ msgstr "ppdc: Selección encontrada en lÃnea %d de %s sin opciones.\n"
+#: ppdc/ppdc-source.cxx:374
+#, c-format
+msgid "ppdc: Expected value after %s on line %d of %s."
+msgstr "ppdc: Se esperaba un valor tras %s en la lÃnea %d de %s."
-#~ msgid "ppdc: Duplicate #po for locale %s on line %d of %s!\n"
-#~ msgstr "ppdc: #po duplicado para código regional %s en lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:1087
+#, c-format
+msgid "ppdc: Expected version after Font on line %d of %s."
+msgstr "ppdc: Se esperaba una versión tras Font en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected a filter definition on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba una definición de filtro en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:229
+#, c-format
+msgid "ppdc: Invalid #include/#po filename \"%s\"."
+msgstr "ppdc: Nombre de archivo #include/#po incorrecto \"%s\"."
-#~ msgid "ppdc: Expected a program name on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba un nombre de programa en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:974
+#, c-format
+msgid "ppdc: Invalid cost for filter on line %d of %s."
+msgstr "ppdc: Coste incorrecto para el filtro en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected charset after Font on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba un juego de caracteres tras Font en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:966
+#, c-format
+msgid "ppdc: Invalid empty MIME type for filter on line %d of %s."
+msgstr "ppdc: Tipo MIME vacÃo incorrecto para el filtro en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected color order for ColorModel on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba un orden de color para ColorModel en la lÃnea %d de %"
-#~ "s.\n"
+#: ppdc/ppdc-source.cxx:982
+#, c-format
+msgid "ppdc: Invalid empty program name for filter on line %d of %s."
+msgstr "ppdc: Nombre de programa vacÃo incorrecto para el filtro en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected colorspace for ColorModel on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba colorspace para ColorModel en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:1629
+#, c-format
+msgid "ppdc: Invalid option section \"%s\" on line %d of %s."
+msgstr "ppdc: Sección de opción incorrecta \"%s\" en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected compression for ColorModel on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba compresión para ColorModel en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:1601
+#, c-format
+msgid "ppdc: Invalid option type \"%s\" on line %d of %s."
+msgstr "ppdc: Tipo de opción incorrecta \"%s\" en la lÃnea %d de %s."
-#~ msgid ""
-#~ "ppdc: Expected constraints string for UIConstraints on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba una cadena de restricciones para UIConstraints en la "
-#~ "lÃnea %d de %s.\n"
+#: ppdc/ppdc.cxx:251
+#: ppdc/ppdpo.cxx:123
+#, c-format
+msgid "ppdc: Loading driver information file \"%s\"."
+msgstr "ppdc: Cargando archivo de información de controlador \"%s\"."
-#~ msgid ""
-#~ "ppdc: Expected driver type keyword following DriverType on line %d of %"
-#~ "s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba una clave de tipo de controlador tras DriverType en la "
-#~ "lÃnea %d de %s.\n"
+#: ppdc/ppdc.cxx:187
+#, c-format
+msgid "ppdc: Loading messages for locale \"%s\"."
+msgstr "ppdc: Cargando mensajes del idioma \"%s\"."
-#~ msgid "ppdc: Expected duplex type after Duplex on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba un tipo dúplex tras Duplex en la lÃnea %d de %s.\n"
+#: ppdc/ppdc.cxx:126
+#, c-format
+msgid "ppdc: Loading messages from \"%s\"."
+msgstr "ppdc: Cargando mensajes desde \"%s\"."
-#~ msgid "ppdc: Expected encoding after Font on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba una codificación tras Font en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:2403
+#: ppdc/ppdc-source.cxx:2635
+#, c-format
+msgid "ppdc: Missing #endif at end of \"%s\"."
+msgstr "ppdc: Falta un #endif al final de \"%s\"."
-#~ msgid "ppdc: Expected filename after #po %s on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba un nombre de archivo tras #po %s en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:2504
+#: ppdc/ppdc-source.cxx:2539
+#: ppdc/ppdc-source.cxx:2569
+#, c-format
+msgid "ppdc: Missing #if on line %d of %s."
+msgstr "ppdc: Falta un #if en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected group name/text on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba un nombre/texto de grupo en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-catalog.cxx:418
+#, c-format
+msgid "ppdc: Need a msgid line before any translation strings on line %d of %s."
+msgstr "ppdc: Se necesita una lÃnea msgid antes de cualquier cadena de traducción en lÃnea %d de %s."
-#~ msgid "ppdc: Expected include filename on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba un nombre de archivo include en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-driver.cxx:730
+#, c-format
+msgid "ppdc: No message catalog provided for locale %s."
+msgstr "ppdc: No se ha proporcionado catálogo de mensajes para el idioma %s."
-#~ msgid "ppdc: Expected integer on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba un número entero en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:1652
+#: ppdc/ppdc-source.cxx:2873
+#: ppdc/ppdc-source.cxx:2959
+#: ppdc/ppdc-source.cxx:3052
+#: ppdc/ppdc-source.cxx:3185
+#: ppdc/ppdc-source.cxx:3318
+#, c-format
+msgid "ppdc: Option %s defined in two different groups on line %d of %s."
+msgstr "ppdc: Opción %s definida en dos diferentes grupos en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected locale after #po on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba un código regional tras #po en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:1645
+#, c-format
+msgid "ppdc: Option %s redefined with a different type on line %d of %s."
+msgstr "ppdc: Opción %s redefinida con un tipo diferente en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected name after %s on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba un nombre tras %s en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:707
+#, c-format
+msgid "ppdc: Option constraint must *name on line %d of %s."
+msgstr "ppdc: Opción de restricción debe *name en lÃnea %d de %s."
-#~ msgid "ppdc: Expected name after FileName on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba un nombre tras FileName en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:2486
+#, c-format
+msgid "ppdc: Too many nested #if's on line %d of %s."
+msgstr "ppdc: Demasiados #if anidados en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected name after Font on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba un nombre tras Font en la lÃnea %d de %s.\n"
+#: ppdc/ppdc.cxx:374
+#, c-format
+msgid "ppdc: Unable to create PPD file \"%s\" - %s."
+msgstr "ppdc: No se ha podido crear el archivo PPD \"%s\" - %s."
-#~ msgid "ppdc: Expected name after Manufacturer on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba un nombre tras Manufacturer en la lÃnea %d de %s.\n"
+#: ppdc/ppdc.cxx:266
+#, c-format
+msgid "ppdc: Unable to create output directory %s: %s"
+msgstr "ppdc: No se ha podido crear el directorio de salida %s: %s"
-#~ msgid "ppdc: Expected name after MediaSize on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba un nombre tras MediaSize en la lÃnea %d de %s.\n"
+#: ppdc/ppdc.cxx:287
+#, c-format
+msgid "ppdc: Unable to create output pipes: %s"
+msgstr "ppdc: No se han podido crear canales (pipes) de salida: %s"
-#~ msgid "ppdc: Expected name after ModelName on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba un nombre tras ModelName en la lÃnea %d de %s.\n"
+#: ppdc/ppdc.cxx:303
+#: ppdc/ppdc.cxx:309
+#, c-format
+msgid "ppdc: Unable to execute cupstestppd: %s"
+msgstr "ppdc: No se ha podido ejecutar cupstestppd: %s"
-#~ msgid "ppdc: Expected name after PCFileName on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba un nombre tras PCFileName en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:1731
+#, c-format
+msgid "ppdc: Unable to find #po file %s on line %d of %s."
+msgstr "ppdc: No se ha podido encontrar el archivo #po %s en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected name/text after %s on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba un nombre/texto tras %s en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:2642
+#, c-format
+msgid "ppdc: Unable to find include file \"%s\" on line %d of %s."
+msgstr "ppdc: No se ha podido encontrar el archivo include \"%s\" en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected name/text after Installable on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba un nombre/texto tras Installable en la lÃnea %d de %s.\n"
+#: ppdc/ppdc.cxx:198
+#, c-format
+msgid "ppdc: Unable to find localization for \"%s\" - %s"
+msgstr "ppdc: No se ha podido encontrar localización para \"%s\" - %s"
-#~ msgid "ppdc: Expected name/text after Resolution on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba un nombre/texto tras Resolution en la lÃnea %d de %s.\n"
+#: ppdc/ppdc.cxx:135
+#, c-format
+msgid "ppdc: Unable to load localization file \"%s\" - %s"
+msgstr "ppdc: No se ha podido cargar el archivo de localización \"%s\" - %s"
-#~ msgid ""
-#~ "ppdc: Expected name/text combination for ColorModel on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba una combinación nombre/texto para ColorModel en la "
-#~ "lÃnea %d de %s.\n"
+#: ppdc/ppdc-file.cxx:49
+#, c-format
+msgid "ppdc: Unable to open %s: %s"
+msgstr "ppdc: No se pudo abrir %s: %s"
-#~ msgid "ppdc: Expected option name/text on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba una opción de nombre/texto en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:2055
+#, c-format
+msgid "ppdc: Undefined variable (%s) on line %d of %s."
+msgstr "ppdc: Variable no definida (%s) en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected option section on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba una sección de opciones en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-catalog.cxx:435
+#, c-format
+msgid "ppdc: Unexpected text on line %d of %s."
+msgstr "ppdc: Texto inesperado en la lÃnea %d del %s."
-#~ msgid "ppdc: Expected option type on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba un tipo de opción en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:2915
+#, c-format
+msgid "ppdc: Unknown driver type %s on line %d of %s."
+msgstr "ppdc: Tipo de controlador desconocido %s en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected override field after Resolution on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba un campo de anulación tras Resolution en la lÃnea %d de "
-#~ "%s.\n"
+#: ppdc/ppdc-source.cxx:908
+#, c-format
+msgid "ppdc: Unknown duplex type \"%s\" on line %d of %s."
+msgstr "ppdc: Tipo dúplex desconocido \"%s\" en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected real number on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba un número real en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:3145
+#, c-format
+msgid "ppdc: Unknown media size \"%s\" on line %d of %s."
+msgstr "ppdc: Tamaño de papel desconocido \"%s\" en la lÃnea %d de %s."
-#~ msgid ""
-#~ "ppdc: Expected resolution/mediatype following ColorProfile on line %d of %"
-#~ "s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba resolución/tipo de soporte tras ColorProfile en la "
-#~ "lÃnea %d de %s.\n"
+#: ppdc/ppdc-catalog.cxx:463
+#, c-format
+msgid "ppdc: Unknown message catalog format for \"%s\"."
+msgstr "ppdc: Formato del catálogo de mensajes para \"%s\" desconocido."
-#~ msgid ""
-#~ "ppdc: Expected resolution/mediatype following SimpleColorProfile on line %"
-#~ "d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Se esperaba resolución/tipo de soporte tras SimpleColorProfile en "
-#~ "la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:3399
+#, c-format
+msgid "ppdc: Unknown token \"%s\" seen on line %d of %s."
+msgstr "ppdc: Elemento desconocido \"%s\" visto en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected selector after %s on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba un selector tras %s en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:1016
+#, c-format
+msgid "ppdc: Unknown trailing characters in real number \"%s\" on line %d of %s."
+msgstr "ppdc: Caracteres finales desconocidos en el número real \"%s\" en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected status after Font on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba un estado tras Font en la lÃnea %d de %s.\n"
+#: ppdc/ppdc-source.cxx:2165
+#, c-format
+msgid "ppdc: Unterminated string starting with %c on line %d of %s."
+msgstr "ppdc: Cadena que comienza por %c sin terminar en la lÃnea %d de %s."
-#~ msgid "ppdc: Expected string after Copyright on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba una cadena tras Copyright en la lÃnea %d de %s.\n"
+#: ppdc/ppdc.cxx:365
+#, c-format
+msgid "ppdc: Warning - overlapping filename \"%s\"."
+msgstr "ppdc: Advertencia - nombre de archivo superpuesto \"%s\"."
-#~ msgid "ppdc: Expected string after Version on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba una cadena tras Version en la lÃnea %d de %s.\n"
+#: ppdc/ppdc.cxx:380
+#, c-format
+msgid "ppdc: Writing %s."
+msgstr "ppdc: Escribiendo %s."
-#~ msgid "ppdc: Expected two option names on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaban dos nombres de opciones en la lÃnea %d de %s.\n"
+#: ppdc/ppdc.cxx:148
+#, c-format
+msgid "ppdc: Writing PPD files to directory \"%s\"."
+msgstr "ppdc: Escribiendo archivos PPD al directorio \"%s\"."
-#~ msgid "ppdc: Expected value after %s on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba un valor tras %s en la lÃnea %d de %s.\n"
+#: ppdc/ppdmerge.cxx:136
+#, c-format
+msgid "ppdmerge: Bad LanguageVersion \"%s\" in %s."
+msgstr "ppdmerge: LanguageVersion \"%s\" incorrecto en %s."
-#~ msgid "ppdc: Expected version after Font on line %d of %s!\n"
-#~ msgstr "ppdc: Se esperaba una versión tras Font en la lÃnea %d de %s'.\n"
+#: ppdc/ppdmerge.cxx:176
+#, c-format
+msgid "ppdmerge: Ignoring PPD file %s."
+msgstr "ppdmerge: Ignorando archivo PPD %s."
-#~ msgid "ppdc: Invalid #include/#po filename \"%s\"!\n"
-#~ msgstr "ppdc: Nombre de fichero #include/#po incorrecto \"%s\".\n"
+#: ppdc/ppdmerge.cxx:160
+#, c-format
+msgid "ppdmerge: Unable to backup %s to %s - %s"
+msgstr "ppdmerge: No se ha podido hacer copia de seguridad de %s a %s- %s"
-#~ msgid "ppdc: Invalid cost for filter on line %d of %s!\n"
-#~ msgstr "ppdc: Coste incorrecto para el filtro en la lÃnea %d de %s.\n"
+#: systemv/lpstat.c:1781
+#, c-format
+msgid "printer %s disabled since %s -"
+msgstr "la impresora %s está deshabilitada desde %s -"
-#~ msgid "ppdc: Invalid empty MIME type for filter on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Tipo MIME vacÃo incorrecto para el filtro en la lÃnea %d de %s.\n"
+#: systemv/lpstat.c:1770
+#, c-format
+msgid "printer %s is idle. enabled since %s"
+msgstr "la impresora %s está inactiva. activada desde %s"
-#~ msgid "ppdc: Invalid empty program name for filter on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Nombre de programa vacÃo incorrecto para el filtro en la lÃnea %d "
-#~ "de %s.\n"
+#: systemv/lpstat.c:1775
+#, c-format
+msgid "printer %s now printing %s-%d. enabled since %s"
+msgstr "la impresora %s está imprimiendo %s-%d. activada desde %s"
-#~ msgid "ppdc: Invalid option section \"%s\" on line %d of %s!\n"
-#~ msgstr "ppdc: Sección de opción incorrecta \"%s\" en la lÃnea %d de %s.\n"
+#: systemv/lpstat.c:1906
+#, c-format
+msgid "printer %s/%s disabled since %s -"
+msgstr "la impresora %s/%s está desactivada desde %s -"
-#~ msgid "ppdc: Invalid option type \"%s\" on line %d of %s!\n"
-#~ msgstr "ppdc: Tipo de opción incorrecta \"%s\" en la lÃnea %d de %s.\n"
+#: systemv/lpstat.c:1892
+#, c-format
+msgid "printer %s/%s is idle. enabled since %s"
+msgstr "la impresora %s/%s está inactiva. activada desde %s"
-#~ msgid "ppdc: Missing #endif at end of \"%s\"!\n"
-#~ msgstr "ppdc: Falta un #endif al final de \"%s\".\n"
+#: systemv/lpstat.c:1899
+#, c-format
+msgid "printer %s/%s now printing %s-%d. enabled since %s"
+msgstr "la impresora %s/%s está imprimiendo %s-%d. activada desde %s"
-#~ msgid "ppdc: Missing #if on line %d of %s!\n"
-#~ msgstr "ppdc: Falta un #if en la lÃnea %d de %s.\n"
+#: cups/notify.c:93
+#: cups/notify.c:134
+msgid "processing"
+msgstr "en proceso"
-#~ msgid "ppdc: No message catalog provided for locale %s!\n"
-#~ msgstr ""
-#~ "ppdc: No se ha proporcionado catálogo de mensajes para el idioma %s.\n"
+#: systemv/lp.c:639
+#, c-format
+msgid "request id is %s-%d (%d file(s))"
+msgstr "la id solicitada es %s-%d (%d archivo(s))"
-#~ msgid "ppdc: Option %s defined in two different groups on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Opción %s definida en dos diferentes grupos en la lÃnea %d de %s.\n"
+#: cups/snmp.c:1020
+msgid "request-id uses indefinite length"
+msgstr "request-id usa una longitud indefinida"
-#~ msgid "ppdc: Option %s redefined with a different type on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Opción %s redefinida con un tipo diferente en la lÃnea %d de %s.\n"
+#: systemv/lpstat.c:2045
+msgid "scheduler is not running"
+msgstr "el planificador de tareas no se está ejecutando"
-#~ msgid "ppdc: Option constraint must *name on line %d of %s!\n"
-#~ msgstr "ppdc: Opción de restricción debe *name en lÃnea %d de %s.\n"
+#: systemv/lpstat.c:2041
+msgid "scheduler is running"
+msgstr "el planificador de tareas se está ejecutando"
-#~ msgid "ppdc: Too many nested #if's on line %d of %s!\n"
-#~ msgstr "ppdc: Demasiados #if anidados en la lÃnea %d de %s.\n"
+#: cups/adminutil.c:2276
+#, c-format
+msgid "stat of %s failed: %s"
+msgstr "estado de %s ha fallado: %s"
-#~ msgid "ppdc: Unable to find #po file %s on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: No se ha podido encontrar el archivo #po %s en la lÃnea %d de %s.\n"
+#: berkeley/lpc.c:211
+msgid "status\t\tShow status of daemon and queue."
+msgstr "status\t\tMuestra el estado del demonio (daemon) y la cola."
-#~ msgid "ppdc: Unable to find include file \"%s\" on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: No se ha podido encontrar el archivo include \"%s\" en la lÃnea %d "
-#~ "de %s.\n"
+#: cups/notify.c:96
+#: cups/notify.c:137
+msgid "stopped"
+msgstr "parada"
-#~ msgid "ppdc: Unknown driver type %s on line %d of %s!\n"
-#~ msgstr "ppdc: Tipo de controlador desconocido %s en la lÃnea %d de %s.\n"
+#: systemv/lpstat.c:1014
+#, c-format
+msgid "system default destination: %s"
+msgstr "destino predeterminado del sistema: %s"
-#~ msgid "ppdc: Unknown duplex type \"%s\" on line %d of %s!\n"
-#~ msgstr "ppdc: Tipo dúplex desconocido \"%s\" en la lÃnea %d de %s.\n"
+#: systemv/lpstat.c:1011
+#, c-format
+msgid "system default destination: %s/%s"
+msgstr "destino predeterminado del sistema: %s/%s"
-#~ msgid "ppdc: Unknown media size \"%s\" on line %d of %s!\n"
-#~ msgstr "ppdc: Tamaño de papel desconocido \"%s\" en la lÃnea %d de %s.\n"
+#: cups/notify.c:108
+#: cups/notify.c:140
+msgid "unknown"
+msgstr "desconocido"
-#~ msgid "ppdc: Unknown token \"%s\" seen on line %d of %s!\n"
-#~ msgstr "ppdc: Elemento desconocido \"%s\" visto en la lÃnea %d de %s.\n"
+#: cups/notify.c:117
+msgid "untitled"
+msgstr "sin tÃtulo"
-#~ msgid ""
-#~ "ppdc: Unknown trailing characters in real number \"%s\" on line %d of %"
-#~ "s!\n"
-#~ msgstr ""
-#~ "ppdc: Caracteres finales desconocidos en el número real \"%s\" en la "
-#~ "lÃnea %d de %s.\n"
+#: cups/snmp.c:1045
+msgid "variable-bindings uses indefinite length"
+msgstr "variable-bindings usa una longitud indefinida"
-#~ msgid "ppdc: Unterminated string starting with %c on line %d of %s!\n"
-#~ msgstr ""
-#~ "ppdc: Cadena que comienza por %c sin terminar en la lÃnea %d de %s.\n"
-#~ msgid "ppdmerge: Bad LanguageVersion \"%s\" in %s!\n"
-#~ msgstr "ppdmerge: LanguageVersion \"%s\" incorrecto en %s.\n"
+#
+# End of "$Id$".
+#
cupsdSetString(&PrintcapGUI, "/usr/bin/glpoptions");
cupsdSetString(&FontPath, CUPS_FONTPATH);
cupsdSetString(&RemoteRoot, "remroot");
- cupsdSetString(&ServerHeader, "CUPS/1.4");
+ cupsdSetStringf(&ServerHeader, "CUPS/%d.%d", CUPS_VERSION_MAJOR,
+ CUPS_VERSION_MINOR);
cupsdSetString(&StateDir, CUPS_STATEDIR);
if (!strcmp(CUPS_DEFAULT_PRINTCAP, "/etc/printers.conf"))
if (!_cups_strcasecmp(value, "ProductOnly"))
cupsdSetString(&ServerHeader, "CUPS");
else if (!_cups_strcasecmp(value, "Major"))
- cupsdSetString(&ServerHeader, "CUPS/1");
+ cupsdSetStringf(&ServerHeader, "CUPS/%d", CUPS_VERSION_MAJOR);
else if (!_cups_strcasecmp(value, "Minor"))
- cupsdSetString(&ServerHeader, "CUPS/1.4");
+ cupsdSetStringf(&ServerHeader, "CUPS/%d.%d", CUPS_VERSION_MAJOR,
+ CUPS_VERSION_MINOR);
else if (!_cups_strcasecmp(value, "Minimal"))
cupsdSetString(&ServerHeader, CUPS_MINIMAL);
else if (!_cups_strcasecmp(value, "OS"))
cupsdSetStringf(&ServerHeader, CUPS_MINIMAL " (%s)", plat.sysname);
else if (!_cups_strcasecmp(value, "Full"))
- cupsdSetStringf(&ServerHeader, CUPS_MINIMAL " (%s) IPP/1.1",
+ cupsdSetStringf(&ServerHeader, CUPS_MINIMAL " (%s) IPP/2.1",
plat.sysname);
else if (!_cups_strcasecmp(value, "None"))
cupsdClearString(&ServerHeader);
name[512], /* ppd-name */
make[128], /* ppd-make */
make_and_model[128], /* ppd-make-and-model */
- device_id[128], /* ppd-device-id */
+ device_id[256], /* ppd-device-id */
languages[128], /* ppd-natural-language */
product[128], /* ppd-product */
psversion[128], /* ppd-psversion */
strcpy(type_str, "postscript");
if (sscanf(line, "\"%511[^\"]\"%127s%*[ \t]\"%127[^\"]\""
- "%*[ \t]\"%127[^\"]\"%*[ \t]\"%127[^\"]\""
+ "%*[ \t]\"%127[^\"]\"%*[ \t]\"%255[^\"]\""
"%*[ \t]\"%127[^\"]\"%*[ \t]\"%127[^\"]\""
"%*[ \t]\"%127[^\"]\"",
name, languages, make, make_and_model,
break;
case 'u' : /* Delete PPD file after conversion */
- removeinfile = 1;
+ removeppd = 1;
break;
case 'U' : /* Specify username... */
filterptr = mimeAddFilter(mime, temptype, desttype, cost, program);
if (!mimeFilterLookup(mime, desttype, filtertype))
- mimeAddFilter(mime, desttype, filtertype, cost, "-");
+ mimeAddFilter(mime, desttype, filtertype, 0, "-");
}
else
filterptr = mimeAddFilter(mime, temptype, filtertype, cost, program);
int filterfds[2][2] = { { -1, -1 }, { -1, -1 } };
/* Pipes used between filters */
int envc; /* Number of environment variables */
+ struct stat fileinfo; /* Job file information */
char **argv = NULL, /* Filter command-line arguments */
filename[1024], /* Job filename */
command[1024], /* Full path to command */
* Local jobs get filtered...
*/
- filters = mimeFilter(MimeDatabase, job->filetypes[job->current_file],
- job->printer->filetype, &(job->cost));
+ snprintf(filename, sizeof(filename), "%s/d%05d-%03d", RequestRoot,
+ job->id, job->current_file + 1);
+ if (stat(filename, &fileinfo))
+ fileinfo.st_size = 0;
+
+ filters = mimeFilter2(MimeDatabase, job->filetypes[job->current_file],
+ fileinfo.st_size, job->printer->filetype,
+ &(job->cost));
if (!filters)
{
free(job->compressions);
free(job->filetypes);
- while (job->num_files > 0)
+ if (action == CUPSD_JOB_PURGE)
{
- snprintf(filename, sizeof(filename), "%s/d%05d-%03d", RequestRoot,
- job->id, job->num_files);
- if (Classification)
- cupsdRemoveFile(filename);
- else
- unlink(filename);
+ while (job->num_files > 0)
+ {
+ snprintf(filename, sizeof(filename), "%s/d%05d-%03d", RequestRoot,
+ job->id, job->num_files);
+ if (Classification)
+ cupsdRemoveFile(filename);
+ else
+ unlink(filename);
- job->num_files --;
+ job->num_files --;
+ }
}
+ else
+ job->num_files = 0;
}
if (job->history)
_mimeDeleteType
_mimeFileType
_mimeFilter
+_mimeFilter2
_mimeFilterLookup
_mimeFirstFilter
_mimeFirstType
va_end(ap);
}
while (status == 0);
-
+
if (status > 0)
{
if ((level > LogLevel ||
const char *format, /* Pointer into PageLogFormat */
*nameend; /* End of attribute name */
ipp_attribute_t *attr; /* Current attribute */
- int number; /* Page number */
- char copies[256]; /* Number of copies */
+ char number[256]; /* Page number */
+ int copies; /* Number of copies */
/*
if (!PageLogFormat)
return (1);
- number = 1;
- strcpy(copies, "1");
- sscanf(page, "%d%255s", &number, copies);
+ strcpy(number, "1");
+ copies = 1;
+ sscanf(page, "%255s%d", number, &copies);
for (format = PageLogFormat, bufptr = buffer; *format; format ++)
{
break;
case 'P' : /* Page number */
- snprintf(bufptr, sizeof(buffer) - (bufptr - buffer), "%d", number);
+ strlcpy(bufptr, number, sizeof(buffer) - (bufptr - buffer));
bufptr += strlen(bufptr);
break;
case 'C' : /* Number of copies */
- strlcpy(bufptr, copies, sizeof(buffer) - (bufptr - buffer));
+ snprintf(bufptr, sizeof(buffer) - (bufptr - buffer), "%d", copies);
bufptr += strlen(bufptr);
break;
}
*bufptr = '\0';
-
+
#ifdef HAVE_VSYSLOG
/*
* See if we are logging pages via syslog...
CUPSD_ACCESSLOG_ACTIONS,/* CUPS-Authenticate-Job */
CUPSD_ACCESSLOG_ALL /* CUPS-Get-PPD */
};
-
+
if ((op <= IPP_SCHEDULE_JOB_AFTER && standard_ops[op] > AccessLogLevel) ||
(op >= CUPS_GET_DEFAULT && op <= CUPS_GET_PPD &&
"add_printer_filter: %s: adding filter %s/%s %s/%s "
"0 -", p->name, desttype->super, desttype->type,
filtertype->super, filtertype->type);
- mimeAddFilter(MimeDatabase, desttype, filtertype, cost, "-");
+ mimeAddFilter(MimeDatabase, desttype, filtertype, 0, "-");
}
}
else
DEBUG_printf(("add_printer_filter: Adding filter %s/%s %s/%s 0 -",
desttype->super, desttype->type, filtertype->super,
filtertype->type));
- mimeAddFilter(mime, desttype, filtertype, cost, "-");
+ mimeAddFilter(mime, desttype, filtertype, 0, "-");
}
}
else
+++ /dev/null
-#
-# "$Id: Makefile 7871 2008-08-27 21:12:43Z mike $"
-#
-# Standards makefile for CUPS.
-#
-# Copyright 2007-2010 by Apple Inc.
-# Copyright 2006 by Easy Software Products.
-#
-# These coded instructions, statements, and computer programs are the
-# property of Apple Inc. and are protected by Federal copyright
-# law. Distribution and use rights are outlined in the file "LICENSE.txt"
-# which should have been included with this file. If this file is
-# file is missing or damaged, see the license at "http://www.cups.org/".
-#
-
-include ../Makedefs
-
-
-#
-# Standards...
-#
-
-RFCS = \
- rfc1155.txt \
- rfc1157.txt \
- rfc1179.txt \
- rfc1213.txt \
- rfc1321.txt \
- rfc2222.txt \
- rfc2246.txt \
- rfc2487.txt \
- rfc2554.txt \
- rfc2567.txt \
- rfc2568.txt \
- rfc2569.txt \
- rfc2578.txt \
- rfc2595.txt \
- rfc2616.txt \
- rfc2617.txt \
- rfc2712.txt \
- rfc2790.txt \
- rfc2817.txt \
- rfc2818.txt \
- rfc2821.txt \
- rfc2822.txt \
- rfc2910.txt \
- rfc2911.txt \
- rfc2965.txt \
- rfc3196.txt \
- rfc3239.txt \
- rfc3380.txt \
- rfc3381.txt \
- rfc3382.txt \
- rfc3391.txt \
- rfc3510.txt \
- rfc3712.txt \
- rfc3805.txt \
- rfc3875.txt \
- rfc3986.txt \
- rfc3995.txt \
- rfc3996.txt \
- rfc3997.txt \
- rfc3998.txt \
- rfc4122.txt \
- rfc4234.txt
-
-.SUFFIXES: .html .txt
-.txt.html: rfctohtml
- echo Converting $< to HTML...
- ./rfctohtml $< ../doc/help/$@
-
-
-#
-# Make everything...
-#
-
-all: rfctohtml $(RFCS:.txt=.html)
-
-
-#
-# Make library targets...
-#
-
-libs:
-
-
-#
-# Make unit tests...
-#
-
-unittests:
-
-
-#
-# Clean all config and object files...
-#
-
-clean:
- $(RM) rfctohtml rfctohtml.o
- $(RM) $(RFCS:.txt=.html)
-
-
-#
-# Dummy depend target...
-#
-
-depend:
-
-
-#
-# Install all targets...
-#
-
-install: all install-data install-headers install-libs install-exec
-
-
-#
-# Install data files...
-#
-
-install-data:
-
-
-#
-# Install programs...
-#
-
-install-exec:
-
-
-#
-# Install headers...
-#
-
-install-headers:
-
-
-#
-# Install libraries...
-#
-
-install-libs:
-
-
-#
-# Uninstall files...
-#
-
-uninstall:
-
-
-#
-# rfctohtml - make html versions of RFCs...
-#
-
-rfctohtml: rfctohtml.o ../cups/$(LIBCUPSSTATIC)
- $(CC) $(ARCHFLAGS) $(LDFLAGS) -o $@ rfctohtml.o ../cups/$(LIBCUPSSTATIC) \
- $(LIBGSSAPI) $(SSLLIBS) $(DNSSDLIBS) $(COMMONLIBS) $(LIBZ)
-
-
-#
-# End of "$Id: Makefile 7871 2008-08-27 21:12:43Z mike $".
-#
+++ /dev/null
-
-
-
-
-
-
-Network Working Group M. Rose
-Request for Comments: 1155 Performance Systems International
-Obsoletes: RFC 1065 K. McCloghrie
- Hughes LAN Systems
- May 1990
-
-
-
- Structure and Identification of Management Information
- for TCP/IP-based Internets
-
- Table of Contents
-
-1. Status of this Memo ............................................. 1
-2. Introduction .................................................... 2
-3. Structure and Identification of Management Information........... 4
-3.1 Names .......................................................... 4
-3.1.1 Directory .................................................... 5
-3.1.2 Mgmt ......................................................... 6
-3.1.3 Experimental ................................................. 6
-3.1.4 Private ...................................................... 7
-3.2 Syntax ......................................................... 7
-3.2.1 Primitive Types .............................................. 7
-3.2.1.1 Guidelines for Enumerated INTEGERs ......................... 7
-3.2.2 Constructor Types ............................................ 8
-3.2.3 Defined Types ................................................ 8
-3.2.3.1 NetworkAddress ............................................. 8
-3.2.3.2 IpAddress .................................................. 8
-3.2.3.3 Counter .................................................... 8
-3.2.3.4 Gauge ...................................................... 9
-3.2.3.5 TimeTicks .................................................. 9
-3.2.3.6 Opaque ..................................................... 9
-3.3 Encodings ...................................................... 9
-4. Managed Objects ................................................. 10
-4.1 Guidelines for Object Names .................................... 10
-4.2 Object Types and Instances ..................................... 10
-4.3 Macros for Managed Objects ..................................... 14
-5. Extensions to the MIB ........................................... 16
-6. Definitions ..................................................... 17
-7. Acknowledgements ................................................ 20
-8. References ...................................................... 21
-9. Security Considerations.......................................... 21
-10. Authors' Addresses.............................................. 22
-
-1. Status of this Memo
-
- This RFC is a re-release of RFC 1065, with a changed "Status of this
- Memo", plus a few minor typographical corrections. The technical
-
-
-
-Rose & McCloghrie [Page 1]
-\f
-RFC 1155 SMI May 1990
-
-
- content of the document is unchanged from RFC 1065.
-
- This memo provides the common definitions for the structure and
- identification of management information for TCP/IP-based internets.
- In particular, together with its companion memos which describe the
- management information base along with the network management
- protocol, these documents provide a simple, workable architecture and
- system for managing TCP/IP-based internets and in particular, the
- Internet.
-
- This memo specifies a Standard Protocol for the Internet community.
- Its status is "Recommended". TCP/IP implementations in the Internet
- which are network manageable are expected to adopt and implement this
- specification.
-
- The Internet Activities Board recommends that all IP and TCP
- implementations be network manageable. This implies implementation
- of the Internet MIB (RFC-1156) and at least one of the two
- recommended management protocols SNMP (RFC-1157) or CMOT (RFC-1095).
- It should be noted that, at this time, SNMP is a full Internet
- standard and CMOT is a draft standard. See also the Host and Gateway
- Requirements RFCs for more specific information on the applicability
- of this standard.
-
- Please refer to the latest edition of the "IAB Official Protocol
- Standards" RFC for current information on the state and status of
- standard Internet protocols.
-
- Distribution of this memo is unlimited.
-
-2. Introduction
-
- This memo describes the common structures and identification scheme
- for the definition of management information used in managing
- TCP/IP-based internets. Included are descriptions of an object
- information model for network management along with a set of generic
- types used to describe management information. Formal descriptions
- of the structure are given using Abstract Syntax Notation One (ASN.1)
- [1].
-
- This memo is largely concerned with organizational concerns and
- administrative policy: it neither specifies the objects which are
- managed, nor the protocols used to manage those objects. These
- concerns are addressed by two companion memos: one describing the
- Management Information Base (MIB) [2], and the other describing the
- Simple Network Management Protocol (SNMP) [3].
-
- This memo is based in part on the work of the Internet Engineering
-
-
-
-Rose & McCloghrie [Page 2]
-\f
-RFC 1155 SMI May 1990
-
-
- Task Force, particularly the working note titled "Structure and
- Identification of Management Information for the Internet" [4]. This
- memo uses a skeletal structure derived from that note, but differs in
- one very significant way: that note focuses entirely on the use of
- OSI-style network management. As such, it is not suitable for use
- with SNMP.
-
- This memo attempts to achieve two goals: simplicity and
- extensibility. Both are motivated by a common concern: although the
- management of TCP/IP-based internets has been a topic of study for
- some time, the authors do not feel that the depth and breadth of such
- understanding is complete. More bluntly, we feel that previous
- experiences, while giving the community insight, are hardly
- conclusive. By fostering a simple SMI, the minimal number of
- constraints are imposed on future potential approaches; further, by
- fostering an extensible SMI, the maximal number of potential
- approaches are available for experimentation.
-
- It is believed that this memo and its two companions comply with the
- guidelines set forth in RFC 1052, "IAB Recommendations for the
- Development of Internet Network Management Standards" [5] and RFC
- 1109, "Report of the Second Ad Hoc Network Management Review Group"
- [6]. In particular, we feel that this memo, along with the memo
- describing the management information base, provide a solid basis for
- network management of the Internet.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Rose & McCloghrie [Page 3]
-\f
-RFC 1155 SMI May 1990
-
-
-3. Structure and Identification of Management Information
-
- Managed objects are accessed via a virtual information store, termed
- the Management Information Base or MIB. Objects in the MIB are
- defined using Abstract Syntax Notation One (ASN.1) [1].
-
- Each type of object (termed an object type) has a name, a syntax, and
- an encoding. The name is represented uniquely as an OBJECT
- IDENTIFIER. An OBJECT IDENTIFIER is an administratively assigned
- name. The administrative policies used for assigning names are
- discussed later in this memo.
-
- The syntax for an object type defines the abstract data structure
- corresponding to that object type. For example, the structure of a
- given object type might be an INTEGER or OCTET STRING. Although in
- general, we should permit any ASN.1 construct to be available for use
- in defining the syntax of an object type, this memo purposely
- restricts the ASN.1 constructs which may be used. These restrictions
- are made solely for the sake of simplicity.
-
- The encoding of an object type is simply how instances of that object
- type are represented using the object's type syntax. Implicitly tied
- to the notion of an object's syntax and encoding is how the object is
- represented when being transmitted on the network. This memo
- specifies the use of the basic encoding rules of ASN.1 [7].
-
- It is beyond the scope of this memo to define either the MIB used for
- network management or the network management protocol. As mentioned
- earlier, these tasks are left to companion memos. This memo attempts
- to minimize the restrictions placed upon its companions so as to
- maximize generality. However, in some cases, restrictions have been
- made (e.g., the syntax which may be used when defining object types
- in the MIB) in order to encourage a particular style of management.
- Future editions of this memo may remove these restrictions.
-
-3.1. Names
-
- Names are used to identify managed objects. This memo specifies
- names which are hierarchical in nature. The OBJECT IDENTIFIER
- concept is used to model this notion. An OBJECT IDENTIFIER can be
- used for purposes other than naming managed object types; for
- example, each international standard has an OBJECT IDENTIFIER
- assigned to it for the purposes of identification. In short, OBJECT
- IDENTIFIERs are a means for identifying some object, regardless of
- the semantics associated with the object (e.g., a network object, a
- standards document, etc.)
-
- An OBJECT IDENTIFIER is a sequence of integers which traverse a
-
-
-
-Rose & McCloghrie [Page 4]
-\f
-RFC 1155 SMI May 1990
-
-
- global tree. The tree consists of a root connected to a number of
- labeled nodes via edges. Each node may, in turn, have children of
- its own which are labeled. In this case, we may term the node a
- subtree. This process may continue to an arbitrary level of depth.
- Central to the notion of the OBJECT IDENTIFIER is the understanding
- that administrative control of the meanings assigned to the nodes may
- be delegated as one traverses the tree. A label is a pairing of a
- brief textual description and an integer.
-
- The root node itself is unlabeled, but has at least three children
- directly under it: one node is administered by the International
- Organization for Standardization, with label iso(1); another is
- administrated by the International Telegraph and Telephone
- Consultative Committee, with label ccitt(0); and the third is jointly
- administered by the ISO and the CCITT, joint-iso-ccitt(2).
-
- Under the iso(1) node, the ISO has designated one subtree for use by
- other (inter)national organizations, org(3). Of the children nodes
- present, two have been assigned to the U.S. National Institutes of
- Standards and Technology. One of these subtrees has been transferred
- by the NIST to the U.S. Department of Defense, dod(6).
-
- As of this writing, the DoD has not indicated how it will manage its
- subtree of OBJECT IDENTIFIERs. This memo assumes that DoD will
- allocate a node to the Internet community, to be administered by the
- Internet Activities Board (IAB) as follows:
-
- internet OBJECT IDENTIFIER ::= { iso org(3) dod(6) 1 }
-
- That is, the Internet subtree of OBJECT IDENTIFIERs starts with the
- prefix:
-
- 1.3.6.1.
-
- This memo, as a standard approved by the IAB, now specifies the
- policy under which this subtree of OBJECT IDENTIFIERs is
- administered. Initially, four nodes are present:
-
- directory OBJECT IDENTIFIER ::= { internet 1 }
- mgmt OBJECT IDENTIFIER ::= { internet 2 }
- experimental OBJECT IDENTIFIER ::= { internet 3 }
- private OBJECT IDENTIFIER ::= { internet 4 }
-
-3.1.1. Directory
-
- The directory(1) subtree is reserved for use with a future memo that
- discusses how the OSI Directory may be used in the Internet.
-
-
-
-
-Rose & McCloghrie [Page 5]
-\f
-RFC 1155 SMI May 1990
-
-
-3.1.2. Mgmt
-
- The mgmt(2) subtree is used to identify objects which are defined in
- IAB-approved documents. Administration of the mgmt(2) subtree is
- delegated by the IAB to the Internet Assigned Numbers Authority for
- the Internet. As RFCs which define new versions of the Internet-
- standard Management Information Base are approved, they are assigned
- an OBJECT IDENTIFIER by the Internet Assigned Numbers Authority for
- identifying the objects defined by that memo.
-
- For example, the RFC which defines the initial Internet standard MIB
- would be assigned management document number 1. This RFC would use
- the OBJECT IDENTIFIER
-
- { mgmt 1 }
-
- or
-
- 1.3.6.1.2.1
-
- in defining the Internet-standard MIB.
-
- The generation of new versions of the Internet-standard MIB is a
- rigorous process. Section 5 of this memo describes the rules used
- when a new version is defined.
-
-3.1.3. Experimental
-
- The experimental(3) subtree is used to identify objects used in
- Internet experiments. Administration of the experimental(3) subtree
- is delegated by the IAB to the Internet Assigned Numbers Authority of
- the Internet.
-
- For example, an experimenter might received number 17, and would have
- available the OBJECT IDENTIFIER
-
- { experimental 17 }
-
- or
-
- 1.3.6.1.3.17
-
- for use.
-
- As a part of the assignment process, the Internet Assigned Numbers
- Authority may make requirements as to how that subtree is used.
-
-
-
-
-
-Rose & McCloghrie [Page 6]
-\f
-RFC 1155 SMI May 1990
-
-
-3.1.4. Private
-
- The private(4) subtree is used to identify objects defined
- unilaterally. Administration of the private(4) subtree is delegated
- by the IAB to the Internet Assigned Numbers Authority for the
- Internet. Initially, this subtree has at least one child:
-
- enterprises OBJECT IDENTIFIER ::= { private 1 }
-
- The enterprises(1) subtree is used, among other things, to permit
- parties providing networking subsystems to register models of their
- products.
-
- Upon receiving a subtree, the enterprise may, for example, define new
- MIB objects in this subtree. In addition, it is strongly recommended
- that the enterprise will also register its networking subsystems
- under this subtree, in order to provide an unambiguous identification
- mechanism for use in management protocols. For example, if the
- "Flintstones, Inc." enterprise produced networking subsystems, then
- they could request a node under the enterprises subtree from the
- Internet Assigned Numbers Authority. Such a node might be numbered:
-
- 1.3.6.1.4.1.42
-
- The "Flintstones, Inc." enterprise might then register their "Fred
- Router" under the name of:
-
- 1.3.6.1.4.1.42.1.1
-
-3.2. Syntax
-
- Syntax is used to define the structure corresponding to object types.
- ASN.1 constructs are used to define this structure, although the full
- generality of ASN.1 is not permitted.
-
- The ASN.1 type ObjectSyntax defines the different syntaxes which may
- be used in defining an object type.
-
-3.2.1. Primitive Types
-
- Only the ASN.1 primitive types INTEGER, OCTET STRING, OBJECT
- IDENTIFIER, and NULL are permitted. These are sometimes referred to
- as non-aggregate types.
-
-3.2.1.1. Guidelines for Enumerated INTEGERs
-
- If an enumerated INTEGER is listed as an object type, then a named-
- number having the value 0 shall not be present in the list of
-
-
-
-Rose & McCloghrie [Page 7]
-\f
-RFC 1155 SMI May 1990
-
-
- enumerations. Use of this value is prohibited.
-
-3.2.2. Constructor Types
-
- The ASN.1 constructor type SEQUENCE is permitted, providing that it
- is used to generate either lists or tables.
-
- For lists, the syntax takes the form:
-
- SEQUENCE { <type1>, ..., <typeN> }
-
- where each <type> resolves to one of the ASN.1 primitive types listed
- above. Further, these ASN.1 types are always present (the DEFAULT
- and OPTIONAL clauses do not appear in the SEQUENCE definition).
-
- For tables, the syntax takes the form:
-
- SEQUENCE OF <entry>
-
- where <entry> resolves to a list constructor.
-
- Lists and tables are sometimes referred to as aggregate types.
-
-3.2.3. Defined Types
-
- In addition, new application-wide types may be defined, so long as
- they resolve into an IMPLICITly defined ASN.1 primitive type, list,
- table, or some other application-wide type. Initially, few
- application-wide types are defined. Future memos will no doubt
- define others once a consensus is reached.
-
-3.2.3.1. NetworkAddress
-
- This CHOICE represents an address from one of possibly several
- protocol families. Currently, only one protocol family, the Internet
- family, is present in this CHOICE.
-
-3.2.3.2. IpAddress
-
- This application-wide type represents a 32-bit internet address. It
- is represented as an OCTET STRING of length 4, in network byte-order.
-
- When this ASN.1 type is encoded using the ASN.1 basic encoding rules,
- only the primitive encoding form shall be used.
-
-3.2.3.3. Counter
-
- This application-wide type represents a non-negative integer which
-
-
-
-Rose & McCloghrie [Page 8]
-\f
-RFC 1155 SMI May 1990
-
-
- monotonically increases until it reaches a maximum value, when it
- wraps around and starts increasing again from zero. This memo
- specifies a maximum value of 2^32-1 (4294967295 decimal) for
- counters.
-
-3.2.3.4. Gauge
-
- This application-wide type represents a non-negative integer, which
- may increase or decrease, but which latches at a maximum value. This
- memo specifies a maximum value of 2^32-1 (4294967295 decimal) for
- gauges.
-
-3.2.3.5. TimeTicks
-
- This application-wide type represents a non-negative integer which
- counts the time in hundredths of a second since some epoch. When
- object types are defined in the MIB which use this ASN.1 type, the
- description of the object type identifies the reference epoch.
-
-3.2.3.6. Opaque
-
- This application-wide type supports the capability to pass arbitrary
- ASN.1 syntax. A value is encoded using the ASN.1 basic rules into a
- string of octets. This, in turn, is encoded as an OCTET STRING, in
- effect "double-wrapping" the original ASN.1 value.
-
- Note that a conforming implementation need only be able to accept and
- recognize opaquely-encoded data. It need not be able to unwrap the
- data and then interpret its contents.
-
- Further note that by use of the ASN.1 EXTERNAL type, encodings other
- than ASN.1 may be used in opaquely-encoded data.
-
-3.3. Encodings
-
- Once an instance of an object type has been identified, its value may
- be transmitted by applying the basic encoding rules of ASN.1 to the
- syntax for the object type.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Rose & McCloghrie [Page 9]
-\f
-RFC 1155 SMI May 1990
-
-
-4. Managed Objects
-
- Although it is not the purpose of this memo to define objects in the
- MIB, this memo specifies a format to be used by other memos which
- define these objects.
-
- An object type definition consists of five fields:
-
- OBJECT:
- -------
- A textual name, termed the OBJECT DESCRIPTOR, for the object type,
- along with its corresponding OBJECT IDENTIFIER.
-
- Syntax:
- The abstract syntax for the object type. This must resolve to an
- instance of the ASN.1 type ObjectSyntax (defined below).
-
- Definition:
- A textual description of the semantics of the object type.
- Implementations should ensure that their instance of the object
- fulfills this definition since this MIB is intended for use in
- multi-vendor environments. As such it is vital that objects have
- consistent meaning across all machines.
-
- Access:
- One of read-only, read-write, write-only, or not-accessible.
-
- Status:
- One of mandatory, optional, or obsolete.
-
- Future memos may also specify other fields for the objects which they
- define.
-
-4.1. Guidelines for Object Names
-
- No object type in the Internet-Standard MIB shall use a sub-
- identifier of 0 in its name. This value is reserved for use with
- future extensions.
-
- Each OBJECT DESCRIPTOR corresponding to an object type in the
- internet-standard MIB shall be a unique, but mnemonic, printable
- string. This promotes a common language for humans to use when
- discussing the MIB and also facilitates simple table mappings for
- user interfaces.
-
-4.2. Object Types and Instances
-
- An object type is a definition of a kind of managed object; it is
-
-
-
-Rose & McCloghrie [Page 10]
-\f
-RFC 1155 SMI May 1990
-
-
- declarative in nature. In contrast, an object instance is an
- instantiation of an object type which has been bound to a value. For
- example, the notion of an entry in a routing table might be defined
- in the MIB. Such a notion corresponds to an object type; individual
- entries in a particular routing table which exist at some time are
- object instances of that object type.
-
- A collection of object types is defined in the MIB. Each such
- subject type is uniquely named by its OBJECT IDENTIFIER and also has
- a textual name, which is its OBJECT DESCRIPTOR. The means whereby
- object instances are referenced is not defined in the MIB. Reference
- to object instances is achieved by a protocol-specific mechanism: it
- is the responsibility of each management protocol adhering to the SMI
- to define this mechanism.
-
- An object type may be defined in the MIB such that an instance of
- that object type represents an aggregation of information also
- represented by instances of some number of "subordinate" object
- types. For example, suppose the following object types are defined
- in the MIB:
-
-
- OBJECT:
- -------
- atIndex { atEntry 1 }
-
- Syntax:
- INTEGER
-
- Definition:
- The interface number for the physical address.
-
- Access:
- read-write.
-
- Status:
- mandatory.
-
-
- OBJECT:
- -------
- atPhysAddress { atEntry 2 }
-
- Syntax:
- OCTET STRING
-
- Definition:
- The media-dependent physical address.
-
-
-
-Rose & McCloghrie [Page 11]
-\f
-RFC 1155 SMI May 1990
-
-
- Access:
- read-write.
-
- Status:
- mandatory.
-
-
- OBJECT:
- -------
- atNetAddress { atEntry 3 }
-
- Syntax:
- NetworkAddress
-
- Definition:
- The network address corresponding to the media-dependent physical
- address.
-
- Access:
- read-write.
-
- Status:
- mandatory.
-
- Then, a fourth object type might also be defined in the MIB:
-
-
- OBJECT:
- -------
- atEntry { atTable 1 }
-
- Syntax:
-
- AtEntry ::= SEQUENCE {
- atIndex
- INTEGER,
- atPhysAddress
- OCTET STRING,
- atNetAddress
- NetworkAddress
- }
-
- Definition:
- An entry in the address translation table.
-
- Access:
- read-write.
-
-
-
-
-Rose & McCloghrie [Page 12]
-\f
-RFC 1155 SMI May 1990
-
-
- Status:
- mandatory.
-
- Each instance of this object type comprises information represented
- by instances of the former three object types. An object type
- defined in this way is called a list.
-
- Similarly, tables can be formed by aggregations of a list type. For
- example, a fifth object type might also be defined in the MIB:
-
-
- OBJECT:
- ------
- atTable { at 1 }
-
- Syntax:
- SEQUENCE OF AtEntry
-
- Definition:
- The address translation table.
-
- Access:
- read-write.
-
- Status:
- mandatory.
-
- such that each instance of the atTable object comprises information
- represented by the set of atEntry object types that collectively
- constitute a given atTable object instance, that is, a given address
- translation table.
-
- Consider how one might refer to a simple object within a table.
- Continuing with the previous example, one might name the object type
-
- { atPhysAddress }
-
- and specify, using a protocol-specific mechanism, the object instance
-
- { atNetAddress } = { internet "10.0.0.52" }
-
- This pairing of object type and object instance would refer to all
- instances of atPhysAddress which are part of any entry in some
- address translation table for which the associated atNetAddress value
- is { internet "10.0.0.52" }.
-
- To continue with this example, consider how one might refer to an
- aggregate object (list) within a table. Naming the object type
-
-
-
-Rose & McCloghrie [Page 13]
-\f
-RFC 1155 SMI May 1990
-
-
- { atEntry }
-
- and specifying, using a protocol-specific mechanism, the object
- instance
-
- { atNetAddress } = { internet "10.0.0.52" }
-
- refers to all instances of entries in the table for which the
- associated atNetAddress value is { internet "10.0.0.52" }.
-
- Each management protocol must provide a mechanism for accessing
- simple (non-aggregate) object types. Each management protocol
- specifies whether or not it supports access to aggregate object
- types. Further, the protocol must specify which instances are
- "returned" when an object type/instance pairing refers to more than
- one instance of a type.
-
- To afford support for a variety of management protocols, all
- information by which instances of a given object type may be usefully
- distinguished, one from another, is represented by instances of
- object types defined in the MIB.
-
-4.3. Macros for Managed Objects
-
- In order to facilitate the use of tools for processing the definition
- of the MIB, the OBJECT-TYPE macro may be used. This macro permits
- the key aspects of an object type to be represented in a formal way.
-
- OBJECT-TYPE MACRO ::=
- BEGIN
- TYPE NOTATION ::= "SYNTAX" type (TYPE ObjectSyntax)
- "ACCESS" Access
- "STATUS" Status
- VALUE NOTATION ::= value (VALUE ObjectName)
-
- Access ::= "read-only"
- | "read-write"
- | "write-only"
- | "not-accessible"
- Status ::= "mandatory"
- | "optional"
- | "obsolete"
- END
-
- Given the object types defined earlier, we might imagine the
- following definitions being present in the MIB:
-
- atIndex OBJECT-TYPE
-
-
-
-Rose & McCloghrie [Page 14]
-\f
-RFC 1155 SMI May 1990
-
-
- SYNTAX INTEGER
- ACCESS read-write
- STATUS mandatory
- ::= { atEntry 1 }
-
- atPhysAddress OBJECT-TYPE
- SYNTAX OCTET STRING
- ACCESS read-write
- STATUS mandatory
- ::= { atEntry 2 }
-
- atNetAddress OBJECT-TYPE
- SYNTAX NetworkAddress
- ACCESS read-write
- STATUS mandatory
- ::= { atEntry 3 }
-
- atEntry OBJECT-TYPE
- SYNTAX AtEntry
- ACCESS read-write
- STATUS mandatory
- ::= { atTable 1 }
-
- atTable OBJECT-TYPE
- SYNTAX SEQUENCE OF AtEntry
- ACCESS read-write
- STATUS mandatory
- ::= { at 1 }
-
- AtEntry ::= SEQUENCE {
- atIndex
- INTEGER,
- atPhysAddress
- OCTET STRING,
- atNetAddress
- NetworkAddress
- }
-
- The first five definitions describe object types, relating, for
- example, the OBJECT DESCRIPTOR atIndex to the OBJECT IDENTIFIER {
- atEntry 1 }. In addition, the syntax of this object is defined
- (INTEGER) along with the access permitted (read-write) and status
- (mandatory). The sixth definition describes an ASN.1 type called
- AtEntry.
-
-
-
-
-
-
-
-Rose & McCloghrie [Page 15]
-\f
-RFC 1155 SMI May 1990
-
-
-5. Extensions to the MIB
-
- Every Internet-standard MIB document obsoletes all previous such
- documents. The portion of a name, termed the tail, following the
- OBJECT IDENTIFIER
-
- { mgmt version-number }
-
- used to name objects shall remain unchanged between versions. New
- versions may:
-
- (1) declare old object types obsolete (if necessary), but not
- delete their names;
-
- (2) augment the definition of an object type corresponding to a
- list by appending non-aggregate object types to the object types
- in the list; or,
-
- (3) define entirely new object types.
-
- New versions may not:
-
- (1) change the semantics of any previously defined object without
- changing the name of that object.
-
- These rules are important because they admit easier support for
- multiple versions of the Internet-standard MIB. In particular, the
- semantics associated with the tail of a name remain constant
- throughout different versions of the MIB. Because multiple versions
- of the MIB may thus coincide in "tail-space," implementations
- supporting multiple versions of the MIB can be vastly simplified.
-
- However, as a consequence, a management agent might return an
- instance corresponding to a superset of the expected object type.
- Following the principle of robustness, in this exceptional case, a
- manager should ignore any additional information beyond the
- definition of the expected object type. However, the robustness
- principle requires that one exercise care with respect to control
- actions: if an instance does not have the same syntax as its
- expected object type, then those control actions must fail. In both
- the monitoring and control cases, the name of an object returned by
- an operation must be identical to the name requested by an operation.
-
-
-
-
-
-
-
-
-
-Rose & McCloghrie [Page 16]
-\f
-RFC 1155 SMI May 1990
-
-
-6. Definitions
-
- RFC1155-SMI DEFINITIONS ::= BEGIN
-
- EXPORTS -- EVERYTHING
- internet, directory, mgmt,
- experimental, private, enterprises,
- OBJECT-TYPE, ObjectName, ObjectSyntax, SimpleSyntax,
- ApplicationSyntax, NetworkAddress, IpAddress,
- Counter, Gauge, TimeTicks, Opaque;
-
- -- the path to the root
-
- internet OBJECT IDENTIFIER ::= { iso org(3) dod(6) 1 }
-
- directory OBJECT IDENTIFIER ::= { internet 1 }
-
- mgmt OBJECT IDENTIFIER ::= { internet 2 }
-
- experimental OBJECT IDENTIFIER ::= { internet 3 }
-
- private OBJECT IDENTIFIER ::= { internet 4 }
- enterprises OBJECT IDENTIFIER ::= { private 1 }
-
-
- -- definition of object types
-
- OBJECT-TYPE MACRO ::=
- BEGIN
- TYPE NOTATION ::= "SYNTAX" type (TYPE ObjectSyntax)
- "ACCESS" Access
- "STATUS" Status
- VALUE NOTATION ::= value (VALUE ObjectName)
-
- Access ::= "read-only"
- | "read-write"
- | "write-only"
- | "not-accessible"
- Status ::= "mandatory"
- | "optional"
- | "obsolete"
- END
-
- -- names of objects in the MIB
-
- ObjectName ::=
- OBJECT IDENTIFIER
-
-
-
-
-Rose & McCloghrie [Page 17]
-\f
-RFC 1155 SMI May 1990
-
-
- -- syntax of objects in the MIB
-
- ObjectSyntax ::=
- CHOICE {
- simple
- SimpleSyntax,
-
- -- note that simple SEQUENCEs are not directly
- -- mentioned here to keep things simple (i.e.,
- -- prevent mis-use). However, application-wide
- -- types which are IMPLICITly encoded simple
- -- SEQUENCEs may appear in the following CHOICE
-
- application-wide
- ApplicationSyntax
- }
-
- SimpleSyntax ::=
- CHOICE {
- number
- INTEGER,
-
- string
- OCTET STRING,
-
- object
- OBJECT IDENTIFIER,
-
- empty
- NULL
- }
-
- ApplicationSyntax ::=
- CHOICE {
- address
- NetworkAddress,
-
- counter
- Counter,
-
- gauge
- Gauge,
-
- ticks
- TimeTicks,
-
- arbitrary
- Opaque
-
-
-
-Rose & McCloghrie [Page 18]
-\f
-RFC 1155 SMI May 1990
-
-
- -- other application-wide types, as they are
- -- defined, will be added here
- }
-
-
- -- application-wide types
-
- NetworkAddress ::=
- CHOICE {
- internet
- IpAddress
- }
-
- IpAddress ::=
- [APPLICATION 0] -- in network-byte order
- IMPLICIT OCTET STRING (SIZE (4))
-
- Counter ::=
- [APPLICATION 1]
- IMPLICIT INTEGER (0..4294967295)
-
- Gauge ::=
- [APPLICATION 2]
- IMPLICIT INTEGER (0..4294967295)
-
- TimeTicks ::=
- [APPLICATION 3]
- IMPLICIT INTEGER (0..4294967295)
-
- Opaque ::=
- [APPLICATION 4] -- arbitrary ASN.1 value,
- IMPLICIT OCTET STRING -- "double-wrapped"
-
- END
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Rose & McCloghrie [Page 19]
-\f
-RFC 1155 SMI May 1990
-
-
-7. Acknowledgements
-
- This memo was influenced by three sets of contributors to earlier
- drafts:
-
- First, Lee Labarre of the MITRE Corporation, who as author of the
- NETMAN SMI [4], presented the basic roadmap for the SMI.
-
- Second, several individuals who provided valuable comments on this
- memo prior to its initial distribution:
-
- James R. Davin, Proteon
- Mark S. Fedor, NYSERNet
- Craig Partridge, BBN Laboratories
- Martin Lee Schoffstall, Rensselaer Polytechnic Institute
- Wengyik Yeong, NYSERNet
-
-
- Third, the IETF MIB working group:
-
- Karl Auerbach, Epilogue Technology
- K. Ramesh Babu, Excelan
- Lawrence Besaw, Hewlett-Packard
- Jeffrey D. Case, University of Tennessee at Knoxville
- James R. Davin, Proteon
- Mark S. Fedor, NYSERNet
- Robb Foster, BBN
- Phill Gross, The MITRE Corporation
- Bent Torp Jensen, Convergent Technology
- Lee Labarre, The MITRE Corporation
- Dan Lynch, Advanced Computing Environments
- Keith McCloghrie, The Wollongong Group
- Dave Mackie, 3Com/Bridge
- Craig Partridge, BBN (chair)
- Jim Robertson, 3Com/Bridge
- Marshall T. Rose, The Wollongong Group
- Greg Satz, cisco
- Martin Lee Schoffstall, Rensselaer Polytechnic Institute
- Lou Steinberg, IBM
- Dean Throop, Data General
- Unni Warrier, Unisys
-
-
-
-
-
-
-
-
-
-
-Rose & McCloghrie [Page 20]
-\f
-RFC 1155 SMI May 1990
-
-
-8. References
-
- [1] Information processing systems - Open Systems Interconnection,
- "Specification of Abstract Syntax Notation One (ASN.1)",
- International Organization for Standardization, International
- Standard 8824, December 1987.
-
- [2] McCloghrie K., and M. Rose, "Management Information Base for
- Network Management of TCP/IP-based Internets", RFC 1156,
- Performance Systems International and Hughes LAN Systems, May
- 1990.
-
- [3] Case, J., M. Fedor, M. Schoffstall, and J. Davin, The Simple
- Network Management Protocol", RFC 1157, University of Tennessee
- at Knoxville, Performance Systems International, Performance
- Systems International, and the MIT Laboratory for Computer
- Science, May 1990.
-
- [4] LaBarre, L., "Structure and Identification of Management
- Information for the Internet", Internet Engineering Task Force
- working note, Network Information Center, SRI International,
- Menlo Park, California, April 1988.
-
- [5] Cerf, V., "IAB Recommendations for the Development of Internet
- Network Management Standards", RFC 1052, IAB, April 1988.
-
- [6] Cerf, V., "Report of the Second Ad Hoc Network Management Review
- Group", RFC 1109, IAB, August 1989.
-
- [7] Information processing systems - Open Systems Interconnection,
- "Specification of Basic Encoding Rules for Abstract Notation One
- (ASN.1)", International Organization for Standardization,
- International Standard 8825, December 1987.
-
-Security Considerations
-
- Security issues are not discussed in this memo.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Rose & McCloghrie [Page 21]
-\f
-RFC 1155 SMI May 1990
-
-
-Authors' Addresses
-
- Marshall T. Rose
- PSI, Inc.
- PSI California Office
- P.O. Box 391776
- Mountain View, CA 94039
-
- Phone: (415) 961-3380
-
- EMail: mrose@PSI.COM
-
-
- Keith McCloghrie
- The Wollongong Group
- 1129 San Antonio Road
- Palo Alto, CA 04303
-
- Phone: (415) 962-7160
-
- EMail: sytek!kzm@HPLABS.HP.COM
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Rose & McCloghrie [Page 22]
-\f
\ No newline at end of file
+++ /dev/null
-
-
-
-
-
-
-Network Working Group J. Case
-Request for Comments: 1157 SNMP Research
-Obsoletes: RFC 1098 M. Fedor
- Performance Systems International
- M. Schoffstall
- Performance Systems International
- J. Davin
- MIT Laboratory for Computer Science
- May 1990
-
-
- A Simple Network Management Protocol (SNMP)
-
- Table of Contents
-
- 1. Status of this Memo ................................... 2
- 2. Introduction .......................................... 2
- 3. The SNMP Architecture ................................. 5
- 3.1 Goals of the Architecture ............................ 5
- 3.2 Elements of the Architecture ......................... 5
- 3.2.1 Scope of Management Information .................... 6
- 3.2.2 Representation of Management Information ........... 6
- 3.2.3 Operations Supported on Management Information ..... 7
- 3.2.4 Form and Meaning of Protocol Exchanges ............. 8
- 3.2.5 Definition of Administrative Relationships ......... 8
- 3.2.6 Form and Meaning of References to Managed Objects .. 12
- 3.2.6.1 Resolution of Ambiguous MIB References ........... 12
- 3.2.6.2 Resolution of References across MIB Versions...... 12
- 3.2.6.3 Identification of Object Instances ............... 12
- 3.2.6.3.1 ifTable Object Type Names ...................... 13
- 3.2.6.3.2 atTable Object Type Names ...................... 13
- 3.2.6.3.3 ipAddrTable Object Type Names .................. 14
- 3.2.6.3.4 ipRoutingTable Object Type Names ............... 14
- 3.2.6.3.5 tcpConnTable Object Type Names ................. 14
- 3.2.6.3.6 egpNeighTable Object Type Names ................ 15
- 4. Protocol Specification ................................ 16
- 4.1 Elements of Procedure ................................ 17
- 4.1.1 Common Constructs .................................. 19
- 4.1.2 The GetRequest-PDU ................................. 20
- 4.1.3 The GetNextRequest-PDU ............................. 21
- 4.1.3.1 Example of Table Traversal ....................... 23
- 4.1.4 The GetResponse-PDU ................................ 24
- 4.1.5 The SetRequest-PDU ................................. 25
- 4.1.6 The Trap-PDU ....................................... 27
- 4.1.6.1 The coldStart Trap ............................... 28
- 4.1.6.2 The warmStart Trap ............................... 28
- 4.1.6.3 The linkDown Trap ................................ 28
- 4.1.6.4 The linkUp Trap .................................. 28
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 1]
-\f
-RFC 1157 SNMP May 1990
-
-
- 4.1.6.5 The authenticationFailure Trap ................... 28
- 4.1.6.6 The egpNeighborLoss Trap ......................... 28
- 4.1.6.7 The enterpriseSpecific Trap ...................... 29
- 5. Definitions ........................................... 30
- 6. Acknowledgements ...................................... 33
- 7. References ............................................ 34
- 8. Security Considerations................................ 35
- 9. Authors' Addresses..................................... 35
-
-1. Status of this Memo
-
- This RFC is a re-release of RFC 1098, with a changed "Status of this
- Memo" section plus a few minor typographical corrections. This memo
- defines a simple protocol by which management information for a
- network element may be inspected or altered by logically remote
- users. In particular, together with its companion memos which
- describe the structure of management information along with the
- management information base, these documents provide a simple,
- workable architecture and system for managing TCP/IP-based internets
- and in particular the Internet.
-
- The Internet Activities Board recommends that all IP and TCP
- implementations be network manageable. This implies implementation
- of the Internet MIB (RFC-1156) and at least one of the two
- recommended management protocols SNMP (RFC-1157) or CMOT (RFC-1095).
- It should be noted that, at this time, SNMP is a full Internet
- standard and CMOT is a draft standard. See also the Host and Gateway
- Requirements RFCs for more specific information on the applicability
- of this standard.
-
- Please refer to the latest edition of the "IAB Official Protocol
- Standards" RFC for current information on the state and status of
- standard Internet protocols.
-
- Distribution of this memo is unlimited.
-
-2. Introduction
-
- As reported in RFC 1052, IAB Recommendations for the Development of
- Internet Network Management Standards [1], a two-prong strategy for
- network management of TCP/IP-based internets was undertaken. In the
- short-term, the Simple Network Management Protocol (SNMP) was to be
- used to manage nodes in the Internet community. In the long-term,
- the use of the OSI network management framework was to be examined.
- Two documents were produced to define the management information: RFC
- 1065, which defined the Structure of Management Information (SMI)
- [2], and RFC 1066, which defined the Management Information Base
- (MIB) [3]. Both of these documents were designed so as to be
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 2]
-\f
-RFC 1157 SNMP May 1990
-
-
- compatible with both the SNMP and the OSI network management
- framework.
-
- This strategy was quite successful in the short-term: Internet-based
- network management technology was fielded, by both the research and
- commercial communities, within a few months. As a result of this,
- portions of the Internet community became network manageable in a
- timely fashion.
-
- As reported in RFC 1109, Report of the Second Ad Hoc Network
- Management Review Group [4], the requirements of the SNMP and the OSI
- network management frameworks were more different than anticipated.
- As such, the requirement for compatibility between the SMI/MIB and
- both frameworks was suspended. This action permitted the operational
- network management framework, the SNMP, to respond to new operational
- needs in the Internet community by producing documents defining new
- MIB items.
-
- The IAB has designated the SNMP, SMI, and the initial Internet MIB to
- be full "Standard Protocols" with "Recommended" status. By this
- action, the IAB recommends that all IP and TCP implementations be
- network manageable and that the implementations that are network
- manageable are expected to adopt and implement the SMI, MIB, and
- SNMP.
-
- As such, the current network management framework for TCP/IP- based
- internets consists of: Structure and Identification of Management
- Information for TCP/IP-based Internets, which describes how managed
- objects contained in the MIB are defined as set forth in RFC 1155
- [5]; Management Information Base for Network Management of TCP/IP-
- based Internets, which describes the managed objects contained in the
- MIB as set forth in RFC 1156 [6]; and, the Simple Network Management
- Protocol, which defines the protocol used to manage these objects, as
- set forth in this memo.
-
- As reported in RFC 1052, IAB Recommendations for the Development of
- Internet Network Management Standards [1], the Internet Activities
- Board has directed the Internet Engineering Task Force (IETF) to
- create two new working groups in the area of network management. One
- group was charged with the further specification and definition of
- elements to be included in the Management Information Base (MIB).
- The other was charged with defining the modifications to the Simple
- Network Management Protocol (SNMP) to accommodate the short-term
- needs of the network vendor and operations communities, and to align
- with the output of the MIB working group.
-
- The MIB working group produced two memos, one which defines a
- Structure for Management Information (SMI) [2] for use by the managed
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 3]
-\f
-RFC 1157 SNMP May 1990
-
-
- objects contained in the MIB. A second memo [3] defines the list of
- managed objects.
-
- The output of the SNMP Extensions working group is this memo, which
- incorporates changes to the initial SNMP definition [7] required to
- attain alignment with the output of the MIB working group. The
- changes should be minimal in order to be consistent with the IAB's
- directive that the working groups be "extremely sensitive to the need
- to keep the SNMP simple." Although considerable care and debate has
- gone into the changes to the SNMP which are reflected in this memo,
- the resulting protocol is not backwardly-compatible with its
- predecessor, the Simple Gateway Monitoring Protocol (SGMP) [8].
- Although the syntax of the protocol has been altered, the original
- philosophy, design decisions, and architecture remain intact. In
- order to avoid confusion, new UDP ports have been allocated for use
- by the protocol described in this memo.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 4]
-\f
-RFC 1157 SNMP May 1990
-
-
-3. The SNMP Architecture
-
- Implicit in the SNMP architectural model is a collection of network
- management stations and network elements. Network management
- stations execute management applications which monitor and control
- network elements. Network elements are devices such as hosts,
- gateways, terminal servers, and the like, which have management
- agents responsible for performing the network management functions
- requested by the network management stations. The Simple Network
- Management Protocol (SNMP) is used to communicate management
- information between the network management stations and the agents in
- the network elements.
-
-3.1. Goals of the Architecture
-
- The SNMP explicitly minimizes the number and complexity of management
- functions realized by the management agent itself. This goal is
- attractive in at least four respects:
-
- (1) The development cost for management agent software
- necessary to support the protocol is accordingly reduced.
-
- (2) The degree of management function that is remotely
- supported is accordingly increased, thereby admitting
- fullest use of internet resources in the management task.
-
- (3) The degree of management function that is remotely
- supported is accordingly increased, thereby imposing the
- fewest possible restrictions on the form and
- sophistication of management tools.
-
- (4) Simplified sets of management functions are easily
- understood and used by developers of network management
- tools.
-
- A second goal of the protocol is that the functional paradigm for
- monitoring and control be sufficiently extensible to accommodate
- additional, possibly unanticipated aspects of network operation and
- management.
-
- A third goal is that the architecture be, as much as possible,
- independent of the architecture and mechanisms of particular hosts or
- particular gateways.
-
-3.2. Elements of the Architecture
-
- The SNMP architecture articulates a solution to the network
- management problem in terms of:
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 5]
-\f
-RFC 1157 SNMP May 1990
-
-
- (1) the scope of the management information communicated by
- the protocol,
-
- (2) the representation of the management information
- communicated by the protocol,
-
- (3) operations on management information supported by the
- protocol,
-
- (4) the form and meaning of exchanges among management
- entities,
-
- (5) the definition of administrative relationships among
- management entities, and
-
- (6) the form and meaning of references to management
- information.
-
-3.2.1. Scope of Management Information
-
- The scope of the management information communicated by operation of
- the SNMP is exactly that represented by instances of all non-
- aggregate object types either defined in Internet-standard MIB or
- defined elsewhere according to the conventions set forth in
- Internet-standard SMI [5].
-
- Support for aggregate object types in the MIB is neither required for
- conformance with the SMI nor realized by the SNMP.
-
-3.2.2. Representation of Management Information
-
- Management information communicated by operation of the SNMP is
- represented according to the subset of the ASN.1 language [9] that is
- specified for the definition of non-aggregate types in the SMI.
-
- The SGMP adopted the convention of using a well-defined subset of the
- ASN.1 language [9]. The SNMP continues and extends this tradition by
- utilizing a moderately more complex subset of ASN.1 for describing
- managed objects and for describing the protocol data units used for
- managing those objects. In addition, the desire to ease eventual
- transition to OSI-based network management protocols led to the
- definition in the ASN.1 language of an Internet-standard Structure of
- Management Information (SMI) [5] and Management Information Base
- (MIB) [6]. The use of the ASN.1 language, was, in part, encouraged
- by the successful use of ASN.1 in earlier efforts, in particular, the
- SGMP. The restrictions on the use of ASN.1 that are part of the SMI
- contribute to the simplicity espoused and validated by experience
- with the SGMP.
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 6]
-\f
-RFC 1157 SNMP May 1990
-
-
- Also for the sake of simplicity, the SNMP uses only a subset of the
- basic encoding rules of ASN.1 [10]. Namely, all encodings use the
- definite-length form. Further, whenever permissible, non-constructor
- encodings are used rather than constructor encodings. This
- restriction applies to all aspects of ASN.1 encoding, both for the
- top-level protocol data units and the data objects they contain.
-
-3.2.3. Operations Supported on Management Information
-
- The SNMP models all management agent functions as alterations or
- inspections of variables. Thus, a protocol entity on a logically
- remote host (possibly the network element itself) interacts with the
- management agent resident on the network element in order to retrieve
- (get) or alter (set) variables. This strategy has at least two
- positive consequences:
-
- (1) It has the effect of limiting the number of essential
- management functions realized by the management agent to
- two: one operation to assign a value to a specified
- configuration or other parameter and another to retrieve
- such a value.
-
- (2) A second effect of this decision is to avoid introducing
- into the protocol definition support for imperative
- management commands: the number of such commands is in
- practice ever-increasing, and the semantics of such
- commands are in general arbitrarily complex.
-
- The strategy implicit in the SNMP is that the monitoring of network
- state at any significant level of detail is accomplished primarily by
- polling for appropriate information on the part of the monitoring
- center(s). A limited number of unsolicited messages (traps) guide
- the timing and focus of the polling. Limiting the number of
- unsolicited messages is consistent with the goal of simplicity and
- minimizing the amount of traffic generated by the network management
- function.
-
- The exclusion of imperative commands from the set of explicitly
- supported management functions is unlikely to preclude any desirable
- management agent operation. Currently, most commands are requests
- either to set the value of some parameter or to retrieve such a
- value, and the function of the few imperative commands currently
- supported is easily accommodated in an asynchronous mode by this
- management model. In this scheme, an imperative command might be
- realized as the setting of a parameter value that subsequently
- triggers the desired action. For example, rather than implementing a
- "reboot command," this action might be invoked by simply setting a
- parameter indicating the number of seconds until system reboot.
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 7]
-\f
-RFC 1157 SNMP May 1990
-
-
-3.2.4. Form and Meaning of Protocol Exchanges
-
- The communication of management information among management entities
- is realized in the SNMP through the exchange of protocol messages.
- The form and meaning of those messages is defined below in Section 4.
-
- Consistent with the goal of minimizing complexity of the management
- agent, the exchange of SNMP messages requires only an unreliable
- datagram service, and every message is entirely and independently
- represented by a single transport datagram. While this document
- specifies the exchange of messages via the UDP protocol [11], the
- mechanisms of the SNMP are generally suitable for use with a wide
- variety of transport services.
-
-3.2.5. Definition of Administrative Relationships
-
- The SNMP architecture admits a variety of administrative
- relationships among entities that participate in the protocol. The
- entities residing at management stations and network elements which
- communicate with one another using the SNMP are termed SNMP
- application entities. The peer processes which implement the SNMP,
- and thus support the SNMP application entities, are termed protocol
- entities.
-
- A pairing of an SNMP agent with some arbitrary set of SNMP
- application entities is called an SNMP community. Each SNMP
- community is named by a string of octets, that is called the
- community name for said community.
-
- An SNMP message originated by an SNMP application entity that in fact
- belongs to the SNMP community named by the community component of
- said message is called an authentic SNMP message. The set of rules
- by which an SNMP message is identified as an authentic SNMP message
- for a particular SNMP community is called an authentication scheme.
- An implementation of a function that identifies authentic SNMP
- messages according to one or more authentication schemes is called an
- authentication service.
-
- Clearly, effective management of administrative relationships among
- SNMP application entities requires authentication services that (by
- the use of encryption or other techniques) are able to identify
- authentic SNMP messages with a high degree of certainty. Some SNMP
- implementations may wish to support only a trivial authentication
- service that identifies all SNMP messages as authentic SNMP messages.
-
- For any network element, a subset of objects in the MIB that pertain
- to that element is called a SNMP MIB view. Note that the names of
- the object types represented in a SNMP MIB view need not belong to a
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 8]
-\f
-RFC 1157 SNMP May 1990
-
-
- single sub-tree of the object type name space.
-
- An element of the set { READ-ONLY, READ-WRITE } is called an SNMP
- access mode.
-
- A pairing of a SNMP access mode with a SNMP MIB view is called an
- SNMP community profile. A SNMP community profile represents
- specified access privileges to variables in a specified MIB view. For
- every variable in the MIB view in a given SNMP community profile,
- access to that variable is represented by the profile according to
- the following conventions:
-
- (1) if said variable is defined in the MIB with "Access:" of
- "none," it is unavailable as an operand for any operator;
-
- (2) if said variable is defined in the MIB with "Access:" of
- "read-write" or "write-only" and the access mode of the
- given profile is READ-WRITE, that variable is available
- as an operand for the get, set, and trap operations;
-
- (3) otherwise, the variable is available as an operand for
- the get and trap operations.
-
- (4) In those cases where a "write-only" variable is an
- operand used for the get or trap operations, the value
- given for the variable is implementation-specific.
-
- A pairing of a SNMP community with a SNMP community profile is called
- a SNMP access policy. An access policy represents a specified
- community profile afforded by the SNMP agent of a specified SNMP
- community to other members of that community. All administrative
- relationships among SNMP application entities are architecturally
- defined in terms of SNMP access policies.
-
- For every SNMP access policy, if the network element on which the
- SNMP agent for the specified SNMP community resides is not that to
- which the MIB view for the specified profile pertains, then that
- policy is called a SNMP proxy access policy. The SNMP agent
- associated with a proxy access policy is called a SNMP proxy agent.
- While careless definition of proxy access policies can result in
- management loops, prudent definition of proxy policies is useful in
- at least two ways:
-
- (1) It permits the monitoring and control of network elements
- which are otherwise not addressable using the management
- protocol and the transport protocol. That is, a proxy
- agent may provide a protocol conversion function allowing
- a management station to apply a consistent management
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 9]
-\f
-RFC 1157 SNMP May 1990
-
-
- framework to all network elements, including devices such
- as modems, multiplexors, and other devices which support
- different management frameworks.
-
- (2) It potentially shields network elements from elaborate
- access control policies. For example, a proxy agent may
- implement sophisticated access control whereby diverse
- subsets of variables within the MIB are made accessible
- to different management stations without increasing the
- complexity of the network element.
-
- By way of example, Figure 1 illustrates the relationship between
- management stations, proxy agents, and management agents. In this
- example, the proxy agent is envisioned to be a normal Internet
- Network Operations Center (INOC) of some administrative domain which
- has a standard managerial relationship with a set of management
- agents.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 10]
-\f
-RFC 1157 SNMP May 1990
-
-
- +------------------+ +----------------+ +----------------+
- | Region #1 INOC | |Region #2 INOC | |PC in Region #3 |
- | | | | | |
- |Domain=Region #1 | |Domain=Region #2| |Domain=Region #3|
- |CPU=super-mini-1 | |CPU=super-mini-1| |CPU=Clone-1 |
- |PCommunity=pub | |PCommunity=pub | |PCommunity=slate|
- | | | | | |
- +------------------+ +----------------+ +----------------+
- /|\ /|\ /|\
- | | |
- | | |
- | \|/ |
- | +-----------------+ |
- +-------------->| Region #3 INOC |<-------------+
- | |
- |Domain=Region #3 |
- |CPU=super-mini-2 |
- |PCommunity=pub, |
- | slate |
- |DCommunity=secret|
- +-------------->| |<-------------+
- | +-----------------+ |
- | /|\ |
- | | |
- | | |
- \|/ \|/ \|/
- +-----------------+ +-----------------+ +-----------------+
- |Domain=Region#3 | |Domain=Region#3 | |Domain=Region#3 |
- |CPU=router-1 | |CPU=mainframe-1 | |CPU=modem-1 |
- |DCommunity=secret| |DCommunity=secret| |DCommunity=secret|
- +-----------------+ +-----------------+ +-----------------+
-
-
- Domain: the administrative domain of the element
- PCommunity: the name of a community utilizing a proxy agent
- DCommunity: the name of a direct community
-
-
- Figure 1
- Example Network Management Configuration
-
-
-
-
-
-
-
-
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 11]
-\f
-RFC 1157 SNMP May 1990
-
-
-3.2.6. Form and Meaning of References to Managed Objects
-
- The SMI requires that the definition of a conformant management
- protocol address:
-
- (1) the resolution of ambiguous MIB references,
-
- (2) the resolution of MIB references in the presence multiple
- MIB versions, and
-
- (3) the identification of particular instances of object
- types defined in the MIB.
-
-3.2.6.1. Resolution of Ambiguous MIB References
-
- Because the scope of any SNMP operation is conceptually confined to
- objects relevant to a single network element, and because all SNMP
- references to MIB objects are (implicitly or explicitly) by unique
- variable names, there is no possibility that any SNMP reference to
- any object type defined in the MIB could resolve to multiple
- instances of that type.
-
-3.2.6.2. Resolution of References across MIB Versions
-
- The object instance referred to by any SNMP operation is exactly that
- specified as part of the operation request or (in the case of a get-
- next operation) its immediate successor in the MIB as a whole. In
- particular, a reference to an object as part of some version of the
- Internet-standard MIB does not resolve to any object that is not part
- of said version of the Internet-standard MIB, except in the case that
- the requested operation is get-next and the specified object name is
- lexicographically last among the names of all objects presented as
- part of said version of the Internet-Standard MIB.
-
-3.2.6.3. Identification of Object Instances
-
- The names for all object types in the MIB are defined explicitly
- either in the Internet-standard MIB or in other documents which
- conform to the naming conventions of the SMI. The SMI requires that
- conformant management protocols define mechanisms for identifying
- individual instances of those object types for a particular network
- element.
-
- Each instance of any object type defined in the MIB is identified in
- SNMP operations by a unique name called its "variable name." In
- general, the name of an SNMP variable is an OBJECT IDENTIFIER of the
- form x.y, where x is the name of a non-aggregate object type defined
- in the MIB and y is an OBJECT IDENTIFIER fragment that, in a way
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 12]
-\f
-RFC 1157 SNMP May 1990
-
-
- specific to the named object type, identifies the desired instance.
-
- This naming strategy admits the fullest exploitation of the semantics
- of the GetNextRequest-PDU (see Section 4), because it assigns names
- for related variables so as to be contiguous in the lexicographical
- ordering of all variable names known in the MIB.
-
- The type-specific naming of object instances is defined below for a
- number of classes of object types. Instances of an object type to
- which none of the following naming conventions are applicable are
- named by OBJECT IDENTIFIERs of the form x.0, where x is the name of
- said object type in the MIB definition.
-
- For example, suppose one wanted to identify an instance of the
- variable sysDescr The object class for sysDescr is:
-
- iso org dod internet mgmt mib system sysDescr
- 1 3 6 1 2 1 1 1
-
- Hence, the object type, x, would be 1.3.6.1.2.1.1.1 to which is
- appended an instance sub-identifier of 0. That is, 1.3.6.1.2.1.1.1.0
- identifies the one and only instance of sysDescr.
-
-3.2.6.3.1. ifTable Object Type Names
-
- The name of a subnet interface, s, is the OBJECT IDENTIFIER value of
- the form i, where i has the value of that instance of the ifIndex
- object type associated with s.
-
- For each object type, t, for which the defined name, n, has a prefix
- of ifEntry, an instance, i, of t is named by an OBJECT IDENTIFIER of
- the form n.s, where s is the name of the subnet interface about which
- i represents information.
-
- For example, suppose one wanted to identify the instance of the
- variable ifType associated with interface 2. Accordingly, ifType.2
- would identify the desired instance.
-
-3.2.6.3.2. atTable Object Type Names
-
- The name of an AT-cached network address, x, is an OBJECT IDENTIFIER
- of the form 1.a.b.c.d, where a.b.c.d is the value (in the familiar
- "dot" notation) of the atNetAddress object type associated with x.
-
- The name of an address translation equivalence e is an OBJECT
- IDENTIFIER value of the form s.w, such that s is the value of that
- instance of the atIndex object type associated with e and such that w
- is the name of the AT-cached network address associated with e.
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 13]
-\f
-RFC 1157 SNMP May 1990
-
-
- For each object type, t, for which the defined name, n, has a prefix
- of atEntry, an instance, i, of t is named by an OBJECT IDENTIFIER of
- the form n.y, where y is the name of the address translation
- equivalence about which i represents information.
-
- For example, suppose one wanted to find the physical address of an
- entry in the address translation table (ARP cache) associated with an
- IP address of 89.1.1.42 and interface 3. Accordingly,
- atPhysAddress.3.1.89.1.1.42 would identify the desired instance.
-
-3.2.6.3.3. ipAddrTable Object Type Names
-
- The name of an IP-addressable network element, x, is the OBJECT
- IDENTIFIER of the form a.b.c.d such that a.b.c.d is the value (in the
- familiar "dot" notation) of that instance of the ipAdEntAddr object
- type associated with x.
-
- For each object type, t, for which the defined name, n, has a prefix
- of ipAddrEntry, an instance, i, of t is named by an OBJECT IDENTIFIER
- of the form n.y, where y is the name of the IP-addressable network
- element about which i represents information.
-
- For example, suppose one wanted to find the network mask of an entry
- in the IP interface table associated with an IP address of 89.1.1.42.
- Accordingly, ipAdEntNetMask.89.1.1.42 would identify the desired
- instance.
-
-3.2.6.3.4. ipRoutingTable Object Type Names
-
- The name of an IP route, x, is the OBJECT IDENTIFIER of the form
- a.b.c.d such that a.b.c.d is the value (in the familiar "dot"
- notation) of that instance of the ipRouteDest object type associated
- with x.
-
- For each object type, t, for which the defined name, n, has a prefix
- of ipRoutingEntry, an instance, i, of t is named by an OBJECT
- IDENTIFIER of the form n.y, where y is the name of the IP route about
- which i represents information.
-
- For example, suppose one wanted to find the next hop of an entry in
- the IP routing table associated with the destination of 89.1.1.42.
- Accordingly, ipRouteNextHop.89.1.1.42 would identify the desired
- instance.
-
-3.2.6.3.5. tcpConnTable Object Type Names
-
- The name of a TCP connection, x, is the OBJECT IDENTIFIER of the form
- a.b.c.d.e.f.g.h.i.j such that a.b.c.d is the value (in the familiar
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 14]
-\f
-RFC 1157 SNMP May 1990
-
-
- "dot" notation) of that instance of the tcpConnLocalAddress object
- type associated with x and such that f.g.h.i is the value (in the
- familiar "dot" notation) of that instance of the tcpConnRemoteAddress
- object type associated with x and such that e is the value of that
- instance of the tcpConnLocalPort object type associated with x and
- such that j is the value of that instance of the tcpConnRemotePort
- object type associated with x.
-
- For each object type, t, for which the defined name, n, has a prefix
- of tcpConnEntry, an instance, i, of t is named by an OBJECT
- IDENTIFIER of the form n.y, where y is the name of the TCP connection
- about which i represents information.
-
- For example, suppose one wanted to find the state of a TCP connection
- between the local address of 89.1.1.42 on TCP port 21 and the remote
- address of 10.0.0.51 on TCP port 2059. Accordingly,
- tcpConnState.89.1.1.42.21.10.0.0.51.2059 would identify the desired
- instance.
-
-3.2.6.3.6. egpNeighTable Object Type Names
-
- The name of an EGP neighbor, x, is the OBJECT IDENTIFIER of the form
- a.b.c.d such that a.b.c.d is the value (in the familiar "dot"
- notation) of that instance of the egpNeighAddr object type associated
- with x.
-
- For each object type, t, for which the defined name, n, has a prefix
- of egpNeighEntry, an instance, i, of t is named by an OBJECT
- IDENTIFIER of the form n.y, where y is the name of the EGP neighbor
- about which i represents information.
-
- For example, suppose one wanted to find the neighbor state for the IP
- address of 89.1.1.42. Accordingly, egpNeighState.89.1.1.42 would
- identify the desired instance.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 15]
-\f
-RFC 1157 SNMP May 1990
-
-
-4. Protocol Specification
-
- The network management protocol is an application protocol by which
- the variables of an agent's MIB may be inspected or altered.
-
- Communication among protocol entities is accomplished by the exchange
- of messages, each of which is entirely and independently represented
- within a single UDP datagram using the basic encoding rules of ASN.1
- (as discussed in Section 3.2.2). A message consists of a version
- identifier, an SNMP community name, and a protocol data unit (PDU).
- A protocol entity receives messages at UDP port 161 on the host with
- which it is associated for all messages except for those which report
- traps (i.e., all messages except those which contain the Trap-PDU).
- Messages which report traps should be received on UDP port 162 for
- further processing. An implementation of this protocol need not
- accept messages whose length exceeds 484 octets. However, it is
- recommended that implementations support larger datagrams whenever
- feasible.
-
- It is mandatory that all implementations of the SNMP support the five
- PDUs: GetRequest-PDU, GetNextRequest-PDU, GetResponse-PDU,
- SetRequest-PDU, and Trap-PDU.
-
- RFC1157-SNMP DEFINITIONS ::= BEGIN
-
- IMPORTS
- ObjectName, ObjectSyntax, NetworkAddress, IpAddress, TimeTicks
- FROM RFC1155-SMI;
-
-
- -- top-level message
-
- Message ::=
- SEQUENCE {
- version -- version-1 for this RFC
- INTEGER {
- version-1(0)
- },
-
- community -- community name
- OCTET STRING,
-
- data -- e.g., PDUs if trivial
- ANY -- authentication is being used
- }
-
-
-
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 16]
-\f
-RFC 1157 SNMP May 1990
-
-
- -- protocol data units
-
- PDUs ::=
- CHOICE {
- get-request
- GetRequest-PDU,
-
- get-next-request
- GetNextRequest-PDU,
-
- get-response
- GetResponse-PDU,
-
- set-request
- SetRequest-PDU,
-
- trap
- Trap-PDU
- }
-
- -- the individual PDUs and commonly used
- -- data types will be defined later
-
- END
-
-
-4.1. Elements of Procedure
-
- This section describes the actions of a protocol entity implementing
- the SNMP. Note, however, that it is not intended to constrain the
- internal architecture of any conformant implementation.
-
- In the text that follows, the term transport address is used. In the
- case of the UDP, a transport address consists of an IP address along
- with a UDP port. Other transport services may be used to support the
- SNMP. In these cases, the definition of a transport address should
- be made accordingly.
-
- The top-level actions of a protocol entity which generates a message
- are as follows:
-
- (1) It first constructs the appropriate PDU, e.g., the
- GetRequest-PDU, as an ASN.1 object.
-
- (2) It then passes this ASN.1 object along with a community
- name its source transport address and the destination
- transport address, to the service which implements the
- desired authentication scheme. This authentication
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 17]
-\f
-RFC 1157 SNMP May 1990
-
-
- service returns another ASN.1 object.
-
- (3) The protocol entity then constructs an ASN.1 Message
- object, using the community name and the resulting ASN.1
- object.
-
- (4) This new ASN.1 object is then serialized, using the basic
- encoding rules of ASN.1, and then sent using a transport
- service to the peer protocol entity.
-
- Similarly, the top-level actions of a protocol entity which receives
- a message are as follows:
-
- (1) It performs a rudimentary parse of the incoming datagram
- to build an ASN.1 object corresponding to an ASN.1
- Message object. If the parse fails, it discards the
- datagram and performs no further actions.
-
- (2) It then verifies the version number of the SNMP message.
- If there is a mismatch, it discards the datagram and
- performs no further actions.
-
- (3) The protocol entity then passes the community name and
- user data found in the ASN.1 Message object, along with
- the datagram's source and destination transport addresses
- to the service which implements the desired
- authentication scheme. This entity returns another ASN.1
- object, or signals an authentication failure. In the
- latter case, the protocol entity notes this failure,
- (possibly) generates a trap, and discards the datagram
- and performs no further actions.
-
- (4) The protocol entity then performs a rudimentary parse on
- the ASN.1 object returned from the authentication service
- to build an ASN.1 object corresponding to an ASN.1 PDUs
- object. If the parse fails, it discards the datagram and
- performs no further actions. Otherwise, using the named
- SNMP community, the appropriate profile is selected, and
- the PDU is processed accordingly. If, as a result of
- this processing, a message is returned then the source
- transport address that the response message is sent from
- shall be identical to the destination transport address
- that the original request message was sent to.
-
-
-
-
-
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 18]
-\f
-RFC 1157 SNMP May 1990
-
-
-4.1.1. Common Constructs
-
- Before introducing the six PDU types of the protocol, it is
- appropriate to consider some of the ASN.1 constructs used frequently:
-
- -- request/response information
-
- RequestID ::=
- INTEGER
-
- ErrorStatus ::=
- INTEGER {
- noError(0),
- tooBig(1),
- noSuchName(2),
- badValue(3),
- readOnly(4)
- genErr(5)
- }
-
- ErrorIndex ::=
- INTEGER
-
-
- -- variable bindings
-
- VarBind ::=
- SEQUENCE {
- name
- ObjectName,
-
- value
- ObjectSyntax
- }
-
- VarBindList ::=
- SEQUENCE OF
- VarBind
-
-
- RequestIDs are used to distinguish among outstanding requests. By
- use of the RequestID, an SNMP application entity can correlate
- incoming responses with outstanding requests. In cases where an
- unreliable datagram service is being used, the RequestID also
- provides a simple means of identifying messages duplicated by the
- network.
-
- A non-zero instance of ErrorStatus is used to indicate that an
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 19]
-\f
-RFC 1157 SNMP May 1990
-
-
- exception occurred while processing a request. In these cases,
- ErrorIndex may provide additional information by indicating which
- variable in a list caused the exception.
-
- The term variable refers to an instance of a managed object. A
- variable binding, or VarBind, refers to the pairing of the name of a
- variable to the variable's value. A VarBindList is a simple list of
- variable names and corresponding values. Some PDUs are concerned
- only with the name of a variable and not its value (e.g., the
- GetRequest-PDU). In this case, the value portion of the binding is
- ignored by the protocol entity. However, the value portion must
- still have valid ASN.1 syntax and encoding. It is recommended that
- the ASN.1 value NULL be used for the value portion of such bindings.
-
-4.1.2. The GetRequest-PDU
-
- The form of the GetRequest-PDU is:
- GetRequest-PDU ::=
- [0]
- IMPLICIT SEQUENCE {
- request-id
- RequestID,
-
- error-status -- always 0
- ErrorStatus,
-
- error-index -- always 0
- ErrorIndex,
-
- variable-bindings
- VarBindList
- }
-
-
- The GetRequest-PDU is generated by a protocol entity only at the
- request of its SNMP application entity.
-
- Upon receipt of the GetRequest-PDU, the receiving protocol entity
- responds according to any applicable rule in the list below:
-
- (1) If, for any object named in the variable-bindings field,
- the object's name does not exactly match the name of some
- object available for get operations in the relevant MIB
- view, then the receiving entity sends to the originator
- of the received message the GetResponse-PDU of identical
- form, except that the value of the error-status field is
- noSuchName, and the value of the error-index field is the
- index of said object name component in the received
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 20]
-\f
-RFC 1157 SNMP May 1990
-
-
- message.
-
- (2) If, for any object named in the variable-bindings field,
- the object is an aggregate type (as defined in the SMI),
- then the receiving entity sends to the originator of the
- received message the GetResponse-PDU of identical form,
- except that the value of the error-status field is
- noSuchName, and the value of the error-index field is the
- index of said object name component in the received
- message.
-
- (3) If the size of the GetResponse-PDU generated as described
- below would exceed a local limitation, then the receiving
- entity sends to the originator of the received message
- the GetResponse-PDU of identical form, except that the
- value of the error-status field is tooBig, and the value
- of the error-index field is zero.
-
- (4) If, for any object named in the variable-bindings field,
- the value of the object cannot be retrieved for reasons
- not covered by any of the foregoing rules, then the
- receiving entity sends to the originator of the received
- message the GetResponse-PDU of identical form, except
- that the value of the error-status field is genErr and
- the value of the error-index field is the index of said
- object name component in the received message.
-
- If none of the foregoing rules apply, then the receiving protocol
- entity sends to the originator of the received message the
- GetResponse-PDU such that, for each object named in the variable-
- bindings field of the received message, the corresponding component
- of the GetResponse-PDU represents the name and value of that
- variable. The value of the error- status field of the GetResponse-
- PDU is noError and the value of the error-index field is zero. The
- value of the request-id field of the GetResponse-PDU is that of the
- received message.
-
-4.1.3. The GetNextRequest-PDU
-
- The form of the GetNextRequest-PDU is identical to that of the
- GetRequest-PDU except for the indication of the PDU type. In the
- ASN.1 language:
-
- GetNextRequest-PDU ::=
- [1]
- IMPLICIT SEQUENCE {
- request-id
- RequestID,
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 21]
-\f
-RFC 1157 SNMP May 1990
-
-
- error-status -- always 0
- ErrorStatus,
-
- error-index -- always 0
- ErrorIndex,
-
- variable-bindings
- VarBindList
- }
-
-
- The GetNextRequest-PDU is generated by a protocol entity only at the
- request of its SNMP application entity.
-
- Upon receipt of the GetNextRequest-PDU, the receiving protocol entity
- responds according to any applicable rule in the list below:
-
- (1) If, for any object name in the variable-bindings field,
- that name does not lexicographically precede the name of
- some object available for get operations in the relevant
- MIB view, then the receiving entity sends to the
- originator of the received message the GetResponse-PDU of
- identical form, except that the value of the error-status
- field is noSuchName, and the value of the error-index
- field is the index of said object name component in the
- received message.
-
- (2) If the size of the GetResponse-PDU generated as described
- below would exceed a local limitation, then the receiving
- entity sends to the originator of the received message
- the GetResponse-PDU of identical form, except that the
- value of the error-status field is tooBig, and the value
- of the error-index field is zero.
-
- (3) If, for any object named in the variable-bindings field,
- the value of the lexicographical successor to the named
- object cannot be retrieved for reasons not covered by any
- of the foregoing rules, then the receiving entity sends
- to the originator of the received message the
- GetResponse-PDU of identical form, except that the value
- of the error-status field is genErr and the value of the
- error-index field is the index of said object name
- component in the received message.
-
- If none of the foregoing rules apply, then the receiving protocol
- entity sends to the originator of the received message the
- GetResponse-PDU such that, for each name in the variable-bindings
- field of the received message, the corresponding component of the
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 22]
-\f
-RFC 1157 SNMP May 1990
-
-
- GetResponse-PDU represents the name and value of that object whose
- name is, in the lexicographical ordering of the names of all objects
- available for get operations in the relevant MIB view, together with
- the value of the name field of the given component, the immediate
- successor to that value. The value of the error-status field of the
- GetResponse-PDU is noError and the value of the errorindex field is
- zero. The value of the request-id field of the GetResponse-PDU is
- that of the received message.
-
-4.1.3.1. Example of Table Traversal
-
- One important use of the GetNextRequest-PDU is the traversal of
- conceptual tables of information within the MIB. The semantics of
- this type of SNMP message, together with the protocol-specific
- mechanisms for identifying individual instances of object types in
- the MIB, affords access to related objects in the MIB as if they
- enjoyed a tabular organization.
-
- By the SNMP exchange sketched below, an SNMP application entity might
- extract the destination address and next hop gateway for each entry
- in the routing table of a particular network element. Suppose that
- this routing table has three entries:
-
- Destination NextHop Metric
-
- 10.0.0.99 89.1.1.42 5
- 9.1.2.3 99.0.0.3 3
- 10.0.0.51 89.1.1.42 5
-
-
- The management station sends to the SNMP agent a GetNextRequest-PDU
- containing the indicated OBJECT IDENTIFIER values as the requested
- variable names:
-
- GetNextRequest ( ipRouteDest, ipRouteNextHop, ipRouteMetric1 )
-
-
- The SNMP agent responds with a GetResponse-PDU:
-
- GetResponse (( ipRouteDest.9.1.2.3 = "9.1.2.3" ),
- ( ipRouteNextHop.9.1.2.3 = "99.0.0.3" ),
- ( ipRouteMetric1.9.1.2.3 = 3 ))
-
-
- The management station continues with:
-
- GetNextRequest ( ipRouteDest.9.1.2.3,
- ipRouteNextHop.9.1.2.3,
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 23]
-\f
-RFC 1157 SNMP May 1990
-
-
- ipRouteMetric1.9.1.2.3 )
-
-
- The SNMP agent responds:
-
- GetResponse (( ipRouteDest.10.0.0.51 = "10.0.0.51" ),
- ( ipRouteNextHop.10.0.0.51 = "89.1.1.42" ),
- ( ipRouteMetric1.10.0.0.51 = 5 ))
-
-
- The management station continues with:
-
- GetNextRequest ( ipRouteDest.10.0.0.51,
- ipRouteNextHop.10.0.0.51,
- ipRouteMetric1.10.0.0.51 )
-
-
- The SNMP agent responds:
-
- GetResponse (( ipRouteDest.10.0.0.99 = "10.0.0.99" ),
- ( ipRouteNextHop.10.0.0.99 = "89.1.1.42" ),
- ( ipRouteMetric1.10.0.0.99 = 5 ))
-
-
- The management station continues with:
-
- GetNextRequest ( ipRouteDest.10.0.0.99,
- ipRouteNextHop.10.0.0.99,
- ipRouteMetric1.10.0.0.99 )
-
-
- As there are no further entries in the table, the SNMP agent returns
- those objects that are next in the lexicographical ordering of the
- known object names. This response signals the end of the routing
- table to the management station.
-
-4.1.4. The GetResponse-PDU
-
- The form of the GetResponse-PDU is identical to that of the
- GetRequest-PDU except for the indication of the PDU type. In the
- ASN.1 language:
-
- GetResponse-PDU ::=
- [2]
- IMPLICIT SEQUENCE {
- request-id
- RequestID,
-
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 24]
-\f
-RFC 1157 SNMP May 1990
-
-
- error-status
- ErrorStatus,
-
- error-index
- ErrorIndex,
-
- variable-bindings
- VarBindList
- }
-
-
- The GetResponse-PDU is generated by a protocol entity only upon
- receipt of the GetRequest-PDU, GetNextRequest-PDU, or SetRequest-PDU,
- as described elsewhere in this document.
-
- Upon receipt of the GetResponse-PDU, the receiving protocol entity
- presents its contents to its SNMP application entity.
-
-4.1.5. The SetRequest-PDU
-
- The form of the SetRequest-PDU is identical to that of the
- GetRequest-PDU except for the indication of the PDU type. In the
- ASN.1 language:
-
- SetRequest-PDU ::=
- [3]
- IMPLICIT SEQUENCE {
- request-id
- RequestID,
-
- error-status -- always 0
- ErrorStatus,
-
- error-index -- always 0
- ErrorIndex,
-
- variable-bindings
- VarBindList
- }
-
-
- The SetRequest-PDU is generated by a protocol entity only at the
- request of its SNMP application entity.
-
- Upon receipt of the SetRequest-PDU, the receiving entity responds
- according to any applicable rule in the list below:
-
- (1) If, for any object named in the variable-bindings field,
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 25]
-\f
-RFC 1157 SNMP May 1990
-
-
- the object is not available for set operations in the
- relevant MIB view, then the receiving entity sends to the
- originator of the received message the GetResponse-PDU of
- identical form, except that the value of the error-status
- field is noSuchName, and the value of the error-index
- field is the index of said object name component in the
- received message.
-
- (2) If, for any object named in the variable-bindings field,
- the contents of the value field does not, according to
- the ASN.1 language, manifest a type, length, and value
- that is consistent with that required for the variable,
- then the receiving entity sends to the originator of the
- received message the GetResponse-PDU of identical form,
- except that the value of the error-status field is
- badValue, and the value of the error-index field is the
- index of said object name in the received message.
-
- (3) If the size of the Get Response type message generated as
- described below would exceed a local limitation, then the
- receiving entity sends to the originator of the received
- message the GetResponse-PDU of identical form, except
- that the value of the error-status field is tooBig, and
- the value of the error-index field is zero.
-
- (4) If, for any object named in the variable-bindings field,
- the value of the named object cannot be altered for
- reasons not covered by any of the foregoing rules, then
- the receiving entity sends to the originator of the
- received message the GetResponse-PDU of identical form,
- except that the value of the error-status field is genErr
- and the value of the error-index field is the index of
- said object name component in the received message.
-
- If none of the foregoing rules apply, then for each object named in
- the variable-bindings field of the received message, the
- corresponding value is assigned to the variable. Each variable
- assignment specified by the SetRequest-PDU should be effected as if
- simultaneously set with respect to all other assignments specified in
- the same message.
-
- The receiving entity then sends to the originator of the received
- message the GetResponse-PDU of identical form except that the value
- of the error-status field of the generated message is noError and the
- value of the error-index field is zero.
-
-
-
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 26]
-\f
-RFC 1157 SNMP May 1990
-
-
-4.1.6. The Trap-PDU
-
- The form of the Trap-PDU is:
-
- Trap-PDU ::=
- [4]
-
- IMPLICIT SEQUENCE {
- enterprise -- type of object generating
- -- trap, see sysObjectID in [5]
- OBJECT IDENTIFIER,
-
- agent-addr -- address of object generating
- NetworkAddress, -- trap
-
- generic-trap -- generic trap type
- INTEGER {
- coldStart(0),
- warmStart(1),
- linkDown(2),
- linkUp(3),
- authenticationFailure(4),
- egpNeighborLoss(5),
- enterpriseSpecific(6)
- },
-
- specific-trap -- specific code, present even
- INTEGER, -- if generic-trap is not
- -- enterpriseSpecific
-
- time-stamp -- time elapsed between the last
- TimeTicks, -- (re)initialization of the network
- -- entity and the generation of the
- trap
-
- variable-bindings -- "interesting" information
- VarBindList
- }
-
-
- The Trap-PDU is generated by a protocol entity only at the request of
- the SNMP application entity. The means by which an SNMP application
- entity selects the destination addresses of the SNMP application
- entities is implementation-specific.
-
- Upon receipt of the Trap-PDU, the receiving protocol entity presents
- its contents to its SNMP application entity.
-
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 27]
-\f
-RFC 1157 SNMP May 1990
-
-
- The significance of the variable-bindings component of the Trap-PDU
- is implementation-specific.
-
- Interpretations of the value of the generic-trap field are:
-
-4.1.6.1. The coldStart Trap
-
- A coldStart(0) trap signifies that the sending protocol entity is
- reinitializing itself such that the agent's configuration or the
- protocol entity implementation may be altered.
-
-4.1.6.2. The warmStart Trap
-
- A warmStart(1) trap signifies that the sending protocol entity is
- reinitializing itself such that neither the agent configuration nor
- the protocol entity implementation is altered.
-
-4.1.6.3. The linkDown Trap
-
- A linkDown(2) trap signifies that the sending protocol entity
- recognizes a failure in one of the communication links represented in
- the agent's configuration.
-
- The Trap-PDU of type linkDown contains as the first element of its
- variable-bindings, the name and value of the ifIndex instance for the
- affected interface.
-
-4.1.6.4. The linkUp Trap
-
- A linkUp(3) trap signifies that the sending protocol entity
- recognizes that one of the communication links represented in the
- agent's configuration has come up.
-
- The Trap-PDU of type linkUp contains as the first element of its
- variable-bindings, the name and value of the ifIndex instance for the
- affected interface.
-
-4.1.6.5. The authenticationFailure Trap
-
- An authenticationFailure(4) trap signifies that the sending protocol
- entity is the addressee of a protocol message that is not properly
- authenticated. While implementations of the SNMP must be capable of
- generating this trap, they must also be capable of suppressing the
- emission of such traps via an implementation-specific mechanism.
-
-4.1.6.6. The egpNeighborLoss Trap
-
- An egpNeighborLoss(5) trap signifies that an EGP neighbor for whom
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 28]
-\f
-RFC 1157 SNMP May 1990
-
-
- the sending protocol entity was an EGP peer has been marked down and
- the peer relationship no longer obtains.
-
- The Trap-PDU of type egpNeighborLoss contains as the first element of
- its variable-bindings, the name and value of the egpNeighAddr
- instance for the affected neighbor.
-
-4.1.6.7. The enterpriseSpecific Trap
-
- A enterpriseSpecific(6) trap signifies that the sending protocol
- entity recognizes that some enterprise-specific event has occurred.
- The specific-trap field identifies the particular trap which
- occurred.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 29]
-\f
-RFC 1157 SNMP May 1990
-
-
-5. Definitions
-
- RFC1157-SNMP DEFINITIONS ::= BEGIN
-
- IMPORTS
- ObjectName, ObjectSyntax, NetworkAddress, IpAddress, TimeTicks
- FROM RFC1155-SMI;
-
-
- -- top-level message
-
- Message ::=
- SEQUENCE {
- version -- version-1 for this RFC
- INTEGER {
- version-1(0)
- },
-
- community -- community name
- OCTET STRING,
-
- data -- e.g., PDUs if trivial
- ANY -- authentication is being used
- }
-
-
- -- protocol data units
-
- PDUs ::=
- CHOICE {
- get-request
- GetRequest-PDU,
-
- get-next-request
- GetNextRequest-PDU,
-
- get-response
- GetResponse-PDU,
-
- set-request
- SetRequest-PDU,
-
- trap
- Trap-PDU
- }
-
-
-
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 30]
-\f
-RFC 1157 SNMP May 1990
-
-
- -- PDUs
-
- GetRequest-PDU ::=
- [0]
- IMPLICIT PDU
-
- GetNextRequest-PDU ::=
- [1]
- IMPLICIT PDU
-
- GetResponse-PDU ::=
- [2]
- IMPLICIT PDU
-
- SetRequest-PDU ::=
- [3]
- IMPLICIT PDU
-
- PDU ::=
- SEQUENCE {
- request-id
- INTEGER,
-
- error-status -- sometimes ignored
- INTEGER {
- noError(0),
- tooBig(1),
- noSuchName(2),
- badValue(3),
- readOnly(4),
- genErr(5)
- },
-
- error-index -- sometimes ignored
- INTEGER,
-
- variable-bindings -- values are sometimes ignored
- VarBindList
- }
-
- Trap-PDU ::=
- [4]
- IMPLICIT SEQUENCE {
- enterprise -- type of object generating
- -- trap, see sysObjectID in [5]
-
-
- OBJECT IDENTIFIER,
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 31]
-\f
-RFC 1157 SNMP May 1990
-
-
- agent-addr -- address of object generating
- NetworkAddress, -- trap
-
- generic-trap -- generic trap type
- INTEGER {
- coldStart(0),
- warmStart(1),
- linkDown(2),
- linkUp(3),
- authenticationFailure(4),
- egpNeighborLoss(5),
- enterpriseSpecific(6)
- },
-
- specific-trap -- specific code, present even
- INTEGER, -- if generic-trap is not
- -- enterpriseSpecific
-
- time-stamp -- time elapsed between the last
- TimeTicks, -- (re)initialization of the
- network
- -- entity and the generation of the
- trap
-
- variable-bindings -- "interesting" information
- VarBindList
- }
-
-
- -- variable bindings
-
- VarBind ::=
- SEQUENCE {
- name
- ObjectName,
-
- value
- ObjectSyntax
- }
-
- VarBindList ::=
- SEQUENCE OF
- VarBind
-
- END
-
-
-
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 32]
-\f
-RFC 1157 SNMP May 1990
-
-
-6. Acknowledgements
-
- This memo was influenced by the IETF SNMP Extensions working
- group:
-
- Karl Auerbach, Epilogue Technology
- K. Ramesh Babu, Excelan
- Amatzia Ben-Artzi, 3Com/Bridge
- Lawrence Besaw, Hewlett-Packard
- Jeffrey D. Case, University of Tennessee at Knoxville
- Anthony Chung, Sytek
- James Davidson, The Wollongong Group
- James R. Davin, MIT Laboratory for Computer Science
- Mark S. Fedor, NYSERNet
- Phill Gross, The MITRE Corporation
- Satish Joshi, ACC
- Dan Lynch, Advanced Computing Environments
- Keith McCloghrie, The Wollongong Group
- Marshall T. Rose, The Wollongong Group (chair)
- Greg Satz, cisco
- Martin Lee Schoffstall, Rensselaer Polytechnic Institute
- Wengyik Yeong, NYSERNet
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 33]
-\f
-RFC 1157 SNMP May 1990
-
-
-7. References
-
- [1] Cerf, V., "IAB Recommendations for the Development of
- Internet Network Management Standards", RFC 1052, IAB,
- April 1988.
-
- [2] Rose, M., and K. McCloghrie, "Structure and Identification
- of Management Information for TCP/IP-based internets",
- RFC 1065, TWG, August 1988.
-
- [3] McCloghrie, K., and M. Rose, "Management Information Base
- for Network Management of TCP/IP-based internets",
- RFC 1066, TWG, August 1988.
-
- [4] Cerf, V., "Report of the Second Ad Hoc Network Management
- Review Group", RFC 1109, IAB, August 1989.
-
- [5] Rose, M., and K. McCloghrie, "Structure and Identification
- of Management Information for TCP/IP-based Internets",
- RFC 1155, Performance Systems International and Hughes LAN
- Systems, May 1990.
-
- [6] McCloghrie, K., and M. Rose, "Management Information Base
- for Network Management of TCP/IP-based Internets",
- RFC 1156, Hughes LAN Systems and Performance Systems
- International, May 1990.
-
- [7] Case, J., M. Fedor, M. Schoffstall, and J. Davin,
- "A Simple Network Management Protocol", Internet
- Engineering Task Force working note, Network Information
- Center, SRI International, Menlo Park, California,
- March 1988.
-
- [8] Davin, J., J. Case, M. Fedor, and M. Schoffstall,
- "A Simple Gateway Monitoring Protocol", RFC 1028,
- Proteon, University of Tennessee at Knoxville,
- Cornell University, and Rensselaer Polytechnic
- Institute, November 1987.
-
- [9] Information processing systems - Open Systems
- Interconnection, "Specification of Abstract Syntax
- Notation One (ASN.1)", International Organization for
- Standardization, International Standard 8824,
- December 1987.
-
- [10] Information processing systems - Open Systems
- Interconnection, "Specification of Basic Encoding Rules
- for Abstract Notation One (ASN.1)", International
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 34]
-\f
-RFC 1157 SNMP May 1990
-
-
- Organization for Standardization, International Standard
- 8825, December 1987.
-
- [11] Postel, J., "User Datagram Protocol", RFC 768,
- USC/Information Sciences Institute, November 1980.
-
-Security Considerations
-
- Security issues are not discussed in this memo.
-
-Authors' Addresses
-
- Jeffrey D. Case
- SNMP Research
- P.O. Box 8593
- Knoxville, TN 37996-4800
-
- Phone: (615) 573-1434
-
- Email: case@CS.UTK.EDU
-
-
- Mark Fedor
- Performance Systems International
- Rensselaer Technology Park
- 125 Jordan Road
- Troy, NY 12180
-
- Phone: (518) 283-8860
-
- Email: fedor@patton.NYSER.NET
-
-
- Martin Lee Schoffstall
- Performance Systems International
- Rensselaer Technology Park
- 165 Jordan Road
- Troy, NY 12180
-
- Phone: (518) 283-8860
-
- Email: schoff@NISC.NYSER.NET
-
-
-
-
-
-
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 35]
-\f
-RFC 1157 SNMP May 1990
-
-
- James R. Davin
- MIT Laboratory for Computer Science, NE43-507
- 545 Technology Square
- Cambridge, MA 02139
-
- Phone: (617) 253-6020
-
- EMail: jrd@ptt.lcs.mit.edu
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Case, Fedor, Schoffstall, & Davin [Page 36]
-\f
\ No newline at end of file
+++ /dev/null
-
-
-
-
-
-
-Network Printing Working Group L. McLaughlin III, Editor
-Request for Comments: 1179 The Wollongong Group
- August 1990
-
-
- Line Printer Daemon Protocol
-
-Status of this Memo
-
- This RFC describes an existing print server protocol widely used on
- the Internet for communicating between line printer daemons (both
- clients and servers). This memo is for informational purposes only,
- and does not specify an Internet standard. Please refer to the
- current edition of the "IAB Official Protocol Standards" for the
- standardization state and status of this protocol. Distribution of
- this memo is unlimited.
-
-1. Introduction
-
- The Berkeley versions of the Unix(tm) operating system provide line
- printer spooling with a collection of programs: lpr (assign to
- queue), lpq (display the queue), lprm (remove from queue), and lpc
- (control the queue). These programs interact with an autonomous
- process called the line printer daemon. This RFC describes the
- protocols with which a line printer daemon client may control
- printing.
-
- This memo is based almost entirely on the work of Robert Knight at
- Princeton University. I gratefully acknowledge his efforts in
- deciphering the UNIX lpr protocol and producing earlier versions of
- this document.
-
-2. Model of Printing Environment
-
- A group of hosts request services from a line printer daemon process
- running on a host. The services provided by the process are related
- to printing jobs. A printing job produces output from one file.
- Each job will have a unique job number which is between 0 and 999,
- inclusive. The jobs are requested by users which have names. These
- user names may not start with a digit.
-
-3. Specification of the Protocol
-
- The specification includes file formats for the control and data
- files as well as messages used by the protocol.
-
-
-
-
-
-
-McLaughlin [Page 1]
-\f
-RFC 1179 LPR August 1990
-
-
-3.1 Message formats
-
- LPR is a a TCP-based protocol. The port on which a line printer
- daemon listens is 515. The source port must be in the range 721 to
- 731, inclusive. A line printer daemon responds to commands send to
- its port. All commands begin with a single octet code, which is a
- binary number which represents the requested function. The code is
- immediately followed by the ASCII name of the printer queue name on
- which the function is to be performed. If there are other operands
- to the command, they are separated from the printer queue name with
- white space (ASCII space, horizontal tab, vertical tab, and form
- feed). The end of the command is indicated with an ASCII line feed
- character.
-
-4. Diagram Conventions
-
- The diagrams in the rest of this RFC use these conventions. These
- diagrams show the format of an octet stream sent to the server. The
- outermost box represents this stream. Each box within the outermost
- one shows one portion of the stream. If the contents of the box is
- two decimal digits, this indicates that the binary 8 bit value is to
- be used. If the contents is two uppercase letters, this indicates
- that the corresponding ASCII control character is to be used. An
- exception to this is that the character SP can be interpreted as
- white space. (See the preceding section for a definition.) If the
- contents is a single letter, the ASCII code for this letter must be
- sent. Otherwise, the contents are intended to be mnemonic of the
- contents of the field which is a sequence of octets.
-
-5. Daemon commands
-
- The verbs in the command names should be interpreted as statements
- made to the daemon. Thus, the command "Print any waiting jobs" is an
- imperative to the line printer daemon to which it is sent. A new
- connection must be made for each command to be given to the daemon.
-
-5.1 01 - Print any waiting jobs
-
- +----+-------+----+
- | 01 | Queue | LF |
- +----+-------+----+
- Command code - 1
- Operand - Printer queue name
-
- This command starts the printing process if it not already running.
-
-
-
-
-
-
-McLaughlin [Page 2]
-\f
-RFC 1179 LPR August 1990
-
-
-5.2 02 - Receive a printer job
-
- +----+-------+----+
- | 02 | Queue | LF |
- +----+-------+----+
- Command code - 2
- Operand - Printer queue name
-
- Receiving a job is controlled by a second level of commands. The
- daemon is given commands by sending them over the same connection.
- The commands are described in the next section (6).
-
- After this command is sent, the client must read an acknowledgement
- octet from the daemon. A positive acknowledgement is an octet of
- zero bits. A negative acknowledgement is an octet of any other
- pattern.
-
-5.3 03 - Send queue state (short)
-
- +----+-------+----+------+----+
- | 03 | Queue | SP | List | LF |
- +----+-------+----+------+----+
- Command code - 3
- Operand 1 - Printer queue name
- Other operands - User names or job numbers
-
- If the user names or job numbers or both are supplied then only those
- jobs for those users or with those numbers will be sent.
-
- The response is an ASCII stream which describes the printer queue.
- The stream continues until the connection closes. Ends of lines are
- indicated with ASCII LF control characters. The lines may also
- contain ASCII HT control characters.
-
-5.4 04 - Send queue state (long)
-
- +----+-------+----+------+----+
- | 04 | Queue | SP | List | LF |
- +----+-------+----+------+----+
- Command code - 4
- Operand 1 - Printer queue name
- Other operands - User names or job numbers
-
- If the user names or job numbers or both are supplied then only those
- jobs for those users or with those numbers will be sent.
-
- The response is an ASCII stream which describes the printer queue.
- The stream continues until the connection closes. Ends of lines are
-
-
-
-McLaughlin [Page 3]
-\f
-RFC 1179 LPR August 1990
-
-
- indicated with ASCII LF control characters. The lines may also
- contain ASCII HT control characters.
-
-5.5 05 - Remove jobs
-
- +----+-------+----+-------+----+------+----+
- | 05 | Queue | SP | Agent | SP | List | LF |
- +----+-------+----+-------+----+------+----+
- Command code - 5
- Operand 1 - Printer queue name
- Operand 2 - User name making request (the agent)
- Other operands - User names or job numbers
-
- This command deletes the print jobs from the specified queue which
- are listed as the other operands. If only the agent is given, the
- command is to delete the currently active job. Unless the agent is
- "root", it is not possible to delete a job which is not owned by the
- user. This is also the case for specifying user names instead of
- numbers. That is, agent "root" can delete jobs by user name but no
- other agents can.
-
-6. Receive job subcommands
-
- These commands are processed when the line printer daemon has
- been given the receive job command. The daemon will continue to
- process commands until the connection is closed.
-
- After a subcommand is sent, the client must wait for an
- acknowledgement from the daemon. A positive acknowledgement is an
- octet of zero bits. A negative acknowledgement is an octet of any
- other pattern.
-
- LPR clients SHOULD be able to sent the receive data file and receive
- control file subcommands in either order. LPR servers MUST be able
- to receive the control file subcommand first and SHOULD be able to
- receive the data file subcommand first.
-
-6.1 01 - Abort job
-
- Command code - 1
- +----+----+
- | 01 | LF |
- +----+----+
-
- No operands should be supplied. This subcommand will remove any
- files which have been created during this "Receive job" command.
-
-
-
-
-
-McLaughlin [Page 4]
-\f
-RFC 1179 LPR August 1990
-
-
-6.2 02 - Receive control file
-
- +----+-------+----+------+----+
- | 02 | Count | SP | Name | LF |
- +----+-------+----+------+----+
- Command code - 2
- Operand 1 - Number of bytes in control file
- Operand 2 - Name of control file
-
- The control file must be an ASCII stream with the ends of lines
- indicated by ASCII LF. The total number of bytes in the stream is
- sent as the first operand. The name of the control file is sent as
- the second. It should start with ASCII "cfA", followed by a three
- digit job number, followed by the host name which has constructed the
- control file. Acknowledgement processing must occur as usual after
- the command is sent.
-
- The next "Operand 1" octets over the same TCP connection are the
- intended contents of the control file. Once all of the contents have
- been delivered, an octet of zero bits is sent as an indication that
- the file being sent is complete. A second level of acknowledgement
- processing must occur at this point.
-
-6.3 03 - Receive data file
-
- +----+-------+----+------+----+
- | 03 | Count | SP | Name | LF |
- +----+-------+----+------+----+
- Command code - 3
- Operand 1 - Number of bytes in data file
- Operand 2 - Name of data file
-
- The data file may contain any 8 bit values at all. The total number
- of bytes in the stream may be sent as the first operand, otherwise
- the field should be cleared to 0. The name of the data file should
- start with ASCII "dfA". This should be followed by a three digit job
- number. The job number should be followed by the host name which has
- constructed the data file. Interpretation of the contents of the
- data file is determined by the contents of the corresponding control
- file. If a data file length has been specified, the next "Operand 1"
- octets over the same TCP connection are the intended contents of the
- data file. In this case, once all of the contents have been
- delivered, an octet of zero bits is sent as an indication that the
- file being sent is complete. A second level of acknowledgement
- processing must occur at this point.
-
-
-
-
-
-
-McLaughlin [Page 5]
-\f
-RFC 1179 LPR August 1990
-
-
-7. Control file lines
-
- This section discusses the format of the lines in the control file
- which is sent to the line printer daemon.
-
- Each line of the control file consists of a single, printable ASCII
- character which represents a function to be performed when the file
- is printed. Interpretation of these command characters are case-
- sensitive. The rest of the line after the command character is the
- command's operand. No leading white space is permitted after the
- command character. The line ends with an ASCII new line.
-
- Those commands which have a lower case letter as a command code are
- used to specify an actual printing request. The commands which use
- upper case are used to describe parametric values or background
- conditions.
-
- Some commands must be included in every control file. These are 'H'
- (responsible host) and 'P' (responsible user). Additionally, there
- must be at least one lower case command to produce any output.
-
-7.1 C - Class for banner page
-
- +---+-------+----+
- | C | Class | LF |
- +---+-------+----+
- Command code - 'C'
- Operand - Name of class for banner pages
-
- This command sets the class name to be printed on the banner page.
- The name must be 31 or fewer octets. The name can be omitted. If it
- is, the name of the host on which the file is printed will be used.
- The class is conventionally used to display the host from which the
- printing job originated. It will be ignored unless the print banner
- command ('L') is also used.
-
-7.2 H - Host name
-
- +---+------+----+
- | H | Host | LF |
- +---+------+----+
- Command code - 'H'
- Operand - Name of host
-
- This command specifies the name of the host which is to be treated as
- the source of the print job. The command must be included in the
- control file. The name of the host must be 31 or fewer octets.
-
-
-
-
-McLaughlin [Page 6]
-\f
-RFC 1179 LPR August 1990
-
-
-7.3 I - Indent Printing
-
- +---+-------+----+
- | I | count | LF |
- +---+-------+----+
- Command code - 'I'
- Operand - Indenting count
-
- This command specifies that, for files which are printed with the
- 'f', of columns given. (It is ignored for other output generating
- commands.) The identing count operand must be all decimal digits.
-
-7.4 J - Job name for banner page
-
- +---+----------+----+
- | J | Job name | LF |
- +---+----------+----+
- Command code - 'J'
- Operand - Job name
-
- This command sets the job name to be printed on the banner page. The
- name of the job must be 99 or fewer octets. It can be omitted. The
- job name is conventionally used to display the name of the file or
- files which were "printed". It will be ignored unless the print
- banner command ('L') is also used.
-
-7.5 L - Print banner page
-
- +---+------+----+
- | L | User | LF |
- +---+------+----+
- Command code - 'L'
- Operand - Name of user for burst pages
-
- This command causes the banner page to be printed. The user name can
- be omitted. The class name for banner page and job name for banner
- page commands must precede this command in the control file to be
- effective.
-
-7.6 M - Mail When Printed
-
- +---+------+----+
- | M | user | LF |
- +---+------+----+
- Command code - 'M'
- Operand - User name
-
- This entry causes mail to be sent to the user given as the operand at
-
-
-
-McLaughlin [Page 7]
-\f
-RFC 1179 LPR August 1990
-
-
- the host specified by the 'H' entry when the printing operation ends
- (successfully or unsuccessfully).
-
-7.7 N - Name of source file
-
- +---+------+----+
- | N | Name | LF |
- +---+------+----+
- Command code - 'N'
- Operand - File name
-
- This command specifies the name of the file from which the data file
- was constructed. It is returned on a query and used in printing with
- the 'p' command when no title has been given. It must be 131 or
- fewer octets.
-
-7.8 P - User identification
-
- +---+------+----+
- | P | Name | LF |
- +---+------+----+
- Command code - 'P'
- Operand - User id
-
- This command specifies the user identification of the entity
- requesting the printing job. This command must be included in the
- control file. The user identification must be 31 or fewer octets.
-
-7.9 S - Symbolic link data
-
- +---+--------+----+-------+----+
- | S | device | SP | inode | LF |
- +---+--------+----+-------+----+
- Command code - 'S'
- Operand 1 - Device number
- Operand 2 - Inode number
-
- This command is used to record symbolic link data on a Unix system so
- that changing a file's directory entry after a file is printed will
- not print the new file. It is ignored if the data file is not
- symbolically linked.
-
-
-
-
-
-
-
-
-
-
-McLaughlin [Page 8]
-\f
-RFC 1179 LPR August 1990
-
-
-7.10 T - Title for pr
-
- +---+-------+----+
- | T | title | LF |
- +---+-------+----+
- Command code - 'T'
- Operand - Title text
-
- This command provides a title for a file which is to be printed with
- either the 'p' command. (It is ignored by all of the other printing
- commands.) The title must be 79 or fewer octets.
-
-7.11 U - Unlink data file
-
- +---+------+----+
- | U | file | LF |
- +---+------+----+
- Command code - 'U'
- Operand - File to unlink
-
- This command indicates that the specified file is no longer needed.
- This should only be used for data files.
-
-7.12 W - Width of output
-
- +---+-------+----+
- | W | width | LF |
- +---+-------+----+
- Command code - 'W'
- Operand - Width count
-
- This command limits the output to the specified number of columns for
- the 'f', 'l', and 'p' commands. (It is ignored for other output
- generating commands.) The width count operand must be all decimal
- digits. It may be silently reduced to some lower value. The default
- value for the width is 132.
-
-7.13 1 - troff R font
-
- +---+------+----+
- | 1 | file | LF |
- +---+------+----+
- Command code - '1'
- Operand - File name
-
- This command specifies the file name for the troff R font. [1] This
- is the font which is printed using Times Roman by default.
-
-
-
-
-McLaughlin [Page 9]
-\f
-RFC 1179 LPR August 1990
-
-
-7.14 2 - troff I font
-
- +---+------+----+
- | 2 | file | LF |
- +---+------+----+
- Command code - '2'
- Operand - File name
-
- This command specifies the file name for the troff I font. [1] This
- is the font which is printed using Times Italic by default.
-
-7.15 3 - troff B font
-
- +---+------+----+
- | 3 | file | LF |
- +---+------+----+
- Command code - '3'
- Operand - File name
-
- This command specifies the file name for the troff B font. [1] This
- is the font which is printed using Times Bold by default.
-
-7.16 4 - troff S font
-
- +---+------+----+
- | 4 | file | LF |
- +---+------+----+
- Command code - '4'
- Operand - File name
-
- This command specifies the file name for the troff S font. [1] This
- is the font which is printed using Special Mathematical Font by
- default.
-
-7.17 c - Plot CIF file
-
- +---+------+----+
- | c | file | LF |
- +---+------+----+
- Command code - 'c'
- Operand - File to plot
-
- This command causes the data file to be plotted, treating the data as
- CIF (CalTech Intermediate Form) graphics language. [2]
-
-
-
-
-
-
-
-McLaughlin [Page 10]
-\f
-RFC 1179 LPR August 1990
-
-
-7.18 d - Print DVI file
-
- +---+------+----+
- | d | file | LF |
- +---+------+----+
- Command code - 'd'
- Operand - File to print
-
- This command causes the data file to be printed, treating the data as
- DVI (TeX output). [3]
-
-7.19 f - Print formatted file
-
- +---+------+----+
- | f | file | LF |
- +---+------+----+
- Command code - 'f'
- Operand - File to print
-
- This command cause the data file to be printed as a plain text file,
- providing page breaks as necessary. Any ASCII control characters
- which are not in the following list are discarded: HT, CR, FF, LF,
- and BS.
-
-7.20 g - Plot file
-
- +---+------+----+
- | g | file | LF |
- +---+------+----+
- Command code - 'g'
- Operand - File to plot
-
- This command causes the data file to be plotted, treating the data as
- output from the Berkeley Unix plot library. [1]
-
-7.21 k - Reserved for use by Kerberized LPR clients and servers.
-
-7.22 l - Print file leaving control characters
-
- +---+------+----+
- | l | file | LF |
- +---+------+----+
- Command code - 'l' (lower case L)
- Operand - File to print
-
- This command causes the specified data file to printed without
- filtering the control characters (as is done with the 'f' command).
-
-
-
-
-McLaughlin [Page 11]
-\f
-RFC 1179 LPR August 1990
-
-
-7.23 n - Print ditroff output file
-
- +---+------+----+
- | n | file | LF |
- +---+------+----+
- Command code - 'n'
- Operand - File to print
-
- This command prints the data file to be printed, treating the data as
- ditroff output. [4]
-
-7.24 o - Print Postscript output file
-
- +---+------+----+
- | o | file | LF |
- +---+------+----+
- Command code - 'o'
- Operand - File to print
-
- This command prints the data file to be printed, treating the data as
- standard Postscript input.
-
-7.25 p - Print file with 'pr' format
-
- +---+------+----+
- | p | file | LF |
- +---+------+----+
- Command code - 'p'
- Operand - File to print
-
- This command causes the data file to be printed with a heading, page
- numbers, and pagination. The heading should include the date and
- time that printing was started, the title, and a page number
- identifier followed by the page number. The title is the name of
- file as specified by the 'N' command, unless the 'T' command (title)
- has been given. After a page of text has been printed, a new page is
- started with a new page number. (There is no way to specify the
- length of the page.)
-
-7.26 r - File to print with FORTRAN carriage control
-
- +---+------+----+
- | r | file | LF |
- +---+------+----+
- Command code - 'r'
- Operand - File to print
-
- This command causes the data file to be printed, interpreting the
-
-
-
-McLaughlin [Page 12]
-\f
-RFC 1179 LPR August 1990
-
-
- first column of each line as FORTRAN carriage control. The FORTRAN
- standard limits this to blank, "1", "0", and "+" carriage controls.
- Most FORTRAN programmers also expect "-" (triple space) to work as
- well.
-
-7.27 t - Print troff output file
-
- +---+------+----+
- | t | file | LF |
- +---+------+----+
- Command code - 't'
- Operand - File to print
-
- This command prints the data file as Graphic Systems C/A/T
- phototypesetter input. [5] This is the standard output of the Unix
- "troff" command.
-
-7.28 v - Print raster file
-
- +---+------+----+
- | v | file | LF |
- +---+------+----+
- Command code - 'v'
- Operand - File to print
-
- This command prints a Sun raster format file. [6]
-
-7.29 z - Reserved for future use with the Palladium print system.
-
-REFERENCES and BIBLIOGRAPHY
-
- [1] Computer Science Research Group, "UNIX Programmer's Reference
- Manual", USENIX, 1986.
-
- [2] Hon and Sequin, "A Guide to LSI Implementation", XEROX PARC,
- 1980.
-
- [3] Knuth, D., "TeX The Program".
-
- [4] Kernighan, B., "A Typesetter-independent TROFF".
-
- [5] "Model C/A/T Phototypesetter", Graphic Systems, Inc. Hudson, N.H.
-
- [6] Sun Microsystems, "Pixrect Reference Manual", Sun Microsystems,
- Mountain View, CA, 1988.
-
-
-
-
-
-
-McLaughlin [Page 13]
-\f
-RFC 1179 LPR August 1990
-
-
-Security Considerations
-
- Security issues are not discussed in this memo.
-
-Author's Address
-
- Leo J. McLaughlin III
- The Wollongong Group
- 1129 San Antonio Road
- Palo Alto, CA 94303
-
- Phone: 415-962-7100
-
- EMail: ljm@twg.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-McLaughlin [Page 14]
-\f
\ No newline at end of file
+++ /dev/null
-
-
-
-
-
-
-Network Working Group K. McCloghrie
-Request for Comments: 1213 Hughes LAN Systems, Inc.
-Obsoletes: RFC 1158 M. Rose
- Performance Systems International
- Editors
- March 1991
-
-
- Management Information Base for Network Management
- of TCP/IP-based internets:
- MIB-II
-
-Status of this Memo
-
- This memo defines the second version of the Management Information
- Base (MIB-II) for use with network management protocols in TCP/IP-
- based internets. This RFC specifies an IAB standards track protocol
- for the Internet community, and requests discussion and suggestions
- for improvements. Please refer to the current edition of the "IAB
- Official Protocol Standards" for the standardization state and status
- of this protocol. Distribution of this memo is unlimited.
-
-Table of Contents
-
- 1. Abstract............................................... 2
- 2. Introduction .......................................... 2
- 3. Changes from RFC 1156 ................................. 3
- 3.1 Deprecated Objects ................................... 3
- 3.2 Display Strings ...................................... 4
- 3.3 Physical Addresses ................................... 4
- 3.4 The System Group ..................................... 5
- 3.5 The Interfaces Group ................................. 5
- 3.6 The Address Translation Group ........................ 6
- 3.7 The IP Group ......................................... 6
- 3.8 The ICMP Group ....................................... 7
- 3.9 The TCP Group ........................................ 7
- 3.10 The UDP Group ....................................... 7
- 3.11 The EGP Group ....................................... 7
- 3.12 The Transmission Group .............................. 8
- 3.13 The SNMP Group ...................................... 8
- 3.14 Changes from RFC 1158 ................. ............. 9
- 4. Objects ............................................... 10
- 4.1 Format of Definitions ................................ 10
- 5. Overview .............................................. 10
- 6. Definitions ........................................... 12
- 6.1 Textual Conventions .................................. 12
- 6.2 Groups in MIB-II ..................................... 13
- 6.3 The System Group ..................................... 13
-
-
-
-SNMP Working Group [Page 1]
-\f
-RFC 1213 MIB-II March 1991
-
-
- 6.4 The Interfaces Group ................................. 16
- 6.5 The Address Translation Group ........................ 23
- 6.6 The IP Group ......................................... 26
- 6.7 The ICMP Group ....................................... 41
- 6.8 The TCP Group ........................................ 46
- 6.9 The UDP Group ........................................ 52
- 6.10 The EGP Group ....................................... 54
- 6.11 The Transmission Group .............................. 60
- 6.12 The SNMP Group ...................................... 60
- 7. Acknowledgements ...................................... 67
- 8. References ............................................ 69
- 9. Security Considerations ............................... 70
- 10. Authors' Addresses ................................... 70
-
-1. Abstract
-
- This memo defines the second version of the Management Information
- Base (MIB-II) for use with network management protocols in TCP/IP-
- based internets. In particular, together with its companion memos
- which describe the structure of management information (RFC 1155)
- along with the network management protocol (RFC 1157) for TCP/IP-
- based internets, these documents provide a simple, workable
- architecture and system for managing TCP/IP-based internets and in
- particular the Internet community.
-
-2. Introduction
-
- As reported in RFC 1052, IAB Recommendations for the Development of
- Internet Network Management Standards [1], a two-prong strategy for
- network management of TCP/IP-based internets was undertaken. In the
- short-term, the Simple Network Management Protocol (SNMP) was to be
- used to manage nodes in the Internet community. In the long-term,
- the use of the OSI network management framework was to be examined.
- Two documents were produced to define the management information: RFC
- 1065, which defined the Structure of Management Information (SMI)
- [2], and RFC 1066, which defined the Management Information Base
- (MIB) [3]. Both of these documents were designed so as to be
- compatible with both the SNMP and the OSI network management
- framework.
-
- This strategy was quite successful in the short-term: Internet-based
- network management technology was fielded, by both the research and
- commercial communities, within a few months. As a result of this,
- portions of the Internet community became network manageable in a
- timely fashion.
-
- As reported in RFC 1109, Report of the Second Ad Hoc Network
- Management Review Group [4], the requirements of the SNMP and the OSI
-
-
-
-SNMP Working Group [Page 2]
-\f
-RFC 1213 MIB-II March 1991
-
-
- network management frameworks were more different than anticipated.
- As such, the requirement for compatibility between the SMI/MIB and
- both frameworks was suspended. This action permitted the operational
- network management framework, the SNMP, to respond to new operational
- needs in the Internet community by producing this document.
-
- As such, the current network management framework for TCP/IP- based
- internets consists of: Structure and Identification of Management
- Information for TCP/IP-based internets, RFC 1155 [12], which
- describes how managed objects contained in the MIB are defined;
- Management Information Base for Network Management of TCP/IP-based
- internets: MIB-II, this memo, which describes the managed objects
- contained in the MIB (and supercedes RFC 1156 [13]); and, the Simple
- Network Management Protocol, RFC 1098 [5], which defines the protocol
- used to manage these objects.
-
-3. Changes from RFC 1156
-
- Features of this MIB include:
-
- (1) incremental additions to reflect new operational
- requirements;
-
- (2) upwards compatibility with the SMI/MIB and the SNMP;
-
- (3) improved support for multi-protocol entities; and,
-
- (4) textual clean-up of the MIB to improve clarity and
- readability.
-
- The objects defined in MIB-II have the OBJECT IDENTIFIER prefix:
-
- mib-2 OBJECT IDENTIFIER ::= { mgmt 1 }
-
- which is identical to the prefix used in MIB-I.
-
-3.1. Deprecated Objects
-
- In order to better prepare implementors for future changes in the
- MIB, a new term "deprecated" may be used when describing an object.
- A deprecated object in the MIB is one which must be supported, but
- one which will most likely be removed from the next version of the
- MIB (e.g., MIB-III).
-
- MIB-II marks one object as being deprecated:
-
- atTable
-
-
-
-
-SNMP Working Group [Page 3]
-\f
-RFC 1213 MIB-II March 1991
-
-
- As a result of deprecating the atTable object, the entire Address
- Translation group is deprecated.
-
- Note that no functionality is lost with the deprecation of these
- objects: new objects providing equivalent or superior functionality
- are defined in MIB-II.
-
-3.2. Display Strings
-
- In the past, there have been misinterpretations of the MIB as to when
- a string of octets should contain printable characters, meant to be
- displayed to a human. As a textual convention in the MIB, the
- datatype
-
- DisplayString ::=
- OCTET STRING
-
- is introduced. A DisplayString is restricted to the NVT ASCII
- character set, as defined in pages 10-11 of [6].
-
- The following objects are now defined in terms of DisplayString:
-
- sysDescr
- ifDescr
-
- It should be noted that this change has no effect on either the
- syntax nor semantics of these objects. The use of the DisplayString
- notation is merely an artifact of the explanatory method used in
- MIB-II and future MIBs.
-
- Further it should be noted that any object defined in terms of OCTET
- STRING may contain arbitrary binary data, in which each octet may
- take any value from 0 to 255 (decimal).
-
-3.3. Physical Addresses
-
- As a further, textual convention in the MIB, the datatype
-
- PhysAddress ::=
- OCTET STRING
-
- is introduced to represent media- or physical-level addresses.
-
- The following objects are now defined in terms of PhysAddress:
-
- ifPhysAddress
- atPhysAddress
- ipNetToMediaPhysAddress
-
-
-
-SNMP Working Group [Page 4]
-\f
-RFC 1213 MIB-II March 1991
-
-
- It should be noted that this change has no effect on either the
- syntax nor semantics of these objects. The use of the PhysAddress
- notation is merely an artifact of the explanatory method used in
- MIB-II and future MIBs.
-
-3.4. The System Group
-
- Four new objects are added to this group:
-
- sysContact
- sysName
- sysLocation
- sysServices
-
- These provide contact, administrative, location, and service
- information regarding the managed node.
-
-3.5. The Interfaces Group
-
- The definition of the ifNumber object was incorrect, as it required
- all interfaces to support IP. (For example, devices without IP, such
- as MAC-layer bridges, could not be managed if this definition was
- strictly followed.) The description of the ifNumber object is
- changed accordingly.
-
- The ifTable object was mistaken marked as read-write, it has been
- (correctly) re-designated as not-accessible. In addition, several
- new values have been added to the ifType column in the ifTable
- object:
-
- ppp(23)
- softwareLoopback(24)
- eon(25)
- ethernet-3Mbit(26)
- nsip(27)
- slip(28)
- ultra(29)
- ds3(30)
- sip(31)
- frame-relay(32)
-
- Finally, a new column has been added to the ifTable object:
-
- ifSpecific
-
- which provides information about information specific to the media
- being used to realize the interface.
-
-
-
-
-SNMP Working Group [Page 5]
-\f
-RFC 1213 MIB-II March 1991
-
-
-3.6. The Address Translation Group
-
- In MIB-I this group contained a table which permitted mappings from
- network addresses (e.g., IP addresses) to physical addresses (e.g.,
- MAC addresses). Experience has shown that efficient implementations
- of this table make two assumptions: a single network protocol
- environment, and mappings occur only from network address to physical
- address.
-
- The need to support multi-protocol nodes (e.g., those with both the
- IP and CLNP active), and the need to support the inverse mapping
- (e.g., for ES-IS), have invalidated both of these assumptions. As
- such, the atTable object is declared deprecated.
-
- In order to meet both the multi-protocol and inverse mapping
- requirements, MIB-II and its successors will allocate up to two
- address translation tables inside each network protocol group. That
- is, the IP group will contain one address translation table, for
- going from IP addresses to physical addresses. Similarly, when a
- document defining MIB objects for the CLNP is produced (e.g., [7]),
- it will contain two tables, for mappings in both directions, as this
- is required for full functionality.
-
- It should be noted that the choice of two tables (one for each
- direction of mapping) provides for ease of implementation in many
- cases, and does not introduce undue burden on implementations which
- realize the address translation abstraction through a single internal
- table.
-
-3.7. The IP Group
-
- The access attribute of the variable ipForwarding has been changed
- from read-only to read-write.
-
- In addition, there is a new column to the ipAddrTable object,
-
- ipAdEntReasmMaxSize
-
- which keeps track of the largest IP datagram that can be re-assembled
- on a particular interface.
-
- The descriptor of the ipRoutingTable object has been changed to
- ipRouteTable for consistency with the other IP routing objects.
- There are also three new columns in the ipRouteTable object,
-
- ipRouteMask
- ipRouteMetric5
- ipRouteInfo
-
-
-
-SNMP Working Group [Page 6]
-\f
-RFC 1213 MIB-II March 1991
-
-
- the first is used for IP routing subsystems that support arbitrary
- subnet masks, and the latter two are IP routing protocol-specific.
-
- Two new objects are added to the IP group:
-
- ipNetToMediaTable
- ipRoutingDiscards
-
- the first is the address translation table for the IP group
- (providing identical functionality to the now deprecated atTable in
- the address translation group), and the latter provides information
- when routes are lost due to a lack of buffer space.
-
-3.8. The ICMP Group
-
- There are no changes to this group.
-
-3.9. The TCP Group
-
- Two new variables are added:
-
- tcpInErrs
- tcpOutRsts
-
- which keep track of the number of incoming TCP segments in error and
- the number of resets generated by a TCP.
-
-3.10. The UDP Group
-
- A new table:
-
- udpTable
-
- is added.
-
-3.11. The EGP Group
-
- Experience has indicated a need for additional objects that are
- useful in EGP monitoring. In addition to making several additions to
- the egpNeighborTable object, i.e.,
-
- egpNeighAs
- egpNeighInMsgs
- egpNeighInErrs
- egpNeighOutMsgs
- egpNeighOutErrs
- egpNeighInErrMsgs
- egpNeighOutErrMsgs
-
-
-
-SNMP Working Group [Page 7]
-\f
-RFC 1213 MIB-II March 1991
-
-
- egpNeighStateUps
- egpNeighStateDowns
- egpNeighIntervalHello
- egpNeighIntervalPoll
- egpNeighMode
- egpNeighEventTrigger
-
- a new variable is added:
-
- egpAs
-
- which gives the autonomous system associated with this EGP entity.
-
-3.12. The Transmission Group
-
- MIB-I was lacking in that it did not distinguish between different
- types of transmission media. A new group, the Transmission group, is
- allocated for this purpose:
-
- transmission OBJECT IDENTIFIER ::= { mib-2 10 }
-
- When Internet-standard definitions for managing transmission media
- are defined, the transmission group is used to provide a prefix for
- the names of those objects.
-
- Typically, such definitions reside in the experimental portion of the
- MIB until they are "proven", then as a part of the Internet
- standardization process, the definitions are accordingly elevated and
- a new object identifier, under the transmission group is defined. By
- convention, the name assigned is:
-
- type OBJECT IDENTIFIER ::= { transmission number }
-
- where "type" is the symbolic value used for the media in the ifType
- column of the ifTable object, and "number" is the actual integer
- value corresponding to the symbol.
-
-3.13. The SNMP Group
-
- The application-oriented working groups of the IETF have been tasked
- to be receptive towards defining MIB variables specific to their
- respective applications.
-
- For the SNMP, it is useful to have statistical information. A new
- group, the SNMP group, is allocated for this purpose:
-
- snmp OBJECT IDENTIFIER ::= { mib-2 11 }
-
-
-
-
-SNMP Working Group [Page 8]
-\f
-RFC 1213 MIB-II March 1991
-
-
-3.14. Changes from RFC 1158
-
- Features of this MIB include:
-
- (1) The managed objects in this document have been defined
- using the conventions defined in the Internet-standard
- SMI, as amended by the extensions specified in [14]. It
- must be emphasized that definitions made using these
- extensions are semantically identically to those in RFC
- 1158.
-
- (2) The PhysAddress textual convention has been introduced to
- represent media addresses.
-
- (3) The ACCESS clause of sysLocation is now read-write.
-
- (4) The definition of sysServices has been clarified.
-
- (5) New ifType values (29-32) have been defined. In
- addition, the textual-descriptor for the DS1 and E1
- interface types has been corrected.
-
- (6) The definition of ipForwarding has been clarified.
-
- (7) The definition of ipRouteType has been clarified.
-
- (8) The ipRouteMetric5 and ipRouteInfo objects have been
- defined.
-
- (9) The ACCESS clause of tcpConnState is now read-write, to
- support deletion of the TCB associated with a TCP
- connection. The definition of this object has been
- clarified to explain this usage.
-
- (10) The definition of egpNeighEventTrigger has been
- clarified.
-
- (11) The definition of several of the variables in the new
- snmp group have been clarified. In addition, the
- snmpInBadTypes and snmpOutReadOnlys objects are no longer
- present. (However, the object identifiers associated
- with those objects are reserved to prevent future use.)
-
- (12) The definition of snmpInReadOnlys has been clarified.
-
- (13) The textual descriptor of the snmpEnableAuthTraps has
- been changed to snmpEnableAuthenTraps, and the definition
- has been clarified.
-
-
-
-SNMP Working Group [Page 9]
-\f
-RFC 1213 MIB-II March 1991
-
-
- (14) The ipRoutingDiscards object was added.
-
- (15) The optional use of an implementation-dependent, small
- positive integer was disallowed when identifying
- instances of the IP address and routing tables.
-
-4. Objects
-
- Managed objects are accessed via a virtual information store, termed
- the Management Information Base or MIB. Objects in the MIB are
- defined using the subset of Abstract Syntax Notation One (ASN.1) [8]
- defined in the SMI. In particular, each object has a name, a syntax,
- and an encoding. The name is an object identifier, an
- administratively assigned name, which specifies an object type. The
- object type together with an object instance serves to uniquely
- identify a specific instantiation of the object. For human
- convenience, we often use a textual string, termed the OBJECT
- DESCRIPTOR, to also refer to the object type.
-
- The syntax of an object type defines the abstract data structure
- corresponding to that object type. The ASN.1 language is used for
- this purpose. However, the SMI [12] purposely restricts the ASN.1
- constructs which may be used. These restrictions are explicitly made
- for simplicity.
-
- The encoding of an object type is simply how that object type is
- represented using the object type's syntax. Implicitly tied to the
- notion of an object type's syntax and encoding is how the object type
- is represented when being transmitted on the network.
-
- The SMI specifies the use of the basic encoding rules of ASN.1 [9],
- subject to the additional requirements imposed by the SNMP.
-
-4.1. Format of Definitions
-
- Section 6 contains contains the specification of all object types
- contained in this MIB module. The object types are defined using the
- conventions defined in the SMI, as amended by the extensions
- specified in [14].
-
-5. Overview
-
- Consistent with the IAB directive to produce simple, workable systems
- in the short-term, the list of managed objects defined here, has been
- derived by taking only those elements which are considered essential.
-
- This approach of taking only the essential objects is NOT
- restrictive, since the SMI defined in the companion memo provides
-
-
-
-SNMP Working Group [Page 10]
-\f
-RFC 1213 MIB-II March 1991
-
-
- three extensibility mechanisms: one, the addition of new standard
- objects through the definitions of new versions of the MIB; two, the
- addition of widely-available but non-standard objects through the
- experimental subtree; and three, the addition of private objects
- through the enterprises subtree. Such additional objects can not
- only be used for vendor-specific elements, but also for
- experimentation as required to further the knowledge of which other
- objects are essential.
-
- The design of MIB-II is heavily influenced by the first extensibility
- mechanism. Several new variables have been added based on
- operational experience and need. Based on this, the criteria for
- including an object in MIB-II are remarkably similar to the MIB-I
- criteria:
-
- (1) An object needed to be essential for either fault or
- configuration management.
-
- (2) Only weak control objects were permitted (by weak, it is
- meant that tampering with them can do only limited
- damage). This criterion reflects the fact that the
- current management protocols are not sufficiently secure
- to do more powerful control operations.
-
- (3) Evidence of current use and utility was required.
-
- (4) In MIB-I, an attempt was made to limit the number of
- objects to about 100 to make it easier for vendors to
- fully instrument their software. In MIB-II, this limit
- was raised given the wide technological base now
- implementing MIB-I.
-
- (5) To avoid redundant variables, it was required that no
- object be included that can be derived from others in the
- MIB.
-
- (6) Implementation specific objects (e.g., for BSD UNIX) were
- excluded.
-
- (7) It was agreed to avoid heavily instrumenting critical
- sections of code. The general guideline was one counter
- per critical section per layer.
-
- MIB-II, like its predecessor, the Internet-standard MIB, contains
- only essential elements. There is no need to allow individual
- objects to be optional. Rather, the objects are arranged into the
- following groups:
-
-
-
-
-SNMP Working Group [Page 11]
-\f
-RFC 1213 MIB-II March 1991
-
-
- - System
- - Interfaces
- - Address Translation (deprecated)
- - IP
- - ICMP
- - TCP
- - UDP
- - EGP
- - Transmission
- - SNMP
-
- These groups are the basic unit of conformance: This method is as
- follows: if the semantics of a group is applicable to an
- implementation, then it must implement all objects in that group.
- For example, an implementation must implement the EGP group if and
- only if it implements the EGP.
-
- There are two reasons for defining these groups: to provide a means
- of assigning object identifiers; and, to provide a method for
- implementations of managed agents to know which objects they must
- implement.
-
-6. Definitions
-
- RFC1213-MIB DEFINITIONS ::= BEGIN
-
- IMPORTS
- mgmt, NetworkAddress, IpAddress, Counter, Gauge,
- TimeTicks
- FROM RFC1155-SMI
- OBJECT-TYPE
- FROM RFC-1212;
-
- -- This MIB module uses the extended OBJECT-TYPE macro as
- -- defined in [14];
-
-
- -- MIB-II (same prefix as MIB-I)
-
- mib-2 OBJECT IDENTIFIER ::= { mgmt 1 }
-
- -- textual conventions
-
- DisplayString ::=
- OCTET STRING
- -- This data type is used to model textual information taken
- -- from the NVT ASCII character set. By convention, objects
- -- with this syntax are declared as having
-
-
-
-SNMP Working Group [Page 12]
-\f
-RFC 1213 MIB-II March 1991
-
-
- --
- -- SIZE (0..255)
-
- PhysAddress ::=
- OCTET STRING
- -- This data type is used to model media addresses. For many
- -- types of media, this will be in a binary representation.
- -- For example, an ethernet address would be represented as
- -- a string of 6 octets.
-
-
- -- groups in MIB-II
-
- system OBJECT IDENTIFIER ::= { mib-2 1 }
-
- interfaces OBJECT IDENTIFIER ::= { mib-2 2 }
-
- at OBJECT IDENTIFIER ::= { mib-2 3 }
-
- ip OBJECT IDENTIFIER ::= { mib-2 4 }
-
- icmp OBJECT IDENTIFIER ::= { mib-2 5 }
-
- tcp OBJECT IDENTIFIER ::= { mib-2 6 }
-
- udp OBJECT IDENTIFIER ::= { mib-2 7 }
-
- egp OBJECT IDENTIFIER ::= { mib-2 8 }
-
- -- historical (some say hysterical)
- -- cmot OBJECT IDENTIFIER ::= { mib-2 9 }
-
- transmission OBJECT IDENTIFIER ::= { mib-2 10 }
-
- snmp OBJECT IDENTIFIER ::= { mib-2 11 }
-
-
- -- the System group
-
- -- Implementation of the System group is mandatory for all
- -- systems. If an agent is not configured to have a value
- -- for any of these variables, a string of length 0 is
- -- returned.
-
- sysDescr OBJECT-TYPE
- SYNTAX DisplayString (SIZE (0..255))
- ACCESS read-only
- STATUS mandatory
-
-
-
-SNMP Working Group [Page 13]
-\f
-RFC 1213 MIB-II March 1991
-
-
- DESCRIPTION
- "A textual description of the entity. This value
- should include the full name and version
- identification of the system's hardware type,
- software operating-system, and networking
- software. It is mandatory that this only contain
- printable ASCII characters."
- ::= { system 1 }
-
- sysObjectID OBJECT-TYPE
- SYNTAX OBJECT IDENTIFIER
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The vendor's authoritative identification of the
- network management subsystem contained in the
- entity. This value is allocated within the SMI
- enterprises subtree (1.3.6.1.4.1) and provides an
- easy and unambiguous means for determining `what
- kind of box' is being managed. For example, if
- vendor `Flintstones, Inc.' was assigned the
- subtree 1.3.6.1.4.1.4242, it could assign the
- identifier 1.3.6.1.4.1.4242.1.1 to its `Fred
- Router'."
- ::= { system 2 }
-
- sysUpTime OBJECT-TYPE
- SYNTAX TimeTicks
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The time (in hundredths of a second) since the
- network management portion of the system was last
- re-initialized."
- ::= { system 3 }
-
- sysContact OBJECT-TYPE
- SYNTAX DisplayString (SIZE (0..255))
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "The textual identification of the contact person
- for this managed node, together with information
- on how to contact this person."
- ::= { system 4 }
-
- sysName OBJECT-TYPE
- SYNTAX DisplayString (SIZE (0..255))
-
-
-
-SNMP Working Group [Page 14]
-\f
-RFC 1213 MIB-II March 1991
-
-
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "An administratively-assigned name for this
- managed node. By convention, this is the node's
- fully-qualified domain name."
- ::= { system 5 }
-
- sysLocation OBJECT-TYPE
- SYNTAX DisplayString (SIZE (0..255))
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "The physical location of this node (e.g.,
- `telephone closet, 3rd floor')."
- ::= { system 6 }
-
- sysServices OBJECT-TYPE
- SYNTAX INTEGER (0..127)
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "A value which indicates the set of services that
- this entity primarily offers.
-
- The value is a sum. This sum initially takes the
- value zero, Then, for each layer, L, in the range
- 1 through 7, that this node performs transactions
- for, 2 raised to (L - 1) is added to the sum. For
- example, a node which performs primarily routing
- functions would have a value of 4 (2^(3-1)). In
- contrast, a node which is a host offering
- application services would have a value of 72
- (2^(4-1) + 2^(7-1)). Note that in the context of
- the Internet suite of protocols, values should be
- calculated accordingly:
-
- layer functionality
- 1 physical (e.g., repeaters)
- 2 datalink/subnetwork (e.g., bridges)
- 3 internet (e.g., IP gateways)
- 4 end-to-end (e.g., IP hosts)
- 7 applications (e.g., mail relays)
-
- For systems including OSI protocols, layers 5 and
- 6 may also be counted."
- ::= { system 7 }
-
-
-
-
-SNMP Working Group [Page 15]
-\f
-RFC 1213 MIB-II March 1991
-
-
- -- the Interfaces group
-
- -- Implementation of the Interfaces group is mandatory for
- -- all systems.
-
- ifNumber OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of network interfaces (regardless of
- their current state) present on this system."
- ::= { interfaces 1 }
-
-
- -- the Interfaces table
-
- -- The Interfaces table contains information on the entity's
- -- interfaces. Each interface is thought of as being
- -- attached to a `subnetwork'. Note that this term should
- -- not be confused with `subnet' which refers to an
- -- addressing partitioning scheme used in the Internet suite
- -- of protocols.
-
- ifTable OBJECT-TYPE
- SYNTAX SEQUENCE OF IfEntry
- ACCESS not-accessible
- STATUS mandatory
- DESCRIPTION
- "A list of interface entries. The number of
- entries is given by the value of ifNumber."
- ::= { interfaces 2 }
-
- ifEntry OBJECT-TYPE
- SYNTAX IfEntry
- ACCESS not-accessible
- STATUS mandatory
- DESCRIPTION
- "An interface entry containing objects at the
- subnetwork layer and below for a particular
- interface."
- INDEX { ifIndex }
- ::= { ifTable 1 }
-
- IfEntry ::=
- SEQUENCE {
- ifIndex
- INTEGER,
-
-
-
-SNMP Working Group [Page 16]
-\f
-RFC 1213 MIB-II March 1991
-
-
- ifDescr
- DisplayString,
- ifType
- INTEGER,
- ifMtu
- INTEGER,
- ifSpeed
- Gauge,
- ifPhysAddress
- PhysAddress,
- ifAdminStatus
- INTEGER,
- ifOperStatus
- INTEGER,
- ifLastChange
- TimeTicks,
- ifInOctets
- Counter,
- ifInUcastPkts
- Counter,
- ifInNUcastPkts
- Counter,
- ifInDiscards
- Counter,
- ifInErrors
- Counter,
- ifInUnknownProtos
- Counter,
- ifOutOctets
- Counter,
- ifOutUcastPkts
- Counter,
- ifOutNUcastPkts
- Counter,
- ifOutDiscards
- Counter,
- ifOutErrors
- Counter,
- ifOutQLen
- Gauge,
- ifSpecific
- OBJECT IDENTIFIER
- }
-
- ifIndex OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-only
- STATUS mandatory
-
-
-
-SNMP Working Group [Page 17]
-\f
-RFC 1213 MIB-II March 1991
-
-
- DESCRIPTION
- "A unique value for each interface. Its value
- ranges between 1 and the value of ifNumber. The
- value for each interface must remain constant at
- least from one re-initialization of the entity's
- network management system to the next re-
- initialization."
- ::= { ifEntry 1 }
-
- ifDescr OBJECT-TYPE
- SYNTAX DisplayString (SIZE (0..255))
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "A textual string containing information about the
- interface. This string should include the name of
- the manufacturer, the product name and the version
- of the hardware interface."
- ::= { ifEntry 2 }
-
- ifType OBJECT-TYPE
- SYNTAX INTEGER {
- other(1), -- none of the following
- regular1822(2),
- hdh1822(3),
- ddn-x25(4),
- rfc877-x25(5),
- ethernet-csmacd(6),
- iso88023-csmacd(7),
- iso88024-tokenBus(8),
- iso88025-tokenRing(9),
- iso88026-man(10),
- starLan(11),
- proteon-10Mbit(12),
- proteon-80Mbit(13),
- hyperchannel(14),
- fddi(15),
- lapb(16),
- sdlc(17),
- ds1(18), -- T-1
- e1(19), -- european equiv. of T-1
- basicISDN(20),
- primaryISDN(21), -- proprietary serial
- propPointToPointSerial(22),
- ppp(23),
- softwareLoopback(24),
- eon(25), -- CLNP over IP [11]
- ethernet-3Mbit(26),
-
-
-
-SNMP Working Group [Page 18]
-\f
-RFC 1213 MIB-II March 1991
-
-
- nsip(27), -- XNS over IP
- slip(28), -- generic SLIP
- ultra(29), -- ULTRA technologies
- ds3(30), -- T-3
- sip(31), -- SMDS
- frame-relay(32)
- }
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The type of interface, distinguished according to
- the physical/link protocol(s) immediately `below'
- the network layer in the protocol stack."
- ::= { ifEntry 3 }
-
- ifMtu OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The size of the largest datagram which can be
- sent/received on the interface, specified in
- octets. For interfaces that are used for
- transmitting network datagrams, this is the size
- of the largest network datagram that can be sent
- on the interface."
- ::= { ifEntry 4 }
-
- ifSpeed OBJECT-TYPE
- SYNTAX Gauge
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "An estimate of the interface's current bandwidth
- in bits per second. For interfaces which do not
- vary in bandwidth or for those where no accurate
- estimation can be made, this object should contain
- the nominal bandwidth."
- ::= { ifEntry 5 }
-
- ifPhysAddress OBJECT-TYPE
- SYNTAX PhysAddress
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The interface's address at the protocol layer
- immediately `below' the network layer in the
- protocol stack. For interfaces which do not have
-
-
-
-SNMP Working Group [Page 19]
-\f
-RFC 1213 MIB-II March 1991
-
-
- such an address (e.g., a serial line), this object
- should contain an octet string of zero length."
- ::= { ifEntry 6 }
-
- ifAdminStatus OBJECT-TYPE
- SYNTAX INTEGER {
- up(1), -- ready to pass packets
- down(2),
- testing(3) -- in some test mode
- }
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "The desired state of the interface. The
- testing(3) state indicates that no operational
- packets can be passed."
- ::= { ifEntry 7 }
-
- ifOperStatus OBJECT-TYPE
- SYNTAX INTEGER {
- up(1), -- ready to pass packets
- down(2),
- testing(3) -- in some test mode
- }
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The current operational state of the interface.
- The testing(3) state indicates that no operational
- packets can be passed."
- ::= { ifEntry 8 }
-
- ifLastChange OBJECT-TYPE
- SYNTAX TimeTicks
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The value of sysUpTime at the time the interface
- entered its current operational state. If the
- current state was entered prior to the last re-
- initialization of the local network management
- subsystem, then this object contains a zero
- value."
- ::= { ifEntry 9 }
-
- ifInOctets OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
-
-
-
-SNMP Working Group [Page 20]
-\f
-RFC 1213 MIB-II March 1991
-
-
- STATUS mandatory
- DESCRIPTION
- "The total number of octets received on the
- interface, including framing characters."
- ::= { ifEntry 10 }
-
- ifInUcastPkts OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of subnetwork-unicast packets
- delivered to a higher-layer protocol."
- ::= { ifEntry 11 }
-
- ifInNUcastPkts OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of non-unicast (i.e., subnetwork-
- broadcast or subnetwork-multicast) packets
- delivered to a higher-layer protocol."
- ::= { ifEntry 12 }
-
- ifInDiscards OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of inbound packets which were chosen
- to be discarded even though no errors had been
- detected to prevent their being deliverable to a
- higher-layer protocol. One possible reason for
- discarding such a packet could be to free up
- buffer space."
- ::= { ifEntry 13 }
-
- ifInErrors OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of inbound packets that contained
- errors preventing them from being deliverable to a
- higher-layer protocol."
- ::= { ifEntry 14 }
-
-
-
-
-SNMP Working Group [Page 21]
-\f
-RFC 1213 MIB-II March 1991
-
-
- ifInUnknownProtos OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of packets received via the interface
- which were discarded because of an unknown or
- unsupported protocol."
- ::= { ifEntry 15 }
-
- ifOutOctets OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of octets transmitted out of the
- interface, including framing characters."
- ::= { ifEntry 16 }
-
- ifOutUcastPkts OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of packets that higher-level
- protocols requested be transmitted to a
- subnetwork-unicast address, including those that
- were discarded or not sent."
- ::= { ifEntry 17 }
-
- ifOutNUcastPkts OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of packets that higher-level
- protocols requested be transmitted to a non-
- unicast (i.e., a subnetwork-broadcast or
- subnetwork-multicast) address, including those
- that were discarded or not sent."
- ::= { ifEntry 18 }
-
- ifOutDiscards OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of outbound packets which were chosen
-
-
-
-SNMP Working Group [Page 22]
-\f
-RFC 1213 MIB-II March 1991
-
-
- to be discarded even though no errors had been
- detected to prevent their being transmitted. One
- possible reason for discarding such a packet could
- be to free up buffer space."
- ::= { ifEntry 19 }
-
- ifOutErrors OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of outbound packets that could not be
- transmitted because of errors."
- ::= { ifEntry 20 }
-
- ifOutQLen OBJECT-TYPE
- SYNTAX Gauge
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The length of the output packet queue (in
- packets)."
- ::= { ifEntry 21 }
-
- ifSpecific OBJECT-TYPE
- SYNTAX OBJECT IDENTIFIER
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "A reference to MIB definitions specific to the
- particular media being used to realize the
- interface. For example, if the interface is
- realized by an ethernet, then the value of this
- object refers to a document defining objects
- specific to ethernet. If this information is not
- present, its value should be set to the OBJECT
- IDENTIFIER { 0 0 }, which is a syntatically valid
- object identifier, and any conformant
- implementation of ASN.1 and BER must be able to
- generate and recognize this value."
- ::= { ifEntry 22 }
-
-
- -- the Address Translation group
-
- -- Implementation of the Address Translation group is
- -- mandatory for all systems. Note however that this group
- -- is deprecated by MIB-II. That is, it is being included
-
-
-
-SNMP Working Group [Page 23]
-\f
-RFC 1213 MIB-II March 1991
-
-
- -- solely for compatibility with MIB-I nodes, and will most
- -- likely be excluded from MIB-III nodes. From MIB-II and
- -- onwards, each network protocol group contains its own
- -- address translation tables.
-
- -- The Address Translation group contains one table which is
- -- the union across all interfaces of the translation tables
- -- for converting a NetworkAddress (e.g., an IP address) into
- -- a subnetwork-specific address. For lack of a better term,
- -- this document refers to such a subnetwork-specific address
- -- as a `physical' address.
-
- -- Examples of such translation tables are: for broadcast
- -- media where ARP is in use, the translation table is
- -- equivalent to the ARP cache; or, on an X.25 network where
- -- non-algorithmic translation to X.121 addresses is
- -- required, the translation table contains the
- -- NetworkAddress to X.121 address equivalences.
-
- atTable OBJECT-TYPE
- SYNTAX SEQUENCE OF AtEntry
- ACCESS not-accessible
- STATUS deprecated
- DESCRIPTION
- "The Address Translation tables contain the
- NetworkAddress to `physical' address equivalences.
- Some interfaces do not use translation tables for
- determining address equivalences (e.g., DDN-X.25
- has an algorithmic method); if all interfaces are
- of this type, then the Address Translation table
- is empty, i.e., has zero entries."
- ::= { at 1 }
-
- atEntry OBJECT-TYPE
- SYNTAX AtEntry
- ACCESS not-accessible
- STATUS deprecated
- DESCRIPTION
- "Each entry contains one NetworkAddress to
- `physical' address equivalence."
- INDEX { atIfIndex,
- atNetAddress }
- ::= { atTable 1 }
-
- AtEntry ::=
- SEQUENCE {
- atIfIndex
- INTEGER,
-
-
-
-SNMP Working Group [Page 24]
-\f
-RFC 1213 MIB-II March 1991
-
-
- atPhysAddress
- PhysAddress,
- atNetAddress
- NetworkAddress
- }
-
- atIfIndex OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-write
- STATUS deprecated
- DESCRIPTION
- "The interface on which this entry's equivalence
- is effective. The interface identified by a
- particular value of this index is the same
- interface as identified by the same value of
- ifIndex."
- ::= { atEntry 1 }
-
- atPhysAddress OBJECT-TYPE
- SYNTAX PhysAddress
- ACCESS read-write
- STATUS deprecated
- DESCRIPTION
- "The media-dependent `physical' address.
-
- Setting this object to a null string (one of zero
- length) has the effect of invaliding the
- corresponding entry in the atTable object. That
- is, it effectively dissasociates the interface
- identified with said entry from the mapping
- identified with said entry. It is an
- implementation-specific matter as to whether the
- agent removes an invalidated entry from the table.
- Accordingly, management stations must be prepared
- to receive tabular information from agents that
- corresponds to entries not currently in use.
- Proper interpretation of such entries requires
- examination of the relevant atPhysAddress object."
- ::= { atEntry 2 }
-
- atNetAddress OBJECT-TYPE
- SYNTAX NetworkAddress
- ACCESS read-write
- STATUS deprecated
- DESCRIPTION
- "The NetworkAddress (e.g., the IP address)
- corresponding to the media-dependent `physical'
- address."
-
-
-
-SNMP Working Group [Page 25]
-\f
-RFC 1213 MIB-II March 1991
-
-
- ::= { atEntry 3 }
-
-
- -- the IP group
-
- -- Implementation of the IP group is mandatory for all
- -- systems.
-
- ipForwarding OBJECT-TYPE
- SYNTAX INTEGER {
- forwarding(1), -- acting as a gateway
- not-forwarding(2) -- NOT acting as a gateway
- }
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "The indication of whether this entity is acting
- as an IP gateway in respect to the forwarding of
- datagrams received by, but not addressed to, this
- entity. IP gateways forward datagrams. IP hosts
- do not (except those source-routed via the host).
-
- Note that for some managed nodes, this object may
- take on only a subset of the values possible.
- Accordingly, it is appropriate for an agent to
- return a `badValue' response if a management
- station attempts to change this object to an
- inappropriate value."
- ::= { ip 1 }
-
- ipDefaultTTL OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "The default value inserted into the Time-To-Live
- field of the IP header of datagrams originated at
- this entity, whenever a TTL value is not supplied
- by the transport layer protocol."
- ::= { ip 2 }
-
- ipInReceives OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of input datagrams received from
- interfaces, including those received in error."
-
-
-
-SNMP Working Group [Page 26]
-\f
-RFC 1213 MIB-II March 1991
-
-
- ::= { ip 3 }
-
- ipInHdrErrors OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of input datagrams discarded due to
- errors in their IP headers, including bad
- checksums, version number mismatch, other format
- errors, time-to-live exceeded, errors discovered
- in processing their IP options, etc."
- ::= { ip 4 }
-
- ipInAddrErrors OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of input datagrams discarded because
- the IP address in their IP header's destination
- field was not a valid address to be received at
- this entity. This count includes invalid
- addresses (e.g., 0.0.0.0) and addresses of
- unsupported Classes (e.g., Class E). For entities
- which are not IP Gateways and therefore do not
- forward datagrams, this counter includes datagrams
- discarded because the destination address was not
- a local address."
- ::= { ip 5 }
-
- ipForwDatagrams OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of input datagrams for which this
- entity was not their final IP destination, as a
- result of which an attempt was made to find a
- route to forward them to that final destination.
- In entities which do not act as IP Gateways, this
- counter will include only those packets which were
- Source-Routed via this entity, and the Source-
- Route option processing was successful."
- ::= { ip 6 }
-
- ipInUnknownProtos OBJECT-TYPE
- SYNTAX Counter
-
-
-
-SNMP Working Group [Page 27]
-\f
-RFC 1213 MIB-II March 1991
-
-
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of locally-addressed datagrams
- received successfully but discarded because of an
- unknown or unsupported protocol."
- ::= { ip 7 }
-
- ipInDiscards OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of input IP datagrams for which no
- problems were encountered to prevent their
- continued processing, but which were discarded
- (e.g., for lack of buffer space). Note that this
- counter does not include any datagrams discarded
- while awaiting re-assembly."
- ::= { ip 8 }
-
- ipInDelivers OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of input datagrams successfully
- delivered to IP user-protocols (including ICMP)."
- ::= { ip 9 }
-
- ipOutRequests OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of IP datagrams which local IP
- user-protocols (including ICMP) supplied to IP in
- requests for transmission. Note that this counter
- does not include any datagrams counted in
- ipForwDatagrams."
- ::= { ip 10 }
-
- ipOutDiscards OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of output IP datagrams for which no
-
-
-
-SNMP Working Group [Page 28]
-\f
-RFC 1213 MIB-II March 1991
-
-
- problem was encountered to prevent their
- transmission to their destination, but which were
- discarded (e.g., for lack of buffer space). Note
- that this counter would include datagrams counted
- in ipForwDatagrams if any such packets met this
- (discretionary) discard criterion."
- ::= { ip 11 }
-
- ipOutNoRoutes OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of IP datagrams discarded because no
- route could be found to transmit them to their
- destination. Note that this counter includes any
- packets counted in ipForwDatagrams which meet this
- `no-route' criterion. Note that this includes any
- datagarms which a host cannot route because all of
- its default gateways are down."
- ::= { ip 12 }
-
- ipReasmTimeout OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The maximum number of seconds which received
- fragments are held while they are awaiting
- reassembly at this entity."
- ::= { ip 13 }
-
- ipReasmReqds OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of IP fragments received which needed
- to be reassembled at this entity."
- ::= { ip 14 }
-
- ipReasmOKs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of IP datagrams successfully re-
- assembled."
-
-
-
-SNMP Working Group [Page 29]
-\f
-RFC 1213 MIB-II March 1991
-
-
- ::= { ip 15 }
-
- ipReasmFails OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of failures detected by the IP re-
- assembly algorithm (for whatever reason: timed
- out, errors, etc). Note that this is not
- necessarily a count of discarded IP fragments
- since some algorithms (notably the algorithm in
- RFC 815) can lose track of the number of fragments
- by combining them as they are received."
- ::= { ip 16 }
-
- ipFragOKs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of IP datagrams that have been
- successfully fragmented at this entity."
- ::= { ip 17 }
-
- ipFragFails OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of IP datagrams that have been
- discarded because they needed to be fragmented at
- this entity but could not be, e.g., because their
- Don't Fragment flag was set."
- ::= { ip 18 }
-
- ipFragCreates OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of IP datagram fragments that have
- been generated as a result of fragmentation at
- this entity."
- ::= { ip 19 }
-
-
-
-
-
-
-SNMP Working Group [Page 30]
-\f
-RFC 1213 MIB-II March 1991
-
-
- -- the IP address table
-
- -- The IP address table contains this entity's IP addressing
- -- information.
-
- ipAddrTable OBJECT-TYPE
- SYNTAX SEQUENCE OF IpAddrEntry
- ACCESS not-accessible
- STATUS mandatory
- DESCRIPTION
- "The table of addressing information relevant to
- this entity's IP addresses."
- ::= { ip 20 }
-
- ipAddrEntry OBJECT-TYPE
- SYNTAX IpAddrEntry
- ACCESS not-accessible
- STATUS mandatory
- DESCRIPTION
- "The addressing information for one of this
- entity's IP addresses."
- INDEX { ipAdEntAddr }
- ::= { ipAddrTable 1 }
-
- IpAddrEntry ::=
- SEQUENCE {
- ipAdEntAddr
- IpAddress,
- ipAdEntIfIndex
- INTEGER,
- ipAdEntNetMask
- IpAddress,
- ipAdEntBcastAddr
- INTEGER,
- ipAdEntReasmMaxSize
- INTEGER (0..65535)
- }
-
- ipAdEntAddr OBJECT-TYPE
- SYNTAX IpAddress
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The IP address to which this entry's addressing
- information pertains."
- ::= { ipAddrEntry 1 }
-
-
-
-
-
-SNMP Working Group [Page 31]
-\f
-RFC 1213 MIB-II March 1991
-
-
- ipAdEntIfIndex OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The index value which uniquely identifies the
- interface to which this entry is applicable. The
- interface identified by a particular value of this
- index is the same interface as identified by the
- same value of ifIndex."
- ::= { ipAddrEntry 2 }
-
- ipAdEntNetMask OBJECT-TYPE
- SYNTAX IpAddress
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The subnet mask associated with the IP address of
- this entry. The value of the mask is an IP
- address with all the network bits set to 1 and all
- the hosts bits set to 0."
- ::= { ipAddrEntry 3 }
-
- ipAdEntBcastAddr OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The value of the least-significant bit in the IP
- broadcast address used for sending datagrams on
- the (logical) interface associated with the IP
- address of this entry. For example, when the
- Internet standard all-ones broadcast address is
- used, the value will be 1. This value applies to
- both the subnet and network broadcasts addresses
- used by the entity on this (logical) interface."
- ::= { ipAddrEntry 4 }
-
- ipAdEntReasmMaxSize OBJECT-TYPE
- SYNTAX INTEGER (0..65535)
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The size of the largest IP datagram which this
- entity can re-assemble from incoming IP fragmented
- datagrams received on this interface."
- ::= { ipAddrEntry 5 }
-
-
-
-
-SNMP Working Group [Page 32]
-\f
-RFC 1213 MIB-II March 1991
-
-
- -- the IP routing table
-
- -- The IP routing table contains an entry for each route
- -- presently known to this entity.
-
- ipRouteTable OBJECT-TYPE
- SYNTAX SEQUENCE OF IpRouteEntry
- ACCESS not-accessible
- STATUS mandatory
- DESCRIPTION
- "This entity's IP Routing table."
- ::= { ip 21 }
-
- ipRouteEntry OBJECT-TYPE
- SYNTAX IpRouteEntry
- ACCESS not-accessible
- STATUS mandatory
- DESCRIPTION
- "A route to a particular destination."
- INDEX { ipRouteDest }
- ::= { ipRouteTable 1 }
-
- IpRouteEntry ::=
- SEQUENCE {
- ipRouteDest
- IpAddress,
- ipRouteIfIndex
- INTEGER,
- ipRouteMetric1
- INTEGER,
- ipRouteMetric2
- INTEGER,
- ipRouteMetric3
- INTEGER,
- ipRouteMetric4
- INTEGER,
- ipRouteNextHop
- IpAddress,
- ipRouteType
- INTEGER,
- ipRouteProto
- INTEGER,
- ipRouteAge
- INTEGER,
- ipRouteMask
- IpAddress,
- ipRouteMetric5
- INTEGER,
-
-
-
-SNMP Working Group [Page 33]
-\f
-RFC 1213 MIB-II March 1991
-
-
- ipRouteInfo
- OBJECT IDENTIFIER
- }
-
- ipRouteDest OBJECT-TYPE
- SYNTAX IpAddress
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "The destination IP address of this route. An
- entry with a value of 0.0.0.0 is considered a
- default route. Multiple routes to a single
- destination can appear in the table, but access to
- such multiple entries is dependent on the table-
- access mechanisms defined by the network
- management protocol in use."
- ::= { ipRouteEntry 1 }
-
- ipRouteIfIndex OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "The index value which uniquely identifies the
- local interface through which the next hop of this
- route should be reached. The interface identified
- by a particular value of this index is the same
- interface as identified by the same value of
- ifIndex."
- ::= { ipRouteEntry 2 }
-
- ipRouteMetric1 OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "The primary routing metric for this route. The
- semantics of this metric are determined by the
- routing-protocol specified in the route's
- ipRouteProto value. If this metric is not used,
- its value should be set to -1."
- ::= { ipRouteEntry 3 }
-
- ipRouteMetric2 OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
-
-
-
-SNMP Working Group [Page 34]
-\f
-RFC 1213 MIB-II March 1991
-
-
- "An alternate routing metric for this route. The
- semantics of this metric are determined by the
- routing-protocol specified in the route's
- ipRouteProto value. If this metric is not used,
- its value should be set to -1."
- ::= { ipRouteEntry 4 }
-
- ipRouteMetric3 OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "An alternate routing metric for this route. The
- semantics of this metric are determined by the
- routing-protocol specified in the route's
- ipRouteProto value. If this metric is not used,
- its value should be set to -1."
- ::= { ipRouteEntry 5 }
-
- ipRouteMetric4 OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "An alternate routing metric for this route. The
- semantics of this metric are determined by the
- routing-protocol specified in the route's
- ipRouteProto value. If this metric is not used,
- its value should be set to -1."
- ::= { ipRouteEntry 6 }
-
- ipRouteNextHop OBJECT-TYPE
- SYNTAX IpAddress
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "The IP address of the next hop of this route.
- (In the case of a route bound to an interface
- which is realized via a broadcast media, the value
- of this field is the agent's IP address on that
- interface.)"
- ::= { ipRouteEntry 7 }
-
- ipRouteType OBJECT-TYPE
- SYNTAX INTEGER {
- other(1), -- none of the following
-
- invalid(2), -- an invalidated route
-
-
-
-SNMP Working Group [Page 35]
-\f
-RFC 1213 MIB-II March 1991
-
-
- -- route to directly
- direct(3), -- connected (sub-)network
-
- -- route to a non-local
- indirect(4) -- host/network/sub-network
- }
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "The type of route. Note that the values
- direct(3) and indirect(4) refer to the notion of
- direct and indirect routing in the IP
- architecture.
-
- Setting this object to the value invalid(2) has
- the effect of invalidating the corresponding entry
- in the ipRouteTable object. That is, it
- effectively dissasociates the destination
- identified with said entry from the route
- identified with said entry. It is an
- implementation-specific matter as to whether the
- agent removes an invalidated entry from the table.
- Accordingly, management stations must be prepared
- to receive tabular information from agents that
- corresponds to entries not currently in use.
- Proper interpretation of such entries requires
- examination of the relevant ipRouteType object."
- ::= { ipRouteEntry 8 }
-
- ipRouteProto OBJECT-TYPE
- SYNTAX INTEGER {
- other(1), -- none of the following
-
- -- non-protocol information,
- -- e.g., manually configured
- local(2), -- entries
-
- -- set via a network
- netmgmt(3), -- management protocol
-
- -- obtained via ICMP,
- icmp(4), -- e.g., Redirect
-
- -- the remaining values are
- -- all gateway routing
- -- protocols
- egp(5),
- ggp(6),
-
-
-
-SNMP Working Group [Page 36]
-\f
-RFC 1213 MIB-II March 1991
-
-
- hello(7),
- rip(8),
- is-is(9),
- es-is(10),
- ciscoIgrp(11),
- bbnSpfIgp(12),
- ospf(13),
- bgp(14)
- }
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The routing mechanism via which this route was
- learned. Inclusion of values for gateway routing
- protocols is not intended to imply that hosts
- should support those protocols."
- ::= { ipRouteEntry 9 }
-
- ipRouteAge OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "The number of seconds since this route was last
- updated or otherwise determined to be correct.
- Note that no semantics of `too old' can be implied
- except through knowledge of the routing protocol
- by which the route was learned."
- ::= { ipRouteEntry 10 }
-
- ipRouteMask OBJECT-TYPE
- SYNTAX IpAddress
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "Indicate the mask to be logical-ANDed with the
- destination address before being compared to the
- value in the ipRouteDest field. For those systems
- that do not support arbitrary subnet masks, an
- agent constructs the value of the ipRouteMask by
- determining whether the value of the correspondent
- ipRouteDest field belong to a class-A, B, or C
- network, and then using one of:
-
- mask network
- 255.0.0.0 class-A
- 255.255.0.0 class-B
- 255.255.255.0 class-C
-
-
-
-SNMP Working Group [Page 37]
-\f
-RFC 1213 MIB-II March 1991
-
-
- If the value of the ipRouteDest is 0.0.0.0 (a
- default route), then the mask value is also
- 0.0.0.0. It should be noted that all IP routing
- subsystems implicitly use this mechanism."
- ::= { ipRouteEntry 11 }
-
- ipRouteMetric5 OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "An alternate routing metric for this route. The
- semantics of this metric are determined by the
- routing-protocol specified in the route's
- ipRouteProto value. If this metric is not used,
- its value should be set to -1."
- ::= { ipRouteEntry 12 }
-
- ipRouteInfo OBJECT-TYPE
- SYNTAX OBJECT IDENTIFIER
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "A reference to MIB definitions specific to the
- particular routing protocol which is responsible
- for this route, as determined by the value
- specified in the route's ipRouteProto value. If
- this information is not present, its value should
- be set to the OBJECT IDENTIFIER { 0 0 }, which is
- a syntatically valid object identifier, and any
- conformant implementation of ASN.1 and BER must be
- able to generate and recognize this value."
- ::= { ipRouteEntry 13 }
-
-
- -- the IP Address Translation table
-
- -- The IP address translation table contain the IpAddress to
- -- `physical' address equivalences. Some interfaces do not
- -- use translation tables for determining address
- -- equivalences (e.g., DDN-X.25 has an algorithmic method);
- -- if all interfaces are of this type, then the Address
- -- Translation table is empty, i.e., has zero entries.
-
- ipNetToMediaTable OBJECT-TYPE
- SYNTAX SEQUENCE OF IpNetToMediaEntry
- ACCESS not-accessible
- STATUS mandatory
-
-
-
-SNMP Working Group [Page 38]
-\f
-RFC 1213 MIB-II March 1991
-
-
- DESCRIPTION
- "The IP Address Translation table used for mapping
- from IP addresses to physical addresses."
- ::= { ip 22 }
-
- ipNetToMediaEntry OBJECT-TYPE
- SYNTAX IpNetToMediaEntry
- ACCESS not-accessible
- STATUS mandatory
- DESCRIPTION
- "Each entry contains one IpAddress to `physical'
- address equivalence."
- INDEX { ipNetToMediaIfIndex,
- ipNetToMediaNetAddress }
- ::= { ipNetToMediaTable 1 }
-
- IpNetToMediaEntry ::=
- SEQUENCE {
- ipNetToMediaIfIndex
- INTEGER,
- ipNetToMediaPhysAddress
- PhysAddress,
- ipNetToMediaNetAddress
- IpAddress,
- ipNetToMediaType
- INTEGER
- }
-
- ipNetToMediaIfIndex OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "The interface on which this entry's equivalence
- is effective. The interface identified by a
- particular value of this index is the same
- interface as identified by the same value of
- ifIndex."
- ::= { ipNetToMediaEntry 1 }
-
- ipNetToMediaPhysAddress OBJECT-TYPE
- SYNTAX PhysAddress
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "The media-dependent `physical' address."
- ::= { ipNetToMediaEntry 2 }
-
-
-
-
-SNMP Working Group [Page 39]
-\f
-RFC 1213 MIB-II March 1991
-
-
- ipNetToMediaNetAddress OBJECT-TYPE
- SYNTAX IpAddress
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "The IpAddress corresponding to the media-
- dependent `physical' address."
- ::= { ipNetToMediaEntry 3 }
-
- ipNetToMediaType OBJECT-TYPE
- SYNTAX INTEGER {
- other(1), -- none of the following
- invalid(2), -- an invalidated mapping
- dynamic(3),
- static(4)
- }
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "The type of mapping.
-
- Setting this object to the value invalid(2) has
- the effect of invalidating the corresponding entry
- in the ipNetToMediaTable. That is, it effectively
- dissasociates the interface identified with said
- entry from the mapping identified with said entry.
- It is an implementation-specific matter as to
- whether the agent removes an invalidated entry
- from the table. Accordingly, management stations
- must be prepared to receive tabular information
- from agents that corresponds to entries not
- currently in use. Proper interpretation of such
- entries requires examination of the relevant
- ipNetToMediaType object."
- ::= { ipNetToMediaEntry 4 }
-
-
- -- additional IP objects
-
- ipRoutingDiscards OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of routing entries which were chosen
- to be discarded even though they are valid. One
- possible reason for discarding such an entry could
- be to free-up buffer space for other routing
-
-
-
-SNMP Working Group [Page 40]
-\f
-RFC 1213 MIB-II March 1991
-
-
- entries."
- ::= { ip 23 }
-
-
- -- the ICMP group
-
- -- Implementation of the ICMP group is mandatory for all
- -- systems.
-
- icmpInMsgs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of ICMP messages which the
- entity received. Note that this counter includes
- all those counted by icmpInErrors."
- ::= { icmp 1 }
-
- icmpInErrors OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP messages which the entity
- received but determined as having ICMP-specific
- errors (bad ICMP checksums, bad length, etc.)."
- ::= { icmp 2 }
-
- icmpInDestUnreachs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Destination Unreachable
- messages received."
- ::= { icmp 3 }
-
- icmpInTimeExcds OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Time Exceeded messages
- received."
- ::= { icmp 4 }
-
-
-
-
-
-SNMP Working Group [Page 41]
-\f
-RFC 1213 MIB-II March 1991
-
-
- icmpInParmProbs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Parameter Problem messages
- received."
- ::= { icmp 5 }
-
- icmpInSrcQuenchs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Source Quench messages
- received."
- ::= { icmp 6 }
-
- icmpInRedirects OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Redirect messages received."
- ::= { icmp 7 }
-
- icmpInEchos OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Echo (request) messages
- received."
- ::= { icmp 8 }
-
- icmpInEchoReps OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Echo Reply messages received."
- ::= { icmp 9 }
-
- icmpInTimestamps OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
-
-
-
-SNMP Working Group [Page 42]
-\f
-RFC 1213 MIB-II March 1991
-
-
- "The number of ICMP Timestamp (request) messages
- received."
- ::= { icmp 10 }
-
- icmpInTimestampReps OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Timestamp Reply messages
- received."
- ::= { icmp 11 }
-
- icmpInAddrMasks OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Address Mask Request messages
- received."
- ::= { icmp 12 }
-
- icmpInAddrMaskReps OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Address Mask Reply messages
- received."
- ::= { icmp 13 }
-
- icmpOutMsgs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of ICMP messages which this
- entity attempted to send. Note that this counter
- includes all those counted by icmpOutErrors."
- ::= { icmp 14 }
-
- icmpOutErrors OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP messages which this entity did
- not send due to problems discovered within ICMP
-
-
-
-SNMP Working Group [Page 43]
-\f
-RFC 1213 MIB-II March 1991
-
-
- such as a lack of buffers. This value should not
- include errors discovered outside the ICMP layer
- such as the inability of IP to route the resultant
- datagram. In some implementations there may be no
- types of error which contribute to this counter's
- value."
- ::= { icmp 15 }
-
- icmpOutDestUnreachs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Destination Unreachable
- messages sent."
- ::= { icmp 16 }
-
- icmpOutTimeExcds OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Time Exceeded messages sent."
- ::= { icmp 17 }
-
- icmpOutParmProbs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Parameter Problem messages
- sent."
- ::= { icmp 18 }
-
- icmpOutSrcQuenchs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Source Quench messages sent."
- ::= { icmp 19 }
-
- icmpOutRedirects OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Redirect messages sent. For a
-
-
-
-SNMP Working Group [Page 44]
-\f
-RFC 1213 MIB-II March 1991
-
-
- host, this object will always be zero, since hosts
- do not send redirects."
- ::= { icmp 20 }
-
- icmpOutEchos OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Echo (request) messages sent."
- ::= { icmp 21 }
-
- icmpOutEchoReps OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Echo Reply messages sent."
- ::= { icmp 22 }
-
- icmpOutTimestamps OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Timestamp (request) messages
- sent."
- ::= { icmp 23 }
-
- icmpOutTimestampReps OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Timestamp Reply messages
- sent."
- ::= { icmp 24 }
-
- icmpOutAddrMasks OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Address Mask Request messages
- sent."
- ::= { icmp 25 }
-
-
-
-
-
-SNMP Working Group [Page 45]
-\f
-RFC 1213 MIB-II March 1991
-
-
- icmpOutAddrMaskReps OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of ICMP Address Mask Reply messages
- sent."
- ::= { icmp 26 }
-
-
- -- the TCP group
-
- -- Implementation of the TCP group is mandatory for all
- -- systems that implement the TCP.
-
- -- Note that instances of object types that represent
- -- information about a particular TCP connection are
- -- transient; they persist only as long as the connection
- -- in question.
-
- tcpRtoAlgorithm OBJECT-TYPE
- SYNTAX INTEGER {
- other(1), -- none of the following
-
- constant(2), -- a constant rto
- rsre(3), -- MIL-STD-1778, Appendix B
- vanj(4) -- Van Jacobson's algorithm [10]
- }
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The algorithm used to determine the timeout value
- used for retransmitting unacknowledged octets."
- ::= { tcp 1 }
-
- tcpRtoMin OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The minimum value permitted by a TCP
- implementation for the retransmission timeout,
- measured in milliseconds. More refined semantics
- for objects of this type depend upon the algorithm
- used to determine the retransmission timeout. In
- particular, when the timeout algorithm is rsre(3),
- an object of this type has the semantics of the
- LBOUND quantity described in RFC 793."
-
-
-
-SNMP Working Group [Page 46]
-\f
-RFC 1213 MIB-II March 1991
-
-
- ::= { tcp 2 }
-
-
- tcpRtoMax OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The maximum value permitted by a TCP
- implementation for the retransmission timeout,
- measured in milliseconds. More refined semantics
- for objects of this type depend upon the algorithm
- used to determine the retransmission timeout. In
- particular, when the timeout algorithm is rsre(3),
- an object of this type has the semantics of the
- UBOUND quantity described in RFC 793."
- ::= { tcp 3 }
-
- tcpMaxConn OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The limit on the total number of TCP connections
- the entity can support. In entities where the
- maximum number of connections is dynamic, this
- object should contain the value -1."
- ::= { tcp 4 }
-
- tcpActiveOpens OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of times TCP connections have made a
- direct transition to the SYN-SENT state from the
- CLOSED state."
- ::= { tcp 5 }
-
- tcpPassiveOpens OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of times TCP connections have made a
- direct transition to the SYN-RCVD state from the
- LISTEN state."
- ::= { tcp 6 }
-
-
-
-SNMP Working Group [Page 47]
-\f
-RFC 1213 MIB-II March 1991
-
-
- tcpAttemptFails OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of times TCP connections have made a
- direct transition to the CLOSED state from either
- the SYN-SENT state or the SYN-RCVD state, plus the
- number of times TCP connections have made a direct
- transition to the LISTEN state from the SYN-RCVD
- state."
- ::= { tcp 7 }
-
- tcpEstabResets OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of times TCP connections have made a
- direct transition to the CLOSED state from either
- the ESTABLISHED state or the CLOSE-WAIT state."
- ::= { tcp 8 }
-
- tcpCurrEstab OBJECT-TYPE
- SYNTAX Gauge
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of TCP connections for which the
- current state is either ESTABLISHED or CLOSE-
- WAIT."
- ::= { tcp 9 }
-
- tcpInSegs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of segments received, including
- those received in error. This count includes
- segments received on currently established
- connections."
- ::= { tcp 10 }
-
- tcpOutSegs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
-
-
-
-SNMP Working Group [Page 48]
-\f
-RFC 1213 MIB-II March 1991
-
-
- DESCRIPTION
- "The total number of segments sent, including
- those on current connections but excluding those
- containing only retransmitted octets."
- ::= { tcp 11 }
-
- tcpRetransSegs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of segments retransmitted - that
- is, the number of TCP segments transmitted
- containing one or more previously transmitted
- octets."
- ::= { tcp 12 }
-
-
- -- the TCP Connection table
-
- -- The TCP connection table contains information about this
- -- entity's existing TCP connections.
-
- tcpConnTable OBJECT-TYPE
- SYNTAX SEQUENCE OF TcpConnEntry
- ACCESS not-accessible
- STATUS mandatory
- DESCRIPTION
- "A table containing TCP connection-specific
- information."
- ::= { tcp 13 }
-
- tcpConnEntry OBJECT-TYPE
- SYNTAX TcpConnEntry
- ACCESS not-accessible
- STATUS mandatory
- DESCRIPTION
- "Information about a particular current TCP
- connection. An object of this type is transient,
- in that it ceases to exist when (or soon after)
- the connection makes the transition to the CLOSED
- state."
- INDEX { tcpConnLocalAddress,
- tcpConnLocalPort,
- tcpConnRemAddress,
- tcpConnRemPort }
- ::= { tcpConnTable 1 }
-
-
-
-
-SNMP Working Group [Page 49]
-\f
-RFC 1213 MIB-II March 1991
-
-
- TcpConnEntry ::=
- SEQUENCE {
- tcpConnState
- INTEGER,
- tcpConnLocalAddress
- IpAddress,
- tcpConnLocalPort
- INTEGER (0..65535),
- tcpConnRemAddress
- IpAddress,
- tcpConnRemPort
- INTEGER (0..65535)
- }
-
- tcpConnState OBJECT-TYPE
- SYNTAX INTEGER {
- closed(1),
- listen(2),
- synSent(3),
- synReceived(4),
- established(5),
- finWait1(6),
- finWait2(7),
- closeWait(8),
- lastAck(9),
- closing(10),
- timeWait(11),
- deleteTCB(12)
- }
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "The state of this TCP connection.
-
- The only value which may be set by a management
- station is deleteTCB(12). Accordingly, it is
- appropriate for an agent to return a `badValue'
- response if a management station attempts to set
- this object to any other value.
-
- If a management station sets this object to the
- value deleteTCB(12), then this has the effect of
- deleting the TCB (as defined in RFC 793) of the
- corresponding connection on the managed node,
- resulting in immediate termination of the
- connection.
-
- As an implementation-specific option, a RST
-
-
-
-SNMP Working Group [Page 50]
-\f
-RFC 1213 MIB-II March 1991
-
-
- segment may be sent from the managed node to the
- other TCP endpoint (note however that RST segments
- are not sent reliably)."
- ::= { tcpConnEntry 1 }
-
- tcpConnLocalAddress OBJECT-TYPE
- SYNTAX IpAddress
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The local IP address for this TCP connection. In
- the case of a connection in the listen state which
- is willing to accept connections for any IP
- interface associated with the node, the value
- 0.0.0.0 is used."
- ::= { tcpConnEntry 2 }
-
- tcpConnLocalPort OBJECT-TYPE
- SYNTAX INTEGER (0..65535)
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The local port number for this TCP connection."
- ::= { tcpConnEntry 3 }
-
- tcpConnRemAddress OBJECT-TYPE
- SYNTAX IpAddress
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The remote IP address for this TCP connection."
- ::= { tcpConnEntry 4 }
-
- tcpConnRemPort OBJECT-TYPE
- SYNTAX INTEGER (0..65535)
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The remote port number for this TCP connection."
- ::= { tcpConnEntry 5 }
-
-
- -- additional TCP objects
-
- tcpInErrs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
-
-
-
-SNMP Working Group [Page 51]
-\f
-RFC 1213 MIB-II March 1991
-
-
- DESCRIPTION
- "The total number of segments received in error
- (e.g., bad TCP checksums)."
- ::= { tcp 14 }
-
- tcpOutRsts OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of TCP segments sent containing the
- RST flag."
- ::= { tcp 15 }
-
-
- -- the UDP group
-
- -- Implementation of the UDP group is mandatory for all
- -- systems which implement the UDP.
-
- udpInDatagrams OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of UDP datagrams delivered to
- UDP users."
- ::= { udp 1 }
-
- udpNoPorts OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of received UDP datagrams for
- which there was no application at the destination
- port."
- ::= { udp 2 }
-
- udpInErrors OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of received UDP datagrams that could
- not be delivered for reasons other than the lack
- of an application at the destination port."
- ::= { udp 3 }
-
-
-
-SNMP Working Group [Page 52]
-\f
-RFC 1213 MIB-II March 1991
-
-
- udpOutDatagrams OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of UDP datagrams sent from this
- entity."
- ::= { udp 4 }
-
-
- -- the UDP Listener table
-
- -- The UDP listener table contains information about this
- -- entity's UDP end-points on which a local application is
- -- currently accepting datagrams.
-
- udpTable OBJECT-TYPE
- SYNTAX SEQUENCE OF UdpEntry
- ACCESS not-accessible
- STATUS mandatory
- DESCRIPTION
- "A table containing UDP listener information."
- ::= { udp 5 }
-
- udpEntry OBJECT-TYPE
- SYNTAX UdpEntry
- ACCESS not-accessible
- STATUS mandatory
- DESCRIPTION
- "Information about a particular current UDP
- listener."
- INDEX { udpLocalAddress, udpLocalPort }
- ::= { udpTable 1 }
-
- UdpEntry ::=
- SEQUENCE {
- udpLocalAddress
- IpAddress,
- udpLocalPort
- INTEGER (0..65535)
- }
-
- udpLocalAddress OBJECT-TYPE
- SYNTAX IpAddress
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The local IP address for this UDP listener. In
-
-
-
-SNMP Working Group [Page 53]
-\f
-RFC 1213 MIB-II March 1991
-
-
- the case of a UDP listener which is willing to
- accept datagrams for any IP interface associated
- with the node, the value 0.0.0.0 is used."
- ::= { udpEntry 1 }
-
- udpLocalPort OBJECT-TYPE
- SYNTAX INTEGER (0..65535)
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The local port number for this UDP listener."
- ::= { udpEntry 2 }
-
-
- -- the EGP group
-
- -- Implementation of the EGP group is mandatory for all
- -- systems which implement the EGP.
-
- egpInMsgs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of EGP messages received without
- error."
- ::= { egp 1 }
-
- egpInErrors OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of EGP messages received that proved
- to be in error."
- ::= { egp 2 }
-
- egpOutMsgs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of locally generated EGP
- messages."
- ::= { egp 3 }
-
- egpOutErrors OBJECT-TYPE
- SYNTAX Counter
-
-
-
-SNMP Working Group [Page 54]
-\f
-RFC 1213 MIB-II March 1991
-
-
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of locally generated EGP messages not
- sent due to resource limitations within an EGP
- entity."
- ::= { egp 4 }
-
-
- -- the EGP Neighbor table
-
- -- The EGP neighbor table contains information about this
- -- entity's EGP neighbors.
-
- egpNeighTable OBJECT-TYPE
- SYNTAX SEQUENCE OF EgpNeighEntry
- ACCESS not-accessible
- STATUS mandatory
- DESCRIPTION
- "The EGP neighbor table."
- ::= { egp 5 }
-
- egpNeighEntry OBJECT-TYPE
- SYNTAX EgpNeighEntry
- ACCESS not-accessible
- STATUS mandatory
- DESCRIPTION
- "Information about this entity's relationship with
- a particular EGP neighbor."
- INDEX { egpNeighAddr }
- ::= { egpNeighTable 1 }
-
- EgpNeighEntry ::=
- SEQUENCE {
- egpNeighState
- INTEGER,
- egpNeighAddr
- IpAddress,
- egpNeighAs
- INTEGER,
- egpNeighInMsgs
- Counter,
- egpNeighInErrs
- Counter,
- egpNeighOutMsgs
- Counter,
- egpNeighOutErrs
- Counter,
-
-
-
-SNMP Working Group [Page 55]
-\f
-RFC 1213 MIB-II March 1991
-
-
- egpNeighInErrMsgs
- Counter,
- egpNeighOutErrMsgs
- Counter,
- egpNeighStateUps
- Counter,
- egpNeighStateDowns
- Counter,
- egpNeighIntervalHello
- INTEGER,
- egpNeighIntervalPoll
- INTEGER,
- egpNeighMode
- INTEGER,
- egpNeighEventTrigger
- INTEGER
- }
-
- egpNeighState OBJECT-TYPE
- SYNTAX INTEGER {
- idle(1),
- acquisition(2),
- down(3),
- up(4),
- cease(5)
- }
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The EGP state of the local system with respect to
- this entry's EGP neighbor. Each EGP state is
- represented by a value that is one greater than
- the numerical value associated with said state in
- RFC 904."
- ::= { egpNeighEntry 1 }
-
- egpNeighAddr OBJECT-TYPE
- SYNTAX IpAddress
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The IP address of this entry's EGP neighbor."
- ::= { egpNeighEntry 2 }
-
- egpNeighAs OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-only
- STATUS mandatory
-
-
-
-SNMP Working Group [Page 56]
-\f
-RFC 1213 MIB-II March 1991
-
-
- DESCRIPTION
- "The autonomous system of this EGP peer. Zero
- should be specified if the autonomous system
- number of the neighbor is not yet known."
- ::= { egpNeighEntry 3 }
-
- egpNeighInMsgs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of EGP messages received without error
- from this EGP peer."
- ::= { egpNeighEntry 4 }
-
- egpNeighInErrs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of EGP messages received from this EGP
- peer that proved to be in error (e.g., bad EGP
- checksum)."
- ::= { egpNeighEntry 5 }
-
- egpNeighOutMsgs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of locally generated EGP messages to
- this EGP peer."
- ::= { egpNeighEntry 6 }
-
- egpNeighOutErrs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of locally generated EGP messages not
- sent to this EGP peer due to resource limitations
- within an EGP entity."
- ::= { egpNeighEntry 7 }
-
- egpNeighInErrMsgs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
-
-
-
-SNMP Working Group [Page 57]
-\f
-RFC 1213 MIB-II March 1991
-
-
- DESCRIPTION
- "The number of EGP-defined error messages received
- from this EGP peer."
- ::= { egpNeighEntry 8 }
-
- egpNeighOutErrMsgs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of EGP-defined error messages sent to
- this EGP peer."
- ::= { egpNeighEntry 9 }
-
- egpNeighStateUps OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of EGP state transitions to the UP
- state with this EGP peer."
- ::= { egpNeighEntry 10 }
-
- egpNeighStateDowns OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The number of EGP state transitions from the UP
- state to any other state with this EGP peer."
- ::= { egpNeighEntry 11 }
-
- egpNeighIntervalHello OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The interval between EGP Hello command
- retransmissions (in hundredths of a second). This
- represents the t1 timer as defined in RFC 904."
- ::= { egpNeighEntry 12 }
-
- egpNeighIntervalPoll OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The interval between EGP poll command
-
-
-
-SNMP Working Group [Page 58]
-\f
-RFC 1213 MIB-II March 1991
-
-
- retransmissions (in hundredths of a second). This
- represents the t3 timer as defined in RFC 904."
- ::= { egpNeighEntry 13 }
-
- egpNeighMode OBJECT-TYPE
- SYNTAX INTEGER { active(1), passive(2) }
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The polling mode of this EGP entity, either
- passive or active."
- ::= { egpNeighEntry 14 }
-
- egpNeighEventTrigger OBJECT-TYPE
- SYNTAX INTEGER { start(1), stop(2) }
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "A control variable used to trigger operator-
- initiated Start and Stop events. When read, this
- variable always returns the most recent value that
- egpNeighEventTrigger was set to. If it has not
- been set since the last initialization of the
- network management subsystem on the node, it
- returns a value of `stop'.
-
- When set, this variable causes a Start or Stop
- event on the specified neighbor, as specified on
- pages 8-10 of RFC 904. Briefly, a Start event
- causes an Idle peer to begin neighbor acquisition
- and a non-Idle peer to reinitiate neighbor
- acquisition. A stop event causes a non-Idle peer
- to return to the Idle state until a Start event
- occurs, either via egpNeighEventTrigger or
- otherwise."
- ::= { egpNeighEntry 15 }
-
-
- -- additional EGP objects
-
- egpAs OBJECT-TYPE
- SYNTAX INTEGER
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The autonomous system number of this EGP entity."
- ::= { egp 6 }
-
-
-
-
-SNMP Working Group [Page 59]
-\f
-RFC 1213 MIB-II March 1991
-
-
- -- the Transmission group
-
- -- Based on the transmission media underlying each interface
- -- on a system, the corresponding portion of the Transmission
- -- group is mandatory for that system.
-
- -- When Internet-standard definitions for managing
- -- transmission media are defined, the transmission group is
- -- used to provide a prefix for the names of those objects.
-
- -- Typically, such definitions reside in the experimental
- -- portion of the MIB until they are "proven", then as a
- -- part of the Internet standardization process, the
- -- definitions are accordingly elevated and a new object
- -- identifier, under the transmission group is defined. By
- -- convention, the name assigned is:
- --
- -- type OBJECT IDENTIFIER ::= { transmission number }
- --
- -- where "type" is the symbolic value used for the media in
- -- the ifType column of the ifTable object, and "number" is
- -- the actual integer value corresponding to the symbol.
-
-
- -- the SNMP group
-
- -- Implementation of the SNMP group is mandatory for all
- -- systems which support an SNMP protocol entity. Some of
- -- the objects defined below will be zero-valued in those
- -- SNMP implementations that are optimized to support only
- -- those functions specific to either a management agent or
- -- a management station. In particular, it should be
- -- observed that the objects below refer to an SNMP entity,
- -- and there may be several SNMP entities residing on a
- -- managed node (e.g., if the node is hosting acting as
- -- a management station).
-
- snmpInPkts OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of Messages delivered to the
- SNMP entity from the transport service."
- ::= { snmp 1 }
-
- snmpOutPkts OBJECT-TYPE
- SYNTAX Counter
-
-
-
-SNMP Working Group [Page 60]
-\f
-RFC 1213 MIB-II March 1991
-
-
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP Messages which were
- passed from the SNMP protocol entity to the
- transport service."
- ::= { snmp 2 }
-
- snmpInBadVersions OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP Messages which were
- delivered to the SNMP protocol entity and were for
- an unsupported SNMP version."
- ::= { snmp 3 }
-
- snmpInBadCommunityNames OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP Messages delivered to
- the SNMP protocol entity which used a SNMP
- community name not known to said entity."
- ::= { snmp 4 }
-
- snmpInBadCommunityUses OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP Messages delivered to
- the SNMP protocol entity which represented an SNMP
- operation which was not allowed by the SNMP
- community named in the Message."
- ::= { snmp 5 }
-
- snmpInASNParseErrs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of ASN.1 or BER errors
- encountered by the SNMP protocol entity when
- decoding received SNMP Messages."
- ::= { snmp 6 }
-
-
-
-SNMP Working Group [Page 61]
-\f
-RFC 1213 MIB-II March 1991
-
-
- -- { snmp 7 } is not used
-
- snmpInTooBigs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP PDUs which were
- delivered to the SNMP protocol entity and for
- which the value of the error-status field is
- `tooBig'."
- ::= { snmp 8 }
-
- snmpInNoSuchNames OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP PDUs which were
- delivered to the SNMP protocol entity and for
- which the value of the error-status field is
- `noSuchName'."
- ::= { snmp 9 }
-
- snmpInBadValues OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP PDUs which were
- delivered to the SNMP protocol entity and for
- which the value of the error-status field is
- `badValue'."
- ::= { snmp 10 }
-
- snmpInReadOnlys OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number valid SNMP PDUs which were
- delivered to the SNMP protocol entity and for
- which the value of the error-status field is
- `readOnly'. It should be noted that it is a
- protocol error to generate an SNMP PDU which
- contains the value `readOnly' in the error-status
- field, as such this object is provided as a means
- of detecting incorrect implementations of the
-
-
-
-SNMP Working Group [Page 62]
-\f
-RFC 1213 MIB-II March 1991
-
-
- SNMP."
- ::= { snmp 11 }
-
- snmpInGenErrs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP PDUs which were
- delivered to the SNMP protocol entity and for
- which the value of the error-status field is
- `genErr'."
- ::= { snmp 12 }
-
- snmpInTotalReqVars OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of MIB objects which have been
- retrieved successfully by the SNMP protocol entity
- as the result of receiving valid SNMP Get-Request
- and Get-Next PDUs."
- ::= { snmp 13 }
-
- snmpInTotalSetVars OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of MIB objects which have been
- altered successfully by the SNMP protocol entity
- as the result of receiving valid SNMP Set-Request
- PDUs."
- ::= { snmp 14 }
-
- snmpInGetRequests OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP Get-Request PDUs which
- have been accepted and processed by the SNMP
- protocol entity."
- ::= { snmp 15 }
-
- snmpInGetNexts OBJECT-TYPE
- SYNTAX Counter
-
-
-
-SNMP Working Group [Page 63]
-\f
-RFC 1213 MIB-II March 1991
-
-
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP Get-Next PDUs which have
- been accepted and processed by the SNMP protocol
- entity."
- ::= { snmp 16 }
-
- snmpInSetRequests OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP Set-Request PDUs which
- have been accepted and processed by the SNMP
- protocol entity."
- ::= { snmp 17 }
-
- snmpInGetResponses OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP Get-Response PDUs which
- have been accepted and processed by the SNMP
- protocol entity."
- ::= { snmp 18 }
-
- snmpInTraps OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP Trap PDUs which have
- been accepted and processed by the SNMP protocol
- entity."
- ::= { snmp 19 }
-
- snmpOutTooBigs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP PDUs which were
- generated by the SNMP protocol entity and for
- which the value of the error-status field is
- `tooBig.'"
- ::= { snmp 20 }
-
-
-
-SNMP Working Group [Page 64]
-\f
-RFC 1213 MIB-II March 1991
-
-
- snmpOutNoSuchNames OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP PDUs which were
- generated by the SNMP protocol entity and for
- which the value of the error-status is
- `noSuchName'."
- ::= { snmp 21 }
-
- snmpOutBadValues OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP PDUs which were
- generated by the SNMP protocol entity and for
- which the value of the error-status field is
- `badValue'."
- ::= { snmp 22 }
-
- -- { snmp 23 } is not used
-
- snmpOutGenErrs OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP PDUs which were
- generated by the SNMP protocol entity and for
- which the value of the error-status field is
- `genErr'."
- ::= { snmp 24 }
-
- snmpOutGetRequests OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP Get-Request PDUs which
- have been generated by the SNMP protocol entity."
- ::= { snmp 25 }
-
- snmpOutGetNexts OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
-
-
-
-SNMP Working Group [Page 65]
-\f
-RFC 1213 MIB-II March 1991
-
-
- DESCRIPTION
- "The total number of SNMP Get-Next PDUs which have
- been generated by the SNMP protocol entity."
- ::= { snmp 26 }
-
- snmpOutSetRequests OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP Set-Request PDUs which
- have been generated by the SNMP protocol entity."
- ::= { snmp 27 }
-
- snmpOutGetResponses OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP Get-Response PDUs which
- have been generated by the SNMP protocol entity."
- ::= { snmp 28 }
-
- snmpOutTraps OBJECT-TYPE
- SYNTAX Counter
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The total number of SNMP Trap PDUs which have
- been generated by the SNMP protocol entity."
- ::= { snmp 29 }
-
- snmpEnableAuthenTraps OBJECT-TYPE
- SYNTAX INTEGER { enabled(1), disabled(2) }
- ACCESS read-write
- STATUS mandatory
- DESCRIPTION
- "Indicates whether the SNMP agent process is
- permitted to generate authentication-failure
- traps. The value of this object overrides any
- configuration information; as such, it provides a
- means whereby all authentication-failure traps may
- be disabled.
-
- Note that it is strongly recommended that this
- object be stored in non-volatile memory so that it
- remains constant between re-initializations of the
- network management system."
-
-
-
-SNMP Working Group [Page 66]
-\f
-RFC 1213 MIB-II March 1991
-
-
- ::= { snmp 30 }
-
- END
-
-7. Acknowledgements
-
- This document was produced by the SNMP Working Group:
-
- Anne Ambler, Spider
- Karl Auerbach, Sun
- Fred Baker, ACC
- David Bridgham, Epilogue Technology
- Ken Brinkerhoff
- Ron Broersma, NOSC
- Brian Brown, Synoptics
- Jack Brown, US Army
- Theodore Brunner, Bellcore
- Jeff Buffum, HP
- Jeffrey Buffum, HP
- John Burress, Wellfleet
- Jeffrey D. Case, University of Tennessee at Knoxville
- Chris Chiptasso, Spartacus
- Paul Ciarfella, DEC
- Bob Collet
- John Cook, Chipcom
- Tracy Cox, Bellcore
- James R. Davin, MIT-LCS
- Eric Decker, cisco
- Kurt Dobbins, Cabletron
- Nadya El-Afandi, Network Systems
- Gary Ellis, HP
- Fred Engle
- Mike Erlinger
- Mark S. Fedor, PSI
- Richard Fox, Synoptics
- Karen Frisa, CMU
- Stan Froyd, ACC
- Chris Gunner, DEC
- Fred Harris, University of Tennessee at Knoxville
- Ken Hibbard, Xylogics
- Ole Jacobsen, Interop
- Ken Jones
- Satish Joshi, Synoptics
- Frank Kastenholz, Racal-Interlan
- Shimshon Kaufman, Spartacus
- Ken Key, University of Tennessee at Knoxville
- Jim Kinder, Fibercom
- Alex Koifman, BBN
-
-
-
-SNMP Working Group [Page 67]
-\f
-RFC 1213 MIB-II March 1991
-
-
- Christopher Kolb, PSI
- Cheryl Krupczak, NCR
- Paul Langille, DEC
- Martin Lee Schoffstall, PSI
- Peter Lin, Vitalink
- John Lunny, TWG
- Carl Malamud
- Gary Malkin, FTP Software, Inc.
- Randy Mayhew, University of Tennessee at Knoxville
- Keith McCloghrie, Hughes LAN Systems
- Donna McMaster, David Systems
- Lynn Monsanto, Sun
- Dave Perkins, 3COM
- Jim Reinstedler, Ungerman Bass
- Anil Rijsinghani, DEC
- Kathy Rinehart, Arnold AFB
- Kary Robertson
- Marshall T. Rose, PSI (chair)
- L. Michael Sabo, NCSC
- Jon Saperia, DEC
- Greg Satz, cisco
- Martin Schoffstall, PSI
- John Seligson
- Steve Sherry, Xyplex
- Fei Shu, NEC
- Sam Sjogren, TGV
- Mark Sleeper, Sparta
- Lance Sprung
- Mike St.Johns
- Bob Stewart, Xyplex
- Emil Sturniold
- Kaj Tesink, Bellcore
- Geoff Thompson, Synoptics
- Dean Throop, Data General
- Bill Townsend, Xylogics
- Maurice Turcotte, Racal-Milgo
- Kannan Varadhou
- Sudhanshu Verma, HP
- Bill Versteeg, Network Research Corporation
- Warren Vik, Interactive Systems
- David Waitzman, BBN
- Steve Waldbusser, CMU
- Dan Wintringhan
- David Wood
- Wengyik Yeong, PSI
- Jeff Young, Cray Research
-
-
-
-
-
-SNMP Working Group [Page 68]
-\f
-RFC 1213 MIB-II March 1991
-
-
- In addition, the comments of the following individuals are also
- acknolwedged:
-
- Craig A. Finseth, Minnesota Supercomputer Center, Inc.
- Jeffrey C. Honig, Cornell University Theory Center
- Philip R. Karn, Bellcore
-
-8. References
-
- [1] Cerf, V., "IAB Recommendations for the Development of Internet
- Network Management Standards", RFC 1052, NRI, April 1988.
-
- [2] Rose M., and K. McCloghrie, "Structure and Identification of
- Management Information for TCP/IP-based internets," RFC 1065,
- TWG, August 1988.
-
- [3] McCloghrie, K., and M. Rose, "Management Information Base for
- Network Management of TCP/IP-based internets, RFC 1066, TWG,
- August 1988.
-
- [4] Cerf, V., "Report of the Second Ad Hoc Network Management Review
- Group", RFC 1109, NRI, August 1989.
-
- [5] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple
- Network Management Protocol (SNMP)", RFC 1098, University of
- Tennessee at Knoxville, NYSERNet, Inc., Rensselaer Polytechnic
- Institute, MIT Laboratory for Computer Science, April 1989.
-
- [6] Postel, J., and J. Reynolds, "TELNET Protocol Specification", RFC
- 854, USC/Information Sciences Institute, May 1983.
-
- [7] Satz, G., "Connectionless Network Protocol (ISO 8473) and End
- System to Intermediate System (ISO 9542) Management Information
- Base", RFC 1162, cisco Systems, Inc., June 1990.
-
- [8] Information processing systems - Open Systems Interconnection -
- Specification of Abstract Syntax Notation One (ASN.1),
- International Organization for Standardization, International
- Standard 8824, December 1987.
-
- [9] Information processing systems - Open Systems Interconnection -
- Specification of Basic Encoding Rules for Abstract Notation One
- (ASN.1), International Organization for Standardization,
- International Standard 8825, December 1987.
-
- [10] Jacobson, V., "Congestion Avoidance and Control", SIGCOMM 1988,
- Stanford, California.
-
-
-
-
-SNMP Working Group [Page 69]
-\f
-RFC 1213 MIB-II March 1991
-
-
- [11] Hagens, R., Hall, N., and M. Rose, "Use of the Internet as a
- Subnetwork for Experimentation with the OSI Network Layer", RFC
- 1070, U of Wiscsonsin - Madison, U of Wiscsonsin - Madison, The
- Wollongong Group, February 1989.
-
- [12] Rose M., and K. McCloghrie, "Structure and Identification of
- Management Information for TCP/IP-based internets", RFC 1155,
- Performance Systems International, Hughes LAN Systems, May 1990.
-
- [13] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple
- Network Management Protocol", RFC 1157, SNMP Research,
- Performance Systems International, Performance Systems
- International, MIT Laboratory for Computer Science, May 1990.
-
- [14] Rose, M., and K. McCloghrie, Editors, "Concise MIB Definitions",
- RFC 1212, Performance Systems International, Hughes LAN Systems,
- March 1991.
-
-9. Security Considerations
-
- Security issues are not discussed in this memo.
-
-10. Authors' Addresses
-
- Keith McCloghrie
- Hughes LAN Systems
- 1225 Charleston Road
- Mountain View, CA 94043
- 1225 Charleston Road
- Mountain View, CA 94043
-
- Phone: (415) 966-7934
-
- EMail: kzm@hls.com
-
-
- Marshall T. Rose
- Performance Systems International
- 5201 Great America Parkway
- Suite 3106
- Santa Clara, CA 95054
-
- Phone: +1 408 562 6222
-
- EMail: mrose@psi.com
- X.500: rose, psi, us
-
-
-
-
-
-SNMP Working Group [Page 70]
-\f
\ No newline at end of file
+++ /dev/null
-
-
-
-
-
-
-Network Working Group R. Rivest
-Request for Comments: 1321 MIT Laboratory for Computer Science
- and RSA Data Security, Inc.
- April 1992
-
-
- The MD5 Message-Digest Algorithm
-
-Status of this Memo
-
- This memo provides information for the Internet community. It does
- not specify an Internet standard. Distribution of this memo is
- unlimited.
-
-Acknowlegements
-
- We would like to thank Don Coppersmith, Burt Kaliski, Ralph Merkle,
- David Chaum, and Noam Nisan for numerous helpful comments and
- suggestions.
-
-Table of Contents
-
- 1. Executive Summary 1
- 2. Terminology and Notation 2
- 3. MD5 Algorithm Description 3
- 4. Summary 6
- 5. Differences Between MD4 and MD5 6
- References 7
- APPENDIX A - Reference Implementation 7
- Security Considerations 21
- Author's Address 21
-
-1. Executive Summary
-
- This document describes the MD5 message-digest algorithm. The
- algorithm takes as input a message of arbitrary length and produces
- as output a 128-bit "fingerprint" or "message digest" of the input.
- It is conjectured that it is computationally infeasible to produce
- two messages having the same message digest, or to produce any
- message having a given prespecified target message digest. The MD5
- algorithm is intended for digital signature applications, where a
- large file must be "compressed" in a secure manner before being
- encrypted with a private (secret) key under a public-key cryptosystem
- such as RSA.
-
-
-
-
-
-
-
-Rivest [Page 1]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
- The MD5 algorithm is designed to be quite fast on 32-bit machines. In
- addition, the MD5 algorithm does not require any large substitution
- tables; the algorithm can be coded quite compactly.
-
- The MD5 algorithm is an extension of the MD4 message-digest algorithm
- 1,2]. MD5 is slightly slower than MD4, but is more "conservative" in
- design. MD5 was designed because it was felt that MD4 was perhaps
- being adopted for use more quickly than justified by the existing
- critical review; because MD4 was designed to be exceptionally fast,
- it is "at the edge" in terms of risking successful cryptanalytic
- attack. MD5 backs off a bit, giving up a little in speed for a much
- greater likelihood of ultimate security. It incorporates some
- suggestions made by various reviewers, and contains additional
- optimizations. The MD5 algorithm is being placed in the public domain
- for review and possible adoption as a standard.
-
- For OSI-based applications, MD5's object identifier is
-
- md5 OBJECT IDENTIFIER ::=
- iso(1) member-body(2) US(840) rsadsi(113549) digestAlgorithm(2) 5}
-
- In the X.509 type AlgorithmIdentifier [3], the parameters for MD5
- should have type NULL.
-
-2. Terminology and Notation
-
- In this document a "word" is a 32-bit quantity and a "byte" is an
- eight-bit quantity. A sequence of bits can be interpreted in a
- natural manner as a sequence of bytes, where each consecutive group
- of eight bits is interpreted as a byte with the high-order (most
- significant) bit of each byte listed first. Similarly, a sequence of
- bytes can be interpreted as a sequence of 32-bit words, where each
- consecutive group of four bytes is interpreted as a word with the
- low-order (least significant) byte given first.
-
- Let x_i denote "x sub i". If the subscript is an expression, we
- surround it in braces, as in x_{i+1}. Similarly, we use ^ for
- superscripts (exponentiation), so that x^i denotes x to the i-th
- power.
-
- Let the symbol "+" denote addition of words (i.e., modulo-2^32
- addition). Let X <<< s denote the 32-bit value obtained by circularly
- shifting (rotating) X left by s bit positions. Let not(X) denote the
- bit-wise complement of X, and let X v Y denote the bit-wise OR of X
- and Y. Let X xor Y denote the bit-wise XOR of X and Y, and let XY
- denote the bit-wise AND of X and Y.
-
-
-
-
-
-Rivest [Page 2]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
-3. MD5 Algorithm Description
-
- We begin by supposing that we have a b-bit message as input, and that
- we wish to find its message digest. Here b is an arbitrary
- nonnegative integer; b may be zero, it need not be a multiple of
- eight, and it may be arbitrarily large. We imagine the bits of the
- message written down as follows:
-
- m_0 m_1 ... m_{b-1}
-
- The following five steps are performed to compute the message digest
- of the message.
-
-3.1 Step 1. Append Padding Bits
-
- The message is "padded" (extended) so that its length (in bits) is
- congruent to 448, modulo 512. That is, the message is extended so
- that it is just 64 bits shy of being a multiple of 512 bits long.
- Padding is always performed, even if the length of the message is
- already congruent to 448, modulo 512.
-
- Padding is performed as follows: a single "1" bit is appended to the
- message, and then "0" bits are appended so that the length in bits of
- the padded message becomes congruent to 448, modulo 512. In all, at
- least one bit and at most 512 bits are appended.
-
-3.2 Step 2. Append Length
-
- A 64-bit representation of b (the length of the message before the
- padding bits were added) is appended to the result of the previous
- step. In the unlikely event that b is greater than 2^64, then only
- the low-order 64 bits of b are used. (These bits are appended as two
- 32-bit words and appended low-order word first in accordance with the
- previous conventions.)
-
- At this point the resulting message (after padding with bits and with
- b) has a length that is an exact multiple of 512 bits. Equivalently,
- this message has a length that is an exact multiple of 16 (32-bit)
- words. Let M[0 ... N-1] denote the words of the resulting message,
- where N is a multiple of 16.
-
-3.3 Step 3. Initialize MD Buffer
-
- A four-word buffer (A,B,C,D) is used to compute the message digest.
- Here each of A, B, C, D is a 32-bit register. These registers are
- initialized to the following values in hexadecimal, low-order bytes
- first):
-
-
-
-
-Rivest [Page 3]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
- word A: 01 23 45 67
- word B: 89 ab cd ef
- word C: fe dc ba 98
- word D: 76 54 32 10
-
-3.4 Step 4. Process Message in 16-Word Blocks
-
- We first define four auxiliary functions that each take as input
- three 32-bit words and produce as output one 32-bit word.
-
- F(X,Y,Z) = XY v not(X) Z
- G(X,Y,Z) = XZ v Y not(Z)
- H(X,Y,Z) = X xor Y xor Z
- I(X,Y,Z) = Y xor (X v not(Z))
-
- In each bit position F acts as a conditional: if X then Y else Z.
- The function F could have been defined using + instead of v since XY
- and not(X)Z will never have 1's in the same bit position.) It is
- interesting to note that if the bits of X, Y, and Z are independent
- and unbiased, the each bit of F(X,Y,Z) will be independent and
- unbiased.
-
- The functions G, H, and I are similar to the function F, in that they
- act in "bitwise parallel" to produce their output from the bits of X,
- Y, and Z, in such a manner that if the corresponding bits of X, Y,
- and Z are independent and unbiased, then each bit of G(X,Y,Z),
- H(X,Y,Z), and I(X,Y,Z) will be independent and unbiased. Note that
- the function H is the bit-wise "xor" or "parity" function of its
- inputs.
-
- This step uses a 64-element table T[1 ... 64] constructed from the
- sine function. Let T[i] denote the i-th element of the table, which
- is equal to the integer part of 4294967296 times abs(sin(i)), where i
- is in radians. The elements of the table are given in the appendix.
-
- Do the following:
-
- /* Process each 16-word block. */
- For i = 0 to N/16-1 do
-
- /* Copy block i into X. */
- For j = 0 to 15 do
- Set X[j] to M[i*16+j].
- end /* of loop on j */
-
- /* Save A as AA, B as BB, C as CC, and D as DD. */
- AA = A
- BB = B
-
-
-
-Rivest [Page 4]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
- CC = C
- DD = D
-
- /* Round 1. */
- /* Let [abcd k s i] denote the operation
- a = b + ((a + F(b,c,d) + X[k] + T[i]) <<< s). */
- /* Do the following 16 operations. */
- [ABCD 0 7 1] [DABC 1 12 2] [CDAB 2 17 3] [BCDA 3 22 4]
- [ABCD 4 7 5] [DABC 5 12 6] [CDAB 6 17 7] [BCDA 7 22 8]
- [ABCD 8 7 9] [DABC 9 12 10] [CDAB 10 17 11] [BCDA 11 22 12]
- [ABCD 12 7 13] [DABC 13 12 14] [CDAB 14 17 15] [BCDA 15 22 16]
-
- /* Round 2. */
- /* Let [abcd k s i] denote the operation
- a = b + ((a + G(b,c,d) + X[k] + T[i]) <<< s). */
- /* Do the following 16 operations. */
- [ABCD 1 5 17] [DABC 6 9 18] [CDAB 11 14 19] [BCDA 0 20 20]
- [ABCD 5 5 21] [DABC 10 9 22] [CDAB 15 14 23] [BCDA 4 20 24]
- [ABCD 9 5 25] [DABC 14 9 26] [CDAB 3 14 27] [BCDA 8 20 28]
- [ABCD 13 5 29] [DABC 2 9 30] [CDAB 7 14 31] [BCDA 12 20 32]
-
- /* Round 3. */
- /* Let [abcd k s t] denote the operation
- a = b + ((a + H(b,c,d) + X[k] + T[i]) <<< s). */
- /* Do the following 16 operations. */
- [ABCD 5 4 33] [DABC 8 11 34] [CDAB 11 16 35] [BCDA 14 23 36]
- [ABCD 1 4 37] [DABC 4 11 38] [CDAB 7 16 39] [BCDA 10 23 40]
- [ABCD 13 4 41] [DABC 0 11 42] [CDAB 3 16 43] [BCDA 6 23 44]
- [ABCD 9 4 45] [DABC 12 11 46] [CDAB 15 16 47] [BCDA 2 23 48]
-
- /* Round 4. */
- /* Let [abcd k s t] denote the operation
- a = b + ((a + I(b,c,d) + X[k] + T[i]) <<< s). */
- /* Do the following 16 operations. */
- [ABCD 0 6 49] [DABC 7 10 50] [CDAB 14 15 51] [BCDA 5 21 52]
- [ABCD 12 6 53] [DABC 3 10 54] [CDAB 10 15 55] [BCDA 1 21 56]
- [ABCD 8 6 57] [DABC 15 10 58] [CDAB 6 15 59] [BCDA 13 21 60]
- [ABCD 4 6 61] [DABC 11 10 62] [CDAB 2 15 63] [BCDA 9 21 64]
-
- /* Then perform the following additions. (That is increment each
- of the four registers by the value it had before this block
- was started.) */
- A = A + AA
- B = B + BB
- C = C + CC
- D = D + DD
-
- end /* of loop on i */
-
-
-
-Rivest [Page 5]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
-3.5 Step 5. Output
-
- The message digest produced as output is A, B, C, D. That is, we
- begin with the low-order byte of A, and end with the high-order byte
- of D.
-
- This completes the description of MD5. A reference implementation in
- C is given in the appendix.
-
-4. Summary
-
- The MD5 message-digest algorithm is simple to implement, and provides
- a "fingerprint" or message digest of a message of arbitrary length.
- It is conjectured that the difficulty of coming up with two messages
- having the same message digest is on the order of 2^64 operations,
- and that the difficulty of coming up with any message having a given
- message digest is on the order of 2^128 operations. The MD5 algorithm
- has been carefully scrutinized for weaknesses. It is, however, a
- relatively new algorithm and further security analysis is of course
- justified, as is the case with any new proposal of this sort.
-
-5. Differences Between MD4 and MD5
-
- The following are the differences between MD4 and MD5:
-
- 1. A fourth round has been added.
-
- 2. Each step now has a unique additive constant.
-
- 3. The function g in round 2 was changed from (XY v XZ v YZ) to
- (XZ v Y not(Z)) to make g less symmetric.
-
- 4. Each step now adds in the result of the previous step. This
- promotes a faster "avalanche effect".
-
- 5. The order in which input words are accessed in rounds 2 and
- 3 is changed, to make these patterns less like each other.
-
- 6. The shift amounts in each round have been approximately
- optimized, to yield a faster "avalanche effect." The shifts in
- different rounds are distinct.
-
-
-
-
-
-
-
-
-
-
-Rivest [Page 6]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
-References
-
- [1] Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT and
- RSA Data Security, Inc., April 1992.
-
- [2] Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes
- and S.A. Vanstone, editors, Advances in Cryptology - CRYPTO '90
- Proceedings, pages 303-311, Springer-Verlag, 1991.
-
- [3] CCITT Recommendation X.509 (1988), "The Directory -
- Authentication Framework."
-
-APPENDIX A - Reference Implementation
-
- This appendix contains the following files taken from RSAREF: A
- Cryptographic Toolkit for Privacy-Enhanced Mail:
-
- global.h -- global header file
-
- md5.h -- header file for MD5
-
- md5c.c -- source code for MD5
-
- For more information on RSAREF, send email to <rsaref@rsa.com>.
-
- The appendix also includes the following file:
-
- mddriver.c -- test driver for MD2, MD4 and MD5
-
- The driver compiles for MD5 by default but can compile for MD2 or MD4
- if the symbol MD is defined on the C compiler command line as 2 or 4.
-
- The implementation is portable and should work on many different
- plaforms. However, it is not difficult to optimize the implementation
- on particular platforms, an exercise left to the reader. For example,
- on "little-endian" platforms where the lowest-addressed byte in a 32-
- bit word is the least significant and there are no alignment
- restrictions, the call to Decode in MD5Transform can be replaced with
- a typecast.
-
-A.1 global.h
-
-/* GLOBAL.H - RSAREF types and constants
- */
-
-/* PROTOTYPES should be set to one if and only if the compiler supports
- function argument prototyping.
-The following makes PROTOTYPES default to 0 if it has not already
-
-
-
-Rivest [Page 7]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
- been defined with C compiler flags.
- */
-#ifndef PROTOTYPES
-#define PROTOTYPES 0
-#endif
-
-/* POINTER defines a generic pointer type */
-typedef unsigned char *POINTER;
-
-/* UINT2 defines a two byte word */
-typedef unsigned short int UINT2;
-
-/* UINT4 defines a four byte word */
-typedef unsigned long int UINT4;
-
-/* PROTO_LIST is defined depending on how PROTOTYPES is defined above.
-If using PROTOTYPES, then PROTO_LIST returns the list, otherwise it
- returns an empty list.
- */
-#if PROTOTYPES
-#define PROTO_LIST(list) list
-#else
-#define PROTO_LIST(list) ()
-#endif
-
-A.2 md5.h
-
-/* MD5.H - header file for MD5C.C
- */
-
-/* Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All
-rights reserved.
-
-License to copy and use this software is granted provided that it
-is identified as the "RSA Data Security, Inc. MD5 Message-Digest
-Algorithm" in all material mentioning or referencing this software
-or this function.
-
-License is also granted to make and use derivative works provided
-that such works are identified as "derived from the RSA Data
-Security, Inc. MD5 Message-Digest Algorithm" in all material
-mentioning or referencing the derived work.
-
-RSA Data Security, Inc. makes no representations concerning either
-the merchantability of this software or the suitability of this
-software for any particular purpose. It is provided "as is"
-without express or implied warranty of any kind.
-
-
-
-
-Rivest [Page 8]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
-These notices must be retained in any copies of any part of this
-documentation and/or software.
- */
-
-/* MD5 context. */
-typedef struct {
- UINT4 state[4]; /* state (ABCD) */
- UINT4 count[2]; /* number of bits, modulo 2^64 (lsb first) */
- unsigned char buffer[64]; /* input buffer */
-} MD5_CTX;
-
-void MD5Init PROTO_LIST ((MD5_CTX *));
-void MD5Update PROTO_LIST
- ((MD5_CTX *, unsigned char *, unsigned int));
-void MD5Final PROTO_LIST ((unsigned char [16], MD5_CTX *));
-
-A.3 md5c.c
-
-/* MD5C.C - RSA Data Security, Inc., MD5 message-digest algorithm
- */
-
-/* Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All
-rights reserved.
-
-License to copy and use this software is granted provided that it
-is identified as the "RSA Data Security, Inc. MD5 Message-Digest
-Algorithm" in all material mentioning or referencing this software
-or this function.
-
-License is also granted to make and use derivative works provided
-that such works are identified as "derived from the RSA Data
-Security, Inc. MD5 Message-Digest Algorithm" in all material
-mentioning or referencing the derived work.
-
-RSA Data Security, Inc. makes no representations concerning either
-the merchantability of this software or the suitability of this
-software for any particular purpose. It is provided "as is"
-without express or implied warranty of any kind.
-
-These notices must be retained in any copies of any part of this
-documentation and/or software.
- */
-
-#include "global.h"
-#include "md5.h"
-
-/* Constants for MD5Transform routine.
- */
-
-
-
-Rivest [Page 9]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
-#define S11 7
-#define S12 12
-#define S13 17
-#define S14 22
-#define S21 5
-#define S22 9
-#define S23 14
-#define S24 20
-#define S31 4
-#define S32 11
-#define S33 16
-#define S34 23
-#define S41 6
-#define S42 10
-#define S43 15
-#define S44 21
-
-static void MD5Transform PROTO_LIST ((UINT4 [4], unsigned char [64]));
-static void Encode PROTO_LIST
- ((unsigned char *, UINT4 *, unsigned int));
-static void Decode PROTO_LIST
- ((UINT4 *, unsigned char *, unsigned int));
-static void MD5_memcpy PROTO_LIST ((POINTER, POINTER, unsigned int));
-static void MD5_memset PROTO_LIST ((POINTER, int, unsigned int));
-
-static unsigned char PADDING[64] = {
- 0x80, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
- 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
- 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
-};
-
-/* F, G, H and I are basic MD5 functions.
- */
-#define F(x, y, z) (((x) & (y)) | ((~x) & (z)))
-#define G(x, y, z) (((x) & (z)) | ((y) & (~z)))
-#define H(x, y, z) ((x) ^ (y) ^ (z))
-#define I(x, y, z) ((y) ^ ((x) | (~z)))
-
-/* ROTATE_LEFT rotates x left n bits.
- */
-#define ROTATE_LEFT(x, n) (((x) << (n)) | ((x) >> (32-(n))))
-
-/* FF, GG, HH, and II transformations for rounds 1, 2, 3, and 4.
-Rotation is separate from addition to prevent recomputation.
- */
-#define FF(a, b, c, d, x, s, ac) { \
- (a) += F ((b), (c), (d)) + (x) + (UINT4)(ac); \
- (a) = ROTATE_LEFT ((a), (s)); \
-
-
-
-Rivest [Page 10]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
- (a) += (b); \
- }
-#define GG(a, b, c, d, x, s, ac) { \
- (a) += G ((b), (c), (d)) + (x) + (UINT4)(ac); \
- (a) = ROTATE_LEFT ((a), (s)); \
- (a) += (b); \
- }
-#define HH(a, b, c, d, x, s, ac) { \
- (a) += H ((b), (c), (d)) + (x) + (UINT4)(ac); \
- (a) = ROTATE_LEFT ((a), (s)); \
- (a) += (b); \
- }
-#define II(a, b, c, d, x, s, ac) { \
- (a) += I ((b), (c), (d)) + (x) + (UINT4)(ac); \
- (a) = ROTATE_LEFT ((a), (s)); \
- (a) += (b); \
- }
-
-/* MD5 initialization. Begins an MD5 operation, writing a new context.
- */
-void MD5Init (context)
-MD5_CTX *context; /* context */
-{
- context->count[0] = context->count[1] = 0;
- /* Load magic initialization constants.
-*/
- context->state[0] = 0x67452301;
- context->state[1] = 0xefcdab89;
- context->state[2] = 0x98badcfe;
- context->state[3] = 0x10325476;
-}
-
-/* MD5 block update operation. Continues an MD5 message-digest
- operation, processing another message block, and updating the
- context.
- */
-void MD5Update (context, input, inputLen)
-MD5_CTX *context; /* context */
-unsigned char *input; /* input block */
-unsigned int inputLen; /* length of input block */
-{
- unsigned int i, index, partLen;
-
- /* Compute number of bytes mod 64 */
- index = (unsigned int)((context->count[0] >> 3) & 0x3F);
-
- /* Update number of bits */
- if ((context->count[0] += ((UINT4)inputLen << 3))
-
-
-
-Rivest [Page 11]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
- < ((UINT4)inputLen << 3))
- context->count[1]++;
- context->count[1] += ((UINT4)inputLen >> 29);
-
- partLen = 64 - index;
-
- /* Transform as many times as possible.
-*/
- if (inputLen >= partLen) {
- MD5_memcpy
- ((POINTER)&context->buffer[index], (POINTER)input, partLen);
- MD5Transform (context->state, context->buffer);
-
- for (i = partLen; i + 63 < inputLen; i += 64)
- MD5Transform (context->state, &input[i]);
-
- index = 0;
- }
- else
- i = 0;
-
- /* Buffer remaining input */
- MD5_memcpy
- ((POINTER)&context->buffer[index], (POINTER)&input[i],
- inputLen-i);
-}
-
-/* MD5 finalization. Ends an MD5 message-digest operation, writing the
- the message digest and zeroizing the context.
- */
-void MD5Final (digest, context)
-unsigned char digest[16]; /* message digest */
-MD5_CTX *context; /* context */
-{
- unsigned char bits[8];
- unsigned int index, padLen;
-
- /* Save number of bits */
- Encode (bits, context->count, 8);
-
- /* Pad out to 56 mod 64.
-*/
- index = (unsigned int)((context->count[0] >> 3) & 0x3f);
- padLen = (index < 56) ? (56 - index) : (120 - index);
- MD5Update (context, PADDING, padLen);
-
- /* Append length (before padding) */
- MD5Update (context, bits, 8);
-
-
-
-Rivest [Page 12]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
- /* Store state in digest */
- Encode (digest, context->state, 16);
-
- /* Zeroize sensitive information.
-*/
- MD5_memset ((POINTER)context, 0, sizeof (*context));
-}
-
-/* MD5 basic transformation. Transforms state based on block.
- */
-static void MD5Transform (state, block)
-UINT4 state[4];
-unsigned char block[64];
-{
- UINT4 a = state[0], b = state[1], c = state[2], d = state[3], x[16];
-
- Decode (x, block, 64);
-
- /* Round 1 */
- FF (a, b, c, d, x[ 0], S11, 0xd76aa478); /* 1 */
- FF (d, a, b, c, x[ 1], S12, 0xe8c7b756); /* 2 */
- FF (c, d, a, b, x[ 2], S13, 0x242070db); /* 3 */
- FF (b, c, d, a, x[ 3], S14, 0xc1bdceee); /* 4 */
- FF (a, b, c, d, x[ 4], S11, 0xf57c0faf); /* 5 */
- FF (d, a, b, c, x[ 5], S12, 0x4787c62a); /* 6 */
- FF (c, d, a, b, x[ 6], S13, 0xa8304613); /* 7 */
- FF (b, c, d, a, x[ 7], S14, 0xfd469501); /* 8 */
- FF (a, b, c, d, x[ 8], S11, 0x698098d8); /* 9 */
- FF (d, a, b, c, x[ 9], S12, 0x8b44f7af); /* 10 */
- FF (c, d, a, b, x[10], S13, 0xffff5bb1); /* 11 */
- FF (b, c, d, a, x[11], S14, 0x895cd7be); /* 12 */
- FF (a, b, c, d, x[12], S11, 0x6b901122); /* 13 */
- FF (d, a, b, c, x[13], S12, 0xfd987193); /* 14 */
- FF (c, d, a, b, x[14], S13, 0xa679438e); /* 15 */
- FF (b, c, d, a, x[15], S14, 0x49b40821); /* 16 */
-
- /* Round 2 */
- GG (a, b, c, d, x[ 1], S21, 0xf61e2562); /* 17 */
- GG (d, a, b, c, x[ 6], S22, 0xc040b340); /* 18 */
- GG (c, d, a, b, x[11], S23, 0x265e5a51); /* 19 */
- GG (b, c, d, a, x[ 0], S24, 0xe9b6c7aa); /* 20 */
- GG (a, b, c, d, x[ 5], S21, 0xd62f105d); /* 21 */
- GG (d, a, b, c, x[10], S22, 0x2441453); /* 22 */
- GG (c, d, a, b, x[15], S23, 0xd8a1e681); /* 23 */
- GG (b, c, d, a, x[ 4], S24, 0xe7d3fbc8); /* 24 */
- GG (a, b, c, d, x[ 9], S21, 0x21e1cde6); /* 25 */
- GG (d, a, b, c, x[14], S22, 0xc33707d6); /* 26 */
- GG (c, d, a, b, x[ 3], S23, 0xf4d50d87); /* 27 */
-
-
-
-Rivest [Page 13]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
- GG (b, c, d, a, x[ 8], S24, 0x455a14ed); /* 28 */
- GG (a, b, c, d, x[13], S21, 0xa9e3e905); /* 29 */
- GG (d, a, b, c, x[ 2], S22, 0xfcefa3f8); /* 30 */
- GG (c, d, a, b, x[ 7], S23, 0x676f02d9); /* 31 */
- GG (b, c, d, a, x[12], S24, 0x8d2a4c8a); /* 32 */
-
- /* Round 3 */
- HH (a, b, c, d, x[ 5], S31, 0xfffa3942); /* 33 */
- HH (d, a, b, c, x[ 8], S32, 0x8771f681); /* 34 */
- HH (c, d, a, b, x[11], S33, 0x6d9d6122); /* 35 */
- HH (b, c, d, a, x[14], S34, 0xfde5380c); /* 36 */
- HH (a, b, c, d, x[ 1], S31, 0xa4beea44); /* 37 */
- HH (d, a, b, c, x[ 4], S32, 0x4bdecfa9); /* 38 */
- HH (c, d, a, b, x[ 7], S33, 0xf6bb4b60); /* 39 */
- HH (b, c, d, a, x[10], S34, 0xbebfbc70); /* 40 */
- HH (a, b, c, d, x[13], S31, 0x289b7ec6); /* 41 */
- HH (d, a, b, c, x[ 0], S32, 0xeaa127fa); /* 42 */
- HH (c, d, a, b, x[ 3], S33, 0xd4ef3085); /* 43 */
- HH (b, c, d, a, x[ 6], S34, 0x4881d05); /* 44 */
- HH (a, b, c, d, x[ 9], S31, 0xd9d4d039); /* 45 */
- HH (d, a, b, c, x[12], S32, 0xe6db99e5); /* 46 */
- HH (c, d, a, b, x[15], S33, 0x1fa27cf8); /* 47 */
- HH (b, c, d, a, x[ 2], S34, 0xc4ac5665); /* 48 */
-
- /* Round 4 */
- II (a, b, c, d, x[ 0], S41, 0xf4292244); /* 49 */
- II (d, a, b, c, x[ 7], S42, 0x432aff97); /* 50 */
- II (c, d, a, b, x[14], S43, 0xab9423a7); /* 51 */
- II (b, c, d, a, x[ 5], S44, 0xfc93a039); /* 52 */
- II (a, b, c, d, x[12], S41, 0x655b59c3); /* 53 */
- II (d, a, b, c, x[ 3], S42, 0x8f0ccc92); /* 54 */
- II (c, d, a, b, x[10], S43, 0xffeff47d); /* 55 */
- II (b, c, d, a, x[ 1], S44, 0x85845dd1); /* 56 */
- II (a, b, c, d, x[ 8], S41, 0x6fa87e4f); /* 57 */
- II (d, a, b, c, x[15], S42, 0xfe2ce6e0); /* 58 */
- II (c, d, a, b, x[ 6], S43, 0xa3014314); /* 59 */
- II (b, c, d, a, x[13], S44, 0x4e0811a1); /* 60 */
- II (a, b, c, d, x[ 4], S41, 0xf7537e82); /* 61 */
- II (d, a, b, c, x[11], S42, 0xbd3af235); /* 62 */
- II (c, d, a, b, x[ 2], S43, 0x2ad7d2bb); /* 63 */
- II (b, c, d, a, x[ 9], S44, 0xeb86d391); /* 64 */
-
- state[0] += a;
- state[1] += b;
- state[2] += c;
- state[3] += d;
-
- /* Zeroize sensitive information.
-
-
-
-Rivest [Page 14]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
-*/
- MD5_memset ((POINTER)x, 0, sizeof (x));
-}
-
-/* Encodes input (UINT4) into output (unsigned char). Assumes len is
- a multiple of 4.
- */
-static void Encode (output, input, len)
-unsigned char *output;
-UINT4 *input;
-unsigned int len;
-{
- unsigned int i, j;
-
- for (i = 0, j = 0; j < len; i++, j += 4) {
- output[j] = (unsigned char)(input[i] & 0xff);
- output[j+1] = (unsigned char)((input[i] >> 8) & 0xff);
- output[j+2] = (unsigned char)((input[i] >> 16) & 0xff);
- output[j+3] = (unsigned char)((input[i] >> 24) & 0xff);
- }
-}
-
-/* Decodes input (unsigned char) into output (UINT4). Assumes len is
- a multiple of 4.
- */
-static void Decode (output, input, len)
-UINT4 *output;
-unsigned char *input;
-unsigned int len;
-{
- unsigned int i, j;
-
- for (i = 0, j = 0; j < len; i++, j += 4)
- output[i] = ((UINT4)input[j]) | (((UINT4)input[j+1]) << 8) |
- (((UINT4)input[j+2]) << 16) | (((UINT4)input[j+3]) << 24);
-}
-
-/* Note: Replace "for loop" with standard memcpy if possible.
- */
-
-static void MD5_memcpy (output, input, len)
-POINTER output;
-POINTER input;
-unsigned int len;
-{
- unsigned int i;
-
- for (i = 0; i < len; i++)
-
-
-
-Rivest [Page 15]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
- output[i] = input[i];
-}
-
-/* Note: Replace "for loop" with standard memset if possible.
- */
-static void MD5_memset (output, value, len)
-POINTER output;
-int value;
-unsigned int len;
-{
- unsigned int i;
-
- for (i = 0; i < len; i++)
- ((char *)output)[i] = (char)value;
-}
-
-A.4 mddriver.c
-
-/* MDDRIVER.C - test driver for MD2, MD4 and MD5
- */
-
-/* Copyright (C) 1990-2, RSA Data Security, Inc. Created 1990. All
-rights reserved.
-
-RSA Data Security, Inc. makes no representations concerning either
-the merchantability of this software or the suitability of this
-software for any particular purpose. It is provided "as is"
-without express or implied warranty of any kind.
-
-These notices must be retained in any copies of any part of this
-documentation and/or software.
- */
-
-/* The following makes MD default to MD5 if it has not already been
- defined with C compiler flags.
- */
-#ifndef MD
-#define MD MD5
-#endif
-
-#include <stdio.h>
-#include <time.h>
-#include <string.h>
-#include "global.h"
-#if MD == 2
-#include "md2.h"
-#endif
-#if MD == 4
-
-
-
-Rivest [Page 16]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
-#include "md4.h"
-#endif
-#if MD == 5
-#include "md5.h"
-#endif
-
-/* Length of test block, number of test blocks.
- */
-#define TEST_BLOCK_LEN 1000
-#define TEST_BLOCK_COUNT 1000
-
-static void MDString PROTO_LIST ((char *));
-static void MDTimeTrial PROTO_LIST ((void));
-static void MDTestSuite PROTO_LIST ((void));
-static void MDFile PROTO_LIST ((char *));
-static void MDFilter PROTO_LIST ((void));
-static void MDPrint PROTO_LIST ((unsigned char [16]));
-
-#if MD == 2
-#define MD_CTX MD2_CTX
-#define MDInit MD2Init
-#define MDUpdate MD2Update
-#define MDFinal MD2Final
-#endif
-#if MD == 4
-#define MD_CTX MD4_CTX
-#define MDInit MD4Init
-#define MDUpdate MD4Update
-#define MDFinal MD4Final
-#endif
-#if MD == 5
-#define MD_CTX MD5_CTX
-#define MDInit MD5Init
-#define MDUpdate MD5Update
-#define MDFinal MD5Final
-#endif
-
-/* Main driver.
-
-Arguments (may be any combination):
- -sstring - digests string
- -t - runs time trial
- -x - runs test script
- filename - digests file
- (none) - digests standard input
- */
-int main (argc, argv)
-int argc;
-
-
-
-Rivest [Page 17]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
-char *argv[];
-{
- int i;
-
- if (argc > 1)
- for (i = 1; i < argc; i++)
- if (argv[i][0] == '-' && argv[i][1] == 's')
- MDString (argv[i] + 2);
- else if (strcmp (argv[i], "-t") == 0)
- MDTimeTrial ();
- else if (strcmp (argv[i], "-x") == 0)
- MDTestSuite ();
- else
- MDFile (argv[i]);
- else
- MDFilter ();
-
- return (0);
-}
-
-/* Digests a string and prints the result.
- */
-static void MDString (string)
-char *string;
-{
- MD_CTX context;
- unsigned char digest[16];
- unsigned int len = strlen (string);
-
- MDInit (&context);
- MDUpdate (&context, string, len);
- MDFinal (digest, &context);
-
- printf ("MD%d (\"%s\") = ", MD, string);
- MDPrint (digest);
- printf ("\n");
-}
-
-/* Measures the time to digest TEST_BLOCK_COUNT TEST_BLOCK_LEN-byte
- blocks.
- */
-static void MDTimeTrial ()
-{
- MD_CTX context;
- time_t endTime, startTime;
- unsigned char block[TEST_BLOCK_LEN], digest[16];
- unsigned int i;
-
-
-
-
-Rivest [Page 18]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
- printf
- ("MD%d time trial. Digesting %d %d-byte blocks ...", MD,
- TEST_BLOCK_LEN, TEST_BLOCK_COUNT);
-
- /* Initialize block */
- for (i = 0; i < TEST_BLOCK_LEN; i++)
- block[i] = (unsigned char)(i & 0xff);
-
- /* Start timer */
- time (&startTime);
-
- /* Digest blocks */
- MDInit (&context);
- for (i = 0; i < TEST_BLOCK_COUNT; i++)
- MDUpdate (&context, block, TEST_BLOCK_LEN);
- MDFinal (digest, &context);
-
- /* Stop timer */
- time (&endTime);
-
- printf (" done\n");
- printf ("Digest = ");
- MDPrint (digest);
- printf ("\nTime = %ld seconds\n", (long)(endTime-startTime));
- printf
- ("Speed = %ld bytes/second\n",
- (long)TEST_BLOCK_LEN * (long)TEST_BLOCK_COUNT/(endTime-startTime));
-}
-
-/* Digests a reference suite of strings and prints the results.
- */
-static void MDTestSuite ()
-{
- printf ("MD%d test suite:\n", MD);
-
- MDString ("");
- MDString ("a");
- MDString ("abc");
- MDString ("message digest");
- MDString ("abcdefghijklmnopqrstuvwxyz");
- MDString
- ("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789");
- MDString
- ("1234567890123456789012345678901234567890\
-1234567890123456789012345678901234567890");
-}
-
-/* Digests a file and prints the result.
-
-
-
-Rivest [Page 19]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
- */
-static void MDFile (filename)
-char *filename;
-{
- FILE *file;
- MD_CTX context;
- int len;
- unsigned char buffer[1024], digest[16];
-
- if ((file = fopen (filename, "rb")) == NULL)
- printf ("%s can't be opened\n", filename);
-
- else {
- MDInit (&context);
- while (len = fread (buffer, 1, 1024, file))
- MDUpdate (&context, buffer, len);
- MDFinal (digest, &context);
-
- fclose (file);
-
- printf ("MD%d (%s) = ", MD, filename);
- MDPrint (digest);
- printf ("\n");
- }
-}
-
-/* Digests the standard input and prints the result.
- */
-static void MDFilter ()
-{
- MD_CTX context;
- int len;
- unsigned char buffer[16], digest[16];
-
- MDInit (&context);
- while (len = fread (buffer, 1, 16, stdin))
- MDUpdate (&context, buffer, len);
- MDFinal (digest, &context);
-
- MDPrint (digest);
- printf ("\n");
-}
-
-/* Prints a message digest in hexadecimal.
- */
-static void MDPrint (digest)
-unsigned char digest[16];
-{
-
-
-
-Rivest [Page 20]
-\f
-RFC 1321 MD5 Message-Digest Algorithm April 1992
-
-
- unsigned int i;
-
- for (i = 0; i < 16; i++)
- printf ("%02x", digest[i]);
-}
-
-A.5 Test suite
-
- The MD5 test suite (driver option "-x") should print the following
- results:
-
-MD5 test suite:
-MD5 ("") = d41d8cd98f00b204e9800998ecf8427e
-MD5 ("a") = 0cc175b9c0f1b6a831c399e269772661
-MD5 ("abc") = 900150983cd24fb0d6963f7d28e17f72
-MD5 ("message digest") = f96b697d7cb7938d525a2f31aaf161d0
-MD5 ("abcdefghijklmnopqrstuvwxyz") = c3fcd3d76192e4007dfb496cca67e13b
-MD5 ("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789") =
-d174ab98d277d9f5a5611c2c9f419d9f
-MD5 ("123456789012345678901234567890123456789012345678901234567890123456
-78901234567890") = 57edf4a22be3c955ac49da2e2107b67a
-
-Security Considerations
-
- The level of security discussed in this memo is considered to be
- sufficient for implementing very high security hybrid digital-
- signature schemes based on MD5 and a public-key cryptosystem.
-
-Author's Address
-
- Ronald L. Rivest
- Massachusetts Institute of Technology
- Laboratory for Computer Science
- NE43-324
- 545 Technology Square
- Cambridge, MA 02139-1986
-
- Phone: (617) 253-5880
- EMail: rivest@theory.lcs.mit.edu
-
-
-
-
-
-
-
-
-
-
-
-
-Rivest [Page 21]
-\f
\ No newline at end of file
+++ /dev/null
-
-
-
-
-
-
-Network Working Group N. Freed
-Request for Comments: 2046 Innosoft
-Obsoletes: 1521, 1522, 1590 N. Borenstein
-Category: Standards Track First Virtual
- November 1996
-
-
- Multipurpose Internet Mail Extensions
- (MIME) Part Two:
- Media Types
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Abstract
-
- STD 11, RFC 822 defines a message representation protocol specifying
- considerable detail about US-ASCII message headers, but which leaves
- the message content, or message body, as flat US-ASCII text. This
- set of documents, collectively called the Multipurpose Internet Mail
- Extensions, or MIME, redefines the format of messages to allow for
-
- (1) textual message bodies in character sets other than
- US-ASCII,
-
- (2) an extensible set of different formats for non-textual
- message bodies,
-
- (3) multi-part message bodies, and
-
- (4) textual header information in character sets other than
- US-ASCII.
-
- These documents are based on earlier work documented in RFC 934, STD
- 11, and RFC 1049, but extends and revises them. Because RFC 822 said
- so little about message bodies, these documents are largely
- orthogonal to (rather than a revision of) RFC 822.
-
- The initial document in this set, RFC 2045, specifies the various
- headers used to describe the structure of MIME messages. This second
- document defines the general structure of the MIME media typing
- system and defines an initial set of media types. The third document,
- RFC 2047, describes extensions to RFC 822 to allow non-US-ASCII text
-
-
-
-Freed & Borenstein Standards Track [Page 1]
-\f
-RFC 2046 Media Types November 1996
-
-
- data in Internet mail header fields. The fourth document, RFC 2048,
- specifies various IANA registration procedures for MIME-related
- facilities. The fifth and final document, RFC 2049, describes MIME
- conformance criteria as well as providing some illustrative examples
- of MIME message formats, acknowledgements, and the bibliography.
-
- These documents are revisions of RFCs 1521 and 1522, which themselves
- were revisions of RFCs 1341 and 1342. An appendix in RFC 2049
- describes differences and changes from previous versions.
-
-Table of Contents
-
- 1. Introduction ......................................... 3
- 2. Definition of a Top-Level Media Type ................. 4
- 3. Overview Of The Initial Top-Level Media Types ........ 4
- 4. Discrete Media Type Values ........................... 6
- 4.1 Text Media Type ..................................... 6
- 4.1.1 Representation of Line Breaks ..................... 7
- 4.1.2 Charset Parameter ................................. 7
- 4.1.3 Plain Subtype ..................................... 11
- 4.1.4 Unrecognized Subtypes ............................. 11
- 4.2 Image Media Type .................................... 11
- 4.3 Audio Media Type .................................... 11
- 4.4 Video Media Type .................................... 12
- 4.5 Application Media Type .............................. 12
- 4.5.1 Octet-Stream Subtype .............................. 13
- 4.5.2 PostScript Subtype ................................ 14
- 4.5.3 Other Application Subtypes ........................ 17
- 5. Composite Media Type Values .......................... 17
- 5.1 Multipart Media Type ................................ 17
- 5.1.1 Common Syntax ..................................... 19
- 5.1.2 Handling Nested Messages and Multiparts ........... 24
- 5.1.3 Mixed Subtype ..................................... 24
- 5.1.4 Alternative Subtype ............................... 24
- 5.1.5 Digest Subtype .................................... 26
- 5.1.6 Parallel Subtype .................................. 27
- 5.1.7 Other Multipart Subtypes .......................... 28
- 5.2 Message Media Type .................................. 28
- 5.2.1 RFC822 Subtype .................................... 28
- 5.2.2 Partial Subtype ................................... 29
- 5.2.2.1 Message Fragmentation and Reassembly ............ 30
- 5.2.2.2 Fragmentation and Reassembly Example ............ 31
- 5.2.3 External-Body Subtype ............................. 33
- 5.2.4 Other Message Subtypes ............................ 40
- 6. Experimental Media Type Values ....................... 40
- 7. Summary .............................................. 41
- 8. Security Considerations .............................. 41
- 9. Authors' Addresses ................................... 42
-
-
-
-Freed & Borenstein Standards Track [Page 2]
-\f
-RFC 2046 Media Types November 1996
-
-
- A. Collected Grammar .................................... 43
-
-1. Introduction
-
- The first document in this set, RFC 2045, defines a number of header
- fields, including Content-Type. The Content-Type field is used to
- specify the nature of the data in the body of a MIME entity, by
- giving media type and subtype identifiers, and by providing auxiliary
- information that may be required for certain media types. After the
- type and subtype names, the remainder of the header field is simply a
- set of parameters, specified in an attribute/value notation. The
- ordering of parameters is not significant.
-
- In general, the top-level media type is used to declare the general
- type of data, while the subtype specifies a specific format for that
- type of data. Thus, a media type of "image/xyz" is enough to tell a
- user agent that the data is an image, even if the user agent has no
- knowledge of the specific image format "xyz". Such information can
- be used, for example, to decide whether or not to show a user the raw
- data from an unrecognized subtype -- such an action might be
- reasonable for unrecognized subtypes of "text", but not for
- unrecognized subtypes of "image" or "audio". For this reason,
- registered subtypes of "text", "image", "audio", and "video" should
- not contain embedded information that is really of a different type.
- Such compound formats should be represented using the "multipart" or
- "application" types.
-
- Parameters are modifiers of the media subtype, and as such do not
- fundamentally affect the nature of the content. The set of
- meaningful parameters depends on the media type and subtype. Most
- parameters are associated with a single specific subtype. However, a
- given top-level media type may define parameters which are applicable
- to any subtype of that type. Parameters may be required by their
- defining media type or subtype or they may be optional. MIME
- implementations must also ignore any parameters whose names they do
- not recognize.
-
- MIME's Content-Type header field and media type mechanism has been
- carefully designed to be extensible, and it is expected that the set
- of media type/subtype pairs and their associated parameters will grow
- significantly over time. Several other MIME facilities, such as
- transfer encodings and "message/external-body" access types, are
- likely to have new values defined over time. In order to ensure that
- the set of such values is developed in an orderly, well-specified,
- and public manner, MIME sets up a registration process which uses the
- Internet Assigned Numbers Authority (IANA) as a central registry for
- MIME's various areas of extensibility. The registration process for
- these areas is described in a companion document, RFC 2048.
-
-
-
-Freed & Borenstein Standards Track [Page 3]
-\f
-RFC 2046 Media Types November 1996
-
-
- The initial seven standard top-level media type are defined and
- described in the remainder of this document.
-
-2. Definition of a Top-Level Media Type
-
- The definition of a top-level media type consists of:
-
- (1) a name and a description of the type, including
- criteria for whether a particular type would qualify
- under that type,
-
- (2) the names and definitions of parameters, if any, which
- are defined for all subtypes of that type (including
- whether such parameters are required or optional),
-
- (3) how a user agent and/or gateway should handle unknown
- subtypes of this type,
-
- (4) general considerations on gatewaying entities of this
- top-level type, if any, and
-
- (5) any restrictions on content-transfer-encodings for
- entities of this top-level type.
-
-3. Overview Of The Initial Top-Level Media Types
-
- The five discrete top-level media types are:
-
- (1) text -- textual information. The subtype "plain" in
- particular indicates plain text containing no
- formatting commands or directives of any sort. Plain
- text is intended to be displayed "as-is". No special
- software is required to get the full meaning of the
- text, aside from support for the indicated character
- set. Other subtypes are to be used for enriched text in
- forms where application software may enhance the
- appearance of the text, but such software must not be
- required in order to get the general idea of the
- content. Possible subtypes of "text" thus include any
- word processor format that can be read without
- resorting to software that understands the format. In
- particular, formats that employ embeddded binary
- formatting information are not considered directly
- readable. A very simple and portable subtype,
- "richtext", was defined in RFC 1341, with a further
- revision in RFC 1896 under the name "enriched".
-
-
-
-
-
-Freed & Borenstein Standards Track [Page 4]
-\f
-RFC 2046 Media Types November 1996
-
-
- (2) image -- image data. "Image" requires a display device
- (such as a graphical display, a graphics printer, or a
- FAX machine) to view the information. An initial
- subtype is defined for the widely-used image format
- JPEG. . subtypes are defined for two widely-used image
- formats, jpeg and gif.
-
- (3) audio -- audio data. "Audio" requires an audio output
- device (such as a speaker or a telephone) to "display"
- the contents. An initial subtype "basic" is defined in
- this document.
-
- (4) video -- video data. "Video" requires the capability
- to display moving images, typically including
- specialized hardware and software. An initial subtype
- "mpeg" is defined in this document.
-
- (5) application -- some other kind of data, typically
- either uninterpreted binary data or information to be
- processed by an application. The subtype "octet-
- stream" is to be used in the case of uninterpreted
- binary data, in which case the simplest recommended
- action is to offer to write the information into a file
- for the user. The "PostScript" subtype is also defined
- for the transport of PostScript material. Other
- expected uses for "application" include spreadsheets,
- data for mail-based scheduling systems, and languages
- for "active" (computational) messaging, and word
- processing formats that are not directly readable.
- Note that security considerations may exist for some
- types of application data, most notably
- "application/PostScript" and any form of active
- messaging. These issues are discussed later in this
- document.
-
- The two composite top-level media types are:
-
- (1) multipart -- data consisting of multiple entities of
- independent data types. Four subtypes are initially
- defined, including the basic "mixed" subtype specifying
- a generic mixed set of parts, "alternative" for
- representing the same data in multiple formats,
- "parallel" for parts intended to be viewed
- simultaneously, and "digest" for multipart entities in
- which each part has a default type of "message/rfc822".
-
-
-
-
-
-
-Freed & Borenstein Standards Track [Page 5]
-\f
-RFC 2046 Media Types November 1996
-
-
- (2) message -- an encapsulated message. A body of media
- type "message" is itself all or a portion of some kind
- of message object. Such objects may or may not in turn
- contain other entities. The "rfc822" subtype is used
- when the encapsulated content is itself an RFC 822
- message. The "partial" subtype is defined for partial
- RFC 822 messages, to permit the fragmented transmission
- of bodies that are thought to be too large to be passed
- through transport facilities in one piece. Another
- subtype, "external-body", is defined for specifying
- large bodies by reference to an external data source.
-
- It should be noted that the list of media type values given here may
- be augmented in time, via the mechanisms described above, and that
- the set of subtypes is expected to grow substantially.
-
-4. Discrete Media Type Values
-
- Five of the seven initial media type values refer to discrete bodies.
- The content of these types must be handled by non-MIME mechanisms;
- they are opaque to MIME processors.
-
-4.1. Text Media Type
-
- The "text" media type is intended for sending material which is
- principally textual in form. A "charset" parameter may be used to
- indicate the character set of the body text for "text" subtypes,
- notably including the subtype "text/plain", which is a generic
- subtype for plain text. Plain text does not provide for or allow
- formatting commands, font attribute specifications, processing
- instructions, interpretation directives, or content markup. Plain
- text is seen simply as a linear sequence of characters, possibly
- interrupted by line breaks or page breaks. Plain text may allow the
- stacking of several characters in the same position in the text.
- Plain text in scripts like Arabic and Hebrew may also include
- facilitites that allow the arbitrary mixing of text segments with
- opposite writing directions.
-
- Beyond plain text, there are many formats for representing what might
- be known as "rich text". An interesting characteristic of many such
- representations is that they are to some extent readable even without
- the software that interprets them. It is useful, then, to
- distinguish them, at the highest level, from such unreadable data as
- images, audio, or text represented in an unreadable form. In the
- absence of appropriate interpretation software, it is reasonable to
- show subtypes of "text" to the user, while it is not reasonable to do
- so with most nontextual data. Such formatted textual data should be
- represented using subtypes of "text".
-
-
-
-Freed & Borenstein Standards Track [Page 6]
-\f
-RFC 2046 Media Types November 1996
-
-
-4.1.1. Representation of Line Breaks
-
- The canonical form of any MIME "text" subtype MUST always represent a
- line break as a CRLF sequence. Similarly, any occurrence of CRLF in
- MIME "text" MUST represent a line break. Use of CR and LF outside of
- line break sequences is also forbidden.
-
- This rule applies regardless of format or character set or sets
- involved.
-
- NOTE: The proper interpretation of line breaks when a body is
- displayed depends on the media type. In particular, while it is
- appropriate to treat a line break as a transition to a new line when
- displaying a "text/plain" body, this treatment is actually incorrect
- for other subtypes of "text" like "text/enriched" [RFC-1896].
- Similarly, whether or not line breaks should be added during display
- operations is also a function of the media type. It should not be
- necessary to add any line breaks to display "text/plain" correctly,
- whereas proper display of "text/enriched" requires the appropriate
- addition of line breaks.
-
- NOTE: Some protocols defines a maximum line length. E.g. SMTP [RFC-
- 821] allows a maximum of 998 octets before the next CRLF sequence.
- To be transported by such protocols, data which includes too long
- segments without CRLF sequences must be encoded with a suitable
- content-transfer-encoding.
-
-4.1.2. Charset Parameter
-
- A critical parameter that may be specified in the Content-Type field
- for "text/plain" data is the character set. This is specified with a
- "charset" parameter, as in:
-
- Content-type: text/plain; charset=iso-8859-1
-
- Unlike some other parameter values, the values of the charset
- parameter are NOT case sensitive. The default character set, which
- must be assumed in the absence of a charset parameter, is US-ASCII.
-
- The specification for any future subtypes of "text" must specify
- whether or not they will also utilize a "charset" parameter, and may
- possibly restrict its values as well. For other subtypes of "text"
- than "text/plain", the semantics of the "charset" parameter should be
- defined to be identical to those specified here for "text/plain",
- i.e., the body consists entirely of characters in the given charset.
- In particular, definers of future "text" subtypes should pay close
- attention to the implications of multioctet character sets for their
- subtype definitions.
-
-
-
-Freed & Borenstein Standards Track [Page 7]
-\f
-RFC 2046 Media Types November 1996
-
-
- The charset parameter for subtypes of "text" gives a name of a
- character set, as "character set" is defined in RFC 2045. The rules
- regarding line breaks detailed in the previous section must also be
- observed -- a character set whose definition does not conform to
- these rules cannot be used in a MIME "text" subtype.
-
- An initial list of predefined character set names can be found at the
- end of this section. Additional character sets may be registered
- with IANA.
-
- Other media types than subtypes of "text" might choose to employ the
- charset parameter as defined here, but with the CRLF/line break
- restriction removed. Therefore, all character sets that conform to
- the general definition of "character set" in RFC 2045 can be
- registered for MIME use.
-
- Note that if the specified character set includes 8-bit characters
- and such characters are used in the body, a Content-Transfer-Encoding
- header field and a corresponding encoding on the data are required in
- order to transmit the body via some mail transfer protocols, such as
- SMTP [RFC-821].
-
- The default character set, US-ASCII, has been the subject of some
- confusion and ambiguity in the past. Not only were there some
- ambiguities in the definition, there have been wide variations in
- practice. In order to eliminate such ambiguity and variations in the
- future, it is strongly recommended that new user agents explicitly
- specify a character set as a media type parameter in the Content-Type
- header field. "US-ASCII" does not indicate an arbitrary 7-bit
- character set, but specifies that all octets in the body must be
- interpreted as characters according to the US-ASCII character set.
- National and application-oriented versions of ISO 646 [ISO-646] are
- usually NOT identical to US-ASCII, and in that case their use in
- Internet mail is explicitly discouraged. The omission of the ISO 646
- character set from this document is deliberate in this regard. The
- character set name of "US-ASCII" explicitly refers to the character
- set defined in ANSI X3.4-1986 [US- ASCII]. The new international
- reference version (IRV) of the 1991 edition of ISO 646 is identical
- to US-ASCII. The character set name "ASCII" is reserved and must not
- be used for any purpose.
-
- NOTE: RFC 821 explicitly specifies "ASCII", and references an earlier
- version of the American Standard. Insofar as one of the purposes of
- specifying a media type and character set is to permit the receiver
- to unambiguously determine how the sender intended the coded message
- to be interpreted, assuming anything other than "strict ASCII" as the
- default would risk unintentional and incompatible changes to the
- semantics of messages now being transmitted. This also implies that
-
-
-
-Freed & Borenstein Standards Track [Page 8]
-\f
-RFC 2046 Media Types November 1996
-
-
- messages containing characters coded according to other versions of
- ISO 646 than US-ASCII and the 1991 IRV, or using code-switching
- procedures (e.g., those of ISO 2022), as well as 8bit or multiple
- octet character encodings MUST use an appropriate character set
- specification to be consistent with MIME.
-
- The complete US-ASCII character set is listed in ANSI X3.4- 1986.
- Note that the control characters including DEL (0-31, 127) have no
- defined meaning in apart from the combination CRLF (US-ASCII values
- 13 and 10) indicating a new line. Two of the characters have de
- facto meanings in wide use: FF (12) often means "start subsequent
- text on the beginning of a new page"; and TAB or HT (9) often (though
- not always) means "move the cursor to the next available column after
- the current position where the column number is a multiple of 8
- (counting the first column as column 0)." Aside from these
- conventions, any use of the control characters or DEL in a body must
- either occur
-
- (1) because a subtype of text other than "plain"
- specifically assigns some additional meaning, or
-
- (2) within the context of a private agreement between the
- sender and recipient. Such private agreements are
- discouraged and should be replaced by the other
- capabilities of this document.
-
- NOTE: An enormous proliferation of character sets exist beyond US-
- ASCII. A large number of partially or totally overlapping character
- sets is NOT a good thing. A SINGLE character set that can be used
- universally for representing all of the world's languages in Internet
- mail would be preferrable. Unfortunately, existing practice in
- several communities seems to point to the continued use of multiple
- character sets in the near future. A small number of standard
- character sets are, therefore, defined for Internet use in this
- document.
-
- The defined charset values are:
-
- (1) US-ASCII -- as defined in ANSI X3.4-1986 [US-ASCII].
-
- (2) ISO-8859-X -- where "X" is to be replaced, as
- necessary, for the parts of ISO-8859 [ISO-8859]. Note
- that the ISO 646 character sets have deliberately been
- omitted in favor of their 8859 replacements, which are
- the designated character sets for Internet mail. As of
- the publication of this document, the legitimate values
- for "X" are the digits 1 through 10.
-
-
-
-
-Freed & Borenstein Standards Track [Page 9]
-\f
-RFC 2046 Media Types November 1996
-
-
- Characters in the range 128-159 has no assigned meaning in ISO-8859-
- X. Characters with values below 128 in ISO-8859-X have the same
- assigned meaning as they do in US-ASCII.
-
- Part 6 of ISO 8859 (Latin/Arabic alphabet) and part 8 (Latin/Hebrew
- alphabet) includes both characters for which the normal writing
- direction is right to left and characters for which it is left to
- right, but do not define a canonical ordering method for representing
- bi-directional text. The charset values "ISO-8859-6" and "ISO-8859-
- 8", however, specify that the visual method is used [RFC-1556].
-
- All of these character sets are used as pure 7bit or 8bit sets
- without any shift or escape functions. The meaning of shift and
- escape sequences in these character sets is not defined.
-
- The character sets specified above are the ones that were relatively
- uncontroversial during the drafting of MIME. This document does not
- endorse the use of any particular character set other than US-ASCII,
- and recognizes that the future evolution of world character sets
- remains unclear.
-
- Note that the character set used, if anything other than US- ASCII,
- must always be explicitly specified in the Content-Type field.
-
- No character set name other than those defined above may be used in
- Internet mail without the publication of a formal specification and
- its registration with IANA, or by private agreement, in which case
- the character set name must begin with "X-".
-
- Implementors are discouraged from defining new character sets unless
- absolutely necessary.
-
- The "charset" parameter has been defined primarily for the purpose of
- textual data, and is described in this section for that reason.
- However, it is conceivable that non-textual data might also wish to
- specify a charset value for some purpose, in which case the same
- syntax and values should be used.
-
- In general, composition software should always use the "lowest common
- denominator" character set possible. For example, if a body contains
- only US-ASCII characters, it SHOULD be marked as being in the US-
- ASCII character set, not ISO-8859-1, which, like all the ISO-8859
- family of character sets, is a superset of US-ASCII. More generally,
- if a widely-used character set is a subset of another character set,
- and a body contains only characters in the widely-used subset, it
- should be labelled as being in that subset. This will increase the
- chances that the recipient will be able to view the resulting entity
- correctly.
-
-
-
-Freed & Borenstein Standards Track [Page 10]
-\f
-RFC 2046 Media Types November 1996
-
-
-4.1.3. Plain Subtype
-
- The simplest and most important subtype of "text" is "plain". This
- indicates plain text that does not contain any formatting commands or
- directives. Plain text is intended to be displayed "as-is", that is,
- no interpretation of embedded formatting commands, font attribute
- specifications, processing instructions, interpretation directives,
- or content markup should be necessary for proper display. The
- default media type of "text/plain; charset=us-ascii" for Internet
- mail describes existing Internet practice. That is, it is the type
- of body defined by RFC 822.
-
- No other "text" subtype is defined by this document.
-
-4.1.4. Unrecognized Subtypes
-
- Unrecognized subtypes of "text" should be treated as subtype "plain"
- as long as the MIME implementation knows how to handle the charset.
- Unrecognized subtypes which also specify an unrecognized charset
- should be treated as "application/octet- stream".
-
-4.2. Image Media Type
-
- A media type of "image" indicates that the body contains an image.
- The subtype names the specific image format. These names are not
- case sensitive. An initial subtype is "jpeg" for the JPEG format
- using JFIF encoding [JPEG].
-
- The list of "image" subtypes given here is neither exclusive nor
- exhaustive, and is expected to grow as more types are registered with
- IANA, as described in RFC 2048.
-
- Unrecognized subtypes of "image" should at a miniumum be treated as
- "application/octet-stream". Implementations may optionally elect to
- pass subtypes of "image" that they do not specifically recognize to a
- secure and robust general-purpose image viewing application, if such
- an application is available.
-
- NOTE: Using of a generic-purpose image viewing application this way
- inherits the security problems of the most dangerous type supported
- by the application.
-
-4.3. Audio Media Type
-
- A media type of "audio" indicates that the body contains audio data.
- Although there is not yet a consensus on an "ideal" audio format for
- use with computers, there is a pressing need for a format capable of
- providing interoperable behavior.
-
-
-
-Freed & Borenstein Standards Track [Page 11]
-\f
-RFC 2046 Media Types November 1996
-
-
- The initial subtype of "basic" is specified to meet this requirement
- by providing an absolutely minimal lowest common denominator audio
- format. It is expected that richer formats for higher quality and/or
- lower bandwidth audio will be defined by a later document.
-
- The content of the "audio/basic" subtype is single channel audio
- encoded using 8bit ISDN mu-law [PCM] at a sample rate of 8000 Hz.
-
- Unrecognized subtypes of "audio" should at a miniumum be treated as
- "application/octet-stream". Implementations may optionally elect to
- pass subtypes of "audio" that they do not specifically recognize to a
- robust general-purpose audio playing application, if such an
- application is available.
-
-4.4. Video Media Type
-
- A media type of "video" indicates that the body contains a time-
- varying-picture image, possibly with color and coordinated sound.
- The term 'video' is used in its most generic sense, rather than with
- reference to any particular technology or format, and is not meant to
- preclude subtypes such as animated drawings encoded compactly. The
- subtype "mpeg" refers to video coded according to the MPEG standard
- [MPEG].
-
- Note that although in general this document strongly discourages the
- mixing of multiple media in a single body, it is recognized that many
- so-called video formats include a representation for synchronized
- audio, and this is explicitly permitted for subtypes of "video".
-
- Unrecognized subtypes of "video" should at a minumum be treated as
- "application/octet-stream". Implementations may optionally elect to
- pass subtypes of "video" that they do not specifically recognize to a
- robust general-purpose video display application, if such an
- application is available.
-
-4.5. Application Media Type
-
- The "application" media type is to be used for discrete data which do
- not fit in any of the other categories, and particularly for data to
- be processed by some type of application program. This is
- information which must be processed by an application before it is
- viewable or usable by a user. Expected uses for the "application"
- media type include file transfer, spreadsheets, data for mail-based
- scheduling systems, and languages for "active" (computational)
- material. (The latter, in particular, can pose security problems
- which must be understood by implementors, and are considered in
- detail in the discussion of the "application/PostScript" media type.)
-
-
-
-
-Freed & Borenstein Standards Track [Page 12]
-\f
-RFC 2046 Media Types November 1996
-
-
- For example, a meeting scheduler might define a standard
- representation for information about proposed meeting dates. An
- intelligent user agent would use this information to conduct a dialog
- with the user, and might then send additional material based on that
- dialog. More generally, there have been several "active" messaging
- languages developed in which programs in a suitably specialized
- language are transported to a remote location and automatically run
- in the recipient's environment.
-
- Such applications may be defined as subtypes of the "application"
- media type. This document defines two subtypes:
-
- octet-stream, and PostScript.
-
- The subtype of "application" will often be either the name or include
- part of the name of the application for which the data are intended.
- This does not mean, however, that any application program name may be
- used freely as a subtype of "application".
-
-4.5.1. Octet-Stream Subtype
-
- The "octet-stream" subtype is used to indicate that a body contains
- arbitrary binary data. The set of currently defined parameters is:
-
- (1) TYPE -- the general type or category of binary data.
- This is intended as information for the human recipient
- rather than for any automatic processing.
-
- (2) PADDING -- the number of bits of padding that were
- appended to the bit-stream comprising the actual
- contents to produce the enclosed 8bit byte-oriented
- data. This is useful for enclosing a bit-stream in a
- body when the total number of bits is not a multiple of
- 8.
-
- Both of these parameters are optional.
-
- An additional parameter, "CONVERSIONS", was defined in RFC 1341 but
- has since been removed. RFC 1341 also defined the use of a "NAME"
- parameter which gave a suggested file name to be used if the data
- were to be written to a file. This has been deprecated in
- anticipation of a separate Content-Disposition header field, to be
- defined in a subsequent RFC.
-
- The recommended action for an implementation that receives an
- "application/octet-stream" entity is to simply offer to put the data
- in a file, with any Content-Transfer-Encoding undone, or perhaps to
- use it as input to a user-specified process.
-
-
-
-Freed & Borenstein Standards Track [Page 13]
-\f
-RFC 2046 Media Types November 1996
-
-
- To reduce the danger of transmitting rogue programs, it is strongly
- recommended that implementations NOT implement a path-search
- mechanism whereby an arbitrary program named in the Content-Type
- parameter (e.g., an "interpreter=" parameter) is found and executed
- using the message body as input.
-
-4.5.2. PostScript Subtype
-
- A media type of "application/postscript" indicates a PostScript
- program. Currently two variants of the PostScript language are
- allowed; the original level 1 variant is described in [POSTSCRIPT]
- and the more recent level 2 variant is described in [POSTSCRIPT2].
-
- PostScript is a registered trademark of Adobe Systems, Inc. Use of
- the MIME media type "application/postscript" implies recognition of
- that trademark and all the rights it entails.
-
- The PostScript language definition provides facilities for internal
- labelling of the specific language features a given program uses.
- This labelling, called the PostScript document structuring
- conventions, or DSC, is very general and provides substantially more
- information than just the language level. The use of document
- structuring conventions, while not required, is strongly recommended
- as an aid to interoperability. Documents which lack proper
- structuring conventions cannot be tested to see whether or not they
- will work in a given environment. As such, some systems may assume
- the worst and refuse to process unstructured documents.
-
- The execution of general-purpose PostScript interpreters entails
- serious security risks, and implementors are discouraged from simply
- sending PostScript bodies to "off- the-shelf" interpreters. While it
- is usually safe to send PostScript to a printer, where the potential
- for harm is greatly constrained by typical printer environments,
- implementors should consider all of the following before they add
- interactive display of PostScript bodies to their MIME readers.
-
- The remainder of this section outlines some, though probably not all,
- of the possible problems with the transport of PostScript entities.
-
- (1) Dangerous operations in the PostScript language
- include, but may not be limited to, the PostScript
- operators "deletefile", "renamefile", "filenameforall",
- and "file". "File" is only dangerous when applied to
- something other than standard input or output.
- Implementations may also define additional nonstandard
- file operators; these may also pose a threat to
- security. "Filenameforall", the wildcard file search
- operator, may appear at first glance to be harmless.
-
-
-
-Freed & Borenstein Standards Track [Page 14]
-\f
-RFC 2046 Media Types November 1996
-
-
- Note, however, that this operator has the potential to
- reveal information about what files the recipient has
- access to, and this information may itself be
- sensitive. Message senders should avoid the use of
- potentially dangerous file operators, since these
- operators are quite likely to be unavailable in secure
- PostScript implementations. Message receiving and
- displaying software should either completely disable
- all potentially dangerous file operators or take
- special care not to delegate any special authority to
- their operation. These operators should be viewed as
- being done by an outside agency when interpreting
- PostScript documents. Such disabling and/or checking
- should be done completely outside of the reach of the
- PostScript language itself; care should be taken to
- insure that no method exists for re-enabling full-
- function versions of these operators.
-
- (2) The PostScript language provides facilities for exiting
- the normal interpreter, or server, loop. Changes made
- in this "outer" environment are customarily retained
- across documents, and may in some cases be retained
- semipermanently in nonvolatile memory. The operators
- associated with exiting the interpreter loop have the
- potential to interfere with subsequent document
- processing. As such, their unrestrained use
- constitutes a threat of service denial. PostScript
- operators that exit the interpreter loop include, but
- may not be limited to, the exitserver and startjob
- operators. Message sending software should not
- generate PostScript that depends on exiting the
- interpreter loop to operate, since the ability to exit
- will probably be unavailable in secure PostScript
- implementations. Message receiving and displaying
- software should completely disable the ability to make
- retained changes to the PostScript environment by
- eliminating or disabling the "startjob" and
- "exitserver" operations. If these operations cannot be
- eliminated or completely disabled the password
- associated with them should at least be set to a hard-
- to-guess value.
-
- (3) PostScript provides operators for setting system-wide
- and device-specific parameters. These parameter
- settings may be retained across jobs and may
- potentially pose a threat to the correct operation of
- the interpreter. The PostScript operators that set
- system and device parameters include, but may not be
-
-
-
-Freed & Borenstein Standards Track [Page 15]
-\f
-RFC 2046 Media Types November 1996
-
-
- limited to, the "setsystemparams" and "setdevparams"
- operators. Message sending software should not
- generate PostScript that depends on the setting of
- system or device parameters to operate correctly. The
- ability to set these parameters will probably be
- unavailable in secure PostScript implementations.
- Message receiving and displaying software should
- disable the ability to change system and device
- parameters. If these operators cannot be completely
- disabled the password associated with them should at
- least be set to a hard-to-guess value.
-
- (4) Some PostScript implementations provide nonstandard
- facilities for the direct loading and execution of
- machine code. Such facilities are quite obviously open
- to substantial abuse. Message sending software should
- not make use of such features. Besides being totally
- hardware-specific, they are also likely to be
- unavailable in secure implementations of PostScript.
- Message receiving and displaying software should not
- allow such operators to be used if they exist.
-
- (5) PostScript is an extensible language, and many, if not
- most, implementations of it provide a number of their
- own extensions. This document does not deal with such
- extensions explicitly since they constitute an unknown
- factor. Message sending software should not make use
- of nonstandard extensions; they are likely to be
- missing from some implementations. Message receiving
- and displaying software should make sure that any
- nonstandard PostScript operators are secure and don't
- present any kind of threat.
-
- (6) It is possible to write PostScript that consumes huge
- amounts of various system resources. It is also
- possible to write PostScript programs that loop
- indefinitely. Both types of programs have the
- potential to cause damage if sent to unsuspecting
- recipients. Message-sending software should avoid the
- construction and dissemination of such programs, which
- is antisocial. Message receiving and displaying
- software should provide appropriate mechanisms to abort
- processing after a reasonable amount of time has
- elapsed. In addition, PostScript interpreters should be
- limited to the consumption of only a reasonable amount
- of any given system resource.
-
-
-
-
-
-Freed & Borenstein Standards Track [Page 16]
-\f
-RFC 2046 Media Types November 1996
-
-
- (7) It is possible to include raw binary information inside
- PostScript in various forms. This is not recommended
- for use in Internet mail, both because it is not
- supported by all PostScript interpreters and because it
- significantly complicates the use of a MIME Content-
- Transfer-Encoding. (Without such binary, PostScript
- may typically be viewed as line-oriented data. The
- treatment of CRLF sequences becomes extremely
- problematic if binary and line-oriented data are mixed
- in a single Postscript data stream.)
-
- (8) Finally, bugs may exist in some PostScript interpreters
- which could possibly be exploited to gain unauthorized
- access to a recipient's system. Apart from noting this
- possibility, there is no specific action to take to
- prevent this, apart from the timely correction of such
- bugs if any are found.
-
-4.5.3. Other Application Subtypes
-
- It is expected that many other subtypes of "application" will be
- defined in the future. MIME implementations must at a minimum treat
- any unrecognized subtypes as being equivalent to "application/octet-
- stream".
-
-5. Composite Media Type Values
-
- The remaining two of the seven initial Content-Type values refer to
- composite entities. Composite entities are handled using MIME
- mechanisms -- a MIME processor typically handles the body directly.
-
-5.1. Multipart Media Type
-
- In the case of multipart entities, in which one or more different
- sets of data are combined in a single body, a "multipart" media type
- field must appear in the entity's header. The body must then contain
- one or more body parts, each preceded by a boundary delimiter line,
- and the last one followed by a closing boundary delimiter line.
- After its boundary delimiter line, each body part then consists of a
- header area, a blank line, and a body area. Thus a body part is
- similar to an RFC 822 message in syntax, but different in meaning.
-
- A body part is an entity and hence is NOT to be interpreted as
- actually being an RFC 822 message. To begin with, NO header fields
- are actually required in body parts. A body part that starts with a
- blank line, therefore, is allowed and is a body part for which all
- default values are to be assumed. In such a case, the absence of a
- Content-Type header usually indicates that the corresponding body has
-
-
-
-Freed & Borenstein Standards Track [Page 17]
-\f
-RFC 2046 Media Types November 1996
-
-
- a content-type of "text/plain; charset=US-ASCII".
-
- The only header fields that have defined meaning for body parts are
- those the names of which begin with "Content-". All other header
- fields may be ignored in body parts. Although they should generally
- be retained if at all possible, they may be discarded by gateways if
- necessary. Such other fields are permitted to appear in body parts
- but must not be depended on. "X-" fields may be created for
- experimental or private purposes, with the recognition that the
- information they contain may be lost at some gateways.
-
- NOTE: The distinction between an RFC 822 message and a body part is
- subtle, but important. A gateway between Internet and X.400 mail,
- for example, must be able to tell the difference between a body part
- that contains an image and a body part that contains an encapsulated
- message, the body of which is a JPEG image. In order to represent
- the latter, the body part must have "Content-Type: message/rfc822",
- and its body (after the blank line) must be the encapsulated message,
- with its own "Content-Type: image/jpeg" header field. The use of
- similar syntax facilitates the conversion of messages to body parts,
- and vice versa, but the distinction between the two must be
- understood by implementors. (For the special case in which parts
- actually are messages, a "digest" subtype is also defined.)
-
- As stated previously, each body part is preceded by a boundary
- delimiter line that contains the boundary delimiter. The boundary
- delimiter MUST NOT appear inside any of the encapsulated parts, on a
- line by itself or as the prefix of any line. This implies that it is
- crucial that the composing agent be able to choose and specify a
- unique boundary parameter value that does not contain the boundary
- parameter value of an enclosing multipart as a prefix.
-
- All present and future subtypes of the "multipart" type must use an
- identical syntax. Subtypes may differ in their semantics, and may
- impose additional restrictions on syntax, but must conform to the
- required syntax for the "multipart" type. This requirement ensures
- that all conformant user agents will at least be able to recognize
- and separate the parts of any multipart entity, even those of an
- unrecognized subtype.
-
- As stated in the definition of the Content-Transfer-Encoding field
- [RFC 2045], no encoding other than "7bit", "8bit", or "binary" is
- permitted for entities of type "multipart". The "multipart" boundary
- delimiters and header fields are always represented as 7bit US-ASCII
- in any case (though the header fields may encode non-US-ASCII header
- text as per RFC 2047) and data within the body parts can be encoded
- on a part-by-part basis, with Content-Transfer-Encoding fields for
- each appropriate body part.
-
-
-
-Freed & Borenstein Standards Track [Page 18]
-\f
-RFC 2046 Media Types November 1996
-
-
-5.1.1. Common Syntax
-
- This section defines a common syntax for subtypes of "multipart".
- All subtypes of "multipart" must use this syntax. A simple example
- of a multipart message also appears in this section. An example of a
- more complex multipart message is given in RFC 2049.
-
- The Content-Type field for multipart entities requires one parameter,
- "boundary". The boundary delimiter line is then defined as a line
- consisting entirely of two hyphen characters ("-", decimal value 45)
- followed by the boundary parameter value from the Content-Type header
- field, optional linear whitespace, and a terminating CRLF.
-
- NOTE: The hyphens are for rough compatibility with the earlier RFC
- 934 method of message encapsulation, and for ease of searching for
- the boundaries in some implementations. However, it should be noted
- that multipart messages are NOT completely compatible with RFC 934
- encapsulations; in particular, they do not obey RFC 934 quoting
- conventions for embedded lines that begin with hyphens. This
- mechanism was chosen over the RFC 934 mechanism because the latter
- causes lines to grow with each level of quoting. The combination of
- this growth with the fact that SMTP implementations sometimes wrap
- long lines made the RFC 934 mechanism unsuitable for use in the event
- that deeply-nested multipart structuring is ever desired.
-
- WARNING TO IMPLEMENTORS: The grammar for parameters on the Content-
- type field is such that it is often necessary to enclose the boundary
- parameter values in quotes on the Content-type line. This is not
- always necessary, but never hurts. Implementors should be sure to
- study the grammar carefully in order to avoid producing invalid
- Content-type fields. Thus, a typical "multipart" Content-Type header
- field might look like this:
-
- Content-Type: multipart/mixed; boundary=gc0p4Jq0M2Yt08j34c0p
-
- But the following is not valid:
-
- Content-Type: multipart/mixed; boundary=gc0pJq0M:08jU534c0p
-
- (because of the colon) and must instead be represented as
-
- Content-Type: multipart/mixed; boundary="gc0pJq0M:08jU534c0p"
-
- This Content-Type value indicates that the content consists of one or
- more parts, each with a structure that is syntactically identical to
- an RFC 822 message, except that the header area is allowed to be
- completely empty, and that the parts are each preceded by the line
-
-
-
-
-Freed & Borenstein Standards Track [Page 19]
-\f
-RFC 2046 Media Types November 1996
-
-
- --gc0pJq0M:08jU534c0p
-
- The boundary delimiter MUST occur at the beginning of a line, i.e.,
- following a CRLF, and the initial CRLF is considered to be attached
- to the boundary delimiter line rather than part of the preceding
- part. The boundary may be followed by zero or more characters of
- linear whitespace. It is then terminated by either another CRLF and
- the header fields for the next part, or by two CRLFs, in which case
- there are no header fields for the next part. If no Content-Type
- field is present it is assumed to be "message/rfc822" in a
- "multipart/digest" and "text/plain" otherwise.
-
- NOTE: The CRLF preceding the boundary delimiter line is conceptually
- attached to the boundary so that it is possible to have a part that
- does not end with a CRLF (line break). Body parts that must be
- considered to end with line breaks, therefore, must have two CRLFs
- preceding the boundary delimiter line, the first of which is part of
- the preceding body part, and the second of which is part of the
- encapsulation boundary.
-
- Boundary delimiters must not appear within the encapsulated material,
- and must be no longer than 70 characters, not counting the two
- leading hyphens.
-
- The boundary delimiter line following the last body part is a
- distinguished delimiter that indicates that no further body parts
- will follow. Such a delimiter line is identical to the previous
- delimiter lines, with the addition of two more hyphens after the
- boundary parameter value.
-
- --gc0pJq0M:08jU534c0p--
-
- NOTE TO IMPLEMENTORS: Boundary string comparisons must compare the
- boundary value with the beginning of each candidate line. An exact
- match of the entire candidate line is not required; it is sufficient
- that the boundary appear in its entirety following the CRLF.
-
- There appears to be room for additional information prior to the
- first boundary delimiter line and following the final boundary
- delimiter line. These areas should generally be left blank, and
- implementations must ignore anything that appears before the first
- boundary delimiter line or after the last one.
-
- NOTE: These "preamble" and "epilogue" areas are generally not used
- because of the lack of proper typing of these parts and the lack of
- clear semantics for handling these areas at gateways, particularly
- X.400 gateways. However, rather than leaving the preamble area
- blank, many MIME implementations have found this to be a convenient
-
-
-
-Freed & Borenstein Standards Track [Page 20]
-\f
-RFC 2046 Media Types November 1996
-
-
- place to insert an explanatory note for recipients who read the
- message with pre-MIME software, since such notes will be ignored by
- MIME-compliant software.
-
- NOTE: Because boundary delimiters must not appear in the body parts
- being encapsulated, a user agent must exercise care to choose a
- unique boundary parameter value. The boundary parameter value in the
- example above could have been the result of an algorithm designed to
- produce boundary delimiters with a very low probability of already
- existing in the data to be encapsulated without having to prescan the
- data. Alternate algorithms might result in more "readable" boundary
- delimiters for a recipient with an old user agent, but would require
- more attention to the possibility that the boundary delimiter might
- appear at the beginning of some line in the encapsulated part. The
- simplest boundary delimiter line possible is something like "---",
- with a closing boundary delimiter line of "-----".
-
- As a very simple example, the following multipart message has two
- parts, both of them plain text, one of them explicitly typed and one
- of them implicitly typed:
-
- From: Nathaniel Borenstein <nsb@bellcore.com>
- To: Ned Freed <ned@innosoft.com>
- Date: Sun, 21 Mar 1993 23:56:48 -0800 (PST)
- Subject: Sample message
- MIME-Version: 1.0
- Content-type: multipart/mixed; boundary="simple boundary"
-
- This is the preamble. It is to be ignored, though it
- is a handy place for composition agents to include an
- explanatory note to non-MIME conformant readers.
-
- --simple boundary
-
- This is implicitly typed plain US-ASCII text.
- It does NOT end with a linebreak.
- --simple boundary
- Content-type: text/plain; charset=us-ascii
-
- This is explicitly typed plain US-ASCII text.
- It DOES end with a linebreak.
-
- --simple boundary--
-
- This is the epilogue. It is also to be ignored.
-
-
-
-
-
-
-Freed & Borenstein Standards Track [Page 21]
-\f
-RFC 2046 Media Types November 1996
-
-
- The use of a media type of "multipart" in a body part within another
- "multipart" entity is explicitly allowed. In such cases, for obvious
- reasons, care must be taken to ensure that each nested "multipart"
- entity uses a different boundary delimiter. See RFC 2049 for an
- example of nested "multipart" entities.
-
- The use of the "multipart" media type with only a single body part
- may be useful in certain contexts, and is explicitly permitted.
-
- NOTE: Experience has shown that a "multipart" media type with a
- single body part is useful for sending non-text media types. It has
- the advantage of providing the preamble as a place to include
- decoding instructions. In addition, a number of SMTP gateways move
- or remove the MIME headers, and a clever MIME decoder can take a good
- guess at multipart boundaries even in the absence of the Content-Type
- header and thereby successfully decode the message.
-
- The only mandatory global parameter for the "multipart" media type is
- the boundary parameter, which consists of 1 to 70 characters from a
- set of characters known to be very robust through mail gateways, and
- NOT ending with white space. (If a boundary delimiter line appears to
- end with white space, the white space must be presumed to have been
- added by a gateway, and must be deleted.) It is formally specified
- by the following BNF:
-
- boundary := 0*69<bchars> bcharsnospace
-
- bchars := bcharsnospace / " "
-
- bcharsnospace := DIGIT / ALPHA / "'" / "(" / ")" /
- "+" / "_" / "," / "-" / "." /
- "/" / ":" / "=" / "?"
-
- Overall, the body of a "multipart" entity may be specified as
- follows:
-
- dash-boundary := "--" boundary
- ; boundary taken from the value of
- ; boundary parameter of the
- ; Content-Type field.
-
- multipart-body := [preamble CRLF]
- dash-boundary transport-padding CRLF
- body-part *encapsulation
- close-delimiter transport-padding
- [CRLF epilogue]
-
-
-
-
-
-Freed & Borenstein Standards Track [Page 22]
-\f
-RFC 2046 Media Types November 1996
-
-
- transport-padding := *LWSP-char
- ; Composers MUST NOT generate
- ; non-zero length transport
- ; padding, but receivers MUST
- ; be able to handle padding
- ; added by message transports.
-
- encapsulation := delimiter transport-padding
- CRLF body-part
-
- delimiter := CRLF dash-boundary
-
- close-delimiter := delimiter "--"
-
- preamble := discard-text
-
- epilogue := discard-text
-
- discard-text := *(*text CRLF) *text
- ; May be ignored or discarded.
-
- body-part := MIME-part-headers [CRLF *OCTET]
- ; Lines in a body-part must not start
- ; with the specified dash-boundary and
- ; the delimiter must not appear anywhere
- ; in the body part. Note that the
- ; semantics of a body-part differ from
- ; the semantics of a message, as
- ; described in the text.
-
- OCTET := <any 0-255 octet value>
-
- IMPORTANT: The free insertion of linear-white-space and RFC 822
- comments between the elements shown in this BNF is NOT allowed since
- this BNF does not specify a structured header field.
-
- NOTE: In certain transport enclaves, RFC 822 restrictions such as
- the one that limits bodies to printable US-ASCII characters may not
- be in force. (That is, the transport domains may exist that resemble
- standard Internet mail transport as specified in RFC 821 and assumed
- by RFC 822, but without certain restrictions.) The relaxation of
- these restrictions should be construed as locally extending the
- definition of bodies, for example to include octets outside of the
- US-ASCII range, as long as these extensions are supported by the
- transport and adequately documented in the Content- Transfer-Encoding
- header field. However, in no event are headers (either message
- headers or body part headers) allowed to contain anything other than
- US-ASCII characters.
-
-
-
-Freed & Borenstein Standards Track [Page 23]
-\f
-RFC 2046 Media Types November 1996
-
-
- NOTE: Conspicuously missing from the "multipart" type is a notion of
- structured, related body parts. It is recommended that those wishing
- to provide more structured or integrated multipart messaging
- facilities should define subtypes of multipart that are syntactically
- identical but define relationships between the various parts. For
- example, subtypes of multipart could be defined that include a
- distinguished part which in turn is used to specify the relationships
- between the other parts, probably referring to them by their
- Content-ID field. Old implementations will not recognize the new
- subtype if this approach is used, but will treat it as
- multipart/mixed and will thus be able to show the user the parts that
- are recognized.
-
-5.1.2. Handling Nested Messages and Multiparts
-
- The "message/rfc822" subtype defined in a subsequent section of this
- document has no terminating condition other than running out of data.
- Similarly, an improperly truncated "multipart" entity may not have
- any terminating boundary marker, and can turn up operationally due to
- mail system malfunctions.
-
- It is essential that such entities be handled correctly when they are
- themselves imbedded inside of another "multipart" structure. MIME
- implementations are therefore required to recognize outer level
- boundary markers at ANY level of inner nesting. It is not sufficient
- to only check for the next expected marker or other terminating
- condition.
-
-5.1.3. Mixed Subtype
-
- The "mixed" subtype of "multipart" is intended for use when the body
- parts are independent and need to be bundled in a particular order.
- Any "multipart" subtypes that an implementation does not recognize
- must be treated as being of subtype "mixed".
-
-5.1.4. Alternative Subtype
-
- The "multipart/alternative" type is syntactically identical to
- "multipart/mixed", but the semantics are different. In particular,
- each of the body parts is an "alternative" version of the same
- information.
-
- Systems should recognize that the content of the various parts are
- interchangeable. Systems should choose the "best" type based on the
- local environment and references, in some cases even through user
- interaction. As with "multipart/mixed", the order of body parts is
- significant. In this case, the alternatives appear in an order of
- increasing faithfulness to the original content. In general, the
-
-
-
-Freed & Borenstein Standards Track [Page 24]
-\f
-RFC 2046 Media Types November 1996
-
-
- best choice is the LAST part of a type supported by the recipient
- system's local environment.
-
- "Multipart/alternative" may be used, for example, to send a message
- in a fancy text format in such a way that it can easily be displayed
- anywhere:
-
- From: Nathaniel Borenstein <nsb@bellcore.com>
- To: Ned Freed <ned@innosoft.com>
- Date: Mon, 22 Mar 1993 09:41:09 -0800 (PST)
- Subject: Formatted text mail
- MIME-Version: 1.0
- Content-Type: multipart/alternative; boundary=boundary42
-
- --boundary42
- Content-Type: text/plain; charset=us-ascii
-
- ... plain text version of message goes here ...
-
- --boundary42
- Content-Type: text/enriched
-
- ... RFC 1896 text/enriched version of same message
- goes here ...
-
- --boundary42
- Content-Type: application/x-whatever
-
- ... fanciest version of same message goes here ...
-
- --boundary42--
-
- In this example, users whose mail systems understood the
- "application/x-whatever" format would see only the fancy version,
- while other users would see only the enriched or plain text version,
- depending on the capabilities of their system.
-
- In general, user agents that compose "multipart/alternative" entities
- must place the body parts in increasing order of preference, that is,
- with the preferred format last. For fancy text, the sending user
- agent should put the plainest format first and the richest format
- last. Receiving user agents should pick and display the last format
- they are capable of displaying. In the case where one of the
- alternatives is itself of type "multipart" and contains unrecognized
- sub-parts, the user agent may choose either to show that alternative,
- an earlier alternative, or both.
-
-
-
-
-
-Freed & Borenstein Standards Track [Page 25]
-\f
-RFC 2046 Media Types November 1996
-
-
- NOTE: From an implementor's perspective, it might seem more sensible
- to reverse this ordering, and have the plainest alternative last.
- However, placing the plainest alternative first is the friendliest
- possible option when "multipart/alternative" entities are viewed
- using a non-MIME-conformant viewer. While this approach does impose
- some burden on conformant MIME viewers, interoperability with older
- mail readers was deemed to be more important in this case.
-
- It may be the case that some user agents, if they can recognize more
- than one of the formats, will prefer to offer the user the choice of
- which format to view. This makes sense, for example, if a message
- includes both a nicely- formatted image version and an easily-edited
- text version. What is most critical, however, is that the user not
- automatically be shown multiple versions of the same data. Either
- the user should be shown the last recognized version or should be
- given the choice.
-
- THE SEMANTICS OF CONTENT-ID IN MULTIPART/ALTERNATIVE: Each part of a
- "multipart/alternative" entity represents the same data, but the
- mappings between the two are not necessarily without information
- loss. For example, information is lost when translating ODA to
- PostScript or plain text. It is recommended that each part should
- have a different Content-ID value in the case where the information
- content of the two parts is not identical. And when the information
- content is identical -- for example, where several parts of type
- "message/external-body" specify alternate ways to access the
- identical data -- the same Content-ID field value should be used, to
- optimize any caching mechanisms that might be present on the
- recipient's end. However, the Content-ID values used by the parts
- should NOT be the same Content-ID value that describes the
- "multipart/alternative" as a whole, if there is any such Content-ID
- field. That is, one Content-ID value will refer to the
- "multipart/alternative" entity, while one or more other Content-ID
- values will refer to the parts inside it.
-
-5.1.5. Digest Subtype
-
- This document defines a "digest" subtype of the "multipart" Content-
- Type. This type is syntactically identical to "multipart/mixed", but
- the semantics are different. In particular, in a digest, the default
- Content-Type value for a body part is changed from "text/plain" to
- "message/rfc822". This is done to allow a more readable digest
- format that is largely compatible (except for the quoting convention)
- with RFC 934.
-
- Note: Though it is possible to specify a Content-Type value for a
- body part in a digest which is other than "message/rfc822", such as a
- "text/plain" part containing a description of the material in the
-
-
-
-Freed & Borenstein Standards Track [Page 26]
-\f
-RFC 2046 Media Types November 1996
-
-
- digest, actually doing so is undesireble. The "multipart/digest"
- Content-Type is intended to be used to send collections of messages.
- If a "text/plain" part is needed, it should be included as a seperate
- part of a "multipart/mixed" message.
-
- A digest in this format might, then, look something like this:
-
- From: Moderator-Address
- To: Recipient-List
- Date: Mon, 22 Mar 1994 13:34:51 +0000
- Subject: Internet Digest, volume 42
- MIME-Version: 1.0
- Content-Type: multipart/mixed;
- boundary="---- main boundary ----"
-
- ------ main boundary ----
-
- ...Introductory text or table of contents...
-
- ------ main boundary ----
- Content-Type: multipart/digest;
- boundary="---- next message ----"
-
- ------ next message ----
-
- From: someone-else
- Date: Fri, 26 Mar 1993 11:13:32 +0200
- Subject: my opinion
-
- ...body goes here ...
-
- ------ next message ----
-
- From: someone-else-again
- Date: Fri, 26 Mar 1993 10:07:13 -0500
- Subject: my different opinion
-
- ... another body goes here ...
-
- ------ next message ------
-
- ------ main boundary ------
-
-5.1.6. Parallel Subtype
-
- This document defines a "parallel" subtype of the "multipart"
- Content-Type. This type is syntactically identical to
- "multipart/mixed", but the semantics are different. In particular,
-
-
-
-Freed & Borenstein Standards Track [Page 27]
-\f
-RFC 2046 Media Types November 1996
-
-
- in a parallel entity, the order of body parts is not significant.
-
- A common presentation of this type is to display all of the parts
- simultaneously on hardware and software that are capable of doing so.
- However, composing agents should be aware that many mail readers will
- lack this capability and will show the parts serially in any event.
-
-5.1.7. Other Multipart Subtypes
-
- Other "multipart" subtypes are expected in the future. MIME
- implementations must in general treat unrecognized subtypes of
- "multipart" as being equivalent to "multipart/mixed".
-
-5.2. Message Media Type
-
- It is frequently desirable, in sending mail, to encapsulate another
- mail message. A special media type, "message", is defined to
- facilitate this. In particular, the "rfc822" subtype of "message" is
- used to encapsulate RFC 822 messages.
-
- NOTE: It has been suggested that subtypes of "message" might be
- defined for forwarded or rejected messages. However, forwarded and
- rejected messages can be handled as multipart messages in which the
- first part contains any control or descriptive information, and a
- second part, of type "message/rfc822", is the forwarded or rejected
- message. Composing rejection and forwarding messages in this manner
- will preserve the type information on the original message and allow
- it to be correctly presented to the recipient, and hence is strongly
- encouraged.
-
- Subtypes of "message" often impose restrictions on what encodings are
- allowed. These restrictions are described in conjunction with each
- specific subtype.
-
- Mail gateways, relays, and other mail handling agents are commonly
- known to alter the top-level header of an RFC 822 message. In
- particular, they frequently add, remove, or reorder header fields.
- These operations are explicitly forbidden for the encapsulated
- headers embedded in the bodies of messages of type "message."
-
-5.2.1. RFC822 Subtype
-
- A media type of "message/rfc822" indicates that the body contains an
- encapsulated message, with the syntax of an RFC 822 message.
- However, unlike top-level RFC 822 messages, the restriction that each
- "message/rfc822" body must include a "From", "Date", and at least one
- destination header is removed and replaced with the requirement that
- at least one of "From", "Subject", or "Date" must be present.
-
-
-
-Freed & Borenstein Standards Track [Page 28]
-\f
-RFC 2046 Media Types November 1996
-
-
- It should be noted that, despite the use of the numbers "822", a
- "message/rfc822" entity isn't restricted to material in strict
- conformance to RFC822, nor are the semantics of "message/rfc822"
- objects restricted to the semantics defined in RFC822. More
- specifically, a "message/rfc822" message could well be a News article
- or a MIME message.
-
- No encoding other than "7bit", "8bit", or "binary" is permitted for
- the body of a "message/rfc822" entity. The message header fields are
- always US-ASCII in any case, and data within the body can still be
- encoded, in which case the Content-Transfer-Encoding header field in
- the encapsulated message will reflect this. Non-US-ASCII text in the
- headers of an encapsulated message can be specified using the
- mechanisms described in RFC 2047.
-
-5.2.2. Partial Subtype
-
- The "partial" subtype is defined to allow large entities to be
- delivered as several separate pieces of mail and automatically
- reassembled by a receiving user agent. (The concept is similar to IP
- fragmentation and reassembly in the basic Internet Protocols.) This
- mechanism can be used when intermediate transport agents limit the
- size of individual messages that can be sent. The media type
- "message/partial" thus indicates that the body contains a fragment of
- a larger entity.
-
- Because data of type "message" may never be encoded in base64 or
- quoted-printable, a problem might arise if "message/partial" entities
- are constructed in an environment that supports binary or 8bit
- transport. The problem is that the binary data would be split into
- multiple "message/partial" messages, each of them requiring binary
- transport. If such messages were encountered at a gateway into a
- 7bit transport environment, there would be no way to properly encode
- them for the 7bit world, aside from waiting for all of the fragments,
- reassembling the inner message, and then encoding the reassembled
- data in base64 or quoted-printable. Since it is possible that
- different fragments might go through different gateways, even this is
- not an acceptable solution. For this reason, it is specified that
- entities of type "message/partial" must always have a content-
- transfer-encoding of 7bit (the default). In particular, even in
- environments that support binary or 8bit transport, the use of a
- content- transfer-encoding of "8bit" or "binary" is explicitly
- prohibited for MIME entities of type "message/partial". This in turn
- implies that the inner message must not use "8bit" or "binary"
- encoding.
-
-
-
-
-
-
-Freed & Borenstein Standards Track [Page 29]
-\f
-RFC 2046 Media Types November 1996
-
-
- Because some message transfer agents may choose to automatically
- fragment large messages, and because such agents may use very
- different fragmentation thresholds, it is possible that the pieces of
- a partial message, upon reassembly, may prove themselves to comprise
- a partial message. This is explicitly permitted.
-
- Three parameters must be specified in the Content-Type field of type
- "message/partial": The first, "id", is a unique identifier, as close
- to a world-unique identifier as possible, to be used to match the
- fragments together. (In general, the identifier is essentially a
- message-id; if placed in double quotes, it can be ANY message-id, in
- accordance with the BNF for "parameter" given in RFC 2045.) The
- second, "number", an integer, is the fragment number, which indicates
- where this fragment fits into the sequence of fragments. The third,
- "total", another integer, is the total number of fragments. This
- third subfield is required on the final fragment, and is optional
- (though encouraged) on the earlier fragments. Note also that these
- parameters may be given in any order.
-
- Thus, the second piece of a 3-piece message may have either of the
- following header fields:
-
- Content-Type: Message/Partial; number=2; total=3;
- id="oc=jpbe0M2Yt4s@thumper.bellcore.com"
-
- Content-Type: Message/Partial;
- id="oc=jpbe0M2Yt4s@thumper.bellcore.com";
- number=2
-
- But the third piece MUST specify the total number of fragments:
-
- Content-Type: Message/Partial; number=3; total=3;
- id="oc=jpbe0M2Yt4s@thumper.bellcore.com"
-
- Note that fragment numbering begins with 1, not 0.
-
- When the fragments of an entity broken up in this manner are put
- together, the result is always a complete MIME entity, which may have
- its own Content-Type header field, and thus may contain any other
- data type.
-
-5.2.2.1. Message Fragmentation and Reassembly
-
- The semantics of a reassembled partial message must be those of the
- "inner" message, rather than of a message containing the inner
- message. This makes it possible, for example, to send a large audio
- message as several partial messages, and still have it appear to the
- recipient as a simple audio message rather than as an encapsulated
-
-
-
-Freed & Borenstein Standards Track [Page 30]
-\f
-RFC 2046 Media Types November 1996
-
-
- message containing an audio message. That is, the encapsulation of
- the message is considered to be "transparent".
-
- When generating and reassembling the pieces of a "message/partial"
- message, the headers of the encapsulated message must be merged with
- the headers of the enclosing entities. In this process the following
- rules must be observed:
-
- (1) Fragmentation agents must split messages at line
- boundaries only. This restriction is imposed because
- splits at points other than the ends of lines in turn
- depends on message transports being able to preserve
- the semantics of messages that don't end with a CRLF
- sequence. Many transports are incapable of preserving
- such semantics.
-
- (2) All of the header fields from the initial enclosing
- message, except those that start with "Content-" and
- the specific header fields "Subject", "Message-ID",
- "Encrypted", and "MIME-Version", must be copied, in
- order, to the new message.
-
- (3) The header fields in the enclosed message which start
- with "Content-", plus the "Subject", "Message-ID",
- "Encrypted", and "MIME-Version" fields, must be
- appended, in order, to the header fields of the new
- message. Any header fields in the enclosed message
- which do not start with "Content-" (except for the
- "Subject", "Message-ID", "Encrypted", and "MIME-
- Version" fields) will be ignored and dropped.
-
- (4) All of the header fields from the second and any
- subsequent enclosing messages are discarded by the
- reassembly process.
-
-5.2.2.2. Fragmentation and Reassembly Example
-
- If an audio message is broken into two pieces, the first piece might
- look something like this:
-
- X-Weird-Header-1: Foo
- From: Bill@host.com
- To: joe@otherhost.com
- Date: Fri, 26 Mar 1993 12:59:38 -0500 (EST)
- Subject: Audio mail (part 1 of 2)
- Message-ID: <id1@host.com>
- MIME-Version: 1.0
- Content-type: message/partial; id="ABC@host.com";
-
-
-
-Freed & Borenstein Standards Track [Page 31]
-\f
-RFC 2046 Media Types November 1996
-
-
- number=1; total=2
-
- X-Weird-Header-1: Bar
- X-Weird-Header-2: Hello
- Message-ID: <anotherid@foo.com>
- Subject: Audio mail
- MIME-Version: 1.0
- Content-type: audio/basic
- Content-transfer-encoding: base64
-
- ... first half of encoded audio data goes here ...
-
- and the second half might look something like this:
-
- From: Bill@host.com
- To: joe@otherhost.com
- Date: Fri, 26 Mar 1993 12:59:38 -0500 (EST)
- Subject: Audio mail (part 2 of 2)
- MIME-Version: 1.0
- Message-ID: <id2@host.com>
- Content-type: message/partial;
- id="ABC@host.com"; number=2; total=2
-
- ... second half of encoded audio data goes here ...
-
- Then, when the fragmented message is reassembled, the resulting
- message to be displayed to the user should look something like this:
-
- X-Weird-Header-1: Foo
- From: Bill@host.com
- To: joe@otherhost.com
- Date: Fri, 26 Mar 1993 12:59:38 -0500 (EST)
- Subject: Audio mail
- Message-ID: <anotherid@foo.com>
- MIME-Version: 1.0
- Content-type: audio/basic
- Content-transfer-encoding: base64
-
- ... first half of encoded audio data goes here ...
- ... second half of encoded audio data goes here ...
-
- The inclusion of a "References" field in the headers of the second
- and subsequent pieces of a fragmented message that references the
- Message-Id on the previous piece may be of benefit to mail readers
- that understand and track references. However, the generation of
- such "References" fields is entirely optional.
-
-
-
-
-
-Freed & Borenstein Standards Track [Page 32]
-\f
-RFC 2046 Media Types November 1996
-
-
- Finally, it should be noted that the "Encrypted" header field has
- been made obsolete by Privacy Enhanced Messaging (PEM) [RFC-1421,
- RFC-1422, RFC-1423, RFC-1424], but the rules above are nevertheless
- believed to describe the correct way to treat it if it is encountered
- in the context of conversion to and from "message/partial" fragments.
-
-5.2.3. External-Body Subtype
-
- The external-body subtype indicates that the actual body data are not
- included, but merely referenced. In this case, the parameters
- describe a mechanism for accessing the external data.
-
- When a MIME entity is of type "message/external-body", it consists of
- a header, two consecutive CRLFs, and the message header for the
- encapsulated message. If another pair of consecutive CRLFs appears,
- this of course ends the message header for the encapsulated message.
- However, since the encapsulated message's body is itself external, it
- does NOT appear in the area that follows. For example, consider the
- following message:
-
- Content-type: message/external-body;
- access-type=local-file;
- name="/u/nsb/Me.jpeg"
-
- Content-type: image/jpeg
- Content-ID: <id42@guppylake.bellcore.com>
- Content-Transfer-Encoding: binary
-
- THIS IS NOT REALLY THE BODY!
-
- The area at the end, which might be called the "phantom body", is
- ignored for most external-body messages. However, it may be used to
- contain auxiliary information for some such messages, as indeed it is
- when the access-type is "mail- server". The only access-type defined
- in this document that uses the phantom body is "mail-server", but
- other access-types may be defined in the future in other
- specifications that use this area.
-
- The encapsulated headers in ALL "message/external-body" entities MUST
- include a Content-ID header field to give a unique identifier by
- which to reference the data. This identifier may be used for caching
- mechanisms, and for recognizing the receipt of the data when the
- access-type is "mail-server".
-
- Note that, as specified here, the tokens that describe external-body
- data, such as file names and mail server commands, are required to be
- in the US-ASCII character set.
-
-
-
-
-Freed & Borenstein Standards Track [Page 33]
-\f
-RFC 2046 Media Types November 1996
-
-
- If this proves problematic in practice, a new mechanism may be
- required as a future extension to MIME, either as newly defined
- access-types for "message/external-body" or by some other mechanism.
-
- As with "message/partial", MIME entities of type "message/external-
- body" MUST have a content-transfer-encoding of 7bit (the default).
- In particular, even in environments that support binary or 8bit
- transport, the use of a content- transfer-encoding of "8bit" or
- "binary" is explicitly prohibited for entities of type
- "message/external-body".
-
-5.2.3.1. General External-Body Parameters
-
- The parameters that may be used with any "message/external- body"
- are:
-
- (1) ACCESS-TYPE -- A word indicating the supported access
- mechanism by which the file or data may be obtained.
- This word is not case sensitive. Values include, but
- are not limited to, "FTP", "ANON-FTP", "TFTP", "LOCAL-
- FILE", and "MAIL-SERVER". Future values, except for
- experimental values beginning with "X-", must be
- registered with IANA, as described in RFC 2048.
- This parameter is unconditionally mandatory and MUST be
- present on EVERY "message/external-body".
-
- (2) EXPIRATION -- The date (in the RFC 822 "date-time"
- syntax, as extended by RFC 1123 to permit 4 digits in
- the year field) after which the existence of the
- external data is not guaranteed. This parameter may be
- used with ANY access-type and is ALWAYS optional.
-
- (3) SIZE -- The size (in octets) of the data. The intent
- of this parameter is to help the recipient decide
- whether or not to expend the necessary resources to
- retrieve the external data. Note that this describes
- the size of the data in its canonical form, that is,
- before any Content-Transfer-Encoding has been applied
- or after the data have been decoded. This parameter
- may be used with ANY access-type and is ALWAYS
- optional.
-
- (4) PERMISSION -- A case-insensitive field that indicates
- whether or not it is expected that clients might also
- attempt to overwrite the data. By default, or if
- permission is "read", the assumption is that they are
- not, and that if the data is retrieved once, it is
- never needed again. If PERMISSION is "read-write",
-
-
-
-Freed & Borenstein Standards Track [Page 34]
-\f
-RFC 2046 Media Types November 1996
-
-
- this assumption is invalid, and any local copy must be
- considered no more than a cache. "Read" and "Read-
- write" are the only defined values of permission. This
- parameter may be used with ANY access-type and is
- ALWAYS optional.
-
- The precise semantics of the access-types defined here are described
- in the sections that follow.
-
-5.2.3.2. The 'ftp' and 'tftp' Access-Types
-
- An access-type of FTP or TFTP indicates that the message body is
- accessible as a file using the FTP [RFC-959] or TFTP [RFC- 783]
- protocols, respectively. For these access-types, the following
- additional parameters are mandatory:
-
- (1) NAME -- The name of the file that contains the actual
- body data.
-
- (2) SITE -- A machine from which the file may be obtained,
- using the given protocol. This must be a fully
- qualified domain name, not a nickname.
-
- (3) Before any data are retrieved, using FTP, the user will
- generally need to be asked to provide a login id and a
- password for the machine named by the site parameter.
- For security reasons, such an id and password are not
- specified as content-type parameters, but must be
- obtained from the user.
-
- In addition, the following parameters are optional:
-
- (1) DIRECTORY -- A directory from which the data named by
- NAME should be retrieved.
-
- (2) MODE -- A case-insensitive string indicating the mode
- to be used when retrieving the information. The valid
- values for access-type "TFTP" are "NETASCII", "OCTET",
- and "MAIL", as specified by the TFTP protocol [RFC-
- 783]. The valid values for access-type "FTP" are
- "ASCII", "EBCDIC", "IMAGE", and "LOCALn" where "n" is a
- decimal integer, typically 8. These correspond to the
- representation types "A" "E" "I" and "L n" as specified
- by the FTP protocol [RFC-959]. Note that "BINARY" and
- "TENEX" are not valid values for MODE and that "OCTET"
- or "IMAGE" or "LOCAL8" should be used instead. IF MODE
- is not specified, the default value is "NETASCII" for
- TFTP and "ASCII" otherwise.
-
-
-
-Freed & Borenstein Standards Track [Page 35]
-\f
-RFC 2046 Media Types November 1996
-
-
-5.2.3.3. The 'anon-ftp' Access-Type
-
- The "anon-ftp" access-type is identical to the "ftp" access type,
- except that the user need not be asked to provide a name and password
- for the specified site. Instead, the ftp protocol will be used with
- login "anonymous" and a password that corresponds to the user's mail
- address.
-
-5.2.3.4. The 'local-file' Access-Type
-
- An access-type of "local-file" indicates that the actual body is
- accessible as a file on the local machine. Two additional parameters
- are defined for this access type:
-
- (1) NAME -- The name of the file that contains the actual
- body data. This parameter is mandatory for the
- "local-file" access-type.
-
- (2) SITE -- A domain specifier for a machine or set of
- machines that are known to have access to the data
- file. This optional parameter is used to describe the
- locality of reference for the data, that is, the site
- or sites at which the file is expected to be visible.
- Asterisks may be used for wildcard matching to a part
- of a domain name, such as "*.bellcore.com", to indicate
- a set of machines on which the data should be directly
- visible, while a single asterisk may be used to
- indicate a file that is expected to be universally
- available, e.g., via a global file system.
-
-5.2.3.5. The 'mail-server' Access-Type
-
- The "mail-server" access-type indicates that the actual body is
- available from a mail server. Two additional parameters are defined
- for this access-type:
-
- (1) SERVER -- The addr-spec of the mail server from which
- the actual body data can be obtained. This parameter
- is mandatory for the "mail-server" access-type.
-
- (2) SUBJECT -- The subject that is to be used in the mail
- that is sent to obtain the data. Note that keying mail
- servers on Subject lines is NOT recommended, but such
- mail servers are known to exist. This is an optional
- parameter.
-
-
-
-
-
-
-Freed & Borenstein Standards Track [Page 36]
-\f
-RFC 2046 Media Types November 1996
-
-
- Because mail servers accept a variety of syntaxes, some of which is
- multiline, the full command to be sent to a mail server is not
- included as a parameter in the content-type header field. Instead,
- it is provided as the "phantom body" when the media type is
- "message/external-body" and the access-type is mail-server.
-
- Note that MIME does not define a mail server syntax. Rather, it
- allows the inclusion of arbitrary mail server commands in the phantom
- body. Implementations must include the phantom body in the body of
- the message it sends to the mail server address to retrieve the
- relevant data.
-
- Unlike other access-types, mail-server access is asynchronous and
- will happen at an unpredictable time in the future. For this reason,
- it is important that there be a mechanism by which the returned data
- can be matched up with the original "message/external-body" entity.
- MIME mail servers must use the same Content-ID field on the returned
- message that was used in the original "message/external-body"
- entities, to facilitate such matching.
-
-5.2.3.6. External-Body Security Issues
-
- "Message/external-body" entities give rise to two important security
- issues:
-
- (1) Accessing data via a "message/external-body" reference
- effectively results in the message recipient performing
- an operation that was specified by the message
- originator. It is therefore possible for the message
- originator to trick a recipient into doing something
- they would not have done otherwise. For example, an
- originator could specify a action that attempts
- retrieval of material that the recipient is not
- authorized to obtain, causing the recipient to
- unwittingly violate some security policy. For this
- reason, user agents capable of resolving external
- references must always take steps to describe the
- action they are to take to the recipient and ask for
- explicit permisssion prior to performing it.
-
- The 'mail-server' access-type is particularly
- vulnerable, in that it causes the recipient to send a
- new message whose contents are specified by the
- original message's originator. Given the potential for
- abuse, any such request messages that are constructed
- should contain a clear indication that they were
- generated automatically (e.g. in a Comments: header
- field) in an attempt to resolve a MIME
-
-
-
-Freed & Borenstein Standards Track [Page 37]
-\f
-RFC 2046 Media Types November 1996
-
-
- "message/external-body" reference.
-
- (2) MIME will sometimes be used in environments that
- provide some guarantee of message integrity and
- authenticity. If present, such guarantees may apply
- only to the actual direct content of messages -- they
- may or may not apply to data accessed through MIME's
- "message/external-body" mechanism. In particular, it
- may be possible to subvert certain access mechanisms
- even when the messaging system itself is secure.
-
- It should be noted that this problem exists either with
- or without the availabilty of MIME mechanisms. A
- casual reference to an FTP site containing a document
- in the text of a secure message brings up similar
- issues -- the only difference is that MIME provides for
- automatic retrieval of such material, and users may
- place unwarranted trust is such automatic retrieval
- mechanisms.
-
-5.2.3.7. Examples and Further Explanations
-
- When the external-body mechanism is used in conjunction with the
- "multipart/alternative" media type it extends the functionality of
- "multipart/alternative" to include the case where the same entity is
- provided in the same format but via different accces mechanisms.
- When this is done the originator of the message must order the parts
- first in terms of preferred formats and then by preferred access
- mechanisms. The recipient's viewer should then evaluate the list
- both in terms of format and access mechanisms.
-
- With the emerging possibility of very wide-area file systems, it
- becomes very hard to know in advance the set of machines where a file
- will and will not be accessible directly from the file system.
- Therefore it may make sense to provide both a file name, to be tried
- directly, and the name of one or more sites from which the file is
- known to be accessible. An implementation can try to retrieve remote
- files using FTP or any other protocol, using anonymous file retrieval
- or prompting the user for the necessary name and password. If an
- external body is accessible via multiple mechanisms, the sender may
- include multiple entities of type "message/external-body" within the
- body parts of an enclosing "multipart/alternative" entity.
-
- However, the external-body mechanism is not intended to be limited to
- file retrieval, as shown by the mail-server access-type. Beyond
- this, one can imagine, for example, using a video server for external
- references to video clips.
-
-
-
-
-Freed & Borenstein Standards Track [Page 38]
-\f
-RFC 2046 Media Types November 1996
-
-
- The embedded message header fields which appear in the body of the
- "message/external-body" data must be used to declare the media type
- of the external body if it is anything other than plain US-ASCII
- text, since the external body does not have a header section to
- declare its type. Similarly, any Content-transfer-encoding other
- than "7bit" must also be declared here. Thus a complete
- "message/external-body" message, referring to an object in PostScript
- format, might look like this:
-
- From: Whomever
- To: Someone
- Date: Whenever
- Subject: whatever
- MIME-Version: 1.0
- Message-ID: <id1@host.com>
- Content-Type: multipart/alternative; boundary=42
- Content-ID: <id001@guppylake.bellcore.com>
-
- --42
- Content-Type: message/external-body; name="BodyFormats.ps";
- site="thumper.bellcore.com"; mode="image";
- access-type=ANON-FTP; directory="pub";
- expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"
-
- Content-type: application/postscript
- Content-ID: <id42@guppylake.bellcore.com>
-
- --42
- Content-Type: message/external-body; access-type=local-file;
- name="/u/nsb/writing/rfcs/RFC-MIME.ps";
- site="thumper.bellcore.com";
- expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"
-
- Content-type: application/postscript
- Content-ID: <id42@guppylake.bellcore.com>
-
- --42
- Content-Type: message/external-body;
- access-type=mail-server
- server="listserv@bogus.bitnet";
- expiration="Fri, 14 Jun 1991 19:13:14 -0400 (EDT)"
-
- Content-type: application/postscript
- Content-ID: <id42@guppylake.bellcore.com>
-
- get RFC-MIME.DOC
-
- --42--
-
-
-
-Freed & Borenstein Standards Track [Page 39]
-\f
-RFC 2046 Media Types November 1996
-
-
- Note that in the above examples, the default Content-transfer-
- encoding of "7bit" is assumed for the external postscript data.
-
- Like the "message/partial" type, the "message/external-body" media
- type is intended to be transparent, that is, to convey the data type
- in the external body rather than to convey a message with a body of
- that type. Thus the headers on the outer and inner parts must be
- merged using the same rules as for "message/partial". In particular,
- this means that the Content-type and Subject fields are overridden,
- but the From field is preserved.
-
- Note that since the external bodies are not transported along with
- the external body reference, they need not conform to transport
- limitations that apply to the reference itself. In particular,
- Internet mail transports may impose 7bit and line length limits, but
- these do not automatically apply to binary external body references.
- Thus a Content-Transfer-Encoding is not generally necessary, though
- it is permitted.
-
- Note that the body of a message of type "message/external-body" is
- governed by the basic syntax for an RFC 822 message. In particular,
- anything before the first consecutive pair of CRLFs is header
- information, while anything after it is body information, which is
- ignored for most access-types.
-
-5.2.4. Other Message Subtypes
-
- MIME implementations must in general treat unrecognized subtypes of
- "message" as being equivalent to "application/octet-stream".
-
- Future subtypes of "message" intended for use with email should be
- restricted to "7bit" encoding. A type other than "message" should be
- used if restriction to "7bit" is not possible.
-
-6. Experimental Media Type Values
-
- A media type value beginning with the characters "X-" is a private
- value, to be used by consenting systems by mutual agreement. Any
- format without a rigorous and public definition must be named with an
- "X-" prefix, and publicly specified values shall never begin with
- "X-". (Older versions of the widely used Andrew system use the "X-
- BE2" name, so new systems should probably choose a different name.)
-
- In general, the use of "X-" top-level types is strongly discouraged.
- Implementors should invent subtypes of the existing types whenever
- possible. In many cases, a subtype of "application" will be more
- appropriate than a new top-level type.
-
-
-
-
-Freed & Borenstein Standards Track [Page 40]
-\f
-RFC 2046 Media Types November 1996
-
-
-7. Summary
-
- The five discrete media types provide provide a standardized
- mechanism for tagging entities as "audio", "image", or several other
- kinds of data. The composite "multipart" and "message" media types
- allow mixing and hierarchical structuring of entities of different
- types in a single message. A distinguished parameter syntax allows
- further specification of data format details, particularly the
- specification of alternate character sets. Additional optional
- header fields provide mechanisms for certain extensions deemed
- desirable by many implementors. Finally, a number of useful media
- types are defined for general use by consenting user agents, notably
- "message/partial" and "message/external-body".
-
-9. Security Considerations
-
- Security issues are discussed in the context of the
- "application/postscript" type, the "message/external-body" type, and
- in RFC 2048. Implementors should pay special attention to the
- security implications of any media types that can cause the remote
- execution of any actions in the recipient's environment. In such
- cases, the discussion of the "application/postscript" type may serve
- as a model for considering other media types with remote execution
- capabilities.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Freed & Borenstein Standards Track [Page 41]
-\f
-RFC 2046 Media Types November 1996
-
-
-9. Authors' Addresses
-
- For more information, the authors of this document are best contacted
- via Internet mail:
-
- Ned Freed
- Innosoft International, Inc.
- 1050 East Garvey Avenue South
- West Covina, CA 91790
- USA
-
- Phone: +1 818 919 3600
- Fax: +1 818 919 3614
- EMail: ned@innosoft.com
-
-
- Nathaniel S. Borenstein
- First Virtual Holdings
- 25 Washington Avenue
- Morristown, NJ 07960
- USA
-
- Phone: +1 201 540 8967
- Fax: +1 201 993 3032
- EMail: nsb@nsb.fv.com
-
-
- MIME is a result of the work of the Internet Engineering Task Force
- Working Group on RFC 822 Extensions. The chairman of that group,
- Greg Vaudreuil, may be reached at:
-
- Gregory M. Vaudreuil
- Octel Network Services
- 17080 Dallas Parkway
- Dallas, TX 75248-1905
- USA
-
- EMail: Greg.Vaudreuil@Octel.Com
-
-
-
-
-
-
-
-
-
-
-
-
-
-Freed & Borenstein Standards Track [Page 42]
-\f
-RFC 2046 Media Types November 1996
-
-
-Appendix A -- Collected Grammar
-
- This appendix contains the complete BNF grammar for all the syntax
- specified by this document.
-
- By itself, however, this grammar is incomplete. It refers by name to
- several syntax rules that are defined by RFC 822. Rather than
- reproduce those definitions here, and risk unintentional differences
- between the two, this document simply refers the reader to RFC 822
- for the remaining definitions. Wherever a term is undefined, it
- refers to the RFC 822 definition.
-
- boundary := 0*69<bchars> bcharsnospace
-
- bchars := bcharsnospace / " "
-
- bcharsnospace := DIGIT / ALPHA / "'" / "(" / ")" /
- "+" / "_" / "," / "-" / "." /
- "/" / ":" / "=" / "?"
-
- body-part := <"message" as defined in RFC 822, with all
- header fields optional, not starting with the
- specified dash-boundary, and with the
- delimiter not occurring anywhere in the
- body part. Note that the semantics of a
- part differ from the semantics of a message,
- as described in the text.>
-
- close-delimiter := delimiter "--"
-
- dash-boundary := "--" boundary
- ; boundary taken from the value of
- ; boundary parameter of the
- ; Content-Type field.
-
- delimiter := CRLF dash-boundary
-
- discard-text := *(*text CRLF)
- ; May be ignored or discarded.
-
- encapsulation := delimiter transport-padding
- CRLF body-part
-
- epilogue := discard-text
-
- multipart-body := [preamble CRLF]
- dash-boundary transport-padding CRLF
- body-part *encapsulation
-
-
-
-Freed & Borenstein Standards Track [Page 43]
-\f
-RFC 2046 Media Types November 1996
-
-
- close-delimiter transport-padding
- [CRLF epilogue]
-
- preamble := discard-text
-
- transport-padding := *LWSP-char
- ; Composers MUST NOT generate
- ; non-zero length transport
- ; padding, but receivers MUST
- ; be able to handle padding
- ; added by message transports.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Freed & Borenstein Standards Track [Page 44]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group J. Myers
-Request for Comments: 2222 Netscape Communications
-Category: Standards Track October 1997
-
-
- Simple Authentication and Security Layer (SASL)
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1997). All Rights Reserved.
-
-Table of Contents
-
- 1. Abstract .............................................. 2
- 2. Organization of this Document ......................... 2
- 2.1. How to Read This Document ............................. 2
- 2.2. Conventions Used in this Document ..................... 2
- 2.3. Examples .............................................. 3
- 3. Introduction and Overview ............................. 3
- 4. Profiling requirements ................................ 4
- 5. Specific issues ....................................... 5
- 5.1. Client sends data first ............................... 5
- 5.2. Server returns success with additional data ........... 5
- 5.3. Multiple authentications .............................. 5
- 6. Registration procedures ............................... 6
- 6.1. Comments on SASL mechanism registrations .............. 6
- 6.2. Location of Registered SASL Mechanism List ............ 6
- 6.3. Change Control ........................................ 7
- 6.4. Registration Template ................................. 7
- 7. Mechanism definitions ................................. 8
- 7.1. Kerberos version 4 mechanism .......................... 8
- 7.2. GSSAPI mechanism ...................................... 9
- 7.2.1 Client side of authentication protocol exchange ....... 9
- 7.2.2 Server side of authentication protocol exchange ....... 10
- 7.2.3 Security layer ........................................ 11
- 7.3. S/Key mechanism ....................................... 11
- 7.4. External mechanism .................................... 12
- 8. References ............................................ 13
- 9. Security Considerations ............................... 13
- 10. Author's Address ...................................... 14
-
-
-
-Myers Standards Track [Page 1]
-\f
-RFC 2222 SASL October 1997
-
-
- Appendix A. Relation of SASL to Transport Security .......... 15
- Full Copyright Statement .................................... 16
-
-1. Abstract
-
- This document describes a method for adding authentication support to
- connection-based protocols. To use this specification, a protocol
- includes a command for identifying and authenticating a user to a
- server and for optionally negotiating protection of subsequent
- protocol interactions. If its use is negotiated, a security layer is
- inserted between the protocol and the connection. This document
- describes how a protocol specifies such a command, defines several
- mechanisms for use by the command, and defines the protocol used for
- carrying a negotiated security layer over the connection.
-
-2. Organization of this Document
-
-2.1. How to Read This Document
-
- This document is written to serve two different audiences, protocol
- designers using this specification to support authentication in their
- protocol, and implementors of clients or servers for those protocols
- using this specification.
-
- The sections "Introduction and Overview", "Profiling requirements",
- and "Security Considerations" cover issues that protocol designers
- need to understand and address in profiling this specification for
- use in a specific protocol.
-
- Implementors of a protocol using this specification need the
- protocol-specific profiling information in addition to the
- information in this document.
-
-2.2. Conventions Used in this Document
-
- In examples, "C:" and "S:" indicate lines sent by the client and
- server respectively.
-
- The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
- in this document are to be interpreted as defined in "Key words for
- use in RFCs to Indicate Requirement Levels" [RFC 2119].
-
-
-
-
-
-
-
-
-
-
-Myers Standards Track [Page 2]
-\f
-RFC 2222 SASL October 1997
-
-
-2.3. Examples
-
- Examples in this document are for the IMAP profile [RFC 2060] of this
- specification. The base64 encoding of challenges and responses, as
- well as the "+ " preceding the responses are part of the IMAP4
- profile, not part of the SASL specification itself.
-
-3. Introduction and Overview
-
- The Simple Authentication and Security Layer (SASL) is a method for
- adding authentication support to connection-based protocols. To use
- this specification, a protocol includes a command for identifying and
- authenticating a user to a server and for optionally negotiating a
- security layer for subsequent protocol interactions.
-
- The command has a required argument identifying a SASL mechanism.
- SASL mechanisms are named by strings, from 1 to 20 characters in
- length, consisting of upper-case letters, digits, hyphens, and/or
- underscores. SASL mechanism names must be registered with the IANA.
- Procedures for registering new SASL mechanisms are given in the
- section "Registration procedures"
-
- If a server supports the requested mechanism, it initiates an
- authentication protocol exchange. This consists of a series of
- server challenges and client responses that are specific to the
- requested mechanism. The challenges and responses are defined by the
- mechanisms as binary tokens of arbitrary length. The protocol's
- profile then specifies how these binary tokens are then encoded for
- transfer over the connection.
-
- After receiving the authentication command or any client response, a
- server may issue a challenge, indicate failure, or indicate
- completion. The protocol's profile specifies how the server
- indicates which of the above it is doing.
-
- After receiving a challenge, a client may issue a response or abort
- the exchange. The protocol's profile specifies how the client
- indicates which of the above it is doing.
-
- During the authentication protocol exchange, the mechanism performs
- authentication, transmits an authorization identity (frequently known
- as a userid) from the client to server, and negotiates the use of a
- mechanism-specific security layer. If the use of a security layer is
- agreed upon, then the mechanism must also define or negotiate the
- maximum cipher-text buffer size that each side is able to receive.
-
-
-
-
-
-
-Myers Standards Track [Page 3]
-\f
-RFC 2222 SASL October 1997
-
-
- The transmitted authorization identity may be different than the
- identity in the client's authentication credentials. This permits
- agents such as proxy servers to authenticate using their own
- credentials, yet request the access privileges of the identity for
- which they are proxying. With any mechanism, transmitting an
- authorization identity of the empty string directs the server to
- derive an authorization identity from the client's authentication
- credentials.
-
- If use of a security layer is negotiated, it is applied to all
- subsequent data sent over the connection. The security layer takes
- effect immediately following the last response of the authentication
- exchange for data sent by the client and the completion indication
- for data sent by the server. Once the security layer is in effect,
- the protocol stream is processed by the security layer into buffers
- of cipher-text. Each buffer is transferred over the connection as a
- stream of octets prepended with a four octet field in network byte
- order that represents the length of the following buffer. The length
- of the cipher-text buffer must be no larger than the maximum size
- that was defined or negotiated by the other side.
-
-4. Profiling requirements
-
- In order to use this specification, a protocol definition must supply
- the following information:
-
- 1. A service name, to be selected from the IANA registry of "service"
- elements for the GSSAPI host-based service name form [RFC 2078].
-
- 2. A definition of the command to initiate the authentication
- protocol exchange. This command must have as a parameter the
- mechanism name being selected by the client.
-
- The command SHOULD have an optional parameter giving an initial
- response. This optional parameter allows the client to avoid a
- round trip when using a mechanism which is defined to have the
- client send data first. When this initial response is sent by the
- client and the selected mechanism is defined to have the server
- start with an initial challenge, the command fails. See section
- 5.1 of this document for further information.
-
- 3. A definition of the method by which the authentication protocol
- exchange is carried out, including how the challenges and
- responses are encoded, how the server indicates completion or
- failure of the exchange, how the client aborts an exchange, and
- how the exchange method interacts with any line length limits in
- the protocol.
-
-
-
-
-Myers Standards Track [Page 4]
-\f
-RFC 2222 SASL October 1997
-
-
- 4. Identification of the octet where any negotiated security layer
- starts to take effect, in both directions.
-
- 5. A specification of how the authorization identity passed from the
- client to the server is to be interpreted.
-
-5. Specific issues
-
-5.1. Client sends data first
-
- Some mechanisms specify that the first data sent in the
- authentication protocol exchange is from the client to the server.
-
- If a protocol's profile permits the command which initiates an
- authentication protocol exchange to contain an initial client
- response, this parameter SHOULD be used with such mechanisms.
-
- If the initial client response parameter is not given, or if a
- protocol's profile does not permit the command which initiates an
- authentication protocol exchange to contain an initial client
- response, then the server issues a challenge with no data. The
- client's response to this challenge is then used as the initial
- client response. (The server then proceeds to send the next
- challenge, indicates completion, or indicates failure.)
-
-5.2. Server returns success with additional data
-
- Some mechanisms may specify that server challenge data be sent to the
- client along with an indication of successful completion of the
- exchange. This data would, for example, authenticate the server to
- the client.
-
- If a protocol's profile does not permit this server challenge to be
- returned with a success indication, then the server issues the server
- challenge without an indication of successful completion. The client
- then responds with no data. After receiving this empty response, the
- server then indicates successful completion.
-
-5.3. Multiple authentications
-
- Unless otherwise stated by the protocol's profile, only one
- successful SASL negotiation may occur in a protocol session. In this
- case, once an authentication protocol exchange has successfully
- completed, further attempts to initiate an authentication protocol
- exchange fail.
-
-
-
-
-
-
-Myers Standards Track [Page 5]
-\f
-RFC 2222 SASL October 1997
-
-
- In the case that a profile explicitly permits multiple successful
- SASL negotiations to occur, then in no case may multiple security
- layers be simultaneously in effect. If a security layer is in effect
- and a subsequent SASL negotiation selects no security layer, the
- original security layer remains in effect. If a security layer is in
- effect and a subsequent SASL negotiation selects a second security
- layer, then the second security layer replaces the first.
-
-6. Registration procedures
-
- Registration of a SASL mechanism is done by filling in the template
- in section 6.4 and sending it in to iana@isi.edu. IANA has the right
- to reject obviously bogus registrations, but will perform no review
- of clams made in the registration form.
-
- There is no naming convention for SASL mechanisms; any name that
- conforms to the syntax of a SASL mechanism name can be registered.
-
- While the registration procedures do not require it, authors of SASL
- mechanisms are encouraged to seek community review and comment
- whenever that is feasible. Authors may seek community review by
- posting a specification of their proposed mechanism as an internet-
- draft. SASL mechanisms intended for widespread use should be
- standardized through the normal IETF process, when appropriate.
-
-6.1. Comments on SASL mechanism registrations
-
- Comments on registered SASL mechanisms should first be sent to the
- "owner" of the mechanism. Submitters of comments may, after a
- reasonable attempt to contact the owner, request IANA to attach their
- comment to the SASL mechanism registration itself. If IANA approves
- of this the comment will be made accessible in conjunction with the
- SASL mechanism registration itself.
-
-6.2. Location of Registered SASL Mechanism List
-
- SASL mechanism registrations will be posted in the anonymous FTP
- directory "ftp://ftp.isi.edu/in-notes/iana/assignments/sasl-
- mechanisms/" and all registered SASL mechanisms will be listed in the
- periodically issued "Assigned Numbers" RFC [currently STD 2, RFC
- 1700]. The SASL mechanism description and other supporting material
- may also be published as an Informational RFC by sending it to "rfc-
- editor@isi.edu" (please follow the instructions to RFC authors [RFC
- 2223]).
-
-
-
-
-
-
-
-Myers Standards Track [Page 6]
-\f
-RFC 2222 SASL October 1997
-
-
-6.3. Change Control
-
- Once a SASL mechanism registration has been published by IANA, the
- author may request a change to its definition. The change request
- follows the same procedure as the registration request.
-
- The owner of a SASL mechanism may pass responsibility for the SASL
- mechanism to another person or agency by informing IANA; this can be
- done without discussion or review.
-
- The IESG may reassign responsibility for a SASL mechanism. The most
- common case of this will be to enable changes to be made to
- mechanisms where the author of the registration has died, moved out
- of contact or is otherwise unable to make changes that are important
- to the community.
-
- SASL mechanism registrations may not be deleted; mechanisms which are
- no longer believed appropriate for use can be declared OBSOLETE by a
- change to their "intended use" field; such SASL mechanisms will be
- clearly marked in the lists published by IANA.
-
- The IESG is considered to be the owner of all SASL mechanisms which
- are on the IETF standards track.
-
-6.4. Registration Template
-
- To: iana@iana.org
- Subject: Registration of SASL mechanism X
-
- SASL mechanism name:
-
- Security considerations:
-
- Published specification (optional, recommended):
-
- Person & email address to contact for further information:
-
- Intended usage:
-
- (One of COMMON, LIMITED USE or OBSOLETE)
-
- Author/Change controller:
-
- (Any other information that the author deems interesting may be
- added below this line.)
-
-
-
-
-
-
-Myers Standards Track [Page 7]
-\f
-RFC 2222 SASL October 1997
-
-
-7. Mechanism definitions
-
- The following mechanisms are hereby defined.
-
-7.1. Kerberos version 4 mechanism
-
- The mechanism name associated with Kerberos version 4 is
- "KERBEROS_V4".
-
- The first challenge consists of a random 32-bit number in network
- byte order. The client responds with a Kerberos ticket and an
- authenticator for the principal "service.hostname@realm", where
- "service" is the service name specified in the protocol's profile,
- "hostname" is the first component of the host name of the server with
- all letters in lower case, and where "realm" is the Kerberos realm of
- the server. The encrypted checksum field included within the
- Kerberos authenticator contains the server provided challenge in
- network byte order.
-
- Upon decrypting and verifying the ticket and authenticator, the
- server verifies that the contained checksum field equals the original
- server provided random 32-bit number. Should the verification be
- successful, the server must add one to the checksum and construct 8
- octets of data, with the first four octets containing the incremented
- checksum in network byte order, the fifth octet containing a bit-mask
- specifying the security layers supported by the server, and the sixth
- through eighth octets containing, in network byte order, the maximum
- cipher-text buffer size the server is able to receive. The server
- must encrypt using DES ECB mode the 8 octets of data in the session
- key and issue that encrypted data in a second challenge. The client
- considers the server authenticated if the first four octets of the
- un-encrypted data is equal to one plus the checksum it previously
- sent.
-
- The client must construct data with the first four octets containing
- the original server-issued checksum in network byte order, the fifth
- octet containing the bit-mask specifying the selected security layer,
- the sixth through eighth octets containing in network byte order the
- maximum cipher-text buffer size the client is able to receive, and
- the following octets containing the authorization identity. The
- client must then append from one to eight zero-valued octets so that
- the length of the data is a multiple of eight octets. The client must
- then encrypt using DES PCBC mode the data with the session key and
- respond with the encrypted data. The server decrypts the data and
- verifies the contained checksum. The server must verify that the
- principal identified in the Kerberos ticket is authorized to connect
- as that authorization identity. After this verification, the
- authentication process is complete.
-
-
-
-Myers Standards Track [Page 8]
-\f
-RFC 2222 SASL October 1997
-
-
- The security layers and their corresponding bit-masks are as follows:
-
- 1 No security layer
- 2 Integrity (krb_mk_safe) protection
- 4 Privacy (krb_mk_priv) protection
-
- Other bit-masks may be defined in the future; bits which are not
- understood must be negotiated off.
-
- EXAMPLE: The following are two Kerberos version 4 login scenarios to
- the IMAP4 protocol (note that the line breaks in the sample
- authenticators are for editorial clarity and are not in real
- authenticators)
-
- S: * OK IMAP4 Server
- C: A001 AUTHENTICATE KERBEROS_V4
- S: + AmFYig==
- C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
- +nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd
- WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh
- S: + or//EoAADZI=
- C: DiAF5A4gA+oOIALuBkAAmw==
- S: A001 OK Kerberos V4 authentication successful
-
-
- S: * OK IMAP4 Server
- C: A001 AUTHENTICATE KERBEROS_V4
- S: + gcfgCA==
- C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
- +nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd
- WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh
- S: A001 NO Kerberos V4 authentication failed
-
-7.2. GSSAPI mechanism
-
- The mechanism name associated with all mechanisms employing the
- GSSAPI [RFC 2078] is "GSSAPI".
-
-7.2.1 Client side of authentication protocol exchange
-
- The client calls GSS_Init_sec_context, passing in 0 for
- input_context_handle (initially) and a targ_name equal to output_name
- from GSS_Import_Name called with input_name_type of
- GSS_C_NT_HOSTBASED_SERVICE and input_name_string of
- "service@hostname" where "service" is the service name specified in
- the protocol's profile, and "hostname" is the fully qualified host
- name of the server. The client then responds with the resulting
- output_token. If GSS_Init_sec_context returns GSS_S_CONTINUE_NEEDED,
-
-
-
-Myers Standards Track [Page 9]
-\f
-RFC 2222 SASL October 1997
-
-
- then the client should expect the server to issue a token in a
- subsequent challenge. The client must pass the token to another call
- to GSS_Init_sec_context, repeating the actions in this paragraph.
-
- When GSS_Init_sec_context returns GSS_S_COMPLETE, the client takes
- the following actions: If the last call to GSS_Init_sec_context
- returned an output_token, then the client responds with the
- output_token, otherwise the client responds with no data. The client
- should then expect the server to issue a token in a subsequent
- challenge. The client passes this token to GSS_Unwrap and interprets
- the first octet of resulting cleartext as a bit-mask specifying the
- security layers supported by the server and the second through fourth
- octets as the maximum size output_message to send to the server. The
- client then constructs data, with the first octet containing the
- bit-mask specifying the selected security layer, the second through
- fourth octets containing in network byte order the maximum size
- output_message the client is able to receive, and the remaining
- octets containing the authorization identity. The client passes the
- data to GSS_Wrap with conf_flag set to FALSE, and responds with the
- generated output_message. The client can then consider the server
- authenticated.
-
-7.2.2 Server side of authentication protocol exchange
-
- The server passes the initial client response to
- GSS_Accept_sec_context as input_token, setting input_context_handle
- to 0 (initially). If GSS_Accept_sec_context returns
- GSS_S_CONTINUE_NEEDED, the server returns the generated output_token
- to the client in challenge and passes the resulting response to
- another call to GSS_Accept_sec_context, repeating the actions in this
- paragraph.
-
- When GSS_Accept_sec_context returns GSS_S_COMPLETE, the client takes
- the following actions: If the last call to GSS_Accept_sec_context
- returned an output_token, the server returns it to the client in a
- challenge and expects a reply from the client with no data. Whether
- or not an output_token was returned (and after receipt of any
- response from the client to such an output_token), the server then
- constructs 4 octets of data, with the first octet containing a bit-
- mask specifying the security layers supported by the server and the
- second through fourth octets containing in network byte order the
- maximum size output_token the server is able to receive. The server
- must then pass the plaintext to GSS_Wrap with conf_flag set to FALSE
- and issue the generated output_message to the client in a challenge.
- The server must then pass the resulting response to GSS_Unwrap and
- interpret the first octet of resulting cleartext as the bit-mask for
- the selected security layer, the second through fourth octets as the
- maximum size output_message to send to the client, and the remaining
-
-
-
-Myers Standards Track [Page 10]
-\f
-RFC 2222 SASL October 1997
-
-
- octets as the authorization identity. The server must verify that
- the src_name is authorized to authenticate as the authorization
- identity. After these verifications, the authentication process is
- complete.
-
-7.2.3 Security layer
-
- The security layers and their corresponding bit-masks are as follows:
-
- 1 No security layer
- 2 Integrity protection.
- Sender calls GSS_Wrap with conf_flag set to FALSE
- 4 Privacy protection.
- Sender calls GSS_Wrap with conf_flag set to TRUE
-
- Other bit-masks may be defined in the future; bits which are not
- understood must be negotiated off.
-
-7.3. S/Key mechanism
-
- The mechanism name associated with S/Key [RFC 1760] using the MD4
- digest algorithm is "SKEY".
-
- The client sends an initial response with the authorization identity.
-
- The server then issues a challenge which contains the decimal
- sequence number followed by a single space and the seed string for
- the indicated authorization identity. The client responds with the
- one-time-password, as either a 64-bit value in network byte order or
- encoded in the "six English words" format.
-
- The server must verify the one-time-password. After this
- verification, the authentication process is complete.
-
- S/Key authentication does not provide for any security layers.
-
- EXAMPLE: The following are two S/Key login scenarios in the IMAP4
- protocol.
-
- S: * OK IMAP4 Server
- C: A001 AUTHENTICATE SKEY
- S: +
- C: bW9yZ2Fu
- S: + OTUgUWE1ODMwOA==
- C: Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
- S: A001 OK S/Key authentication successful
-
-
-
-
-
-Myers Standards Track [Page 11]
-\f
-RFC 2222 SASL October 1997
-
-
- S: * OK IMAP4 Server
- C: A001 AUTHENTICATE SKEY
- S: +
- C: c21pdGg=
- S: + OTUgUWE1ODMwOA==
- C: BsAY3g4gBNo=
- S: A001 NO S/Key authentication failed
-
- The following is an S/Key login scenario in an IMAP4-like protocol
- which has an optional "initial response" argument to the AUTHENTICATE
- command.
-
- S: * OK IMAP4-Like Server
- C: A001 AUTHENTICATE SKEY bW9yZ2Fu
- S: + OTUgUWE1ODMwOA==
- C: Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
- S: A001 OK S/Key authentication successful
-
-7.4. External mechanism
-
- The mechanism name associated with external authentication is
- "EXTERNAL".
-
- The client sends an initial response with the authorization identity.
-
- The server uses information, external to SASL, to determine whether
- the client is authorized to authenticate as the authorization
- identity. If the client is so authorized, the server indicates
- successful completion of the authentication exchange; otherwise the
- server indicates failure.
-
- The system providing this external information may be, for example,
- IPsec or TLS.
-
- If the client sends the empty string as the authorization identity
- (thus requesting the authorization identity be derived from the
- client's authentication credentials), the authorization identity is
- to be derived from authentication credentials which exist in the
- system which is providing the external authentication.
-
-
-
-
-
-
-
-
-
-
-
-
-Myers Standards Track [Page 12]
-\f
-RFC 2222 SASL October 1997
-
-
-8. References
-
- [RFC 2060] Crispin, M., "Internet Message Access Protocol - Version
- 4rev1", RFC 2060, December 1996.
-
- [RFC 2078] Linn, J., "Generic Security Service Application Program
- Interface, Version 2", RFC 2078, January 1997.
-
- [RFC 2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", RFC 2119, March 1997.
-
- [RFC 2223] Postel, J., and J. Reynolds, "Instructions to RFC
- Authors", RFC 2223, October 1997.
-
- [RFC 1760] Haller, N., "The S/Key One-Time Password System", RFC
- 1760, February 1995.
-
- [RFC 1700] Reynolds, J., and J. Postel, "Assigned Numbers", STD 2,
- RFC 1700, October 1994.
-
-9. Security Considerations
-
- Security issues are discussed throughout this memo.
-
- The mechanisms that support integrity protection are designed such
- that the negotiation of the security layer and authorization identity
- is integrity protected. When the client selects a security layer
- with at least integrity protection, this protects against an active
- attacker hijacking the connection and modifying the authentication
- exchange to negotiate a plaintext connection.
-
- When a server or client supports multiple authentication mechanisms,
- each of which has a different security strength, it is possible for
- an active attacker to cause a party to use the least secure mechanism
- supported. To protect against this sort of attack, a client or
- server which supports mechanisms of different strengths should have a
- configurable minimum strength that it will use. It is not sufficient
- for this minimum strength check to only be on the server, since an
- active attacker can change which mechanisms the client sees as being
- supported, causing the client to send authentication credentials for
- its weakest supported mechanism.
-
-
-
-
-
-
-
-
-
-
-Myers Standards Track [Page 13]
-\f
-RFC 2222 SASL October 1997
-
-
- The client's selection of a SASL mechanism is done in the clear and
- may be modified by an active attacker. It is important for any new
- SASL mechanisms to be designed such that an active attacker cannot
- obtain an authentication with weaker security properties by modifying
- the SASL mechanism name and/or the challenges and responses.
-
- Any protocol interactions prior to authentication are performed in
- the clear and may be modified by an active attacker. In the case
- where a client selects integrity protection, it is important that any
- security-sensitive protocol negotiations be performed after
- authentication is complete. Protocols should be designed such that
- negotiations performed prior to authentication should be either
- ignored or revalidated once authentication is complete.
-
-10. Author's Address
-
- John G. Myers
- Netscape Communications
- 501 E. Middlefield Road
- Mail Stop MV-029
- Mountain View, CA 94043-4042
-
- EMail: jgmyers@netscape.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Myers Standards Track [Page 14]
-\f
-RFC 2222 SASL October 1997
-
-
-Appendix A. Relation of SASL to Transport Security
-
- Questions have been raised about the relationship between SASL and
- various services (such as IPsec and TLS) which provide a secured
- connection.
-
- Two of the key features of SASL are:
-
- 1. The separation of the authorization identity from the identity in
- the client's credentials. This permits agents such as proxy
- servers to authenticate using their own credentials, yet request
- the access privileges of the identity for which they are proxying.
-
- 2. Upon successful completion of an authentication exchange, the
- server knows the authorization identity the client wishes to use.
- This allows servers to move to a "user is authenticated" state in
- the protocol.
-
- These features are extremely important to some application protocols,
- yet Transport Security services do not always provide them. To
- define SASL mechanisms based on these services would be a very messy
- task, as the framing of these services would be redundant with the
- framing of SASL and some method of providing these important SASL
- features would have to be devised.
-
- Sometimes it is desired to enable within an existing connection the
- use of a security service which does not fit the SASL model. (TLS is
- an example of such a service.) This can be done by adding a command,
- for example "STARTTLS", to the protocol. Such a command is outside
- the scope of SASL, and should be different from the command which
- starts a SASL authentication protocol exchange.
-
- In certain situations, it is reasonable to use SASL underneath one of
- these Transport Security services. The transport service would
- secure the connection, either service would authenticate the client,
- and SASL would negotiate the authorization identity. The SASL
- negotiation would be what moves the protocol from "unauthenticated"
- to "authenticated" state. The "EXTERNAL" SASL mechanism is
- explicitly intended to handle the case where the transport service
- secures the connection and authenticates the client and SASL
- negotiates the authorization identity.
-
- When using SASL underneath a sufficiently strong Transport Security
- service, a SASL security layer would most likely be redundant. The
- client and server would thus probably want to negotiate off the use
- of a SASL security layer.
-
-
-
-
-
-Myers Standards Track [Page 15]
-\f
-RFC 2222 SASL October 1997
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (1997). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implmentation may be prepared, copied, published
- andand distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Myers Standards Track [Page 16]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group T. Dierks
-Request for Comments: 2246 Certicom
-Category: Standards Track C. Allen
- Certicom
- January 1999
-
-
- The TLS Protocol
- Version 1.0
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-Abstract
-
- This document specifies Version 1.0 of the Transport Layer Security
- (TLS) protocol. The TLS protocol provides communications privacy over
- the Internet. The protocol allows client/server applications to
- communicate in a way that is designed to prevent eavesdropping,
- tampering, or message forgery.
-
-Table of Contents
-
- 1. Introduction 3
- 2. Goals 4
- 3. Goals of this document 5
- 4. Presentation language 5
- 4.1. Basic block size 6
- 4.2. Miscellaneous 6
- 4.3. Vectors 6
- 4.4. Numbers 7
- 4.5. Enumerateds 7
- 4.6. Constructed types 8
- 4.6.1. Variants 9
- 4.7. Cryptographic attributes 10
- 4.8. Constants 11
- 5. HMAC and the pseudorandom function 11
- 6. The TLS Record Protocol 13
- 6.1. Connection states 14
-
-
-
-Dierks & Allen Standards Track [Page 1]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- 6.2. Record layer 16
- 6.2.1. Fragmentation 16
- 6.2.2. Record compression and decompression 17
- 6.2.3. Record payload protection 18
- 6.2.3.1. Null or standard stream cipher 19
- 6.2.3.2. CBC block cipher 19
- 6.3. Key calculation 21
- 6.3.1. Export key generation example 22
- 7. The TLS Handshake Protocol 23
- 7.1. Change cipher spec protocol 24
- 7.2. Alert protocol 24
- 7.2.1. Closure alerts 25
- 7.2.2. Error alerts 26
- 7.3. Handshake Protocol overview 29
- 7.4. Handshake protocol 32
- 7.4.1. Hello messages 33
- 7.4.1.1. Hello request 33
- 7.4.1.2. Client hello 34
- 7.4.1.3. Server hello 36
- 7.4.2. Server certificate 37
- 7.4.3. Server key exchange message 39
- 7.4.4. Certificate request 41
- 7.4.5. Server hello done 42
- 7.4.6. Client certificate 43
- 7.4.7. Client key exchange message 43
- 7.4.7.1. RSA encrypted premaster secret message 44
- 7.4.7.2. Client Diffie-Hellman public value 45
- 7.4.8. Certificate verify 45
- 7.4.9. Finished 46
- 8. Cryptographic computations 47
- 8.1. Computing the master secret 47
- 8.1.1. RSA 48
- 8.1.2. Diffie-Hellman 48
- 9. Mandatory Cipher Suites 48
- 10. Application data protocol 48
- A. Protocol constant values 49
- A.1. Record layer 49
- A.2. Change cipher specs message 50
- A.3. Alert messages 50
- A.4. Handshake protocol 51
- A.4.1. Hello messages 51
- A.4.2. Server authentication and key exchange messages 52
- A.4.3. Client authentication and key exchange messages 53
- A.4.4. Handshake finalization message 54
- A.5. The CipherSuite 54
- A.6. The Security Parameters 56
- B. Glossary 57
- C. CipherSuite definitions 61
-
-
-
-Dierks & Allen Standards Track [Page 2]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- D. Implementation Notes 64
- D.1. Temporary RSA keys 64
- D.2. Random Number Generation and Seeding 64
- D.3. Certificates and authentication 65
- D.4. CipherSuites 65
- E. Backward Compatibility With SSL 66
- E.1. Version 2 client hello 67
- E.2. Avoiding man-in-the-middle version rollback 68
- F. Security analysis 69
- F.1. Handshake protocol 69
- F.1.1. Authentication and key exchange 69
- F.1.1.1. Anonymous key exchange 69
- F.1.1.2. RSA key exchange and authentication 70
- F.1.1.3. Diffie-Hellman key exchange with authentication 71
- F.1.2. Version rollback attacks 71
- F.1.3. Detecting attacks against the handshake protocol 72
- F.1.4. Resuming sessions 72
- F.1.5. MD5 and SHA 72
- F.2. Protecting application data 72
- F.3. Final notes 73
- G. Patent Statement 74
- Security Considerations 75
- References 75
- Credits 77
- Comments 78
- Full Copyright Statement 80
-
-1. Introduction
-
- The primary goal of the TLS Protocol is to provide privacy and data
- integrity between two communicating applications. The protocol is
- composed of two layers: the TLS Record Protocol and the TLS Handshake
- Protocol. At the lowest level, layered on top of some reliable
- transport protocol (e.g., TCP[TCP]), is the TLS Record Protocol. The
- TLS Record Protocol provides connection security that has two basic
- properties:
-
- - The connection is private. Symmetric cryptography is used for
- data encryption (e.g., DES [DES], RC4 [RC4], etc.) The keys for
- this symmetric encryption are generated uniquely for each
- connection and are based on a secret negotiated by another
- protocol (such as the TLS Handshake Protocol). The Record
- Protocol can also be used without encryption.
-
- - The connection is reliable. Message transport includes a message
- integrity check using a keyed MAC. Secure hash functions (e.g.,
- SHA, MD5, etc.) are used for MAC computations. The Record
- Protocol can operate without a MAC, but is generally only used in
-
-
-
-Dierks & Allen Standards Track [Page 3]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- this mode while another protocol is using the Record Protocol as
- a transport for negotiating security parameters.
-
- The TLS Record Protocol is used for encapsulation of various higher
- level protocols. One such encapsulated protocol, the TLS Handshake
- Protocol, allows the server and client to authenticate each other and
- to negotiate an encryption algorithm and cryptographic keys before
- the application protocol transmits or receives its first byte of
- data. The TLS Handshake Protocol provides connection security that
- has three basic properties:
-
- - The peer's identity can be authenticated using asymmetric, or
- public key, cryptography (e.g., RSA [RSA], DSS [DSS], etc.). This
- authentication can be made optional, but is generally required
- for at least one of the peers.
-
- - The negotiation of a shared secret is secure: the negotiated
- secret is unavailable to eavesdroppers, and for any authenticated
- connection the secret cannot be obtained, even by an attacker who
- can place himself in the middle of the connection.
-
- - The negotiation is reliable: no attacker can modify the
- negotiation communication without being detected by the parties
- to the communication.
-
- One advantage of TLS is that it is application protocol independent.
- Higher level protocols can layer on top of the TLS Protocol
- transparently. The TLS standard, however, does not specify how
- protocols add security with TLS; the decisions on how to initiate TLS
- handshaking and how to interpret the authentication certificates
- exchanged are left up to the judgment of the designers and
- implementors of protocols which run on top of TLS.
-
-2. Goals
-
- The goals of TLS Protocol, in order of their priority, are:
-
- 1. Cryptographic security: TLS should be used to establish a secure
- connection between two parties.
-
- 2. Interoperability: Independent programmers should be able to
- develop applications utilizing TLS that will then be able to
- successfully exchange cryptographic parameters without knowledge
- of one another's code.
-
- 3. Extensibility: TLS seeks to provide a framework into which new
- public key and bulk encryption methods can be incorporated as
- necessary. This will also accomplish two sub-goals: to prevent
-
-
-
-Dierks & Allen Standards Track [Page 4]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- the need to create a new protocol (and risking the introduction
- of possible new weaknesses) and to avoid the need to implement an
- entire new security library.
-
- 4. Relative efficiency: Cryptographic operations tend to be highly
- CPU intensive, particularly public key operations. For this
- reason, the TLS protocol has incorporated an optional session
- caching scheme to reduce the number of connections that need to
- be established from scratch. Additionally, care has been taken to
- reduce network activity.
-
-3. Goals of this document
-
- This document and the TLS protocol itself are based on the SSL 3.0
- Protocol Specification as published by Netscape. The differences
- between this protocol and SSL 3.0 are not dramatic, but they are
- significant enough that TLS 1.0 and SSL 3.0 do not interoperate
- (although TLS 1.0 does incorporate a mechanism by which a TLS
- implementation can back down to SSL 3.0). This document is intended
- primarily for readers who will be implementing the protocol and those
- doing cryptographic analysis of it. The specification has been
- written with this in mind, and it is intended to reflect the needs of
- those two groups. For that reason, many of the algorithm-dependent
- data structures and rules are included in the body of the text (as
- opposed to in an appendix), providing easier access to them.
-
- This document is not intended to supply any details of service
- definition nor interface definition, although it does cover select
- areas of policy as they are required for the maintenance of solid
- security.
-
-4. Presentation language
-
- This document deals with the formatting of data in an external
- representation. The following very basic and somewhat casually
- defined presentation syntax will be used. The syntax draws from
- several sources in its structure. Although it resembles the
- programming language "C" in its syntax and XDR [XDR] in both its
- syntax and intent, it would be risky to draw too many parallels. The
- purpose of this presentation language is to document TLS only, not to
- have general application beyond that particular goal.
-
-
-
-
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 5]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-4.1. Basic block size
-
- The representation of all data items is explicitly specified. The
- basic data block size is one byte (i.e. 8 bits). Multiple byte data
- items are concatenations of bytes, from left to right, from top to
- bottom. From the bytestream a multi-byte item (a numeric in the
- example) is formed (using C notation) by:
-
- value = (byte[0] << 8*(n-1)) | (byte[1] << 8*(n-2)) |
- ... | byte[n-1];
-
- This byte ordering for multi-byte values is the commonplace network
- byte order or big endian format.
-
-4.2. Miscellaneous
-
- Comments begin with "/*" and end with "*/".
-
- Optional components are denoted by enclosing them in "[[ ]]" double
- brackets.
-
- Single byte entities containing uninterpreted data are of type
- opaque.
-
-4.3. Vectors
-
- A vector (single dimensioned array) is a stream of homogeneous data
- elements. The size of the vector may be specified at documentation
- time or left unspecified until runtime. In either case the length
- declares the number of bytes, not the number of elements, in the
- vector. The syntax for specifying a new type T' that is a fixed
- length vector of type T is
-
- T T'[n];
-
- Here T' occupies n bytes in the data stream, where n is a multiple of
- the size of T. The length of the vector is not included in the
- encoded stream.
-
- In the following example, Datum is defined to be three consecutive
- bytes that the protocol does not interpret, while Data is three
- consecutive Datum, consuming a total of nine bytes.
-
- opaque Datum[3]; /* three uninterpreted bytes */
- Datum Data[9]; /* 3 consecutive 3 byte vectors */
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 6]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- Variable length vectors are defined by specifying a subrange of legal
- lengths, inclusively, using the notation <floor..ceiling>. When
- encoded, the actual length precedes the vector's contents in the byte
- stream. The length will be in the form of a number consuming as many
- bytes as required to hold the vector's specified maximum (ceiling)
- length. A variable length vector with an actual length field of zero
- is referred to as an empty vector.
-
- T T'<floor..ceiling>;
-
- In the following example, mandatory is a vector that must contain
- between 300 and 400 bytes of type opaque. It can never be empty. The
- actual length field consumes two bytes, a uint16, sufficient to
- represent the value 400 (see Section 4.4). On the other hand, longer
- can represent up to 800 bytes of data, or 400 uint16 elements, and it
- may be empty. Its encoding will include a two byte actual length
- field prepended to the vector. The length of an encoded vector must
- be an even multiple of the length of a single element (for example, a
- 17 byte vector of uint16 would be illegal).
-
- opaque mandatory<300..400>;
- /* length field is 2 bytes, cannot be empty */
- uint16 longer<0..800>;
- /* zero to 400 16-bit unsigned integers */
-
-4.4. Numbers
-
- The basic numeric data type is an unsigned byte (uint8). All larger
- numeric data types are formed from fixed length series of bytes
- concatenated as described in Section 4.1 and are also unsigned. The
- following numeric types are predefined.
-
- uint8 uint16[2];
- uint8 uint24[3];
- uint8 uint32[4];
- uint8 uint64[8];
-
- All values, here and elsewhere in the specification, are stored in
- "network" or "big-endian" order; the uint32 represented by the hex
- bytes 01 02 03 04 is equivalent to the decimal value 16909060.
-
-4.5. Enumerateds
-
- An additional sparse data type is available called enum. A field of
- type enum can only assume the values declared in the definition.
- Each definition is a different type. Only enumerateds of the same
- type may be assigned or compared. Every element of an enumerated must
-
-
-
-
-Dierks & Allen Standards Track [Page 7]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- be assigned a value, as demonstrated in the following example. Since
- the elements of the enumerated are not ordered, they can be assigned
- any unique value, in any order.
-
- enum { e1(v1), e2(v2), ... , en(vn) [[, (n)]] } Te;
-
- Enumerateds occupy as much space in the byte stream as would its
- maximal defined ordinal value. The following definition would cause
- one byte to be used to carry fields of type Color.
-
- enum { red(3), blue(5), white(7) } Color;
-
- One may optionally specify a value without its associated tag to
- force the width definition without defining a superfluous element.
- In the following example, Taste will consume two bytes in the data
- stream but can only assume the values 1, 2 or 4.
-
- enum { sweet(1), sour(2), bitter(4), (32000) } Taste;
-
- The names of the elements of an enumeration are scoped within the
- defined type. In the first example, a fully qualified reference to
- the second element of the enumeration would be Color.blue. Such
- qualification is not required if the target of the assignment is well
- specified.
-
- Color color = Color.blue; /* overspecified, legal */
- Color color = blue; /* correct, type implicit */
-
- For enumerateds that are never converted to external representation,
- the numerical information may be omitted.
-
- enum { low, medium, high } Amount;
-
-4.6. Constructed types
-
- Structure types may be constructed from primitive types for
- convenience. Each specification declares a new, unique type. The
- syntax for definition is much like that of C.
-
- struct {
- T1 f1;
- T2 f2;
- ...
- Tn fn;
- } [[T]];
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 8]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- The fields within a structure may be qualified using the type's name
- using a syntax much like that available for enumerateds. For example,
- T.f2 refers to the second field of the previous declaration.
- Structure definitions may be embedded.
-
-4.6.1. Variants
-
- Defined structures may have variants based on some knowledge that is
- available within the environment. The selector must be an enumerated
- type that defines the possible variants the structure defines. There
- must be a case arm for every element of the enumeration declared in
- the select. The body of the variant structure may be given a label
- for reference. The mechanism by which the variant is selected at
- runtime is not prescribed by the presentation language.
-
- struct {
- T1 f1;
- T2 f2;
- ....
- Tn fn;
- select (E) {
- case e1: Te1;
- case e2: Te2;
- ....
- case en: Ten;
- } [[fv]];
- } [[Tv]];
-
- For example:
-
- enum { apple, orange } VariantTag;
- struct {
- uint16 number;
- opaque string<0..10>; /* variable length */
- } V1;
- struct {
- uint32 number;
- opaque string[10]; /* fixed length */
- } V2;
- struct {
- select (VariantTag) { /* value of selector is implicit */
- case apple: V1; /* VariantBody, tag = apple */
- case orange: V2; /* VariantBody, tag = orange */
- } variant_body; /* optional label on variant */
- } VariantRecord;
-
- Variant structures may be qualified (narrowed) by specifying a value
- for the selector prior to the type. For example, a
-
-
-
-Dierks & Allen Standards Track [Page 9]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- orange VariantRecord
-
- is a narrowed type of a VariantRecord containing a variant_body of
- type V2.
-
-4.7. Cryptographic attributes
-
- The four cryptographic operations digital signing, stream cipher
- encryption, block cipher encryption, and public key encryption are
- designated digitally-signed, stream-ciphered, block-ciphered, and
- public-key-encrypted, respectively. A field's cryptographic
- processing is specified by prepending an appropriate key word
- designation before the field's type specification. Cryptographic keys
- are implied by the current session state (see Section 6.1).
-
- In digital signing, one-way hash functions are used as input for a
- signing algorithm. A digitally-signed element is encoded as an opaque
- vector <0..2^16-1>, where the length is specified by the signing
- algorithm and key.
-
- In RSA signing, a 36-byte structure of two hashes (one SHA and one
- MD5) is signed (encrypted with the private key). It is encoded with
- PKCS #1 block type 0 or type 1 as described in [PKCS1].
-
- In DSS, the 20 bytes of the SHA hash are run directly through the
- Digital Signing Algorithm with no additional hashing. This produces
- two values, r and s. The DSS signature is an opaque vector, as above,
- the contents of which are the DER encoding of:
-
- Dss-Sig-Value ::= SEQUENCE {
- r INTEGER,
- s INTEGER
- }
-
- In stream cipher encryption, the plaintext is exclusive-ORed with an
- identical amount of output generated from a cryptographically-secure
- keyed pseudorandom number generator.
-
- In block cipher encryption, every block of plaintext encrypts to a
- block of ciphertext. All block cipher encryption is done in CBC
- (Cipher Block Chaining) mode, and all items which are block-ciphered
- will be an exact multiple of the cipher block length.
-
- In public key encryption, a public key algorithm is used to encrypt
- data in such a way that it can be decrypted only with the matching
- private key. A public-key-encrypted element is encoded as an opaque
- vector <0..2^16-1>, where the length is specified by the signing
- algorithm and key.
-
-
-
-Dierks & Allen Standards Track [Page 10]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- An RSA encrypted value is encoded with PKCS #1 block type 2 as
- described in [PKCS1].
-
- In the following example:
-
- stream-ciphered struct {
- uint8 field1;
- uint8 field2;
- digitally-signed opaque hash[20];
- } UserType;
-
- The contents of hash are used as input for the signing algorithm,
- then the entire structure is encrypted with a stream cipher. The
- length of this structure, in bytes would be equal to 2 bytes for
- field1 and field2, plus two bytes for the length of the signature,
- plus the length of the output of the signing algorithm. This is known
- due to the fact that the algorithm and key used for the signing are
- known prior to encoding or decoding this structure.
-
-4.8. Constants
-
- Typed constants can be defined for purposes of specification by
- declaring a symbol of the desired type and assigning values to it.
- Under-specified types (opaque, variable length vectors, and
- structures that contain opaque) cannot be assigned values. No fields
- of a multi-element structure or vector may be elided.
-
- For example,
-
- struct {
- uint8 f1;
- uint8 f2;
- } Example1;
-
- Example1 ex1 = {1, 4}; /* assigns f1 = 1, f2 = 4 */
-
-5. HMAC and the pseudorandom function
-
- A number of operations in the TLS record and handshake layer required
- a keyed MAC; this is a secure digest of some data protected by a
- secret. Forging the MAC is infeasible without knowledge of the MAC
- secret. The construction we use for this operation is known as HMAC,
- described in [HMAC].
-
- HMAC can be used with a variety of different hash algorithms. TLS
- uses it in the handshake with two different algorithms: MD5 and SHA-
- 1, denoting these as HMAC_MD5(secret, data) and HMAC_SHA(secret,
-
-
-
-
-Dierks & Allen Standards Track [Page 11]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- data). Additional hash algorithms can be defined by cipher suites and
- used to protect record data, but MD5 and SHA-1 are hard coded into
- the description of the handshaking for this version of the protocol.
-
- In addition, a construction is required to do expansion of secrets
- into blocks of data for the purposes of key generation or validation.
- This pseudo-random function (PRF) takes as input a secret, a seed,
- and an identifying label and produces an output of arbitrary length.
-
- In order to make the PRF as secure as possible, it uses two hash
- algorithms in a way which should guarantee its security if either
- algorithm remains secure.
-
- First, we define a data expansion function, P_hash(secret, data)
- which uses a single hash function to expand a secret and seed into an
- arbitrary quantity of output:
-
- P_hash(secret, seed) = HMAC_hash(secret, A(1) + seed) +
- HMAC_hash(secret, A(2) + seed) +
- HMAC_hash(secret, A(3) + seed) + ...
-
- Where + indicates concatenation.
-
- A() is defined as:
- A(0) = seed
- A(i) = HMAC_hash(secret, A(i-1))
-
- P_hash can be iterated as many times as is necessary to produce the
- required quantity of data. For example, if P_SHA-1 was being used to
- create 64 bytes of data, it would have to be iterated 4 times
- (through A(4)), creating 80 bytes of output data; the last 16 bytes
- of the final iteration would then be discarded, leaving 64 bytes of
- output data.
-
- TLS's PRF is created by splitting the secret into two halves and
- using one half to generate data with P_MD5 and the other half to
- generate data with P_SHA-1, then exclusive-or'ing the outputs of
- these two expansion functions together.
-
- S1 and S2 are the two halves of the secret and each is the same
- length. S1 is taken from the first half of the secret, S2 from the
- second half. Their length is created by rounding up the length of the
- overall secret divided by two; thus, if the original secret is an odd
- number of bytes long, the last byte of S1 will be the same as the
- first byte of S2.
-
- L_S = length in bytes of secret;
- L_S1 = L_S2 = ceil(L_S / 2);
-
-
-
-Dierks & Allen Standards Track [Page 12]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- The secret is partitioned into two halves (with the possibility of
- one shared byte) as described above, S1 taking the first L_S1 bytes
- and S2 the last L_S2 bytes.
-
- The PRF is then defined as the result of mixing the two pseudorandom
- streams by exclusive-or'ing them together.
-
- PRF(secret, label, seed) = P_MD5(S1, label + seed) XOR
- P_SHA-1(S2, label + seed);
-
- The label is an ASCII string. It should be included in the exact form
- it is given without a length byte or trailing null character. For
- example, the label "slithy toves" would be processed by hashing the
- following bytes:
-
- 73 6C 69 74 68 79 20 74 6F 76 65 73
-
- Note that because MD5 produces 16 byte outputs and SHA-1 produces 20
- byte outputs, the boundaries of their internal iterations will not be
- aligned; to generate a 80 byte output will involve P_MD5 being
- iterated through A(5), while P_SHA-1 will only iterate through A(4).
-
-6. The TLS Record Protocol
-
- The TLS Record Protocol is a layered protocol. At each layer,
- messages may include fields for length, description, and content.
- The Record Protocol takes messages to be transmitted, fragments the
- data into manageable blocks, optionally compresses the data, applies
- a MAC, encrypts, and transmits the result. Received data is
- decrypted, verified, decompressed, and reassembled, then delivered to
- higher level clients.
-
- Four record protocol clients are described in this document: the
- handshake protocol, the alert protocol, the change cipher spec
- protocol, and the application data protocol. In order to allow
- extension of the TLS protocol, additional record types can be
- supported by the record protocol. Any new record types should
- allocate type values immediately beyond the ContentType values for
- the four record types described here (see Appendix A.2). If a TLS
- implementation receives a record type it does not understand, it
- should just ignore it. Any protocol designed for use over TLS must be
- carefully designed to deal with all possible attacks against it.
- Note that because the type and length of a record are not protected
- by encryption, care should be take to minimize the value of traffic
- analysis of these values.
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 13]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-6.1. Connection states
-
- A TLS connection state is the operating environment of the TLS Record
- Protocol. It specifies a compression algorithm, encryption algorithm,
- and MAC algorithm. In addition, the parameters for these algorithms
- are known: the MAC secret and the bulk encryption keys and IVs for
- the connection in both the read and the write directions. Logically,
- there are always four connection states outstanding: the current read
- and write states, and the pending read and write states. All records
- are processed under the current read and write states. The security
- parameters for the pending states can be set by the TLS Handshake
- Protocol, and the Handshake Protocol can selectively make either of
- the pending states current, in which case the appropriate current
- state is disposed of and replaced with the pending state; the pending
- state is then reinitialized to an empty state. It is illegal to make
- a state which has not been initialized with security parameters a
- current state. The initial current state always specifies that no
- encryption, compression, or MAC will be used.
-
- The security parameters for a TLS Connection read and write state are
- set by providing the following values:
-
- connection end
- Whether this entity is considered the "client" or the "server" in
- this connection.
-
- bulk encryption algorithm
- An algorithm to be used for bulk encryption. This specification
- includes the key size of this algorithm, how much of that key is
- secret, whether it is a block or stream cipher, the block size of
- the cipher (if appropriate), and whether it is considered an
- "export" cipher.
-
- MAC algorithm
- An algorithm to be used for message authentication. This
- specification includes the size of the hash which is returned by
- the MAC algorithm.
-
- compression algorithm
- An algorithm to be used for data compression. This specification
- must include all information the algorithm requires to do
- compression.
-
- master secret
- A 48 byte secret shared between the two peers in the connection.
-
- client random
- A 32 byte value provided by the client.
-
-
-
-Dierks & Allen Standards Track [Page 14]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- server random
- A 32 byte value provided by the server.
-
- These parameters are defined in the presentation language as:
-
- enum { server, client } ConnectionEnd;
-
- enum { null, rc4, rc2, des, 3des, des40 } BulkCipherAlgorithm;
-
- enum { stream, block } CipherType;
-
- enum { true, false } IsExportable;
-
- enum { null, md5, sha } MACAlgorithm;
-
- enum { null(0), (255) } CompressionMethod;
-
- /* The algorithms specified in CompressionMethod,
- BulkCipherAlgorithm, and MACAlgorithm may be added to. */
-
- struct {
- ConnectionEnd entity;
- BulkCipherAlgorithm bulk_cipher_algorithm;
- CipherType cipher_type;
- uint8 key_size;
- uint8 key_material_length;
- IsExportable is_exportable;
- MACAlgorithm mac_algorithm;
- uint8 hash_size;
- CompressionMethod compression_algorithm;
- opaque master_secret[48];
- opaque client_random[32];
- opaque server_random[32];
- } SecurityParameters;
-
- The record layer will use the security parameters to generate the
- following six items:
-
- client write MAC secret
- server write MAC secret
- client write key
- server write key
- client write IV (for block ciphers only)
- server write IV (for block ciphers only)
-
- The client write parameters are used by the server when receiving and
- processing records and vice-versa. The algorithm used for generating
- these items from the security parameters is described in section 6.3.
-
-
-
-Dierks & Allen Standards Track [Page 15]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- Once the security parameters have been set and the keys have been
- generated, the connection states can be instantiated by making them
- the current states. These current states must be updated for each
- record processed. Each connection state includes the following
- elements:
-
- compression state
- The current state of the compression algorithm.
-
- cipher state
- The current state of the encryption algorithm. This will consist
- of the scheduled key for that connection. In addition, for block
- ciphers running in CBC mode (the only mode specified for TLS),
- this will initially contain the IV for that connection state and
- be updated to contain the ciphertext of the last block encrypted
- or decrypted as records are processed. For stream ciphers, this
- will contain whatever the necessary state information is to allow
- the stream to continue to encrypt or decrypt data.
-
- MAC secret
- The MAC secret for this connection as generated above.
-
- sequence number
- Each connection state contains a sequence number, which is
- maintained separately for read and write states. The sequence
- number must be set to zero whenever a connection state is made
- the active state. Sequence numbers are of type uint64 and may not
- exceed 2^64-1. A sequence number is incremented after each
- record: specifically, the first record which is transmitted under
- a particular connection state should use sequence number 0.
-
-6.2. Record layer
-
- The TLS Record Layer receives uninterpreted data from higher layers
- in non-empty blocks of arbitrary size.
-
-6.2.1. Fragmentation
-
- The record layer fragments information blocks into TLSPlaintext
- records carrying data in chunks of 2^14 bytes or less. Client message
- boundaries are not preserved in the record layer (i.e., multiple
- client messages of the same ContentType may be coalesced into a
- single TLSPlaintext record, or a single message may be fragmented
- across several records).
-
- struct {
- uint8 major, minor;
- } ProtocolVersion;
-
-
-
-Dierks & Allen Standards Track [Page 16]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- enum {
- change_cipher_spec(20), alert(21), handshake(22),
- application_data(23), (255)
- } ContentType;
-
- struct {
- ContentType type;
- ProtocolVersion version;
- uint16 length;
- opaque fragment[TLSPlaintext.length];
- } TLSPlaintext;
-
- type
- The higher level protocol used to process the enclosed fragment.
-
- version
- The version of the protocol being employed. This document
- describes TLS Version 1.0, which uses the version { 3, 1 }. The
- version value 3.1 is historical: TLS version 1.0 is a minor
- modification to the SSL 3.0 protocol, which bears the version
- value 3.0. (See Appendix A.1).
-
- length
- The length (in bytes) of the following TLSPlaintext.fragment.
- The length should not exceed 2^14.
-
- fragment
- The application data. This data is transparent and treated as an
- independent block to be dealt with by the higher level protocol
- specified by the type field.
-
- Note: Data of different TLS Record layer content types may be
- interleaved. Application data is generally of lower precedence
- for transmission than other content types.
-
-6.2.2. Record compression and decompression
-
- All records are compressed using the compression algorithm defined in
- the current session state. There is always an active compression
- algorithm; however, initially it is defined as
- CompressionMethod.null. The compression algorithm translates a
- TLSPlaintext structure into a TLSCompressed structure. Compression
- functions are initialized with default state information whenever a
- connection state is made active.
-
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 17]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- Compression must be lossless and may not increase the content length
- by more than 1024 bytes. If the decompression function encounters a
- TLSCompressed.fragment that would decompress to a length in excess of
- 2^14 bytes, it should report a fatal decompression failure error.
-
- struct {
- ContentType type; /* same as TLSPlaintext.type */
- ProtocolVersion version;/* same as TLSPlaintext.version */
- uint16 length;
- opaque fragment[TLSCompressed.length];
- } TLSCompressed;
-
- length
- The length (in bytes) of the following TLSCompressed.fragment.
- The length should not exceed 2^14 + 1024.
-
- fragment
- The compressed form of TLSPlaintext.fragment.
-
- Note: A CompressionMethod.null operation is an identity operation; no
- fields are altered.
-
- Implementation note:
- Decompression functions are responsible for ensuring that
- messages cannot cause internal buffer overflows.
-
-6.2.3. Record payload protection
-
- The encryption and MAC functions translate a TLSCompressed structure
- into a TLSCiphertext. The decryption functions reverse the process.
- The MAC of the record also includes a sequence number so that
- missing, extra or repeated messages are detectable.
-
- struct {
- ContentType type;
- ProtocolVersion version;
- uint16 length;
- select (CipherSpec.cipher_type) {
- case stream: GenericStreamCipher;
- case block: GenericBlockCipher;
- } fragment;
- } TLSCiphertext;
-
- type
- The type field is identical to TLSCompressed.type.
-
- version
- The version field is identical to TLSCompressed.version.
-
-
-
-Dierks & Allen Standards Track [Page 18]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- length
- The length (in bytes) of the following TLSCiphertext.fragment.
- The length may not exceed 2^14 + 2048.
-
- fragment
- The encrypted form of TLSCompressed.fragment, with the MAC.
-
-6.2.3.1. Null or standard stream cipher
-
- Stream ciphers (including BulkCipherAlgorithm.null - see Appendix
- A.6) convert TLSCompressed.fragment structures to and from stream
- TLSCiphertext.fragment structures.
-
- stream-ciphered struct {
- opaque content[TLSCompressed.length];
- opaque MAC[CipherSpec.hash_size];
- } GenericStreamCipher;
-
- The MAC is generated as:
-
- HMAC_hash(MAC_write_secret, seq_num + TLSCompressed.type +
- TLSCompressed.version + TLSCompressed.length +
- TLSCompressed.fragment));
-
- where "+" denotes concatenation.
-
- seq_num
- The sequence number for this record.
-
- hash
- The hashing algorithm specified by
- SecurityParameters.mac_algorithm.
-
- Note that the MAC is computed before encryption. The stream cipher
- encrypts the entire block, including the MAC. For stream ciphers that
- do not use a synchronization vector (such as RC4), the stream cipher
- state from the end of one record is simply used on the subsequent
- packet. If the CipherSuite is TLS_NULL_WITH_NULL_NULL, encryption
- consists of the identity operation (i.e., the data is not encrypted
- and the MAC size is zero implying that no MAC is used).
- TLSCiphertext.length is TLSCompressed.length plus
- CipherSpec.hash_size.
-
-6.2.3.2. CBC block cipher
-
- For block ciphers (such as RC2 or DES), the encryption and MAC
- functions convert TLSCompressed.fragment structures to and from block
- TLSCiphertext.fragment structures.
-
-
-
-Dierks & Allen Standards Track [Page 19]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- block-ciphered struct {
- opaque content[TLSCompressed.length];
- opaque MAC[CipherSpec.hash_size];
- uint8 padding[GenericBlockCipher.padding_length];
- uint8 padding_length;
- } GenericBlockCipher;
-
- The MAC is generated as described in Section 6.2.3.1.
-
- padding
- Padding that is added to force the length of the plaintext to be
- an integral multiple of the block cipher's block length. The
- padding may be any length up to 255 bytes long, as long as it
- results in the TLSCiphertext.length being an integral multiple of
- the block length. Lengths longer than necessary might be
- desirable to frustrate attacks on a protocol based on analysis of
- the lengths of exchanged messages. Each uint8 in the padding data
- vector must be filled with the padding length value.
-
- padding_length
- The padding length should be such that the total size of the
- GenericBlockCipher structure is a multiple of the cipher's block
- length. Legal values range from zero to 255, inclusive. This
- length specifies the length of the padding field exclusive of the
- padding_length field itself.
-
- The encrypted data length (TLSCiphertext.length) is one more than the
- sum of TLSCompressed.length, CipherSpec.hash_size, and
- padding_length.
-
- Example: If the block length is 8 bytes, the content length
- (TLSCompressed.length) is 61 bytes, and the MAC length is 20
- bytes, the length before padding is 82 bytes. Thus, the
- padding length modulo 8 must be equal to 6 in order to make
- the total length an even multiple of 8 bytes (the block
- length). The padding length can be 6, 14, 22, and so on,
- through 254. If the padding length were the minimum necessary,
- 6, the padding would be 6 bytes, each containing the value 6.
- Thus, the last 8 octets of the GenericBlockCipher before block
- encryption would be xx 06 06 06 06 06 06 06, where xx is the
- last octet of the MAC.
-
- Note: With block ciphers in CBC mode (Cipher Block Chaining) the
- initialization vector (IV) for the first record is generated with
- the other keys and secrets when the security parameters are set.
- The IV for subsequent records is the last ciphertext block from
- the previous record.
-
-
-
-
-Dierks & Allen Standards Track [Page 20]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-6.3. Key calculation
-
- The Record Protocol requires an algorithm to generate keys, IVs, and
- MAC secrets from the security parameters provided by the handshake
- protocol.
-
- The master secret is hashed into a sequence of secure bytes, which
- are assigned to the MAC secrets, keys, and non-export IVs required by
- the current connection state (see Appendix A.6). CipherSpecs require
- a client write MAC secret, a server write MAC secret, a client write
- key, a server write key, a client write IV, and a server write IV,
- which are generated from the master secret in that order. Unused
- values are empty.
-
- When generating keys and MAC secrets, the master secret is used as an
- entropy source, and the random values provide unencrypted salt
- material and IVs for exportable ciphers.
-
- To generate the key material, compute
-
- key_block = PRF(SecurityParameters.master_secret,
- "key expansion",
- SecurityParameters.server_random +
- SecurityParameters.client_random);
-
- until enough output has been generated. Then the key_block is
- partitioned as follows:
-
- client_write_MAC_secret[SecurityParameters.hash_size]
- server_write_MAC_secret[SecurityParameters.hash_size]
- client_write_key[SecurityParameters.key_material_length]
- server_write_key[SecurityParameters.key_material_length]
- client_write_IV[SecurityParameters.IV_size]
- server_write_IV[SecurityParameters.IV_size]
-
- The client_write_IV and server_write_IV are only generated for non-
- export block ciphers. For exportable block ciphers, the
- initialization vectors are generated later, as described below. Any
- extra key_block material is discarded.
-
- Implementation note:
- The cipher spec which is defined in this document which requires
- the most material is 3DES_EDE_CBC_SHA: it requires 2 x 24 byte
- keys, 2 x 20 byte MAC secrets, and 2 x 8 byte IVs, for a total of
- 104 bytes of key material.
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 21]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- Exportable encryption algorithms (for which CipherSpec.is_exportable
- is true) require additional processing as follows to derive their
- final write keys:
-
- final_client_write_key =
- PRF(SecurityParameters.client_write_key,
- "client write key",
- SecurityParameters.client_random +
- SecurityParameters.server_random);
- final_server_write_key =
- PRF(SecurityParameters.server_write_key,
- "server write key",
- SecurityParameters.client_random +
- SecurityParameters.server_random);
-
- Exportable encryption algorithms derive their IVs solely from the
- random values from the hello messages:
-
- iv_block = PRF("", "IV block", SecurityParameters.client_random +
- SecurityParameters.server_random);
-
- The iv_block is partitioned into two initialization vectors as the
- key_block was above:
-
- client_write_IV[SecurityParameters.IV_size]
- server_write_IV[SecurityParameters.IV_size]
-
- Note that the PRF is used without a secret in this case: this just
- means that the secret has a length of zero bytes and contributes
- nothing to the hashing in the PRF.
-
-6.3.1. Export key generation example
-
- TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 requires five random bytes for
- each of the two encryption keys and 16 bytes for each of the MAC
- keys, for a total of 42 bytes of key material. The PRF output is
- stored in the key_block. The key_block is partitioned, and the write
- keys are salted because this is an exportable encryption algorithm.
-
- key_block = PRF(master_secret,
- "key expansion",
- server_random +
- client_random)[0..41]
- client_write_MAC_secret = key_block[0..15]
- server_write_MAC_secret = key_block[16..31]
- client_write_key = key_block[32..36]
- server_write_key = key_block[37..41]
-
-
-
-
-Dierks & Allen Standards Track [Page 22]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- final_client_write_key = PRF(client_write_key,
- "client write key",
- client_random +
- server_random)[0..15]
- final_server_write_key = PRF(server_write_key,
- "server write key",
- client_random +
- server_random)[0..15]
-
- iv_block = PRF("", "IV block", client_random +
- server_random)[0..15]
- client_write_IV = iv_block[0..7]
- server_write_IV = iv_block[8..15]
-
-7. The TLS Handshake Protocol
-
- The TLS Handshake Protocol consists of a suite of three sub-protocols
- which are used to allow peers to agree upon security parameters for
- the record layer, authenticate themselves, instantiate negotiated
- security parameters, and report error conditions to each other.
-
- The Handshake Protocol is responsible for negotiating a session,
- which consists of the following items:
-
- session identifier
- An arbitrary byte sequence chosen by the server to identify an
- active or resumable session state.
-
- peer certificate
- X509v3 [X509] certificate of the peer. This element of the state
- may be null.
-
- compression method
- The algorithm used to compress data prior to encryption.
-
- cipher spec
- Specifies the bulk data encryption algorithm (such as null, DES,
- etc.) and a MAC algorithm (such as MD5 or SHA). It also defines
- cryptographic attributes such as the hash_size. (See Appendix A.6
- for formal definition)
-
- master secret
- 48-byte secret shared between the client and server.
-
- is resumable
- A flag indicating whether the session can be used to initiate new
- connections.
-
-
-
-
-Dierks & Allen Standards Track [Page 23]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- These items are then used to create security parameters for use by
- the Record Layer when protecting application data. Many connections
- can be instantiated using the same session through the resumption
- feature of the TLS Handshake Protocol.
-
-7.1. Change cipher spec protocol
-
- The change cipher spec protocol exists to signal transitions in
- ciphering strategies. The protocol consists of a single message,
- which is encrypted and compressed under the current (not the pending)
- connection state. The message consists of a single byte of value 1.
-
- struct {
- enum { change_cipher_spec(1), (255) } type;
- } ChangeCipherSpec;
-
- The change cipher spec message is sent by both the client and server
- to notify the receiving party that subsequent records will be
- protected under the newly negotiated CipherSpec and keys. Reception
- of this message causes the receiver to instruct the Record Layer to
- immediately copy the read pending state into the read current state.
- Immediately after sending this message, the sender should instruct
- the record layer to make the write pending state the write active
- state. (See section 6.1.) The change cipher spec message is sent
- during the handshake after the security parameters have been agreed
- upon, but before the verifying finished message is sent (see section
- 7.4.9).
-
-7.2. Alert protocol
-
- One of the content types supported by the TLS Record layer is the
- alert type. Alert messages convey the severity of the message and a
- description of the alert. Alert messages with a level of fatal result
- in the immediate termination of the connection. In this case, other
- connections corresponding to the session may continue, but the
- session identifier must be invalidated, preventing the failed session
- from being used to establish new connections. Like other messages,
- alert messages are encrypted and compressed, as specified by the
- current connection state.
-
- enum { warning(1), fatal(2), (255) } AlertLevel;
-
- enum {
- close_notify(0),
- unexpected_message(10),
- bad_record_mac(20),
- decryption_failed(21),
- record_overflow(22),
-
-
-
-Dierks & Allen Standards Track [Page 24]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- decompression_failure(30),
- handshake_failure(40),
- bad_certificate(42),
- unsupported_certificate(43),
- certificate_revoked(44),
- certificate_expired(45),
- certificate_unknown(46),
- illegal_parameter(47),
- unknown_ca(48),
- access_denied(49),
- decode_error(50),
- decrypt_error(51),
- export_restriction(60),
- protocol_version(70),
- insufficient_security(71),
- internal_error(80),
- user_canceled(90),
- no_renegotiation(100),
- (255)
- } AlertDescription;
-
- struct {
- AlertLevel level;
- AlertDescription description;
- } Alert;
-
-7.2.1. Closure alerts
-
- The client and the server must share knowledge that the connection is
- ending in order to avoid a truncation attack. Either party may
- initiate the exchange of closing messages.
-
- close_notify
- This message notifies the recipient that the sender will not send
- any more messages on this connection. The session becomes
- unresumable if any connection is terminated without proper
- close_notify messages with level equal to warning.
-
- Either party may initiate a close by sending a close_notify alert.
- Any data received after a closure alert is ignored.
-
- Each party is required to send a close_notify alert before closing
- the write side of the connection. It is required that the other party
- respond with a close_notify alert of its own and close down the
- connection immediately, discarding any pending writes. It is not
- required for the initiator of the close to wait for the responding
- close_notify alert before closing the read side of the connection.
-
-
-
-
-Dierks & Allen Standards Track [Page 25]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- If the application protocol using TLS provides that any data may be
- carried over the underlying transport after the TLS connection is
- closed, the TLS implementation must receive the responding
- close_notify alert before indicating to the application layer that
- the TLS connection has ended. If the application protocol will not
- transfer any additional data, but will only close the underlying
- transport connection, then the implementation may choose to close the
- transport without waiting for the responding close_notify. No part of
- this standard should be taken to dictate the manner in which a usage
- profile for TLS manages its data transport, including when
- connections are opened or closed.
-
- NB: It is assumed that closing a connection reliably delivers
- pending data before destroying the transport.
-
-7.2.2. Error alerts
-
- Error handling in the TLS Handshake protocol is very simple. When an
- error is detected, the detecting party sends a message to the other
- party. Upon transmission or receipt of an fatal alert message, both
- parties immediately close the connection. Servers and clients are
- required to forget any session-identifiers, keys, and secrets
- associated with a failed connection. The following error alerts are
- defined:
-
- unexpected_message
- An inappropriate message was received. This alert is always fatal
- and should never be observed in communication between proper
- implementations.
-
- bad_record_mac
- This alert is returned if a record is received with an incorrect
- MAC. This message is always fatal.
-
- decryption_failed
- A TLSCiphertext decrypted in an invalid way: either it wasn`t an
- even multiple of the block length or its padding values, when
- checked, weren`t correct. This message is always fatal.
-
- record_overflow
- A TLSCiphertext record was received which had a length more than
- 2^14+2048 bytes, or a record decrypted to a TLSCompressed record
- with more than 2^14+1024 bytes. This message is always fatal.
-
- decompression_failure
- The decompression function received improper input (e.g. data
- that would expand to excessive length). This message is always
- fatal.
-
-
-
-Dierks & Allen Standards Track [Page 26]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- handshake_failure
- Reception of a handshake_failure alert message indicates that the
- sender was unable to negotiate an acceptable set of security
- parameters given the options available. This is a fatal error.
-
- bad_certificate
- A certificate was corrupt, contained signatures that did not
- verify correctly, etc.
-
- unsupported_certificate
- A certificate was of an unsupported type.
-
- certificate_revoked
- A certificate was revoked by its signer.
-
- certificate_expired
- A certificate has expired or is not currently valid.
-
- certificate_unknown
- Some other (unspecified) issue arose in processing the
- certificate, rendering it unacceptable.
-
- illegal_parameter
- A field in the handshake was out of range or inconsistent with
- other fields. This is always fatal.
-
- unknown_ca
- A valid certificate chain or partial chain was received, but the
- certificate was not accepted because the CA certificate could not
- be located or couldn`t be matched with a known, trusted CA. This
- message is always fatal.
-
- access_denied
- A valid certificate was received, but when access control was
- applied, the sender decided not to proceed with negotiation.
- This message is always fatal.
-
- decode_error
- A message could not be decoded because some field was out of the
- specified range or the length of the message was incorrect. This
- message is always fatal.
-
- decrypt_error
- A handshake cryptographic operation failed, including being
- unable to correctly verify a signature, decrypt a key exchange,
- or validate a finished message.
-
-
-
-
-
-Dierks & Allen Standards Track [Page 27]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- export_restriction
- A negotiation not in compliance with export restrictions was
- detected; for example, attempting to transfer a 1024 bit
- ephemeral RSA key for the RSA_EXPORT handshake method. This
- message is always fatal.
-
- protocol_version
- The protocol version the client has attempted to negotiate is
- recognized, but not supported. (For example, old protocol
- versions might be avoided for security reasons). This message is
- always fatal.
-
- insufficient_security
- Returned instead of handshake_failure when a negotiation has
- failed specifically because the server requires ciphers more
- secure than those supported by the client. This message is always
- fatal.
-
- internal_error
- An internal error unrelated to the peer or the correctness of the
- protocol makes it impossible to continue (such as a memory
- allocation failure). This message is always fatal.
-
- user_canceled
- This handshake is being canceled for some reason unrelated to a
- protocol failure. If the user cancels an operation after the
- handshake is complete, just closing the connection by sending a
- close_notify is more appropriate. This alert should be followed
- by a close_notify. This message is generally a warning.
-
- no_renegotiation
- Sent by the client in response to a hello request or by the
- server in response to a client hello after initial handshaking.
- Either of these would normally lead to renegotiation; when that
- is not appropriate, the recipient should respond with this alert;
- at that point, the original requester can decide whether to
- proceed with the connection. One case where this would be
- appropriate would be where a server has spawned a process to
- satisfy a request; the process might receive security parameters
- (key length, authentication, etc.) at startup and it might be
- difficult to communicate changes to these parameters after that
- point. This message is always a warning.
-
- For all errors where an alert level is not explicitly specified, the
- sending party may determine at its discretion whether this is a fatal
- error or not; if an alert with a level of warning is received, the
-
-
-
-
-
-Dierks & Allen Standards Track [Page 28]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- receiving party may decide at its discretion whether to treat this as
- a fatal error or not. However, all messages which are transmitted
- with a level of fatal must be treated as fatal messages.
-
-7.3. Handshake Protocol overview
-
- The cryptographic parameters of the session state are produced by the
- TLS Handshake Protocol, which operates on top of the TLS Record
- Layer. When a TLS client and server first start communicating, they
- agree on a protocol version, select cryptographic algorithms,
- optionally authenticate each other, and use public-key encryption
- techniques to generate shared secrets.
-
- The TLS Handshake Protocol involves the following steps:
-
- - Exchange hello messages to agree on algorithms, exchange random
- values, and check for session resumption.
-
- - Exchange the necessary cryptographic parameters to allow the
- client and server to agree on a premaster secret.
-
- - Exchange certificates and cryptographic information to allow the
- client and server to authenticate themselves.
-
- - Generate a master secret from the premaster secret and exchanged
- random values.
-
- - Provide security parameters to the record layer.
-
- - Allow the client and server to verify that their peer has
- calculated the same security parameters and that the handshake
- occurred without tampering by an attacker.
-
- Note that higher layers should not be overly reliant on TLS always
- negotiating the strongest possible connection between two peers:
- there are a number of ways a man in the middle attacker can attempt
- to make two entities drop down to the least secure method they
- support. The protocol has been designed to minimize this risk, but
- there are still attacks available: for example, an attacker could
- block access to the port a secure service runs on, or attempt to get
- the peers to negotiate an unauthenticated connection. The fundamental
- rule is that higher levels must be cognizant of what their security
- requirements are and never transmit information over a channel less
- secure than what they require. The TLS protocol is secure, in that
- any cipher suite offers its promised level of security: if you
- negotiate 3DES with a 1024 bit RSA key exchange with a host whose
- certificate you have verified, you can expect to be that secure.
-
-
-
-
-Dierks & Allen Standards Track [Page 29]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- However, you should never send data over a link encrypted with 40 bit
- security unless you feel that data is worth no more than the effort
- required to break that encryption.
-
- These goals are achieved by the handshake protocol, which can be
- summarized as follows: The client sends a client hello message to
- which the server must respond with a server hello message, or else a
- fatal error will occur and the connection will fail. The client hello
- and server hello are used to establish security enhancement
- capabilities between client and server. The client hello and server
- hello establish the following attributes: Protocol Version, Session
- ID, Cipher Suite, and Compression Method. Additionally, two random
- values are generated and exchanged: ClientHello.random and
- ServerHello.random.
-
- The actual key exchange uses up to four messages: the server
- certificate, the server key exchange, the client certificate, and the
- client key exchange. New key exchange methods can be created by
- specifying a format for these messages and defining the use of the
- messages to allow the client and server to agree upon a shared
- secret. This secret should be quite long; currently defined key
- exchange methods exchange secrets which range from 48 to 128 bytes in
- length.
-
- Following the hello messages, the server will send its certificate,
- if it is to be authenticated. Additionally, a server key exchange
- message may be sent, if it is required (e.g. if their server has no
- certificate, or if its certificate is for signing only). If the
- server is authenticated, it may request a certificate from the
- client, if that is appropriate to the cipher suite selected. Now the
- server will send the server hello done message, indicating that the
- hello-message phase of the handshake is complete. The server will
- then wait for a client response. If the server has sent a certificate
- request message, the client must send the certificate message. The
- client key exchange message is now sent, and the content of that
- message will depend on the public key algorithm selected between the
- client hello and the server hello. If the client has sent a
- certificate with signing ability, a digitally-signed certificate
- verify message is sent to explicitly verify the certificate.
-
- At this point, a change cipher spec message is sent by the client,
- and the client copies the pending Cipher Spec into the current Cipher
- Spec. The client then immediately sends the finished message under
- the new algorithms, keys, and secrets. In response, the server will
- send its own change cipher spec message, transfer the pending to the
- current Cipher Spec, and send its finished message under the new
-
-
-
-
-
-Dierks & Allen Standards Track [Page 30]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- Cipher Spec. At this point, the handshake is complete and the client
- and server may begin to exchange application layer data. (See flow
- chart below.)
-
- Client Server
-
- ClientHello -------->
- ServerHello
- Certificate*
- ServerKeyExchange*
- CertificateRequest*
- <-------- ServerHelloDone
- Certificate*
- ClientKeyExchange
- CertificateVerify*
- [ChangeCipherSpec]
- Finished -------->
- [ChangeCipherSpec]
- <-------- Finished
- Application Data <-------> Application Data
-
- Fig. 1 - Message flow for a full handshake
-
- * Indicates optional or situation-dependent messages that are not
- always sent.
-
- Note: To help avoid pipeline stalls, ChangeCipherSpec is an
- independent TLS Protocol content type, and is not actually a TLS
- handshake message.
-
- When the client and server decide to resume a previous session or
- duplicate an existing session (instead of negotiating new security
- parameters) the message flow is as follows:
-
- The client sends a ClientHello using the Session ID of the session to
- be resumed. The server then checks its session cache for a match. If
- a match is found, and the server is willing to re-establish the
- connection under the specified session state, it will send a
- ServerHello with the same Session ID value. At this point, both
- client and server must send change cipher spec messages and proceed
- directly to finished messages. Once the re-establishment is complete,
- the client and server may begin to exchange application layer data.
- (See flow chart below.) If a Session ID match is not found, the
- server generates a new session ID and the TLS client and server
- perform a full handshake.
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 31]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- Client Server
-
- ClientHello -------->
- ServerHello
- [ChangeCipherSpec]
- <-------- Finished
- [ChangeCipherSpec]
- Finished -------->
- Application Data <-------> Application Data
-
- Fig. 2 - Message flow for an abbreviated handshake
-
- The contents and significance of each message will be presented in
- detail in the following sections.
-
-7.4. Handshake protocol
-
- The TLS Handshake Protocol is one of the defined higher level clients
- of the TLS Record Protocol. This protocol is used to negotiate the
- secure attributes of a session. Handshake messages are supplied to
- the TLS Record Layer, where they are encapsulated within one or more
- TLSPlaintext structures, which are processed and transmitted as
- specified by the current active session state.
-
- enum {
- hello_request(0), client_hello(1), server_hello(2),
- certificate(11), server_key_exchange (12),
- certificate_request(13), server_hello_done(14),
- certificate_verify(15), client_key_exchange(16),
- finished(20), (255)
- } HandshakeType;
-
- struct {
- HandshakeType msg_type; /* handshake type */
- uint24 length; /* bytes in message */
- select (HandshakeType) {
- case hello_request: HelloRequest;
- case client_hello: ClientHello;
- case server_hello: ServerHello;
- case certificate: Certificate;
- case server_key_exchange: ServerKeyExchange;
- case certificate_request: CertificateRequest;
- case server_hello_done: ServerHelloDone;
- case certificate_verify: CertificateVerify;
- case client_key_exchange: ClientKeyExchange;
- case finished: Finished;
- } body;
- } Handshake;
-
-
-
-Dierks & Allen Standards Track [Page 32]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- The handshake protocol messages are presented below in the order they
- must be sent; sending handshake messages in an unexpected order
- results in a fatal error. Unneeded handshake messages can be omitted,
- however. Note one exception to the ordering: the Certificate message
- is used twice in the handshake (from server to client, then from
- client to server), but described only in its first position. The one
- message which is not bound by these ordering rules in the Hello
- Request message, which can be sent at any time, but which should be
- ignored by the client if it arrives in the middle of a handshake.
-
-7.4.1. Hello messages
-
- The hello phase messages are used to exchange security enhancement
- capabilities between the client and server. When a new session
- begins, the Record Layer's connection state encryption, hash, and
- compression algorithms are initialized to null. The current
- connection state is used for renegotiation messages.
-
-7.4.1.1. Hello request
-
- When this message will be sent:
- The hello request message may be sent by the server at any time.
-
- Meaning of this message:
- Hello request is a simple notification that the client should
- begin the negotiation process anew by sending a client hello
- message when convenient. This message will be ignored by the
- client if the client is currently negotiating a session. This
- message may be ignored by the client if it does not wish to
- renegotiate a session, or the client may, if it wishes, respond
- with a no_renegotiation alert. Since handshake messages are
- intended to have transmission precedence over application data,
- it is expected that the negotiation will begin before no more
- than a few records are received from the client. If the server
- sends a hello request but does not receive a client hello in
- response, it may close the connection with a fatal alert.
-
- After sending a hello request, servers should not repeat the request
- until the subsequent handshake negotiation is complete.
-
- Structure of this message:
- struct { } HelloRequest;
-
- Note: This message should never be included in the message hashes which
- are maintained throughout the handshake and used in the finished
- messages and the certificate verify message.
-
-
-
-
-
-Dierks & Allen Standards Track [Page 33]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-7.4.1.2. Client hello
-
- When this message will be sent:
- When a client first connects to a server it is required to send
- the client hello as its first message. The client can also send a
- client hello in response to a hello request or on its own
- initiative in order to renegotiate the security parameters in an
- existing connection.
-
- Structure of this message:
- The client hello message includes a random structure, which is
- used later in the protocol.
-
- struct {
- uint32 gmt_unix_time;
- opaque random_bytes[28];
- } Random;
-
- gmt_unix_time
- The current time and date in standard UNIX 32-bit format (seconds
- since the midnight starting Jan 1, 1970, GMT) according to the
- sender's internal clock. Clocks are not required to be set
- correctly by the basic TLS Protocol; higher level or application
- protocols may define additional requirements.
-
- random_bytes
- 28 bytes generated by a secure random number generator.
-
- The client hello message includes a variable length session
- identifier. If not empty, the value identifies a session between the
- same client and server whose security parameters the client wishes to
- reuse. The session identifier may be from an earlier connection, this
- connection, or another currently active connection. The second option
- is useful if the client only wishes to update the random structures
- and derived values of a connection, while the third option makes it
- possible to establish several independent secure connections without
- repeating the full handshake protocol. These independent connections
- may occur sequentially or simultaneously; a SessionID becomes valid
- when the handshake negotiating it completes with the exchange of
- Finished messages and persists until removed due to aging or because
- a fatal error was encountered on a connection associated with the
- session. The actual contents of the SessionID are defined by the
- server.
-
- opaque SessionID<0..32>;
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 34]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- Warning:
- Because the SessionID is transmitted without encryption or
- immediate MAC protection, servers must not place confidential
- information in session identifiers or let the contents of fake
- session identifiers cause any breach of security. (Note that the
- content of the handshake as a whole, including the SessionID, is
- protected by the Finished messages exchanged at the end of the
- handshake.)
-
- The CipherSuite list, passed from the client to the server in the
- client hello message, contains the combinations of cryptographic
- algorithms supported by the client in order of the client's
- preference (favorite choice first). Each CipherSuite defines a key
- exchange algorithm, a bulk encryption algorithm (including secret key
- length) and a MAC algorithm. The server will select a cipher suite
- or, if no acceptable choices are presented, return a handshake
- failure alert and close the connection.
-
- uint8 CipherSuite[2]; /* Cryptographic suite selector */
-
- The client hello includes a list of compression algorithms supported
- by the client, ordered according to the client's preference.
-
- enum { null(0), (255) } CompressionMethod;
-
- struct {
- ProtocolVersion client_version;
- Random random;
- SessionID session_id;
- CipherSuite cipher_suites<2..2^16-1>;
- CompressionMethod compression_methods<1..2^8-1>;
- } ClientHello;
-
- client_version
- The version of the TLS protocol by which the client wishes to
- communicate during this session. This should be the latest
- (highest valued) version supported by the client. For this
- version of the specification, the version will be 3.1 (See
- Appendix E for details about backward compatibility).
-
- random
- A client-generated random structure.
-
- session_id
- The ID of a session the client wishes to use for this connection.
- This field should be empty if no session_id is available or the
- client wishes to generate new security parameters.
-
-
-
-
-Dierks & Allen Standards Track [Page 35]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- cipher_suites
- This is a list of the cryptographic options supported by the
- client, with the client's first preference first. If the
- session_id field is not empty (implying a session resumption
- request) this vector must include at least the cipher_suite from
- that session. Values are defined in Appendix A.5.
-
- compression_methods
- This is a list of the compression methods supported by the
- client, sorted by client preference. If the session_id field is
- not empty (implying a session resumption request) it must include
- the compression_method from that session. This vector must
- contain, and all implementations must support,
- CompressionMethod.null. Thus, a client and server will always be
- able to agree on a compression method.
-
- After sending the client hello message, the client waits for a server
- hello message. Any other handshake message returned by the server
- except for a hello request is treated as a fatal error.
-
- Forward compatibility note:
- In the interests of forward compatibility, it is permitted for a
- client hello message to include extra data after the compression
- methods. This data must be included in the handshake hashes, but
- must otherwise be ignored. This is the only handshake message for
- which this is legal; for all other messages, the amount of data
- in the message must match the description of the message
- precisely.
-
-7.4.1.3. Server hello
-
- When this message will be sent:
- The server will send this message in response to a client hello
- message when it was able to find an acceptable set of algorithms.
- If it cannot find such a match, it will respond with a handshake
- failure alert.
-
- Structure of this message:
- struct {
- ProtocolVersion server_version;
- Random random;
- SessionID session_id;
- CipherSuite cipher_suite;
- CompressionMethod compression_method;
- } ServerHello;
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 36]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- server_version
- This field will contain the lower of that suggested by the client
- in the client hello and the highest supported by the server. For
- this version of the specification, the version is 3.1 (See
- Appendix E for details about backward compatibility).
-
- random
- This structure is generated by the server and must be different
- from (and independent of) ClientHello.random.
-
- session_id
- This is the identity of the session corresponding to this
- connection. If the ClientHello.session_id was non-empty, the
- server will look in its session cache for a match. If a match is
- found and the server is willing to establish the new connection
- using the specified session state, the server will respond with
- the same value as was supplied by the client. This indicates a
- resumed session and dictates that the parties must proceed
- directly to the finished messages. Otherwise this field will
- contain a different value identifying the new session. The server
- may return an empty session_id to indicate that the session will
- not be cached and therefore cannot be resumed. If a session is
- resumed, it must be resumed using the same cipher suite it was
- originally negotiated with.
-
- cipher_suite
- The single cipher suite selected by the server from the list in
- ClientHello.cipher_suites. For resumed sessions this field is the
- value from the state of the session being resumed.
-
- compression_method
- The single compression algorithm selected by the server from the
- list in ClientHello.compression_methods. For resumed sessions
- this field is the value from the resumed session state.
-
-7.4.2. Server certificate
-
- When this message will be sent:
- The server must send a certificate whenever the agreed-upon key
- exchange method is not an anonymous one. This message will always
- immediately follow the server hello message.
-
- Meaning of this message:
- The certificate type must be appropriate for the selected cipher
- suite's key exchange algorithm, and is generally an X.509v3
- certificate. It must contain a key which matches the key exchange
- method, as follows. Unless otherwise specified, the signing
-
-
-
-
-Dierks & Allen Standards Track [Page 37]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- algorithm for the certificate must be the same as the algorithm
- for the certificate key. Unless otherwise specified, the public
- key may be of any length.
-
- Key Exchange Algorithm Certificate Key Type
-
- RSA RSA public key; the certificate must
- allow the key to be used for encryption.
-
- RSA_EXPORT RSA public key of length greater than
- 512 bits which can be used for signing,
- or a key of 512 bits or shorter which
- can be used for either encryption or
- signing.
-
- DHE_DSS DSS public key.
-
- DHE_DSS_EXPORT DSS public key.
-
- DHE_RSA RSA public key which can be used for
- signing.
-
- DHE_RSA_EXPORT RSA public key which can be used for
- signing.
-
- DH_DSS Diffie-Hellman key. The algorithm used
- to sign the certificate should be DSS.
-
- DH_RSA Diffie-Hellman key. The algorithm used
- to sign the certificate should be RSA.
-
- All certificate profiles, key and cryptographic formats are defined
- by the IETF PKIX working group [PKIX]. When a key usage extension is
- present, the digitalSignature bit must be set for the key to be
- eligible for signing, as described above, and the keyEncipherment bit
- must be present to allow encryption, as described above. The
- keyAgreement bit must be set on Diffie-Hellman certificates.
-
- As CipherSuites which specify new key exchange methods are specified
- for the TLS Protocol, they will imply certificate format and the
- required encoded keying information.
-
- Structure of this message:
- opaque ASN.1Cert<1..2^24-1>;
-
- struct {
- ASN.1Cert certificate_list<0..2^24-1>;
- } Certificate;
-
-
-
-Dierks & Allen Standards Track [Page 38]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- certificate_list
- This is a sequence (chain) of X.509v3 certificates. The sender's
- certificate must come first in the list. Each following
- certificate must directly certify the one preceding it. Because
- certificate validation requires that root keys be distributed
- independently, the self-signed certificate which specifies the
- root certificate authority may optionally be omitted from the
- chain, under the assumption that the remote end must already
- possess it in order to validate it in any case.
-
- The same message type and structure will be used for the client's
- response to a certificate request message. Note that a client may
- send no certificates if it does not have an appropriate certificate
- to send in response to the server's authentication request.
-
- Note: PKCS #7 [PKCS7] is not used as the format for the certificate
- vector because PKCS #6 [PKCS6] extended certificates are not
- used. Also PKCS #7 defines a SET rather than a SEQUENCE, making
- the task of parsing the list more difficult.
-
-7.4.3. Server key exchange message
-
- When this message will be sent:
- This message will be sent immediately after the server
- certificate message (or the server hello message, if this is an
- anonymous negotiation).
-
- The server key exchange message is sent by the server only when
- the server certificate message (if sent) does not contain enough
- data to allow the client to exchange a premaster secret. This is
- true for the following key exchange methods:
-
- RSA_EXPORT (if the public key in the server certificate is
- longer than 512 bits)
- DHE_DSS
- DHE_DSS_EXPORT
- DHE_RSA
- DHE_RSA_EXPORT
- DH_anon
-
- It is not legal to send the server key exchange message for the
- following key exchange methods:
-
- RSA
- RSA_EXPORT (when the public key in the server certificate is
- less than or equal to 512 bits in length)
- DH_DSS
- DH_RSA
-
-
-
-Dierks & Allen Standards Track [Page 39]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- Meaning of this message:
- This message conveys cryptographic information to allow the
- client to communicate the premaster secret: either an RSA public
- key to encrypt the premaster secret with, or a Diffie-Hellman
- public key with which the client can complete a key exchange
- (with the result being the premaster secret.)
-
- As additional CipherSuites are defined for TLS which include new key
- exchange algorithms, the server key exchange message will be sent if
- and only if the certificate type associated with the key exchange
- algorithm does not provide enough information for the client to
- exchange a premaster secret.
-
- Note: According to current US export law, RSA moduli larger than 512
- bits may not be used for key exchange in software exported from
- the US. With this message, the larger RSA keys encoded in
- certificates may be used to sign temporary shorter RSA keys for
- the RSA_EXPORT key exchange method.
-
- Structure of this message:
- enum { rsa, diffie_hellman } KeyExchangeAlgorithm;
-
- struct {
- opaque rsa_modulus<1..2^16-1>;
- opaque rsa_exponent<1..2^16-1>;
- } ServerRSAParams;
-
- rsa_modulus
- The modulus of the server's temporary RSA key.
-
- rsa_exponent
- The public exponent of the server's temporary RSA key.
-
- struct {
- opaque dh_p<1..2^16-1>;
- opaque dh_g<1..2^16-1>;
- opaque dh_Ys<1..2^16-1>;
- } ServerDHParams; /* Ephemeral DH parameters */
-
- dh_p
- The prime modulus used for the Diffie-Hellman operation.
-
- dh_g
- The generator used for the Diffie-Hellman operation.
-
- dh_Ys
- The server's Diffie-Hellman public value (g^X mod p).
-
-
-
-
-Dierks & Allen Standards Track [Page 40]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- struct {
- select (KeyExchangeAlgorithm) {
- case diffie_hellman:
- ServerDHParams params;
- Signature signed_params;
- case rsa:
- ServerRSAParams params;
- Signature signed_params;
- };
- } ServerKeyExchange;
-
- params
- The server's key exchange parameters.
-
- signed_params
- For non-anonymous key exchanges, a hash of the corresponding
- params value, with the signature appropriate to that hash
- applied.
-
- md5_hash
- MD5(ClientHello.random + ServerHello.random + ServerParams);
-
- sha_hash
- SHA(ClientHello.random + ServerHello.random + ServerParams);
-
- enum { anonymous, rsa, dsa } SignatureAlgorithm;
-
- select (SignatureAlgorithm)
- { case anonymous: struct { };
- case rsa:
- digitally-signed struct {
- opaque md5_hash[16];
- opaque sha_hash[20];
- };
- case dsa:
- digitally-signed struct {
- opaque sha_hash[20];
- };
- } Signature;
-
-7.4.4. Certificate request
-
- When this message will be sent:
- A non-anonymous server can optionally request a certificate from
- the client, if appropriate for the selected cipher suite. This
- message, if sent, will immediately follow the Server Key Exchange
- message (if it is sent; otherwise, the Server Certificate
- message).
-
-
-
-Dierks & Allen Standards Track [Page 41]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- Structure of this message:
- enum {
- rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4),
- (255)
- } ClientCertificateType;
-
- opaque DistinguishedName<1..2^16-1>;
-
- struct {
- ClientCertificateType certificate_types<1..2^8-1>;
- DistinguishedName certificate_authorities<3..2^16-1>;
- } CertificateRequest;
-
- certificate_types
- This field is a list of the types of certificates requested,
- sorted in order of the server's preference.
-
- certificate_authorities
- A list of the distinguished names of acceptable certificate
- authorities. These distinguished names may specify a desired
- distinguished name for a root CA or for a subordinate CA;
- thus, this message can be used both to describe known roots
- and a desired authorization space.
-
- Note: DistinguishedName is derived from [X509].
-
- Note: It is a fatal handshake_failure alert for an anonymous server to
- request client identification.
-
-7.4.5. Server hello done
-
- When this message will be sent:
- The server hello done message is sent by the server to indicate
- the end of the server hello and associated messages. After
- sending this message the server will wait for a client response.
-
- Meaning of this message:
- This message means that the server is done sending messages to
- support the key exchange, and the client can proceed with its
- phase of the key exchange.
-
- Upon receipt of the server hello done message the client should
- verify that the server provided a valid certificate if required
- and check that the server hello parameters are acceptable.
-
- Structure of this message:
- struct { } ServerHelloDone;
-
-
-
-
-Dierks & Allen Standards Track [Page 42]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-7.4.6. Client certificate
-
- When this message will be sent:
- This is the first message the client can send after receiving a
- server hello done message. This message is only sent if the
- server requests a certificate. If no suitable certificate is
- available, the client should send a certificate message
- containing no certificates. If client authentication is required
- by the server for the handshake to continue, it may respond with
- a fatal handshake failure alert. Client certificates are sent
- using the Certificate structure defined in Section 7.4.2.
-
- Note: When using a static Diffie-Hellman based key exchange method
- (DH_DSS or DH_RSA), if client authentication is requested, the
- Diffie-Hellman group and generator encoded in the client's
- certificate must match the server specified Diffie-Hellman
- parameters if the client's parameters are to be used for the key
- exchange.
-
-7.4.7. Client key exchange message
-
- When this message will be sent:
- This message is always sent by the client. It will immediately
- follow the client certificate message, if it is sent. Otherwise
- it will be the first message sent by the client after it receives
- the server hello done message.
-
- Meaning of this message:
- With this message, the premaster secret is set, either though
- direct transmission of the RSA-encrypted secret, or by the
- transmission of Diffie-Hellman parameters which will allow each
- side to agree upon the same premaster secret. When the key
- exchange method is DH_RSA or DH_DSS, client certification has
- been requested, and the client was able to respond with a
- certificate which contained a Diffie-Hellman public key whose
- parameters (group and generator) matched those specified by the
- server in its certificate, this message will not contain any
- data.
-
- Structure of this message:
- The choice of messages depends on which key exchange method has
- been selected. See Section 7.4.3 for the KeyExchangeAlgorithm
- definition.
-
- struct {
- select (KeyExchangeAlgorithm) {
- case rsa: EncryptedPreMasterSecret;
- case diffie_hellman: ClientDiffieHellmanPublic;
-
-
-
-Dierks & Allen Standards Track [Page 43]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- } exchange_keys;
- } ClientKeyExchange;
-
-7.4.7.1. RSA encrypted premaster secret message
-
- Meaning of this message:
- If RSA is being used for key agreement and authentication, the
- client generates a 48-byte premaster secret, encrypts it using
- the public key from the server's certificate or the temporary RSA
- key provided in a server key exchange message, and sends the
- result in an encrypted premaster secret message. This structure
- is a variant of the client key exchange message, not a message in
- itself.
-
- Structure of this message:
- struct {
- ProtocolVersion client_version;
- opaque random[46];
- } PreMasterSecret;
-
- client_version
- The latest (newest) version supported by the client. This is
- used to detect version roll-back attacks. Upon receiving the
- premaster secret, the server should check that this value
- matches the value transmitted by the client in the client
- hello message.
-
- random
- 46 securely-generated random bytes.
-
- struct {
- public-key-encrypted PreMasterSecret pre_master_secret;
- } EncryptedPreMasterSecret;
-
- Note: An attack discovered by Daniel Bleichenbacher [BLEI] can be used
- to attack a TLS server which is using PKCS#1 encoded RSA. The
- attack takes advantage of the fact that by failing in different
- ways, a TLS server can be coerced into revealing whether a
- particular message, when decrypted, is properly PKCS#1 formatted
- or not.
-
- The best way to avoid vulnerability to this attack is to treat
- incorrectly formatted messages in a manner indistinguishable from
- correctly formatted RSA blocks. Thus, when it receives an
- incorrectly formatted RSA block, a server should generate a
- random 48-byte value and proceed using it as the premaster
- secret. Thus, the server will act identically whether the
- received RSA block is correctly encoded or not.
-
-
-
-Dierks & Allen Standards Track [Page 44]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- pre_master_secret
- This random value is generated by the client and is used to
- generate the master secret, as specified in Section 8.1.
-
-7.4.7.2. Client Diffie-Hellman public value
-
- Meaning of this message:
- This structure conveys the client's Diffie-Hellman public value
- (Yc) if it was not already included in the client's certificate.
- The encoding used for Yc is determined by the enumerated
- PublicValueEncoding. This structure is a variant of the client
- key exchange message, not a message in itself.
-
- Structure of this message:
- enum { implicit, explicit } PublicValueEncoding;
-
- implicit
- If the client certificate already contains a suitable
- Diffie-Hellman key, then Yc is implicit and does not need to
- be sent again. In this case, the Client Key Exchange message
- will be sent, but will be empty.
-
- explicit
- Yc needs to be sent.
-
- struct {
- select (PublicValueEncoding) {
- case implicit: struct { };
- case explicit: opaque dh_Yc<1..2^16-1>;
- } dh_public;
- } ClientDiffieHellmanPublic;
-
- dh_Yc
- The client's Diffie-Hellman public value (Yc).
-
-7.4.8. Certificate verify
-
- When this message will be sent:
- This message is used to provide explicit verification of a client
- certificate. This message is only sent following a client
- certificate that has signing capability (i.e. all certificates
- except those containing fixed Diffie-Hellman parameters). When
- sent, it will immediately follow the client key exchange message.
-
- Structure of this message:
- struct {
- Signature signature;
- } CertificateVerify;
-
-
-
-Dierks & Allen Standards Track [Page 45]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- The Signature type is defined in 7.4.3.
-
- CertificateVerify.signature.md5_hash
- MD5(handshake_messages);
-
- Certificate.signature.sha_hash
- SHA(handshake_messages);
-
- Here handshake_messages refers to all handshake messages sent or
- received starting at client hello up to but not including this
- message, including the type and length fields of the handshake
- messages. This is the concatenation of all the Handshake structures
- as defined in 7.4 exchanged thus far.
-
-7.4.9. Finished
-
- When this message will be sent:
- A finished message is always sent immediately after a change
- cipher spec message to verify that the key exchange and
- authentication processes were successful. It is essential that a
- change cipher spec message be received between the other
- handshake messages and the Finished message.
-
- Meaning of this message:
- The finished message is the first protected with the just-
- negotiated algorithms, keys, and secrets. Recipients of finished
- messages must verify that the contents are correct. Once a side
- has sent its Finished message and received and validated the
- Finished message from its peer, it may begin to send and receive
- application data over the connection.
-
- struct {
- opaque verify_data[12];
- } Finished;
-
- verify_data
- PRF(master_secret, finished_label, MD5(handshake_messages) +
- SHA-1(handshake_messages)) [0..11];
-
- finished_label
- For Finished messages sent by the client, the string "client
- finished". For Finished messages sent by the server, the
- string "server finished".
-
- handshake_messages
- All of the data from all handshake messages up to but not
- including this message. This is only data visible at the
- handshake layer and does not include record layer headers.
-
-
-
-Dierks & Allen Standards Track [Page 46]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- This is the concatenation of all the Handshake structures as
- defined in 7.4 exchanged thus far.
-
- It is a fatal error if a finished message is not preceded by a change
- cipher spec message at the appropriate point in the handshake.
-
- The hash contained in finished messages sent by the server
- incorporate Sender.server; those sent by the client incorporate
- Sender.client. The value handshake_messages includes all handshake
- messages starting at client hello up to, but not including, this
- finished message. This may be different from handshake_messages in
- Section 7.4.8 because it would include the certificate verify message
- (if sent). Also, the handshake_messages for the finished message sent
- by the client will be different from that for the finished message
- sent by the server, because the one which is sent second will include
- the prior one.
-
- Note: Change cipher spec messages, alerts and any other record types
- are not handshake messages and are not included in the hash
- computations. Also, Hello Request messages are omitted from
- handshake hashes.
-
-8. Cryptographic computations
-
- In order to begin connection protection, the TLS Record Protocol
- requires specification of a suite of algorithms, a master secret, and
- the client and server random values. The authentication, encryption,
- and MAC algorithms are determined by the cipher_suite selected by the
- server and revealed in the server hello message. The compression
- algorithm is negotiated in the hello messages, and the random values
- are exchanged in the hello messages. All that remains is to calculate
- the master secret.
-
-8.1. Computing the master secret
-
- For all key exchange methods, the same algorithm is used to convert
- the pre_master_secret into the master_secret. The pre_master_secret
- should be deleted from memory once the master_secret has been
- computed.
-
- master_secret = PRF(pre_master_secret, "master secret",
- ClientHello.random + ServerHello.random)
- [0..47];
-
- The master secret is always exactly 48 bytes in length. The length of
- the premaster secret will vary depending on key exchange method.
-
-
-
-
-
-Dierks & Allen Standards Track [Page 47]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-8.1.1. RSA
-
- When RSA is used for server authentication and key exchange, a 48-
- byte pre_master_secret is generated by the client, encrypted under
- the server's public key, and sent to the server. The server uses its
- private key to decrypt the pre_master_secret. Both parties then
- convert the pre_master_secret into the master_secret, as specified
- above.
-
- RSA digital signatures are performed using PKCS #1 [PKCS1] block type
- 1. RSA public key encryption is performed using PKCS #1 block type 2.
-
-8.1.2. Diffie-Hellman
-
- A conventional Diffie-Hellman computation is performed. The
- negotiated key (Z) is used as the pre_master_secret, and is converted
- into the master_secret, as specified above.
-
- Note: Diffie-Hellman parameters are specified by the server, and may
- be either ephemeral or contained within the server's certificate.
-
-9. Mandatory Cipher Suites
-
- In the absence of an application profile standard specifying
- otherwise, a TLS compliant application MUST implement the cipher
- suite TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA.
-
-10. Application data protocol
-
- Application data messages are carried by the Record Layer and are
- fragmented, compressed and encrypted based on the current connection
- state. The messages are treated as transparent data to the record
- layer.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 48]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-A. Protocol constant values
-
- This section describes protocol types and constants.
-
-A.1. Record layer
-
- struct {
- uint8 major, minor;
- } ProtocolVersion;
-
- ProtocolVersion version = { 3, 1 }; /* TLS v1.0 */
-
- enum {
- change_cipher_spec(20), alert(21), handshake(22),
- application_data(23), (255)
- } ContentType;
-
- struct {
- ContentType type;
- ProtocolVersion version;
- uint16 length;
- opaque fragment[TLSPlaintext.length];
- } TLSPlaintext;
-
- struct {
- ContentType type;
- ProtocolVersion version;
- uint16 length;
- opaque fragment[TLSCompressed.length];
- } TLSCompressed;
-
- struct {
- ContentType type;
- ProtocolVersion version;
- uint16 length;
- select (CipherSpec.cipher_type) {
- case stream: GenericStreamCipher;
- case block: GenericBlockCipher;
- } fragment;
- } TLSCiphertext;
-
- stream-ciphered struct {
- opaque content[TLSCompressed.length];
- opaque MAC[CipherSpec.hash_size];
- } GenericStreamCipher;
-
- block-ciphered struct {
- opaque content[TLSCompressed.length];
-
-
-
-Dierks & Allen Standards Track [Page 49]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- opaque MAC[CipherSpec.hash_size];
- uint8 padding[GenericBlockCipher.padding_length];
- uint8 padding_length;
- } GenericBlockCipher;
-
-A.2. Change cipher specs message
-
- struct {
- enum { change_cipher_spec(1), (255) } type;
- } ChangeCipherSpec;
-
-A.3. Alert messages
-
- enum { warning(1), fatal(2), (255) } AlertLevel;
-
- enum {
- close_notify(0),
- unexpected_message(10),
- bad_record_mac(20),
- decryption_failed(21),
- record_overflow(22),
- decompression_failure(30),
- handshake_failure(40),
- bad_certificate(42),
- unsupported_certificate(43),
- certificate_revoked(44),
- certificate_expired(45),
- certificate_unknown(46),
- illegal_parameter(47),
- unknown_ca(48),
- access_denied(49),
- decode_error(50),
- decrypt_error(51),
- export_restriction(60),
- protocol_version(70),
- insufficient_security(71),
- internal_error(80),
- user_canceled(90),
- no_renegotiation(100),
- (255)
- } AlertDescription;
-
- struct {
- AlertLevel level;
- AlertDescription description;
- } Alert;
-
-
-
-
-
-Dierks & Allen Standards Track [Page 50]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-A.4. Handshake protocol
-
- enum {
- hello_request(0), client_hello(1), server_hello(2),
- certificate(11), server_key_exchange (12),
- certificate_request(13), server_hello_done(14),
- certificate_verify(15), client_key_exchange(16),
- finished(20), (255)
- } HandshakeType;
-
- struct {
- HandshakeType msg_type;
- uint24 length;
- select (HandshakeType) {
- case hello_request: HelloRequest;
- case client_hello: ClientHello;
- case server_hello: ServerHello;
- case certificate: Certificate;
- case server_key_exchange: ServerKeyExchange;
- case certificate_request: CertificateRequest;
- case server_hello_done: ServerHelloDone;
- case certificate_verify: CertificateVerify;
- case client_key_exchange: ClientKeyExchange;
- case finished: Finished;
- } body;
- } Handshake;
-
-A.4.1. Hello messages
-
- struct { } HelloRequest;
-
- struct {
- uint32 gmt_unix_time;
- opaque random_bytes[28];
- } Random;
-
- opaque SessionID<0..32>;
-
- uint8 CipherSuite[2];
-
- enum { null(0), (255) } CompressionMethod;
-
- struct {
- ProtocolVersion client_version;
- Random random;
- SessionID session_id;
- CipherSuite cipher_suites<2..2^16-1>;
- CompressionMethod compression_methods<1..2^8-1>;
-
-
-
-Dierks & Allen Standards Track [Page 51]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- } ClientHello;
-
- struct {
- ProtocolVersion server_version;
- Random random;
- SessionID session_id;
- CipherSuite cipher_suite;
- CompressionMethod compression_method;
- } ServerHello;
-
-A.4.2. Server authentication and key exchange messages
-
- opaque ASN.1Cert<2^24-1>;
-
- struct {
- ASN.1Cert certificate_list<1..2^24-1>;
- } Certificate;
-
- enum { rsa, diffie_hellman } KeyExchangeAlgorithm;
-
- struct {
- opaque RSA_modulus<1..2^16-1>;
- opaque RSA_exponent<1..2^16-1>;
- } ServerRSAParams;
-
- struct {
- opaque DH_p<1..2^16-1>;
- opaque DH_g<1..2^16-1>;
- opaque DH_Ys<1..2^16-1>;
- } ServerDHParams;
-
- struct {
- select (KeyExchangeAlgorithm) {
- case diffie_hellman:
- ServerDHParams params;
- Signature signed_params;
- case rsa:
- ServerRSAParams params;
- Signature signed_params;
- };
- } ServerKeyExchange;
-
- enum { anonymous, rsa, dsa } SignatureAlgorithm;
-
- select (SignatureAlgorithm)
- { case anonymous: struct { };
- case rsa:
- digitally-signed struct {
-
-
-
-Dierks & Allen Standards Track [Page 52]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- opaque md5_hash[16];
- opaque sha_hash[20];
- };
- case dsa:
- digitally-signed struct {
- opaque sha_hash[20];
- };
- } Signature;
-
- enum {
- rsa_sign(1), dss_sign(2), rsa_fixed_dh(3), dss_fixed_dh(4),
- (255)
- } ClientCertificateType;
-
- opaque DistinguishedName<1..2^16-1>;
-
- struct {
- ClientCertificateType certificate_types<1..2^8-1>;
- DistinguishedName certificate_authorities<3..2^16-1>;
- } CertificateRequest;
-
- struct { } ServerHelloDone;
-
-A.4.3. Client authentication and key exchange messages
-
- struct {
- select (KeyExchangeAlgorithm) {
- case rsa: EncryptedPreMasterSecret;
- case diffie_hellman: DiffieHellmanClientPublicValue;
- } exchange_keys;
- } ClientKeyExchange;
-
- struct {
- ProtocolVersion client_version;
- opaque random[46];
-
- } PreMasterSecret;
-
- struct {
- public-key-encrypted PreMasterSecret pre_master_secret;
- } EncryptedPreMasterSecret;
-
- enum { implicit, explicit } PublicValueEncoding;
-
- struct {
- select (PublicValueEncoding) {
- case implicit: struct {};
- case explicit: opaque DH_Yc<1..2^16-1>;
-
-
-
-Dierks & Allen Standards Track [Page 53]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- } dh_public;
- } ClientDiffieHellmanPublic;
-
- struct {
- Signature signature;
- } CertificateVerify;
-
-A.4.4. Handshake finalization message
-
- struct {
- opaque verify_data[12];
- } Finished;
-
-A.5. The CipherSuite
-
- The following values define the CipherSuite codes used in the client
- hello and server hello messages.
-
- A CipherSuite defines a cipher specification supported in TLS Version
- 1.0.
-
- TLS_NULL_WITH_NULL_NULL is specified and is the initial state of a
- TLS connection during the first handshake on that channel, but must
- not be negotiated, as it provides no more protection than an
- unsecured connection.
-
- CipherSuite TLS_NULL_WITH_NULL_NULL = { 0x00,0x00 };
-
- The following CipherSuite definitions require that the server provide
- an RSA certificate that can be used for key exchange. The server may
- request either an RSA or a DSS signature-capable certificate in the
- certificate request message.
-
- CipherSuite TLS_RSA_WITH_NULL_MD5 = { 0x00,0x01 };
- CipherSuite TLS_RSA_WITH_NULL_SHA = { 0x00,0x02 };
- CipherSuite TLS_RSA_EXPORT_WITH_RC4_40_MD5 = { 0x00,0x03 };
- CipherSuite TLS_RSA_WITH_RC4_128_MD5 = { 0x00,0x04 };
- CipherSuite TLS_RSA_WITH_RC4_128_SHA = { 0x00,0x05 };
- CipherSuite TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 = { 0x00,0x06 };
- CipherSuite TLS_RSA_WITH_IDEA_CBC_SHA = { 0x00,0x07 };
- CipherSuite TLS_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x08 };
- CipherSuite TLS_RSA_WITH_DES_CBC_SHA = { 0x00,0x09 };
- CipherSuite TLS_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x0A };
-
- The following CipherSuite definitions are used for server-
- authenticated (and optionally client-authenticated) Diffie-Hellman.
- DH denotes cipher suites in which the server's certificate contains
- the Diffie-Hellman parameters signed by the certificate authority
-
-
-
-Dierks & Allen Standards Track [Page 54]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- (CA). DHE denotes ephemeral Diffie-Hellman, where the Diffie-Hellman
- parameters are signed by a DSS or RSA certificate, which has been
- signed by the CA. The signing algorithm used is specified after the
- DH or DHE parameter. The server can request an RSA or DSS signature-
- capable certificate from the client for client authentication or it
- may request a Diffie-Hellman certificate. Any Diffie-Hellman
- certificate provided by the client must use the parameters (group and
- generator) described by the server.
-
- CipherSuite TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x0B };
- CipherSuite TLS_DH_DSS_WITH_DES_CBC_SHA = { 0x00,0x0C };
- CipherSuite TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00,0x0D };
- CipherSuite TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x0E };
- CipherSuite TLS_DH_RSA_WITH_DES_CBC_SHA = { 0x00,0x0F };
- CipherSuite TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x10 };
- CipherSuite TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x11 };
- CipherSuite TLS_DHE_DSS_WITH_DES_CBC_SHA = { 0x00,0x12 };
- CipherSuite TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00,0x13 };
- CipherSuite TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x14 };
- CipherSuite TLS_DHE_RSA_WITH_DES_CBC_SHA = { 0x00,0x15 };
- CipherSuite TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00,0x16 };
-
- The following cipher suites are used for completely anonymous
- Diffie-Hellman communications in which neither party is
- authenticated. Note that this mode is vulnerable to man-in-the-middle
- attacks and is therefore deprecated.
-
- CipherSuite TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 = { 0x00,0x17 };
- CipherSuite TLS_DH_anon_WITH_RC4_128_MD5 = { 0x00,0x18 };
- CipherSuite TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA = { 0x00,0x19 };
- CipherSuite TLS_DH_anon_WITH_DES_CBC_SHA = { 0x00,0x1A };
- CipherSuite TLS_DH_anon_WITH_3DES_EDE_CBC_SHA = { 0x00,0x1B };
-
- Note: All cipher suites whose first byte is 0xFF are considered
- private and can be used for defining local/experimental
- algorithms. Interoperability of such types is a local matter.
-
- Note: Additional cipher suites can be registered by publishing an RFC
- which specifies the cipher suites, including the necessary TLS
- protocol information, including message encoding, premaster
- secret derivation, symmetric encryption and MAC calculation and
- appropriate reference information for the algorithms involved.
- The RFC editor's office may, at its discretion, choose to publish
- specifications for cipher suites which are not completely
- described (e.g., for classified algorithms) if it finds the
- specification to be of technical interest and completely
- specified.
-
-
-
-
-Dierks & Allen Standards Track [Page 55]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- Note: The cipher suite values { 0x00, 0x1C } and { 0x00, 0x1D } are
- reserved to avoid collision with Fortezza-based cipher suites in
- SSL 3.
-
-A.6. The Security Parameters
-
- These security parameters are determined by the TLS Handshake
- Protocol and provided as parameters to the TLS Record Layer in order
- to initialize a connection state. SecurityParameters includes:
-
- enum { null(0), (255) } CompressionMethod;
-
- enum { server, client } ConnectionEnd;
-
- enum { null, rc4, rc2, des, 3des, des40, idea }
- BulkCipherAlgorithm;
-
- enum { stream, block } CipherType;
-
- enum { true, false } IsExportable;
-
- enum { null, md5, sha } MACAlgorithm;
-
- /* The algorithms specified in CompressionMethod,
- BulkCipherAlgorithm, and MACAlgorithm may be added to. */
-
- struct {
- ConnectionEnd entity;
- BulkCipherAlgorithm bulk_cipher_algorithm;
- CipherType cipher_type;
- uint8 key_size;
- uint8 key_material_length;
- IsExportable is_exportable;
- MACAlgorithm mac_algorithm;
- uint8 hash_size;
- CompressionMethod compression_algorithm;
- opaque master_secret[48];
- opaque client_random[32];
- opaque server_random[32];
- } SecurityParameters;
-
-
-
-
-
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 56]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-B. Glossary
-
- application protocol
- An application protocol is a protocol that normally layers
- directly on top of the transport layer (e.g., TCP/IP). Examples
- include HTTP, TELNET, FTP, and SMTP.
-
- asymmetric cipher
- See public key cryptography.
-
- authentication
- Authentication is the ability of one entity to determine the
- identity of another entity.
-
- block cipher
- A block cipher is an algorithm that operates on plaintext in
- groups of bits, called blocks. 64 bits is a common block size.
-
- bulk cipher
- A symmetric encryption algorithm used to encrypt large quantities
- of data.
-
- cipher block chaining (CBC)
- CBC is a mode in which every plaintext block encrypted with a
- block cipher is first exclusive-ORed with the previous ciphertext
- block (or, in the case of the first block, with the
- initialization vector). For decryption, every block is first
- decrypted, then exclusive-ORed with the previous ciphertext block
- (or IV).
-
- certificate
- As part of the X.509 protocol (a.k.a. ISO Authentication
- framework), certificates are assigned by a trusted Certificate
- Authority and provide a strong binding between a party's identity
- or some other attributes and its public key.
-
- client
- The application entity that initiates a TLS connection to a
- server. This may or may not imply that the client initiated the
- underlying transport connection. The primary operational
- difference between the server and client is that the server is
- generally authenticated, while the client is only optionally
- authenticated.
-
- client write key
- The key used to encrypt data written by the client.
-
-
-
-
-
-Dierks & Allen Standards Track [Page 57]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- client write MAC secret
- The secret data used to authenticate data written by the client.
-
- connection
- A connection is a transport (in the OSI layering model
- definition) that provides a suitable type of service. For TLS,
- such connections are peer to peer relationships. The connections
- are transient. Every connection is associated with one session.
-
- Data Encryption Standard
- DES is a very widely used symmetric encryption algorithm. DES is
- a block cipher with a 56 bit key and an 8 byte block size. Note
- that in TLS, for key generation purposes, DES is treated as
- having an 8 byte key length (64 bits), but it still only provides
- 56 bits of protection. (The low bit of each key byte is presumed
- to be set to produce odd parity in that key byte.) DES can also
- be operated in a mode where three independent keys and three
- encryptions are used for each block of data; this uses 168 bits
- of key (24 bytes in the TLS key generation method) and provides
- the equivalent of 112 bits of security. [DES], [3DES]
-
- Digital Signature Standard (DSS)
- A standard for digital signing, including the Digital Signing
- Algorithm, approved by the National Institute of Standards and
- Technology, defined in NIST FIPS PUB 186, "Digital Signature
- Standard," published May, 1994 by the U.S. Dept. of Commerce.
- [DSS]
-
- digital signatures
- Digital signatures utilize public key cryptography and one-way
- hash functions to produce a signature of the data that can be
- authenticated, and is difficult to forge or repudiate.
-
- handshake
- An initial negotiation between client and server that establishes
- the parameters of their transactions.
-
- Initialization Vector (IV)
- When a block cipher is used in CBC mode, the initialization
- vector is exclusive-ORed with the first plaintext block prior to
- encryption.
-
- IDEA
- A 64-bit block cipher designed by Xuejia Lai and James Massey.
- [IDEA]
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 58]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- Message Authentication Code (MAC)
- A Message Authentication Code is a one-way hash computed from a
- message and some secret data. It is difficult to forge without
- knowing the secret data. Its purpose is to detect if the message
- has been altered.
-
- master secret
- Secure secret data used for generating encryption keys, MAC
- secrets, and IVs.
-
- MD5
- MD5 is a secure hashing function that converts an arbitrarily
- long data stream into a digest of fixed size (16 bytes). [MD5]
-
- public key cryptography
- A class of cryptographic techniques employing two-key ciphers.
- Messages encrypted with the public key can only be decrypted with
- the associated private key. Conversely, messages signed with the
- private key can be verified with the public key.
-
- one-way hash function
- A one-way transformation that converts an arbitrary amount of
- data into a fixed-length hash. It is computationally hard to
- reverse the transformation or to find collisions. MD5 and SHA are
- examples of one-way hash functions.
-
- RC2
- A block cipher developed by Ron Rivest at RSA Data Security, Inc.
- [RSADSI] described in [RC2].
-
- RC4
- A stream cipher licensed by RSA Data Security [RSADSI]. A
- compatible cipher is described in [RC4].
-
- RSA
- A very widely used public-key algorithm that can be used for
- either encryption or digital signing. [RSA]
-
- salt
- Non-secret random data used to make export encryption keys resist
- precomputation attacks.
-
- server
- The server is the application entity that responds to requests
- for connections from clients. See also under client.
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 59]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- session
- A TLS session is an association between a client and a server.
- Sessions are created by the handshake protocol. Sessions define a
- set of cryptographic security parameters, which can be shared
- among multiple connections. Sessions are used to avoid the
- expensive negotiation of new security parameters for each
- connection.
-
- session identifier
- A session identifier is a value generated by a server that
- identifies a particular session.
-
- server write key
- The key used to encrypt data written by the server.
-
- server write MAC secret
- The secret data used to authenticate data written by the server.
-
- SHA
- The Secure Hash Algorithm is defined in FIPS PUB 180-1. It
- produces a 20-byte output. Note that all references to SHA
- actually use the modified SHA-1 algorithm. [SHA]
-
- SSL
- Netscape's Secure Socket Layer protocol [SSL3]. TLS is based on
- SSL Version 3.0
-
- stream cipher
- An encryption algorithm that converts a key into a
- cryptographically-strong keystream, which is then exclusive-ORed
- with the plaintext.
-
- symmetric cipher
- See bulk cipher.
-
- Transport Layer Security (TLS)
- This protocol; also, the Transport Layer Security working group
- of the Internet Engineering Task Force (IETF). See "Comments" at
- the end of this document.
-
-
-
-
-
-
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 60]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-C. CipherSuite definitions
-
-CipherSuite Is Key Cipher Hash
- Exportable Exchange
-
-TLS_NULL_WITH_NULL_NULL * NULL NULL NULL
-TLS_RSA_WITH_NULL_MD5 * RSA NULL MD5
-TLS_RSA_WITH_NULL_SHA * RSA NULL SHA
-TLS_RSA_EXPORT_WITH_RC4_40_MD5 * RSA_EXPORT RC4_40 MD5
-TLS_RSA_WITH_RC4_128_MD5 RSA RC4_128 MD5
-TLS_RSA_WITH_RC4_128_SHA RSA RC4_128 SHA
-TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 * RSA_EXPORT RC2_CBC_40 MD5
-TLS_RSA_WITH_IDEA_CBC_SHA RSA IDEA_CBC SHA
-TLS_RSA_EXPORT_WITH_DES40_CBC_SHA * RSA_EXPORT DES40_CBC SHA
-TLS_RSA_WITH_DES_CBC_SHA RSA DES_CBC SHA
-TLS_RSA_WITH_3DES_EDE_CBC_SHA RSA 3DES_EDE_CBC SHA
-TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA * DH_DSS_EXPORT DES40_CBC SHA
-TLS_DH_DSS_WITH_DES_CBC_SHA DH_DSS DES_CBC SHA
-TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA DH_DSS 3DES_EDE_CBC SHA
-TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA * DH_RSA_EXPORT DES40_CBC SHA
-TLS_DH_RSA_WITH_DES_CBC_SHA DH_RSA DES_CBC SHA
-TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA DH_RSA 3DES_EDE_CBC SHA
-TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA * DHE_DSS_EXPORT DES40_CBC SHA
-TLS_DHE_DSS_WITH_DES_CBC_SHA DHE_DSS DES_CBC SHA
-TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE_DSS 3DES_EDE_CBC SHA
-TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA * DHE_RSA_EXPORT DES40_CBC SHA
-TLS_DHE_RSA_WITH_DES_CBC_SHA DHE_RSA DES_CBC SHA
-TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE_RSA 3DES_EDE_CBC SHA
-TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 * DH_anon_EXPORT RC4_40 MD5
-TLS_DH_anon_WITH_RC4_128_MD5 DH_anon RC4_128 MD5
-TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA DH_anon DES40_CBC SHA
-TLS_DH_anon_WITH_DES_CBC_SHA DH_anon DES_CBC SHA
-TLS_DH_anon_WITH_3DES_EDE_CBC_SHA DH_anon 3DES_EDE_CBC SHA
-
-
- * Indicates IsExportable is True
-
- Key
- Exchange
- Algorithm Description Key size limit
-
- DHE_DSS Ephemeral DH with DSS signatures None
- DHE_DSS_EXPORT Ephemeral DH with DSS signatures DH = 512 bits
- DHE_RSA Ephemeral DH with RSA signatures None
- DHE_RSA_EXPORT Ephemeral DH with RSA signatures DH = 512 bits,
- RSA = none
- DH_anon Anonymous DH, no signatures None
- DH_anon_EXPORT Anonymous DH, no signatures DH = 512 bits
-
-
-
-Dierks & Allen Standards Track [Page 61]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- DH_DSS DH with DSS-based certificates None
- DH_DSS_EXPORT DH with DSS-based certificates DH = 512 bits
- DH_RSA DH with RSA-based certificates None
- DH_RSA_EXPORT DH with RSA-based certificates DH = 512 bits,
- RSA = none
- NULL No key exchange N/A
- RSA RSA key exchange None
- RSA_EXPORT RSA key exchange RSA = 512 bits
-
- Key size limit
- The key size limit gives the size of the largest public key that
- can be legally used for encryption in cipher suites that are
- exportable.
-
- Key Expanded Effective IV Block
- Cipher Type Material Key Material Key Bits Size Size
-
- NULL * Stream 0 0 0 0 N/A
- IDEA_CBC Block 16 16 128 8 8
- RC2_CBC_40 * Block 5 16 40 8 8
- RC4_40 * Stream 5 16 40 0 N/A
- RC4_128 Stream 16 16 128 0 N/A
- DES40_CBC * Block 5 8 40 8 8
- DES_CBC Block 8 8 56 8 8
- 3DES_EDE_CBC Block 24 24 168 8 8
-
- * Indicates IsExportable is true.
-
- Type
- Indicates whether this is a stream cipher or a block cipher
- running in CBC mode.
-
- Key Material
- The number of bytes from the key_block that are used for
- generating the write keys.
-
- Expanded Key Material
- The number of bytes actually fed into the encryption algorithm
-
- Effective Key Bits
- How much entropy material is in the key material being fed into
- the encryption routines.
-
- IV Size
- How much data needs to be generated for the initialization
- vector. Zero for stream ciphers; equal to the block size for
- block ciphers.
-
-
-
-
-Dierks & Allen Standards Track [Page 62]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- Block Size
- The amount of data a block cipher enciphers in one chunk; a
- block cipher running in CBC mode can only encrypt an even
- multiple of its block size.
-
- Hash Hash Padding
- function Size Size
- NULL 0 0
- MD5 16 48
- SHA 20 40
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 63]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-D. Implementation Notes
-
- The TLS protocol cannot prevent many common security mistakes. This
- section provides several recommendations to assist implementors.
-
-D.1. Temporary RSA keys
-
- US Export restrictions limit RSA keys used for encryption to 512
- bits, but do not place any limit on lengths of RSA keys used for
- signing operations. Certificates often need to be larger than 512
- bits, since 512-bit RSA keys are not secure enough for high-value
- transactions or for applications requiring long-term security. Some
- certificates are also designated signing-only, in which case they
- cannot be used for key exchange.
-
- When the public key in the certificate cannot be used for encryption,
- the server signs a temporary RSA key, which is then exchanged. In
- exportable applications, the temporary RSA key should be the maximum
- allowable length (i.e., 512 bits). Because 512-bit RSA keys are
- relatively insecure, they should be changed often. For typical
- electronic commerce applications, it is suggested that keys be
- changed daily or every 500 transactions, and more often if possible.
- Note that while it is acceptable to use the same temporary key for
- multiple transactions, it must be signed each time it is used.
-
- RSA key generation is a time-consuming process. In many cases, a
- low-priority process can be assigned the task of key generation.
-
- Whenever a new key is completed, the existing temporary key can be
- replaced with the new one.
-
-D.2. Random Number Generation and Seeding
-
- TLS requires a cryptographically-secure pseudorandom number generator
- (PRNG). Care must be taken in designing and seeding PRNGs. PRNGs
- based on secure hash operations, most notably MD5 and/or SHA, are
- acceptable, but cannot provide more security than the size of the
- random number generator state. (For example, MD5-based PRNGs usually
- provide 128 bits of state.)
-
- To estimate the amount of seed material being produced, add the
- number of bits of unpredictable information in each seed byte. For
- example, keystroke timing values taken from a PC compatible's 18.2 Hz
- timer provide 1 or 2 secure bits each, even though the total size of
- the counter value is 16 bits or more. To seed a 128-bit PRNG, one
- would thus require approximately 100 such timer values.
-
-
-
-
-
-Dierks & Allen Standards Track [Page 64]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- Warning: The seeding functions in RSAREF and versions of BSAFE prior to
- 3.0 are order-independent. For example, if 1000 seed bits are
- supplied, one at a time, in 1000 separate calls to the seed
- function, the PRNG will end up in a state which depends only
- on the number of 0 or 1 seed bits in the seed data (i.e.,
- there are 1001 possible final states). Applications using
- BSAFE or RSAREF must take extra care to ensure proper seeding.
- This may be accomplished by accumulating seed bits into a
- buffer and processing them all at once or by processing an
- incrementing counter with every seed bit; either method will
- reintroduce order dependence into the seeding process.
-
-D.3. Certificates and authentication
-
- Implementations are responsible for verifying the integrity of
- certificates and should generally support certificate revocation
- messages. Certificates should always be verified to ensure proper
- signing by a trusted Certificate Authority (CA). The selection and
- addition of trusted CAs should be done very carefully. Users should
- be able to view information about the certificate and root CA.
-
-D.4. CipherSuites
-
- TLS supports a range of key sizes and security levels, including some
- which provide no or minimal security. A proper implementation will
- probably not support many cipher suites. For example, 40-bit
- encryption is easily broken, so implementations requiring strong
- security should not allow 40-bit keys. Similarly, anonymous Diffie-
- Hellman is strongly discouraged because it cannot prevent man-in-
- the-middle attacks. Applications should also enforce minimum and
- maximum key sizes. For example, certificate chains containing 512-bit
- RSA keys or signatures are not appropriate for high-security
- applications.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 65]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-E. Backward Compatibility With SSL
-
- For historical reasons and in order to avoid a profligate consumption
- of reserved port numbers, application protocols which are secured by
- TLS 1.0, SSL 3.0, and SSL 2.0 all frequently share the same
- connection port: for example, the https protocol (HTTP secured by SSL
- or TLS) uses port 443 regardless of which security protocol it is
- using. Thus, some mechanism must be determined to distinguish and
- negotiate among the various protocols.
-
- TLS version 1.0 and SSL 3.0 are very similar; thus, supporting both
- is easy. TLS clients who wish to negotiate with SSL 3.0 servers
- should send client hello messages using the SSL 3.0 record format and
- client hello structure, sending {3, 1} for the version field to note
- that they support TLS 1.0. If the server supports only SSL 3.0, it
- will respond with an SSL 3.0 server hello; if it supports TLS, with a
- TLS server hello. The negotiation then proceeds as appropriate for
- the negotiated protocol.
-
- Similarly, a TLS server which wishes to interoperate with SSL 3.0
- clients should accept SSL 3.0 client hello messages and respond with
- an SSL 3.0 server hello if an SSL 3.0 client hello is received which
- has a version field of {3, 0}, denoting that this client does not
- support TLS.
-
- Whenever a client already knows the highest protocol known to a
- server (for example, when resuming a session), it should initiate the
- connection in that native protocol.
-
- TLS 1.0 clients that support SSL Version 2.0 servers must send SSL
- Version 2.0 client hello messages [SSL2]. TLS servers should accept
- either client hello format if they wish to support SSL 2.0 clients on
- the same connection port. The only deviations from the Version 2.0
- specification are the ability to specify a version with a value of
- three and the support for more ciphering types in the CipherSpec.
-
- Warning: The ability to send Version 2.0 client hello messages will be
- phased out with all due haste. Implementors should make every
- effort to move forward as quickly as possible. Version 3.0
- provides better mechanisms for moving to newer versions.
-
- The following cipher specifications are carryovers from SSL Version
- 2.0. These are assumed to use RSA for key exchange and
- authentication.
-
- V2CipherSpec TLS_RC4_128_WITH_MD5 = { 0x01,0x00,0x80 };
- V2CipherSpec TLS_RC4_128_EXPORT40_WITH_MD5 = { 0x02,0x00,0x80 };
- V2CipherSpec TLS_RC2_CBC_128_CBC_WITH_MD5 = { 0x03,0x00,0x80 };
-
-
-
-Dierks & Allen Standards Track [Page 66]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- V2CipherSpec TLS_RC2_CBC_128_CBC_EXPORT40_WITH_MD5
- = { 0x04,0x00,0x80 };
- V2CipherSpec TLS_IDEA_128_CBC_WITH_MD5 = { 0x05,0x00,0x80 };
- V2CipherSpec TLS_DES_64_CBC_WITH_MD5 = { 0x06,0x00,0x40 };
- V2CipherSpec TLS_DES_192_EDE3_CBC_WITH_MD5 = { 0x07,0x00,0xC0 };
-
- Cipher specifications native to TLS can be included in Version 2.0
- client hello messages using the syntax below. Any V2CipherSpec
- element with its first byte equal to zero will be ignored by Version
- 2.0 servers. Clients sending any of the above V2CipherSpecs should
- also include the TLS equivalent (see Appendix A.5):
-
- V2CipherSpec (see TLS name) = { 0x00, CipherSuite };
-
-E.1. Version 2 client hello
-
- The Version 2.0 client hello message is presented below using this
- document's presentation model. The true definition is still assumed
- to be the SSL Version 2.0 specification.
-
- uint8 V2CipherSpec[3];
-
- struct {
- uint8 msg_type;
- Version version;
- uint16 cipher_spec_length;
- uint16 session_id_length;
- uint16 challenge_length;
- V2CipherSpec cipher_specs[V2ClientHello.cipher_spec_length];
- opaque session_id[V2ClientHello.session_id_length];
- Random challenge;
- } V2ClientHello;
-
- msg_type
- This field, in conjunction with the version field, identifies a
- version 2 client hello message. The value should be one (1).
-
- version
- The highest version of the protocol supported by the client
- (equals ProtocolVersion.version, see Appendix A.1).
-
- cipher_spec_length
- This field is the total length of the field cipher_specs. It
- cannot be zero and must be a multiple of the V2CipherSpec length
- (3).
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 67]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- session_id_length
- This field must have a value of either zero or 16. If zero, the
- client is creating a new session. If 16, the session_id field
- will contain the 16 bytes of session identification.
-
- challenge_length
- The length in bytes of the client's challenge to the server to
- authenticate itself. This value must be 32.
-
- cipher_specs
- This is a list of all CipherSpecs the client is willing and able
- to use. There must be at least one CipherSpec acceptable to the
- server.
-
- session_id
- If this field's length is not zero, it will contain the
- identification for a session that the client wishes to resume.
-
- challenge
- The client challenge to the server for the server to identify
- itself is a (nearly) arbitrary length random. The TLS server will
- right justify the challenge data to become the ClientHello.random
- data (padded with leading zeroes, if necessary), as specified in
- this protocol specification. If the length of the challenge is
- greater than 32 bytes, only the last 32 bytes are used. It is
- legitimate (but not necessary) for a V3 server to reject a V2
- ClientHello that has fewer than 16 bytes of challenge data.
-
- Note: Requests to resume a TLS session should use a TLS client hello.
-
-E.2. Avoiding man-in-the-middle version rollback
-
- When TLS clients fall back to Version 2.0 compatibility mode, they
- should use special PKCS #1 block formatting. This is done so that TLS
- servers will reject Version 2.0 sessions with TLS-capable clients.
-
- When TLS clients are in Version 2.0 compatibility mode, they set the
- right-hand (least-significant) 8 random bytes of the PKCS padding
- (not including the terminal null of the padding) for the RSA
- encryption of the ENCRYPTED-KEY-DATA field of the CLIENT-MASTER-KEY
- to 0x03 (the other padding bytes are random). After decrypting the
- ENCRYPTED-KEY-DATA field, servers that support TLS should issue an
- error if these eight padding bytes are 0x03. Version 2.0 servers
- receiving blocks padded in this manner will proceed normally.
-
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 68]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-F. Security analysis
-
- The TLS protocol is designed to establish a secure connection between
- a client and a server communicating over an insecure channel. This
- document makes several traditional assumptions, including that
- attackers have substantial computational resources and cannot obtain
- secret information from sources outside the protocol. Attackers are
- assumed to have the ability to capture, modify, delete, replay, and
- otherwise tamper with messages sent over the communication channel.
- This appendix outlines how TLS has been designed to resist a variety
- of attacks.
-
-F.1. Handshake protocol
-
- The handshake protocol is responsible for selecting a CipherSpec and
- generating a Master Secret, which together comprise the primary
- cryptographic parameters associated with a secure session. The
- handshake protocol can also optionally authenticate parties who have
- certificates signed by a trusted certificate authority.
-
-F.1.1. Authentication and key exchange
-
- TLS supports three authentication modes: authentication of both
- parties, server authentication with an unauthenticated client, and
- total anonymity. Whenever the server is authenticated, the channel is
- secure against man-in-the-middle attacks, but completely anonymous
- sessions are inherently vulnerable to such attacks. Anonymous
- servers cannot authenticate clients. If the server is authenticated,
- its certificate message must provide a valid certificate chain
- leading to an acceptable certificate authority. Similarly,
- authenticated clients must supply an acceptable certificate to the
- server. Each party is responsible for verifying that the other's
- certificate is valid and has not expired or been revoked.
-
- The general goal of the key exchange process is to create a
- pre_master_secret known to the communicating parties and not to
- attackers. The pre_master_secret will be used to generate the
- master_secret (see Section 8.1). The master_secret is required to
- generate the certificate verify and finished messages, encryption
- keys, and MAC secrets (see Sections 7.4.8, 7.4.9 and 6.3). By sending
- a correct finished message, parties thus prove that they know the
- correct pre_master_secret.
-
-F.1.1.1. Anonymous key exchange
-
- Completely anonymous sessions can be established using RSA or
- Diffie-Hellman for key exchange. With anonymous RSA, the client
- encrypts a pre_master_secret with the server's uncertified public key
-
-
-
-Dierks & Allen Standards Track [Page 69]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- extracted from the server key exchange message. The result is sent in
- a client key exchange message. Since eavesdroppers do not know the
- server's private key, it will be infeasible for them to decode the
- pre_master_secret. (Note that no anonymous RSA Cipher Suites are
- defined in this document).
-
- With Diffie-Hellman, the server's public parameters are contained in
- the server key exchange message and the client's are sent in the
- client key exchange message. Eavesdroppers who do not know the
- private values should not be able to find the Diffie-Hellman result
- (i.e. the pre_master_secret).
-
- Warning: Completely anonymous connections only provide protection
- against passive eavesdropping. Unless an independent tamper-
- proof channel is used to verify that the finished messages
- were not replaced by an attacker, server authentication is
- required in environments where active man-in-the-middle
- attacks are a concern.
-
-F.1.1.2. RSA key exchange and authentication
-
- With RSA, key exchange and server authentication are combined. The
- public key may be either contained in the server's certificate or may
- be a temporary RSA key sent in a server key exchange message. When
- temporary RSA keys are used, they are signed by the server's RSA or
- DSS certificate. The signature includes the current
- ClientHello.random, so old signatures and temporary keys cannot be
- replayed. Servers may use a single temporary RSA key for multiple
- negotiation sessions.
-
- Note: The temporary RSA key option is useful if servers need large
- certificates but must comply with government-imposed size limits
- on keys used for key exchange.
-
- After verifying the server's certificate, the client encrypts a
- pre_master_secret with the server's public key. By successfully
- decoding the pre_master_secret and producing a correct finished
- message, the server demonstrates that it knows the private key
- corresponding to the server certificate.
-
- When RSA is used for key exchange, clients are authenticated using
- the certificate verify message (see Section 7.4.8). The client signs
- a value derived from the master_secret and all preceding handshake
- messages. These handshake messages include the server certificate,
- which binds the signature to the server, and ServerHello.random,
- which binds the signature to the current handshake process.
-
-
-
-
-
-Dierks & Allen Standards Track [Page 70]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-F.1.1.3. Diffie-Hellman key exchange with authentication
-
- When Diffie-Hellman key exchange is used, the server can either
- supply a certificate containing fixed Diffie-Hellman parameters or
- can use the server key exchange message to send a set of temporary
- Diffie-Hellman parameters signed with a DSS or RSA certificate.
- Temporary parameters are hashed with the hello.random values before
- signing to ensure that attackers do not replay old parameters. In
- either case, the client can verify the certificate or signature to
- ensure that the parameters belong to the server.
-
- If the client has a certificate containing fixed Diffie-Hellman
- parameters, its certificate contains the information required to
- complete the key exchange. Note that in this case the client and
- server will generate the same Diffie-Hellman result (i.e.,
- pre_master_secret) every time they communicate. To prevent the
- pre_master_secret from staying in memory any longer than necessary,
- it should be converted into the master_secret as soon as possible.
- Client Diffie-Hellman parameters must be compatible with those
- supplied by the server for the key exchange to work.
-
- If the client has a standard DSS or RSA certificate or is
- unauthenticated, it sends a set of temporary parameters to the server
- in the client key exchange message, then optionally uses a
- certificate verify message to authenticate itself.
-
-F.1.2. Version rollback attacks
-
- Because TLS includes substantial improvements over SSL Version 2.0,
- attackers may try to make TLS-capable clients and servers fall back
- to Version 2.0. This attack can occur if (and only if) two TLS-
- capable parties use an SSL 2.0 handshake.
-
- Although the solution using non-random PKCS #1 block type 2 message
- padding is inelegant, it provides a reasonably secure way for Version
- 3.0 servers to detect the attack. This solution is not secure against
- attackers who can brute force the key and substitute a new
- ENCRYPTED-KEY-DATA message containing the same key (but with normal
- padding) before the application specified wait threshold has expired.
- Parties concerned about attacks of this scale should not be using
- 40-bit encryption keys anyway. Altering the padding of the least-
- significant 8 bytes of the PKCS padding does not impact security for
- the size of the signed hashes and RSA key lengths used in the
- protocol, since this is essentially equivalent to increasing the
- input block size by 8 bytes.
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 71]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-F.1.3. Detecting attacks against the handshake protocol
-
- An attacker might try to influence the handshake exchange to make the
- parties select different encryption algorithms than they would
- normally choose. Because many implementations will support 40-bit
- exportable encryption and some may even support null encryption or
- MAC algorithms, this attack is of particular concern.
-
- For this attack, an attacker must actively change one or more
- handshake messages. If this occurs, the client and server will
- compute different values for the handshake message hashes. As a
- result, the parties will not accept each others' finished messages.
- Without the master_secret, the attacker cannot repair the finished
- messages, so the attack will be discovered.
-
-F.1.4. Resuming sessions
-
- When a connection is established by resuming a session, new
- ClientHello.random and ServerHello.random values are hashed with the
- session's master_secret. Provided that the master_secret has not been
- compromised and that the secure hash operations used to produce the
- encryption keys and MAC secrets are secure, the connection should be
- secure and effectively independent from previous connections.
- Attackers cannot use known encryption keys or MAC secrets to
- compromise the master_secret without breaking the secure hash
- operations (which use both SHA and MD5).
-
- Sessions cannot be resumed unless both the client and server agree.
- If either party suspects that the session may have been compromised,
- or that certificates may have expired or been revoked, it should
- force a full handshake. An upper limit of 24 hours is suggested for
- session ID lifetimes, since an attacker who obtains a master_secret
- may be able to impersonate the compromised party until the
- corresponding session ID is retired. Applications that may be run in
- relatively insecure environments should not write session IDs to
- stable storage.
-
-F.1.5. MD5 and SHA
-
- TLS uses hash functions very conservatively. Where possible, both MD5
- and SHA are used in tandem to ensure that non-catastrophic flaws in
- one algorithm will not break the overall protocol.
-
-F.2. Protecting application data
-
- The master_secret is hashed with the ClientHello.random and
- ServerHello.random to produce unique data encryption keys and MAC
- secrets for each connection.
-
-
-
-Dierks & Allen Standards Track [Page 72]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- Outgoing data is protected with a MAC before transmission. To prevent
- message replay or modification attacks, the MAC is computed from the
- MAC secret, the sequence number, the message length, the message
- contents, and two fixed character strings. The message type field is
- necessary to ensure that messages intended for one TLS Record Layer
- client are not redirected to another. The sequence number ensures
- that attempts to delete or reorder messages will be detected. Since
- sequence numbers are 64-bits long, they should never overflow.
- Messages from one party cannot be inserted into the other's output,
- since they use independent MAC secrets. Similarly, the server-write
- and client-write keys are independent so stream cipher keys are used
- only once.
-
- If an attacker does break an encryption key, all messages encrypted
- with it can be read. Similarly, compromise of a MAC key can make
- message modification attacks possible. Because MACs are also
- encrypted, message-alteration attacks generally require breaking the
- encryption algorithm as well as the MAC.
-
- Note: MAC secrets may be larger than encryption keys, so messages can
- remain tamper resistant even if encryption keys are broken.
-
-F.3. Final notes
-
- For TLS to be able to provide a secure connection, both the client
- and server systems, keys, and applications must be secure. In
- addition, the implementation must be free of security errors.
-
- The system is only as strong as the weakest key exchange and
- authentication algorithm supported, and only trustworthy
- cryptographic functions should be used. Short public keys, 40-bit
- bulk encryption keys, and anonymous servers should be used with great
- caution. Implementations and users must be careful when deciding
- which certificates and certificate authorities are acceptable; a
- dishonest certificate authority can do tremendous damage.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 73]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-G. Patent Statement
-
- Some of the cryptographic algorithms proposed for use in this
- protocol have patent claims on them. In addition Netscape
- Communications Corporation has a patent claim on the Secure Sockets
- Layer (SSL) work that this standard is based on. The Internet
- Standards Process as defined in RFC 2026 requests that a statement be
- obtained from a Patent holder indicating that a license will be made
- available to applicants under reasonable terms and conditions.
-
- The Massachusetts Institute of Technology has granted RSA Data
- Security, Inc., exclusive sub-licensing rights to the following
- patent issued in the United States:
-
- Cryptographic Communications System and Method ("RSA"), No.
- 4,405,829
-
- Netscape Communications Corporation has been issued the following
- patent in the United States:
-
- Secure Socket Layer Application Program Apparatus And Method
- ("SSL"), No. 5,657,390
-
- Netscape Communications has issued the following statement:
-
- Intellectual Property Rights
-
- Secure Sockets Layer
-
- The United States Patent and Trademark Office ("the PTO")
- recently issued U.S. Patent No. 5,657,390 ("the SSL Patent") to
- Netscape for inventions described as Secure Sockets Layers
- ("SSL"). The IETF is currently considering adopting SSL as a
- transport protocol with security features. Netscape encourages
- the royalty-free adoption and use of the SSL protocol upon the
- following terms and conditions:
-
- * If you already have a valid SSL Ref license today which
- includes source code from Netscape, an additional patent
- license under the SSL patent is not required.
-
- * If you don't have an SSL Ref license, you may have a royalty
- free license to build implementations covered by the SSL
- Patent Claims or the IETF TLS specification provided that you
- do not to assert any patent rights against Netscape or other
- companies for the implementation of SSL or the IETF TLS
- recommendation.
-
-
-
-
-Dierks & Allen Standards Track [Page 74]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- What are "Patent Claims":
-
- Patent claims are claims in an issued foreign or domestic patent
- that:
-
- 1) must be infringed in order to implement methods or build
- products according to the IETF TLS specification; or
-
- 2) patent claims which require the elements of the SSL patent
- claims and/or their equivalents to be infringed.
-
- The Internet Society, Internet Architecture Board, Internet
- Engineering Steering Group and the Corporation for National Research
- Initiatives take no position on the validity or scope of the patents
- and patent applications, nor on the appropriateness of the terms of
- the assurance. The Internet Society and other groups mentioned above
- have not made any determination as to any other intellectual property
- rights which may apply to the practice of this standard. Any further
- consideration of these matters is the user's own responsibility.
-
-Security Considerations
-
- Security issues are discussed throughout this memo.
-
-References
-
- [3DES] W. Tuchman, "Hellman Presents No Shortcut Solutions To DES,"
- IEEE Spectrum, v. 16, n. 7, July 1979, pp40-41.
-
- [BLEI] Bleichenbacher D., "Chosen Ciphertext Attacks against
- Protocols Based on RSA Encryption Standard PKCS #1" in
- Advances in Cryptology -- CRYPTO'98, LNCS vol. 1462, pages:
- 1--12, 1998.
-
- [DES] ANSI X3.106, "American National Standard for Information
- Systems-Data Link Encryption," American National Standards
- Institute, 1983.
-
- [DH1] W. Diffie and M. E. Hellman, "New Directions in
- Cryptography," IEEE Transactions on Information Theory, V.
- IT-22, n. 6, Jun 1977, pp. 74-84.
-
- [DSS] NIST FIPS PUB 186, "Digital Signature Standard," National
- Institute of Standards and Technology, U.S. Department of
- Commerce, May 18, 1994.
-
- [FTP] Postel J., and J. Reynolds, "File Transfer Protocol", STD 9,
- RFC 959, October 1985.
-
-
-
-Dierks & Allen Standards Track [Page 75]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- [HTTP] Berners-Lee, T., Fielding, R., and H. Frystyk, "Hypertext
- Transfer Protocol -- HTTP/1.0", RFC 1945, May 1996.
-
- [HMAC] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
- Hashing for Message Authentication," RFC 2104, February
- 1997.
-
- [IDEA] X. Lai, "On the Design and Security of Block Ciphers," ETH
- Series in Information Processing, v. 1, Konstanz: Hartung-
- Gorre Verlag, 1992.
-
- [MD2] Kaliski, B., "The MD2 Message Digest Algorithm", RFC 1319,
- April 1992.
-
- [MD5] Rivest, R., "The MD5 Message Digest Algorithm", RFC 1321,
- April 1992.
-
- [PKCS1] RSA Laboratories, "PKCS #1: RSA Encryption Standard,"
- version 1.5, November 1993.
-
- [PKCS6] RSA Laboratories, "PKCS #6: RSA Extended Certificate Syntax
- Standard," version 1.5, November 1993.
-
- [PKCS7] RSA Laboratories, "PKCS #7: RSA Cryptographic Message Syntax
- Standard," version 1.5, November 1993.
-
- [PKIX] Housley, R., Ford, W., Polk, W. and D. Solo, "Internet
- Public Key Infrastructure: Part I: X.509 Certificate and CRL
- Profile", RFC 2459, January 1999.
-
- [RC2] Rivest, R., "A Description of the RC2(r) Encryption
- Algorithm", RFC 2268, January 1998.
-
- [RC4] Thayer, R. and K. Kaukonen, A Stream Cipher Encryption
- Algorithm, Work in Progress.
-
- [RSA] R. Rivest, A. Shamir, and L. M. Adleman, "A Method for
- Obtaining Digital Signatures and Public-Key Cryptosystems,"
- Communications of the ACM, v. 21, n. 2, Feb 1978, pp. 120-
- 126.
-
- [RSADSI] Contact RSA Data Security, Inc., Tel: 415-595-8782
-
- [SCH] B. Schneier. Applied Cryptography: Protocols, Algorithms,
- and Source Code in C, Published by John Wiley & Sons, Inc.
- 1994.
-
-
-
-
-
-Dierks & Allen Standards Track [Page 76]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- [SHA] NIST FIPS PUB 180-1, "Secure Hash Standard," National
- Institute of Standards and Technology, U.S. Department of
- Commerce, Work in Progress, May 31, 1994.
-
- [SSL2] Hickman, Kipp, "The SSL Protocol", Netscape Communications
- Corp., Feb 9, 1995.
-
- [SSL3] A. Frier, P. Karlton, and P. Kocher, "The SSL 3.0 Protocol",
- Netscape Communications Corp., Nov 18, 1996.
-
- [TCP] Postel, J., "Transmission Control Protocol," STD 7, RFC 793,
- September 1981.
-
- [TEL] Postel J., and J. Reynolds, "Telnet Protocol
- Specifications", STD 8, RFC 854, May 1993.
-
- [TEL] Postel J., and J. Reynolds, "Telnet Option Specifications",
- STD 8, RFC 855, May 1993.
-
- [X509] CCITT. Recommendation X.509: "The Directory - Authentication
- Framework". 1988.
-
- [XDR] R. Srinivansan, Sun Microsystems, RFC-1832: XDR: External
- Data Representation Standard, August 1995.
-
-Credits
-
- Win Treese
- Open Market
-
- EMail: treese@openmarket.com
-
-
- Editors
-
- Christopher Allen Tim Dierks
- Certicom Certicom
-
- EMail: callen@certicom.com EMail: tdierks@certicom.com
-
-
- Authors' Addresses
-
- Tim Dierks Philip L. Karlton
- Certicom Netscape Communications
-
- EMail: tdierks@certicom.com
-
-
-
-
-Dierks & Allen Standards Track [Page 77]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- Alan O. Freier Paul C. Kocher
- Netscape Communications Independent Consultant
-
- EMail: freier@netscape.com EMail: pck@netcom.com
-
-
- Other contributors
-
- Martin Abadi Robert Relyea
- Digital Equipment Corporation Netscape Communications
-
- EMail: ma@pa.dec.com EMail: relyea@netscape.com
-
- Ran Canetti Jim Roskind
- IBM Watson Research Center Netscape Communications
-
- EMail: canetti@watson.ibm.com EMail: jar@netscape.com
-
-
- Taher Elgamal Micheal J. Sabin, Ph. D.
- Securify Consulting Engineer
-
- EMail: elgamal@securify.com EMail: msabin@netcom.com
-
-
- Anil R. Gangolli Dan Simon
- Structured Arts Computing Corp. Microsoft
-
- EMail: gangolli@structuredarts.com EMail: dansimon@microsoft.com
-
-
- Kipp E.B. Hickman Tom Weinstein
- Netscape Communications Netscape Communications
-
- EMail: kipp@netscape.com EMail: tomw@netscape.com
-
-
- Hugo Krawczyk
- IBM Watson Research Center
-
- EMail: hugo@watson.ibm.com
-
-Comments
-
- The discussion list for the IETF TLS working group is located at the
- e-mail address <ietf-tls@lists.consensus.com>. Information on the
- group and information on how to subscribe to the list is at
- <http://lists.consensus.com/>.
-
-
-
-Dierks & Allen Standards Track [Page 78]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
- Archives of the list can be found at:
- <http://www.imc.org/ietf-tls/mail-archive/>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 79]
-\f
-RFC 2246 The TLS Protocol Version 1.0 January 1999
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dierks & Allen Standards Track [Page 80]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group P. Hoffman
-Request for Comments: 2487 Internet Mail Consortium
-Category: Standards Track January 1999
-
-
- SMTP Service Extension for Secure SMTP over TLS
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-1. Abstract
-
- This document describes an extension to the SMTP service that allows
- an SMTP server and client to use transport-layer security to provide
- private, authenticated communication over the Internet. This gives
- SMTP agents the ability to protect some or all of their
- communications from eavesdroppers and attackers.
-
-2. Introduction
-
- SMTP [RFC-821] servers and clients normally communicate in the clear
- over the Internet. In many cases, this communication goes through one
- or more router that is not controlled or trusted by either entity.
- Such an untrusted router might allow a third party to monitor or
- alter the communications between the server and client.
-
- Further, there is often a desire for two SMTP agents to be able to
- authenticate each others' identities. For example, a secure SMTP
- server might only allow communications from other SMTP agents it
- knows, or it might act differently for messages received from an
- agent it knows than from one it doesn't know.
-
- TLS [TLS], more commonly known as SSL, is a popular mechanism for
- enhancing TCP communications with privacy and authentication. TLS is
- in wide use with the HTTP protocol, and is also being used for adding
- security to many other common protocols that run over TCP.
-
-
-
-
-
-
-Hoffman Standards Track [Page 1]
-\f
-RFC 2487 SMTP Service Extension January 1999
-
-
-2.1 Terminology
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in [RFC-2119].
-
-3. STARTTLS Extension
-
- The STARTTLS extension to SMTP is laid out as follows:
-
- (1) the name of the SMTP service defined here is STARTTLS;
-
- (2) the EHLO keyword value associated with the extension is STARTTLS;
-
- (3) the STARTTLS keyword has no parameters;
-
- (4) a new SMTP verb, "STARTTLS", is defined;
-
- (5) no additional parameters are added to any SMTP command.
-
-4. The STARTTLS Keyword
-
- The STARTTLS keyword is used to tell the SMTP client that the SMTP
- server allows use of TLS. It takes no parameters.
-
-5. The STARTTLS Command
-
- The format for the STARTTLS command is:
-
- STARTTLS
-
- with no parameters.
-
- After the client gives the STARTTLS command, the server responds with
- one of the following reply codes:
-
- 220 Ready to start TLS
- 501 Syntax error (no parameters allowed)
- 454 TLS not available due to temporary reason
-
- A publicly-referenced SMTP server MUST NOT require use of the
- STARTTLS extension in order to deliver mail locally. This rule
- prevents the STARTTLS extension from damaging the interoperability of
- the Internet's SMTP infrastructure. A publicly-referenced SMTP server
- is an SMTP server which runs on port 25 of an Internet host listed in
- the MX record (or A record if an MX record is not present) for the
- domain name on the right hand side of an Internet mail address.
-
-
-
-
-Hoffman Standards Track [Page 2]
-\f
-RFC 2487 SMTP Service Extension January 1999
-
-
- Any SMTP server may refuse to accept messages for relay based on
- authentication supplied during the TLS negotiation. An SMTP server
- that is not publicly referenced may refuse to accept any messages for
- relay or local delivery based on authentication supplied during the
- TLS negotiation.
-
- A SMTP server that is not publicly referenced may choose to require
- that the client perform a TLS negotiation before accepting any
- commands. In this case, the server SHOULD return the reply code:
-
- 530 Must issue a STARTTLS command first
-
- to every command other than NOOP, EHLO, STARTTLS, or QUIT. If the
- client and server are using the ENHANCEDSTATUSCODES ESMTP extension
- [RFC-2034], the status code to be returned SHOULD be 5.7.0.
-
- After receiving a 220 response to a STARTTLS command, the client
- SHOULD start the TLS negotiation before giving any other SMTP
- commands.
-
- If the SMTP client is using pipelining as defined in RFC 1854, the
- STARTTLS command must be the last command in a group.
-
-5.1 Processing After the STARTTLS Command
-
- After the TLS handshake has been completed, both parties MUST
- immediately decide whether or not to continue based on the
- authentication and privacy achieved. The SMTP client and server may
- decide to move ahead even if the TLS negotiation ended with no
- authentication and/or no privacy because most SMTP services are
- performed with no authentication and no privacy, but some SMTP
- clients or servers may want to continue only if a particular level of
- authentication and/or privacy was achieved.
-
- If the SMTP client decides that the level of authentication or
- privacy is not high enough for it to continue, it SHOULD issue an
- SMTP QUIT command immediately after the TLS negotiation is complete.
- If the SMTP server decides that the level of authentication or
- privacy is not high enough for it to continue, it SHOULD reply to
- every SMTP command from the client (other than a QUIT command) with
- the 554 reply code (with a possible text string such as "Command
- refused due to lack of security").
-
- The decision of whether or not to believe the authenticity of the
- other party in a TLS negotiation is a local matter. However, some
- general rules for the decisions are:
-
-
-
-
-
-Hoffman Standards Track [Page 3]
-\f
-RFC 2487 SMTP Service Extension January 1999
-
-
- - A SMTP client would probably only want to authenticate an SMTP
- server whose server certificate has a domain name that is the
- domain name that the client thought it was connecting to.
- - A publicly-referenced SMTP server would probably want to accept
- any certificate from an SMTP client, and would possibly want to
- put distinguishing information about the certificate in the
- Received header of messages that were relayed or submitted from
- the client.
-
-5.2 Result of the STARTTLS Command
-
- Upon completion of the TLS handshake, the SMTP protocol is reset to
- the initial state (the state in SMTP after a server issues a 220
- service ready greeting). The server MUST discard any knowledge
- obtained from the client, such as the argument to the EHLO command,
- which was not obtained from the TLS negotiation itself. The client
- MUST discard any knowledge obtained from the server, such as the list
- of SMTP service extensions, which was not obtained from the TLS
- negotiation itself. The client SHOULD send an EHLO command as the
- first command after a successful TLS negotiation.
-
- The list of SMTP service extensions returned in response to an EHLO
- command received after the TLS handshake MAY be different than the
- list returned before the TLS handshake. For example, an SMTP server
- might not want to advertise support for a particular SASL mechanism
- [SASL] unless a client has sent an appropriate client certificate
- during a TLS handshake.
-
- Both the client and the server MUST know if there is a TLS session
- active. A client MUST NOT attempt to start a TLS session if a TLS
- session is already active. A server MUST NOT return the TLS extension
- in response to an EHLO command received after a TLS handshake has
- completed.
-
-6. Usage Example
-
- The following dialog illustrates how a client and server can start a
- TLS session:
-
- S: <waits for connection on TCP port 25>
- C: <opens connection>
- S: 220 mail.imc.org SMTP service ready
- C: EHLO mail.ietf.org
- S: 250-mail.imc.org offers a warm hug of welcome
- S: 250 STARTTLS
- C: STARTTLS
- S: 220 Go ahead
- C: <starts TLS negotiation>
-
-
-
-Hoffman Standards Track [Page 4]
-\f
-RFC 2487 SMTP Service Extension January 1999
-
-
- C & S: <negotiate a TLS session>
- C & S: <check result of negotiation>
- C: <continues by sending an SMTP command>
- . . .
-
-7. Security Considerations
-
- It should be noted that SMTP is not an end-to-end mechanism. Thus, if
- an SMTP client/server pair decide to add TLS privacy, they are not
- securing the transport from the originating mail user agent to the
- recipient. Further, because delivery of a single piece of mail may
- go between more than two SMTP servers, adding TLS privacy to one pair
- of servers does not mean that the entire SMTP chain has been made
- private. Further, just because an SMTP server can authenticate an
- SMTP client, it does not mean that the mail from the SMTP client was
- authenticated by the SMTP client when the client received it.
-
- Both the STMP client and server must check the result of the TLS
- negotiation to see whether acceptable authentication or privacy was
- achieved. Ignoring this step completely invalidates using TLS for
- security. The decision about whether acceptable authentication or
- privacy was achieved is made locally, is implementation-dependant,
- and is beyond the scope of this document.
-
- The SMTP client and server should note carefully the result of the
- TLS negotiation. If the negotiation results in no privacy, or if it
- results in privacy using algorithms or key lengths that are deemed
- not strong enough, or if the authentication is not good enough for
- either party, the client may choose to end the SMTP session with an
- immediate QUIT command, or the server may choose to not accept any
- more SMTP commands.
-
- A server announcing in an EHLO response that it uses a particular TLS
- protocol should not pose any security issues, since any use of TLS
- will be at least as secure as no use of TLS.
-
- A man-in-the-middle attack can be launched by deleting the "250
- STARTTLS" response from the server. This would cause the client not
- to try to start a TLS session. An SMTP client can protect against
- this attack by recording the fact that a particular SMTP server
- offers TLS during one session and generating an alarm if it does not
- appear in the EHLO response for a later session. The lack of TLS
- during a session SHOULD NOT result in the bouncing of email, although
- it could result in delayed processing.
-
-
-
-
-
-
-
-Hoffman Standards Track [Page 5]
-\f
-RFC 2487 SMTP Service Extension January 1999
-
-
- Before the TLS handshake has begun, any protocol interactions are
- performed in the clear and may be modified by an active attacker. For
- this reason, clients and servers MUST discard any knowledge obtained
- prior to the start of the TLS handshake upon completion of the TLS
- handshake.
-
- The STARTTLS extension is not suitable for authenticating the author
- of an email message unless every hop in the delivery chain, including
- the submission to the first SMTP server, is authenticated. Another
- proposal [SMTP-AUTH] can be used to authenticate delivery and MIME
- security multiparts [MIME-SEC] can be used to authenticate the author
- of an email message. In addition, the [SMTP-AUTH] proposal offers
- simpler and more flexible options to authenticate an SMTP client and
- the SASL EXTERNAL mechanism [SASL] MAY be used in conjunction with
- the STARTTLS command to provide an authorization identity.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hoffman Standards Track [Page 6]
-\f
-RFC 2487 SMTP Service Extension January 1999
-
-
-A. References
-
- [RFC-821] Postel, J., "Simple Mail Transfer Protocol", RFC 821,
- August 1982.
-
- [RFC-1869] Klensin, J., Freed, N, Rose, M, Stefferud, E. and D.
- Crocker, "SMTP Service Extensions", STD 10, RFC 1869,
- November 1995.
-
- [RFC-2034] Freed, N., "SMTP Service Extension for Returning Enhanced
- Error Codes", RFC 2034, October 1996.
-
- [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [SASL] Myers, J., "Simple Authentication and Security Layer
- (SASL)", RFC 2222, October 1997.
-
- [SMTP-AUTH] "SMTP Service Extension for Authentication", Work in
- Progress.
-
- [TLS] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
- RFC 2246, January 1999.
-
-B. Author's Address
-
- Paul Hoffman
- Internet Mail Consortium
- 127 Segre Place
- Santa Cruz, CA 95060
-
- Phone: (831) 426-9827
- EMail: phoffman@imc.org
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hoffman Standards Track [Page 7]
-\f
-RFC 2487 SMTP Service Extension January 1999
-
-
-C. Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hoffman Standards Track [Page 8]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group J. Myers
-Request for Comments: 2554 Netscape Communications
-Category: Standards Track March 1999
-
-
- SMTP Service Extension
- for Authentication
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-
-1. Introduction
-
- This document defines an SMTP service extension [ESMTP] whereby an
- SMTP client may indicate an authentication mechanism to the server,
- perform an authentication protocol exchange, and optionally negotiate
- a security layer for subsequent protocol interactions. This
- extension is a profile of the Simple Authentication and Security
- Layer [SASL].
-
-
-2. Conventions Used in this Document
-
- In examples, "C:" and "S:" indicate lines sent by the client and
- server respectively.
-
- The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
- in this document are to be interpreted as defined in "Key words for
- use in RFCs to Indicate Requirement Levels" [KEYWORDS].
-
-
-3. The Authentication service extension
-
-
- (1) the name of the SMTP service extension is "Authentication"
-
- (2) the EHLO keyword value associated with this extension is "AUTH"
-
-
-
-
-Myers Standards Track [Page 1]
-\f
-RFC 2554 SMTP Authentication March 1999
-
-
- (3) The AUTH EHLO keyword contains as a parameter a space separated
- list of the names of supported SASL mechanisms.
-
- (4) a new SMTP verb "AUTH" is defined
-
- (5) an optional parameter using the keyword "AUTH" is added to the
- MAIL FROM command, and extends the maximum line length of the
- MAIL FROM command by 500 characters.
-
- (6) this extension is appropriate for the submission protocol
- [SUBMIT].
-
-
-4. The AUTH command
-
- AUTH mechanism [initial-response]
-
- Arguments:
- a string identifying a SASL authentication mechanism.
- an optional base64-encoded response
-
- Restrictions:
- After an AUTH command has successfully completed, no more AUTH
- commands may be issued in the same session. After a successful
- AUTH command completes, a server MUST reject any further AUTH
- commands with a 503 reply.
-
- The AUTH command is not permitted during a mail transaction.
-
- Discussion:
- The AUTH command indicates an authentication mechanism to the
- server. If the server supports the requested authentication
- mechanism, it performs an authentication protocol exchange to
- authenticate and identify the user. Optionally, it also
- negotiates a security layer for subsequent protocol
- interactions. If the requested authentication mechanism is not
- supported, the server rejects the AUTH command with a 504
- reply.
-
- The authentication protocol exchange consists of a series of
- server challenges and client answers that are specific to the
- authentication mechanism. A server challenge, otherwise known
- as a ready response, is a 334 reply with the text part
- containing a BASE64 encoded string. The client answer consists
- of a line containing a BASE64 encoded string. If the client
- wishes to cancel an authentication exchange, it issues a line
- with a single "*". If the server receives such an answer, it
- MUST reject the AUTH command by sending a 501 reply.
-
-
-
-Myers Standards Track [Page 2]
-\f
-RFC 2554 SMTP Authentication March 1999
-
-
- The optional initial-response argument to the AUTH command is
- used to save a round trip when using authentication mechanisms
- that are defined to send no data in the initial challenge.
- When the initial-response argument is used with such a
- mechanism, the initial empty challenge is not sent to the
- client and the server uses the data in the initial-response
- argument as if it were sent in response to the empty challenge.
- Unlike a zero-length client answer to a 334 reply, a zero-
- length initial response is sent as a single equals sign ("=").
- If the client uses an initial-response argument to the AUTH
- command with a mechanism that sends data in the initial
- challenge, the server rejects the AUTH command with a 535
- reply.
-
- If the server cannot BASE64 decode the argument, it rejects the
- AUTH command with a 501 reply. If the server rejects the
- authentication data, it SHOULD reject the AUTH command with a
- 535 reply unless a more specific error code, such as one listed
- in section 6, is appropriate. Should the client successfully
- complete the authentication exchange, the SMTP server issues a
- 235 reply.
-
- The service name specified by this protocol's profile of SASL
- is "smtp".
-
- If a security layer is negotiated through the SASL
- authentication exchange, it takes effect immediately following
- the CRLF that concludes the authentication exchange for the
- client, and the CRLF of the success reply for the server. Upon
- a security layer's taking effect, the SMTP protocol is reset to
- the initial state (the state in SMTP after a server issues a
- 220 service ready greeting). The server MUST discard any
- knowledge obtained from the client, such as the argument to the
- EHLO command, which was not obtained from the SASL negotiation
- itself. The client MUST discard any knowledge obtained from
- the server, such as the list of SMTP service extensions, which
- was not obtained from the SASL negotiation itself (with the
- exception that a client MAY compare the list of advertised SASL
- mechanisms before and after authentication in order to detect
- an active down-negotiation attack). The client SHOULD send an
- EHLO command as the first command after a successful SASL
- negotiation which results in the enabling of a security layer.
-
- The server is not required to support any particular
- authentication mechanism, nor are authentication mechanisms
- required to support any security layers. If an AUTH command
- fails, the client may try another authentication mechanism by
- issuing another AUTH command.
-
-
-
-Myers Standards Track [Page 3]
-\f
-RFC 2554 SMTP Authentication March 1999
-
-
- If an AUTH command fails, the server MUST behave the same as if
- the client had not issued the AUTH command.
-
- The BASE64 string may in general be arbitrarily long. Clients
- and servers MUST be able to support challenges and responses
- that are as long as are generated by the authentication
- mechanisms they support, independent of any line length
- limitations the client or server may have in other parts of its
- protocol implementation.
-
- Examples:
- S: 220 smtp.example.com ESMTP server ready
- C: EHLO jgm.example.com
- S: 250-smtp.example.com
- S: 250 AUTH CRAM-MD5 DIGEST-MD5
- C: AUTH FOOBAR
- S: 504 Unrecognized authentication type.
- C: AUTH CRAM-MD5
- S: 334
- PENCeUxFREJoU0NnbmhNWitOMjNGNndAZWx3b29kLmlubm9zb2Z0LmNvbT4=
- C: ZnJlZCA5ZTk1YWVlMDljNDBhZjJiODRhMGMyYjNiYmFlNzg2ZQ==
- S: 235 Authentication successful.
-
-
-
-5. The AUTH parameter to the MAIL FROM command
-
- AUTH=addr-spec
-
- Arguments:
- An addr-spec containing the identity which submitted the message
- to the delivery system, or the two character sequence "<>"
- indicating such an identity is unknown or insufficiently
- authenticated. To comply with the restrictions imposed on ESMTP
- parameters, the addr-spec is encoded inside an xtext. The syntax
- of an xtext is described in section 5 of [ESMTP-DSN].
-
- Discussion:
- The optional AUTH parameter to the MAIL FROM command allows
- cooperating agents in a trusted environment to communicate the
- authentication of individual messages.
-
- If the server trusts the authenticated identity of the client to
- assert that the message was originally submitted by the supplied
- addr-spec, then the server SHOULD supply the same addr-spec in an
- AUTH parameter when relaying the message to any server which
- supports the AUTH extension.
-
-
-
-
-Myers Standards Track [Page 4]
-\f
-RFC 2554 SMTP Authentication March 1999
-
-
- A MAIL FROM parameter of AUTH=<> indicates that the original
- submitter of the message is not known. The server MUST NOT treat
- the message as having been originally submitted by the client.
-
- If the AUTH parameter to the MAIL FROM is not supplied, the
- client has authenticated, and the server believes the message is
- an original submission by the client, the server MAY supply the
- client's identity in the addr-spec in an AUTH parameter when
- relaying the message to any server which supports the AUTH
- extension.
-
- If the server does not sufficiently trust the authenticated
- identity of the client, or if the client is not authenticated,
- then the server MUST behave as if the AUTH=<> parameter was
- supplied. The server MAY, however, write the value of the AUTH
- parameter to a log file.
-
- If an AUTH=<> parameter was supplied, either explicitly or due to
- the requirement in the previous paragraph, then the server MUST
- supply the AUTH=<> parameter when relaying the message to any
- server which it has authenticated to using the AUTH extension.
-
- A server MAY treat expansion of a mailing list as a new
- submission, setting the AUTH parameter to the mailing list
- address or mailing list administration address when relaying the
- message to list subscribers.
-
- It is conforming for an implementation to be hard-coded to treat
- all clients as being insufficiently trusted. In that case, the
- implementation does nothing more than parse and discard
- syntactically valid AUTH parameters to the MAIL FROM command and
- supply AUTH=<> parameters to any servers to which it
- authenticates using the AUTH extension.
-
- Examples:
- C: MAIL FROM:<e=mc2@example.com> AUTH=e+3Dmc2@example.com
- S: 250 OK
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Myers Standards Track [Page 5]
-\f
-RFC 2554 SMTP Authentication March 1999
-
-
-6. Error Codes
-
- The following error codes may be used to indicate various conditions
- as described.
-
- 432 A password transition is needed
-
- This response to the AUTH command indicates that the user needs to
- transition to the selected authentication mechanism. This typically
- done by authenticating once using the PLAIN authentication mechanism.
-
- 534 Authentication mechanism is too weak
-
- This response to the AUTH command indicates that the selected
- authentication mechanism is weaker than server policy permits for
- that user.
-
- 538 Encryption required for requested authentication mechanism
-
- This response to the AUTH command indicates that the selected
- authentication mechanism may only be used when the underlying SMTP
- connection is encrypted.
-
- 454 Temporary authentication failure
-
- This response to the AUTH command indicates that the authentication
- failed due to a temporary server failure.
-
- 530 Authentication required
-
- This response may be returned by any command other than AUTH, EHLO,
- HELO, NOOP, RSET, or QUIT. It indicates that server policy requires
- authentication in order to perform the requested action.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Myers Standards Track [Page 6]
-\f
-RFC 2554 SMTP Authentication March 1999
-
-
-7. Formal Syntax
-
- The following syntax specification uses the augmented Backus-Naur
- Form (BNF) notation as specified in [ABNF].
-
- Except as noted otherwise, all alphabetic characters are case-
- insensitive. The use of upper or lower case characters to define
- token strings is for editorial clarity only. Implementations MUST
- accept these strings in a case-insensitive fashion.
-
- UPALPHA = %x41-5A ;; Uppercase: A-Z
-
- LOALPHA = %x61-7A ;; Lowercase: a-z
-
- ALPHA = UPALPHA / LOALPHA ;; case insensitive
-
- DIGIT = %x30-39 ;; Digits 0-9
-
- HEXDIGIT = %x41-46 / DIGIT ;; hexidecimal digit (uppercase)
-
- hexchar = "+" HEXDIGIT HEXDIGIT
-
- xchar = %x21-2A / %x2C-3C / %x3E-7E
- ;; US-ASCII except for "+", "=", SPACE and CTL
-
- xtext = *(xchar / hexchar)
-
- AUTH_CHAR = ALPHA / DIGIT / "-" / "_"
-
- auth_type = 1*20AUTH_CHAR
-
- auth_command = "AUTH" SPACE auth_type [SPACE (base64 / "=")]
- *(CRLF [base64]) CRLF
-
- auth_param = "AUTH=" xtext
- ;; The decoded form of the xtext MUST be either
- ;; an addr-spec or the two characters "<>"
-
- base64 = base64_terminal /
- ( 1*(4base64_CHAR) [base64_terminal] )
-
- base64_char = UPALPHA / LOALPHA / DIGIT / "+" / "/"
- ;; Case-sensitive
-
- base64_terminal = (2base64_char "==") / (3base64_char "=")
-
- continue_req = "334" SPACE [base64] CRLF
-
-
-
-
-Myers Standards Track [Page 7]
-\f
-RFC 2554 SMTP Authentication March 1999
-
-
- CR = %x0C ;; ASCII CR, carriage return
-
- CRLF = CR LF
-
- CTL = %x00-1F / %x7F ;; any ASCII control character and DEL
-
- LF = %x0A ;; ASCII LF, line feed
-
- SPACE = %x20 ;; ASCII SP, space
-
-
-
-
-8. References
-
- [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", RFC 2234, November 1997.
-
- [CRAM-MD5] Klensin, J., Catoe, R. and P. Krumviede, "IMAP/POP
- AUTHorize Extension for Simple Challenge/Response", RFC
- 2195, September 1997.
-
- [ESMTP] Klensin, J., Freed, N., Rose, M., Stefferud, E. and D.
- Crocker, "SMTP Service Extensions", RFC 1869, November
- 1995.
-
- [ESMTP-DSN] Moore, K, "SMTP Service Extension for Delivery Status
- Notifications", RFC 1891, January 1996.
-
- [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [SASL] Myers, J., "Simple Authentication and Security Layer
- (SASL)", RFC 2222, October 1997.
-
- [SUBMIT] Gellens, R. and J. Klensin, "Message Submission", RFC
- 2476, December 1998.
-
- [RFC821] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC
- 821, August 1982.
-
- [RFC822] Crocker, D., "Standard for the Format of ARPA Internet
- Text Messages", STD 11, RFC 822, August 1982.
-
-
-
-
-
-
-
-
-Myers Standards Track [Page 8]
-\f
-RFC 2554 SMTP Authentication March 1999
-
-
-9. Security Considerations
-
- Security issues are discussed throughout this memo.
-
- If a client uses this extension to get an encrypted tunnel through an
- insecure network to a cooperating server, it needs to be configured
- to never send mail to that server when the connection is not mutually
- authenticated and encrypted. Otherwise, an attacker could steal the
- client's mail by hijacking the SMTP connection and either pretending
- the server does not support the Authentication extension or causing
- all AUTH commands to fail.
-
- Before the SASL negotiation has begun, any protocol interactions are
- performed in the clear and may be modified by an active attacker.
- For this reason, clients and servers MUST discard any knowledge
- obtained prior to the start of the SASL negotiation upon completion
- of a SASL negotiation which results in a security layer.
-
- This mechanism does not protect the TCP port, so an active attacker
- may redirect a relay connection attempt to the submission port
- [SUBMIT]. The AUTH=<> parameter prevents such an attack from causing
- an relayed message without an envelope authentication to pick up the
- authentication of the relay client.
-
- A message submission client may require the user to authenticate
- whenever a suitable SASL mechanism is advertised. Therefore, it may
- not be desirable for a submission server [SUBMIT] to advertise a SASL
- mechanism when use of that mechanism grants the client no benefits
- over anonymous submission.
-
- This extension is not intended to replace or be used instead of end-
- to-end message signature and encryption systems such as S/MIME or
- PGP. This extension addresses a different problem than end-to-end
- systems; it has the following key differences:
-
- (1) it is generally useful only within a trusted enclave
-
- (2) it protects the entire envelope of a message, not just the
- message's body.
-
- (3) it authenticates the message submission, not authorship of the
- message content
-
- (4) it can give the sender some assurance the message was
- delivered to the next hop in the case where the sender
- mutually authenticates with the next hop and negotiates an
- appropriate security layer.
-
-
-
-
-Myers Standards Track [Page 9]
-\f
-RFC 2554 SMTP Authentication March 1999
-
-
- Additional security considerations are mentioned in the SASL
- specification [SASL].
-
-
-
-10. Author's Address
-
- John Gardiner Myers
- Netscape Communications
- 501 East Middlefield Road
- Mail Stop MV-029
- Mountain View, CA 94043
-
- EMail: jgmyers@netscape.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Myers Standards Track [Page 10]
-\f
-RFC 2554 SMTP Authentication March 1999
-
-
-11. Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Myers Standards Track [Page 11]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group F.D. Wright
-Request for Comments: 2567 Lexmark International
-Category: Experimental April 1999
-
-
- Design Goals for an Internet Printing Protocol
-
-Status of this Memo
-
- This memo defines an Experimental Protocol for the Internet
- community. It does not specify an Internet standard of any kind.
- Discussion and suggestions for improvement are requested.
- Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-IESG Note
-
- This document defines an Experimental protocol for the Internet
- community. The IESG expects that a revised version of this protocol
- will be published as Proposed Standard protocol. The Proposed
- Standard, when published, is expected to change from the protocol
- defined in this memo. In particular, it is expected that the
- standards-track version of the protocol will incorporate strong
- authentication and privacy features, and that an "ipp:" URL type will
- be defined which supports those security measures. Other changes to
- the protocol are also possible. Implementers are warned that future
- versions of this protocol may not interoperate with the version of
- IPP defined in this document, or if they do interoperate, that some
- protocol features may not be available.
-
- The IESG encourages experimentation with this protocol, especially in
- combination with Transport Layer Security (TLS) [RFC2246], to help
- determine how TLS may effectively be used as a security layer for
- IPP.
-
-Abstract
-
- This document is one of a set of documents, which together describe
- all aspects of a new Internet Printing Protocol (IPP). IPP is an
- application level protocol that can be used for distributed printing
- using Internet tools and technologies. This document takes a broad
- look at distributed printing functionality, and it enumerates real-
- life scenarios that help to clarify the features that need to be
- included in a printing protocol for the Internet. It identifies
- requirements for three types of users: end users, operators, and
-
-
-
-Wright Experimental [Page 1]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- administrators. The design goals document calls out a subset of end
- user requirements that are satisfied in IPP/1.0. Operator and
- administrator requirements are out of scope for version 1.0.
-
- The full set of IPP documents includes:
-
- Design Goals for an Internet Printing Protocol (this document)
- Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol [RFC2568]
- Internet Printing Protocol/1.0: Model and Semantics [RFC2568]
- Internet Printing Protocol/1.0: Encoding and Transport [RFC2565]
- Internet Printing Protocol/1.0: Implementer's Guide [ipp-iig]
- Mapping between LPD and IPP Protocols [RFC2569]
-
- The "Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol" document describes IPP from a high level
- view, defines a roadmap for the various documents that form the suite
- of IPP specifications, and gives background and rationale for the
- IETF working group's major decisions.
-
- The "Internet Printing Protocol/1.0: Model and Semantics" document
- describes a simplified model consisting of abstract objects, their
- attributes, and their operations that is independent of encoding and
- transport. The model consists of a Printer and a Job object. The
- Job optionally supports multiple documents. IPP 1.0 semantics allow
- end-users and operators to query printer capabilities, submit print
- jobs, inquire about the status of print jobs and printers, and cancel
- print jobs. This document also addresses security,
- internationalization, and directory issues.
-
- The "Internet Printing Protocol/1.0: Encoding and Transport" document
- is a formal mapping of the abstract operations and attributes defined
- in the model document onto HTTP/1.1. It defines the encoding rules
- for a new Internet media type called "application/ipp".
-
- The "Internet Printing Protocol/1.0: Implementer's Guide" document
- gives insight and advice to implementers of IPP clients and IPP
- objects. It is intended to help them understand IPP/1.0 and some of
- the considerations that may assist them in the design of their client
- and/or IPP object implementations. For example, a typical order of
- processing requests is given, including error checking. Motivation
- for some of the specification decisions is also included.
-
- The "Mapping between LPD and IPP Protocols" document gives some
- advice to implementers of gateways between IPP and LPD (Line Printer
- Daemon) implementations.
-
-
-
-
-
-Wright Experimental [Page 2]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
-TABLE OF CONTENTS
-
- 1. INTRODUCTION.....................................................4
- 2. TERMINOLOGY......................................................4
- 3. DESIGN GOALS.....................................................6
- 3.1. End-user.......................................................6
- 3.1.1. Finding or locating a printer................................6
- 3.1.2. Create an instance of the printer............................7
- 3.1.3. Viewing the status and capabilities of a printer.............7
- 3.1.4. Submitting a print job.......................................8
- 3.1.5. Viewing the status of a submitted print job..................9
- 3.1.6. Canceling a Print Job........................................9
- 3.2. Operator (NOT REQUIRED FOR V1.0)...............................9
- 3.2.1. Alerting.....................................................9
- 3.2.2. Changing Print and Job Status...............................10
- 3.3. Administrator (NOT REQUIRED FOR v1.0).........................10
- 4. OBJECTIVES OF THE PROTOCOL......................................10
- 4.1. SECURITY CONSIDERATIONS.......................................11
- 4.2. Interaction with LPD (RFC1179)................................12
- 4.3. Extensibility.................................................12
- 4.4. Firewalls.....................................................13
- 4.5. Internationalization..........................................13
- 5. IPP SCENARIOS...................................................13
- 5.1. Printer Discovery.............................................14
- 5.2. Driver Installation...........................................15
- 5.3. Submitting a Print Job........................................15
- 5.4. Getting Status/Capabilities...................................16
- 5.5. Asynchronous Notification.....................................17
- 5.6. Job Canceling.................................................17
- 6. Security Considerations.........................................18
- 7. REFERENCES......................................................18
- 8. ACKNOWLEDGMENTS.................................................19
- 9. AUTHOR'S ADDRESS................................................19
- 10. APPENDIX - DETAILED SCENARIOS..................................20
- 10.1. Printer discovery within an enterprise.......................20
- 10.2. Printer discovery across enterprises.........................21
- 10.3. Printer discovery on the Internet -logical operations........21
- 10.4. Printer discovery on the Internet - authentication...........22
- 10.5. Driver Download..............................................23
- 10.6. Submitting a print job as a file.............................24
- 10.7. Submitting a print job with two documents....................24
- 10.8. Submitting a print job as a file, printing fails.............25
- 10.9. Submitting a print job with authentication, PRIVACY and
- payment......................................................26
- 10.10. Submitting a print job with decryption error................27
- 10.11. Submitting a print job with authentication..................28
- 10.12. Submitting a print job generated dynamically................29
- 10.13. Submitting a print job with a Printer jam - CANCELED........29
-
-
-
-Wright Experimental [Page 3]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- 10.14. Submitting a print job with a Printer jam - recovered.......30
- 10.15. Submitting a print job with server pull.....................31
- 10.16. Submitting a print job with referenced resources............32
- 10.17. Getting Capabilities........................................33
- 10.17.1. Submission Attributes.....................................33
- 10.17.2. Printer Capabilities......................................33
- 10.18. Getting Status..............................................34
- 10.18.1. Printer State/Status......................................34
- 10.18.2. Job Status................................................34
- 10.18.3. Status of All My Jobs.....................................34
- 10.19. Asynchronous Notification...................................35
- 10.19.1. Job Completion............................................35
- 10.19.2. Job Complete with Data....................................35
- 10.19.3. Print Job Fails...........................................35
- 10.20. Cancel a job................................................36
- 10.21. End to end Scenario - within an enterprise..................36
- 10.22. End to end Scenario - across enterprises....................37
- 10.23. End to End Scenario - on the internet.......................40
- 11. Full Copyright Statement.......................................43
-
-1. INTRODUCTION
-
- The IPP protocol is heavily influenced by the printing model
- introduced in the Document Printing Application (DPA) [ISO10175]
- standard. Although DPA specifies both end user and administrative
- features, IPP version 1.0 (IPP/1.0) focuses only on end user
- functionality.
-
-2. TERMINOLOGY
-
- Internet Printing for the purposes of this document is the
- application of Internet tools, programs, servers and networks to
- allow end-users to print to a remote printer using, after initial
- setup or configuration, the same methods, operations and paradigms as
- would be used for a locally attached or a local area network attached
- printer. This could include the use of HTTP servers and browsers and
- other applications for providing static, dynamic and interactive
- printer locating services, user installation, selection,
- configuration, print job submission, printer capability inquiry and
- status inquiry of remote printers and jobs.
-
- For the purposes of this document, a WEB Browser is software
- available from a number of sources including but not limited to the
- following: Microsoft Internet Explorer, NCSA Mosaic, Netscape
- Navigator, Sun Hot Java!. The major task of these products is to use
- the Hypertext Transport Protocol (HTTP) to retrieve, interpret and
- display Hypertext Markup Language (HTML). These products are often a
- part of a complete Internet Printing system because they are often
-
-
-
-Wright Experimental [Page 4]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- used as a means of obtaining the status of or more information about
- the printing system; however, they may not be present in all
- implementations.
-
- Throughout this document, 'printer' shall be interpreted to include
- any device which is capable of marking on a piece of media using any
- available technology. These design goals do not include support for
- multi-tiered printing solutions involving servers (single or
- multiple) logically in front of the actual printing device yet all
- such configurations shall be supported but shall appear to the end-
- user as only a single device.
-
- Throughout this document 'driver' refers to the code installed in
- some client operating system to generate the print data stream for
- the intended printer. Some computing environments may not include a
- separate printer driver. Rather, the generation of the proper print
- data stream is accomplished in an application on that computer. How
- such a computer environment or application is updated to support a
- new printer now made available using IPP is outside the scope of IPP.
- The actual details for installing a printer driver are operating
- system dependent and are also outside the scope of IPP. See also
- section 4.1 (SECURITY CONSIDERATIONS) for security implications of
- driver download and installation.
-
- The IPP protocol will support the following physical configurations:
-
- - An IPP client talking to an IPP Printer object imbedded in a
- single, physical output device.
- - An IPP Client talking to a server containing one or more IPP
- Printer objects. Each Printer object is associated with exactly one
- physical output device supported by the server. The protocol
- between the server and the output devices is undefined.
- - An IPP Client talking to an IPP Printer object in a server. The
- Printer object is associated with one or more physical output
- devices, but the client only sees the Printer object, which is an
- abstraction and represents all of the associated physical output
- devices. The protocol between the server and the physical output
- devices is undefined.
-
- Throughout this document, certain design goals will be identified as
- not being a part of version 1.0 (or V1.0) of the protocol or as being
- satisfied by means outside of IPP. IPP is assumed to be one part, an
- enabler, of a complete Internet Printing solution. For example
- printer instance creation is not performed by but is enabled by the
- protocol. Globally, none of the operator or administrators wants and
- needs are included in the design goals for version 1.0. Some of the
- end-user wants and needs may also be excluded from version 1.0 and
- will be so noted in the description of them. Subsequent versions of
-
-
-
-Wright Experimental [Page 5]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- the protocol (e.g. V2.0) may include support for these initially
- excluded wants and needs.
-
-3. DESIGN GOALS
-
- The next three sections identify the design goals for an Internet
- printing protocol from three roles assumed by humans: end-user,
- operator, and administrator. The goals defined here are only those
- that need to be addressed by an Internet printing protocol. Other
- wants and needs, such as that the operator needs physical access to
- the printer (e.g. to be able to load paper or clear jams) are not
- covered by this document. Section 5 contains scenarios which provide
- more detailed examples of the entire process including discovery,
- status, printing and end-of-job reporting.
-
-3.1. END-USER
-
- An end-user of a printer accepting jobs through the Internet is one
- of the roles in which humans act. The end-user is the person that
- will submit a job to be printed on the printer.
-
- The wants and needs of the end-user are broken down into six
- categories: finding/locating a printer, creating a local instance of
- a printer, viewing printer status, viewing printer capabilities,
- submitting a print job, viewing print job status, altering the
- attributes of a print job.
-
-3.1.1. Finding or locating a printer.
-
- End-users want to be able to find and locate printers to which they
- are authorized to print. They want to be able to perform this
- function using a standard WEB browser or other application. Multiple
- criteria can be applied to find the printers needed. These criteria
- include but are not limited to:
-
- - by name (Printer 1, Joes-color-printer, etc.)
- - by geographic location (bldg 1, Kentucky, etc.)
- - by capability or attribute (color, duplex, legal paper, etc.)
-
- Additionally, while it is outside of scope of IPP, end-users want to
- be able to limit the scope of their searching to:
-
- - inside a functional sub-domain
- - include only a particular domain (lexmark.com)
- - exclude specified domains
-
-
-
-
-
-
-Wright Experimental [Page 6]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- While an Internet printing protocol may not of itself include this
- function, IPP must define and enable a directory schema which will
- provide the necessary information for a directory service
- implementation to consistently represent printers by their IPP
- attributes.
-
-3.1.2. Create an instance of the printer.
-
- After finding the desired printer, an end-user needs to be able to
- create a local instance of that printer within the end-user operating
- system or desktop. This local instance will vary depending upon the
- printing paradigm of the operating system. For example, some UNIX
- users will only want a queue or a reference to a remote printer
- created on their machine while other UNIX users and Windows NT users
- will want the queue and also the necessary icons and registry entries
- to be created and initialized. Where required, drivers may need to
- be downloaded from some repository and installed on the computer.
- All necessary decompressing, unpacking, and other installation
- actions should occur without end-user interaction or intervention
- excepting initial approval by the end-user. Once the local instance
- of the printer has been installed, it shall appear to the end-user of
- the operating system and to the applications running there as any
- other printer (local, local area network connected, or network
- operating system connected) on the end-user desktop or environment.
- IPP's role in this goal is simply to enable the creation of the
- printer instance providing information such as where to locate a
- printer driver for this printer, as an attribute of an IPP Printer.
-
-3.1.3. Viewing the status and capabilities of a printer.
-
- Before using a selected printer or, in fact at any time, the end-user
- needs the ability to verify the characteristics and status of both
- printers and jobs queued for that printer. When checking the
- characteristics of a printer, the end-user typically wants to be able
- to determine the capability of the device, e.g.:
-
- - supported media, commonly paper, by size and type
- - paper handling capability, e.g. duplex, collating, finishing
- - color capability
-
- When checking the status of the printer and its print jobs, the end-
- user typically wants to be able to determine:
-
- - is the printer on-line?
- - what are the defaults to be used for printing?
- - how many jobs are queued for the printer?
- - how are job priorities assigned? (outside the scope of IPP)
-
-
-
-
-Wright Experimental [Page 7]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
-3.1.4. Submitting a print job.
-
- Once the desired printer has been located and installed, the end-user
- wants to print to that printer from normal applications using
- standard methods. These normal applications include such programs as
- word processors, spreadsheets, data-base applications, WEB browsers,
- production printing applications, etc. Additionally, the end-user
- may want to print a file already existing on the end-user's computer
- -- "simple push". In addition to printing from an application and
- simple push, the end-user needs to have the ability to submit a print
- job by reference. Printing by reference is defined to mean as
- submitting a job by providing a reference to an existing document.
- The reference, a URI, will be resolved before the actual print
- process occurs. Submitting a job by reference relieves the user from
- downloading the document from the remote server and then sending it
- via IPP to the printer. This saves both time and network bandwidth.
-
- Some means shall be provided to determine if the format of a job
- matches the capability of the printer. This can be done by one of
- the following (all of which are outside of scope of the IPP
- protocol):
-
- - the end-user selects the correct printer driver
- - the printer automatically selects the proper interpreter
- - the end-user uses some other manual procedure.
-
- A standard action shall be defined should the job's requirements not
- match the capabilities of the printer.
-
- Because the end-user does not want to know the details of the
- underlying printing process, the protocol must support job-to-printer
- capability matching (all implementations are not necessarily required
- to implement this function.) This matching capability requires
- knowing both the printer's capabilities and attributes and those
- capabilities and attributes required by the job. Actions taken when
- a print job requires capabilities or attributes that are not
- available on the printer vary and can include but are not limited to:
-
- - rejecting the print job
- - redirecting the print job to another printer (Not in V1.0)
- - printing the job, accepting differences in the appearance
-
- Print jobs will also be submitted by background or batch applications
- without human intervention.
-
- End-users need the ability to set certain print job parameters at the
- time the job is submitted. These parameters include but are not
- limited to:
-
-
-
-Wright Experimental [Page 8]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- - number of copies
- - single or two sided printing
- - finishing
- - job priority
-
-3.1.5. Viewing the status of a submitted print job.
-
- After a job has been submitted to a printer, the end-user needs a way
- to view the status of that job (i.e. job waiting, job printing, job
- done) and to determine where the job is in the print queue.
-
- In addition to the need to inquire about the status of a print job,
- automatic notification of the completion of that job is also
- required.
-
- Notification means are not defined by the protocol but the protocol
- must provide a means of enabling and disabling the notification.
-
-3.1.6. Canceling a Print Job
-
- While a job is waiting to be printed or has been started but not yet
- completed, the original creator/submitter of the print job (i.e. the
- end-user) shall be able to cancel the job entirely (job is waiting)
- or the remaining portion of it (job is printing.) Altering the print
- job itself is not a V1.0 design goal.
-
-3.2. OPERATOR (NOT REQUIRED FOR V1.0)
-
- An operator of a printer accepting jobs through the Internet is one
- of the roles in which humans act. The operator has the
- responsibility of monitoring the status of the printer as well as
- managing and controlling the jobs at the device. These
- responsibilities include but are not limited to the replenishing of
- supplies (ink, toner, paper, etc.), the clearing of minor errors
- (paper jams, etc.) and the re-prioritization of end-user jobs.
- Operator wants and needs will not be addressed by V1.0 of the
- protocol.
-
- The wants and needs of the operator include all those of the end-user
- but may include additional privileges. For example, an operator may
- be able to view all print jobs on a printer while the end-user might
- only be able to see his own jobs.
-
-3.2.1. Alerting.
-
- One of the required operator functions is having the ability to
- discover or to be alerted to changes in the status of a printer
- particularly those changes that cause a printer to stop printing and
-
-
-
-Wright Experimental [Page 9]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- to be able to correct those problems. As such, an Internet printing
- protocol shall be able to alert a designated operator or operators to
- these conditions such as 'out of paper', 'out of ink', etc.
- Additionally. the operator shall be able to, asynchronous to other
- printer activity, inquire as to a printer's or a job's status.
-
-3.2.2. Changing Print and Job Status.
-
- Another of the required operator functions is the ability to affect
- changes to printer and job status remotely. For example, the
- operator will need to be able to re-prioritize or cancel any print
- jobs on a printer to which the operator has authority.
-
-3.3. ADMINISTRATOR (NOT REQUIRED FOR V1.0)
-
- An administrator of a printer accepting jobs through the Internet is
- one of the roles in which humans act. The administrator has the
- responsibility of creating the printer instances and controlling the
- authorization of other end-users and operators. Administrator wants
- and needs will not be addressed by V1.0 of the protocol.
-
- The wants and needs of the administrator include all those of the
- end-user and, in some environments, some or all of those of the
- operator. Minimally, the administrator must also have the tools,
- programs, utilities and supporting protocols available to be able to:
-
- - create an instance of a printer
- - create, edit and maintain the list of authorized end-users
- - create, edit and maintain the list of authorized operators
- - create, edit and maintain the list of authorized
- administrators
- - create, customize, change or otherwise alter the manner in
- which the status capabilities and other information about printers
- and jobs are presented
- - create, customize, or change other printer or job features
- - administrate billing or other charge-back mechanisms
- - create sets of defaults
- - create sets of capabilities
-
- The administrator must have the capability to perform all the above
- tasks locally or remotely to the printer.
-
-4. OBJECTIVES OF THE PROTOCOL
-
- The protocol to be defined by an Internet printing working group will
- address the wants and needs of the end-user (V1.0). It will not, at
- least initially, address the operator or administrator wants and
- needs (V2.0).
-
-
-
-Wright Experimental [Page 10]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- The protocol defined shall be independent of the operating system of
- both the client and the server. Generally, any platform capable of
- supporting a WEB Browser should be capable of being a client.
- Generally, any platform providing a WEB/HTTP server and printing
- services should be capable of being a server. Usage of the WEB
- Browser and Server is not required for IPP; the operating system,
- operating system extensions or other applications may provide IPP
- functionality directly.
-
- In many environments such as Windows 95, Windows NT and OS/2, the
- print data is created and transmitted to the printer on the fly
- rather than being created, spooled and then transmitted to the
- printer (a typical UNIX method.) The Internet Printing Protocol must
- properly handle either methodology and make this transparent to the
- end-user.
-
-4.1. SECURITY CONSIDERATIONS
-
- It is required that the Internet Printing Protocol be able to operate
- within a secure environment. Wherever reasonable, IPP ought to make
- use of existing security protocols and services. IPP will not invent
- new security features when the design goals described in this
- document can be met by existing protocols and services. Examples of
- such services include Secure Socket Layer Version 3 (SSL3) [SSL] and
- HTTP Digest Access Authentication [RFC2069]. Note: SSL3 is not on
- the IETF standards track.
-
- Since we cannot anticipate the security levels or the specific
- threats that any given IPP print administrator may be concerned with,
- IPP must be capable of operating with different security mechanisms
- and policies as required by the individual installation. The initial
- security needs of IPP are derived from two primary considerations.
- First, the printing environments described in this document take into
- account that the client, the Printer, and the document to be printed
- may each exist in different security domains. When objects are in
- different security domains the design goals for authentication and
- message protection may be much stronger than when they are all in the
- same domain.
-
- Secondly, the sensitivity and value of the content being printed will
- vary from one instance of a print job to another. For example, a
- publicly available document does not need the same level of
- protection as a payroll document does. Message protection design
- goals include data origin authentication, privacy, integrity, and
- non-repudiation.
-
-
-
-
-
-
-Wright Experimental [Page 11]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- In many environments (e.g. Windows, OS/2) a printer driver may be
- needed to create the proper datastream for printer. This document
- discusses downloading such a new driver from a variety of sources.
- Downloading and installing any software, including drivers) on a
- computer exposes that computer to a number of security risks
- including but not limited to:
-
- - defective software
- - malicious software (e.g. Trojan horses)
- - inappropriate software (i.e. software doing something
- deemed unreasonable by the user.)
-
- As such, proper security considerations and actions need to be taken
- by the user and/or a system administrator to prevent the compromising
- of the computer. Administrators should configure downloading
- mechanism for printer drivers in such a way as to be able to verify
- the source of driver software and encrypt or otherwise protect that
- software during download.
-
- Examples including security considerations can be found in sections 5
- (IPP SCENARIOS) and 10 (APPENDIX - DETAILED SCENARIOS) later in this
- document.
-
-4.2. INTERACTION WITH LPD (RFC1179)
-
- Many versions of UNIX and in fact other operating systems provide a
- means of printing as described in [RFC1179] (Line Printer Daemon
- Protocol.) This document describes the file formats for the control
- and data files as well as the messages used by the protocol. Because
- of the simplistic approach taken by this protocol, many manufacturers
- have include proprietary enhancements and extensions to 'lpd.'
- Because of this divergence and due to other design goals described in
- this document, there is no requirement for backward compatibility or
- interoperability with 'lpd'. However, a mapping of LPD functionality
- and IPP functionality shall be provided so as to enable a gateway
- between LPD and IPP.
-
-4.3. EXTENSIBILITY
-
- The Internet Printing Protocol shall be extensible by several means
- that facilitate interoperability and prevent implementation
- collisions:
-
- - by providing a process whereby implementers can submit proposals
- for registration of new attributes and new enumerated values for
- existing attributes.
-
-
-
-
-
-Wright Experimental [Page 12]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- * that require review and approval. The Internet Assigned
- Number Authority (IANA) will be the repository for such
- accepted registration proposals after review.
-
- * that do not require review and approval. IANA will be the
- repository for such registrations.
-
- - by providing syntax in the protocol so that implementers may add
- private (i.e. unregistered) attributes and enumerated attribute
- values.
-
- - by providing versioning and negotiation so as to enable future
- implementations of IPP to interoperate with implementations of
- version 1.0 of IPP.
-
-4.4. FIREWALLS
-
- As stated in section 3 Design Goals, Internet printing shall, by
- definition, support printing from one enterprise to another. As
- such, the Internet printing protocol must be capable of passing
- through firewalls and/or proxy servers (where enabled by the firewall
- administrator) preferably without modification to the existing
- firewall technology.
-
-4.5. INTERNATIONALIZATION
-
- Users of Internet printing will come from all over the world. As
- such, where appropriate, internationalization and localization will
- be enabled for the protocol.
-
-5. IPP SCENARIOS
-
- Each of the scenarios in this section describes a specific IPP
- operation, such as submitting a print job. Section 10 contains
- several detailed flows for each scenario to provide additional
- detail. The examples should not be considered exhaustive, but
- illustrative of the functions and features required in the protocol.
- Flows are intended to be protocol neutral. It is not assumed that all
- of the functions and features described in these scenarios will
- necessarily be supported directly by IPP or in version 1.0 of IPP.
-
- See the IPP Model and Semantics document for details on
- configurations of clients, servers and firewalls.
-
-
-
-
-
-
-
-
-Wright Experimental [Page 13]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
-5.1. PRINTER DISCOVERY
-
- Client Directory Service
- Service
-
- +----------------------------------------------------------- >
- give me information on printers with these characteristics
-
-
- < -----------------------------------------------------------+
- Information on Printers matching these characteristics
-
- The objective of printer discovery is to locate printers that meet
- the client's wants and needs. The Directory Service should provide
- enough information for the client to make an initial choice. The
- client may have to connect to each individual Printer offered to get
- more detail. Not all information available from the Directory
- Service is obtained using IPP; some information may be
- administratively provided.
-
- The actual protocol used between client and Directory or Name Service
- is considered outside the scope of IPP. Printer Discover is included
- in the scenarios to provide design goals for the directory schema for
- IPP Printers and to further define Printer attributes.
-
- Characteristics that might be considered when locating a Printer
- include:
-
- - capabilities of the Printer, e.g. PDLs supported
- - physical location, e.g. in building 010
- - driver required and location
- - cost per page to print (outside the scope of IPP)
- - whether or not printer is access controlled
- - whether or not usage requires client authentication
- - whether or not Printer can be authenticated
- - whether or not payment is required for printing (outside the scope
- of IPP)
- - maximum job size (spool size) (outside the scope of IPP)
- - whether or not Printer support compression (outside the scope of
- IPP)
- - whether or not Printer supports encryption
- - administrative limits on this Printer
- - maximum number of copies per job
- - maximum number of pages per job
-
-
-
-
-
-
-
-Wright Experimental [Page 14]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- Responses could additionally include:
-
- - how to get more information
- - web page
- - telephone number
- - help desk
-
-5.2. DRIVER INSTALLATION
-
- Client Printer
-
- +----------------------------------------------------------- >
- Where can I find a driver & software to install it?
-
-
- < -----------------------------------------------------------+
- URIs for drivers and install software
-
- Driver here refers to the code installed in some client operating
- system to generate the print data stream for the intended printer.
- The actual details for installing a printer driver are operating
- system dependent and are also outside the scope of IPP. However, an
- IPP printer or a directory service advertising an IPP Printer should
- be capable of telling a client what drivers are available and/or
- required, where they can be found, and provide pointers to
- installation instructions, installation code or initialization
- strings required to install the driver. See section 4.1 (SECURITY
- CONSIDERATIONS) for security implications of driver download and
- installation.
-
-5.3. SUBMITTING A PRINT JOB
-
- Client IPP Printer
-
- +----------------------------------------------------------- >
- Here is a Print Job
- - Job attributes
- - Print data
-
-
- < -----------------------------------------------------------+
- Response
-
- The protocol must support these sources of client data:
-
- - Print data is a file submitted with the job
- - Print data is generated on the fly by an application
- - Print data is a file referenced by a URI
-
-
-
-Wright Experimental [Page 15]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- The protocol must handle overrun conditions in the printer and must
- support overlapped printing and downloading of the file in devices
- that are unable to spool files before printing them.
-
- Every print request will have a response. Responses will indicate
- success or failure of the request and provide information on failures
- when they occur. Responses would include things like:
-
- - Got the print job and queued it
- - Got the print job and am printing it
- - Got the print job, started to print it, but printing failed
- - why it failed (e.g. unrecoverable PostScript error)
- - state of the printer
- - how much printed
- - Got the print job but couldn't print it
- - why it can't be printed
- - state of the printer
- - Got the print job but don't know what to do with it
- - Didn't get a complete print job (e.g. communication failure)
-
-5.4. GETTING STATUS/CAPABILITIES
-
- Client IPP Printer
-
- +----------------------------------------------------------- >
- Get status and/or capabilities of Printer
-
-
- < -----------------------------------------------------------+
- Status/Capabilities
-
- Clients will need to get information about
-
- - Static capabilities of the device
- - Dynamic state of the Printer (e.g. out of paper)
- - State of a specific job owned by this client
- - State of all jobs owned by this client
- - queued
- - printing
- - completed
-
-
-
-
-
-
-
-
-
-
-
-Wright Experimental [Page 16]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- - Job submission attributes supported/required
- - scheduling attributes (e.g. priority)
- - production attributes (e.g. number of copies)
-
-5.5. ASYNCHRONOUS NOTIFICATION
-
- Client IPP Printer
-
- +----------------------------------------------------------- >
- Use the following method to notify me of Printer events
-
- .
- .
- .
- < -----------------------------------------------------------+
- Asynchronous notification of Printer event
-
- Clients must be able to request asynchronous notification for Printer
- events such as
-
- - job completion
- - a fatal error that requires the job to be resubmitted
- - a condition that severely impacts a queued job for this client
- e.g. printer is out of paper
-
- Note: end-user notification is a V1.0 design goal while operator
- notification is for V2.0.
-
-5.6. JOB CANCELING
-
- Client IPP Printer
-
- +----------------------------------------------------------- >
- Cancel the named job as indicated
-
-
- < -----------------------------------------------------------+
- Response (did it or not)
-
- Similarly clients must be able to make changes to jobs which have
- been submitted and are queued for printing. Changing of job
- attributes should also be supported. Job modifications, holding and
- releasing of jobs are not included in the design goals for IPP v1.0.
-
-
-
-
-
-
-
-
-Wright Experimental [Page 17]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
-6. SECURITY CONSIDERATIONS
-
- The security considerations for IPP are described in Section 4.1
- above.
-
-7. REFERENCES
-
- [ipp-iig] Hastings, T. and C. Manros, "Internet Printing
- Protocol/1.0: Implementer's Guide", Work in Progress.
-
- [RFC2569] Herriot, R., Hastings, T., Jacobs, N. and J. Martin,
- "Mapping between LPD and IPP Protocols", RFC 2569, April
- 1999.
-
- [RFC2566] deBry, R., Hastings, T., Herriot, R., Isaacson, S. and P.
- Powell, "Internet Printing Protocol/1.0: Model and
- Semantics", RFC 2568, April 1999.
-
- [RFC2565] Herriot, R., Butler, S., Moore, P. and R. Tuner, "Internet
- Printing Protocol/1.0: Encoding and Transport", RFC 2565,
- April 1999.
-
- [RFC2568] Zilles, S., "Rationale for the Structure and Model and
- Protocol for the Internet Printing Protocol", RFC 2568,
- April 1999.
-
- [ISO10175] ISO/IEC 10175, Document Printing Application, June 1996.
-
- [RFC1179] McLaughlin, L., "Line Printer Daemon Protocol" RFC 1179,
- August 1990.
-
- [SSL] Netscape, The SSL Protocol, Version 3, (Text version
- 3.02), November 1996.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Wright Experimental [Page 18]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
-8. ACKNOWLEDGMENTS
-
- This document draws heavily from preliminary work done by others
- especially in the Printer Working Group (PWG). The author gratefully
- acknowledges the specific contributions of:
-
- Scott Isaacson Roger deBry
- Novell Utah Valley State College
- sisaacson@novell.com debryro@uvsc.edu
-
- Carl-Uno Manros Robert Herriot
- Xerox Sun
- manros@cp10.es.xerox.com Robert.Herrior@pahv.xerox.xom
-
- Tom Hastings Peter Zehler
- Xerox Xerox
- hastings@cp10.es.xerox.com Peter.Zehler@usa.xerox.com
-
-9. AUTHOR'S ADDRESS
-
- F.D. (Don) Wright
- Lexmark International
- C14/035-3
- 740 New Circle Rd
- Lexington, KY 40550
-
- Phone: 606-232-4808
- Fax: 606-232-6740
- EMail: don@lexmark.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Wright Experimental [Page 19]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
-10. APPENDIX - DETAILED SCENARIOS
-
- The following are more detailed scenarios illustrating how the
- Internet Printing Protocol is expected to be used as a part of a
- complete Internet Printing system. Some parts of the scenarios
- include concepts, functions and information that may be outside of
- the scope of version 1.0 of IPP (e.g. cost per page, payments means
- available, etc.) The information contained herein is meant to be
- generic. There may not be an exact wording or terminology match
- between these scenarios and the implementation documents.
-
-10.1. PRINTER DISCOVERY WITHIN AN ENTERPRISE
-
- A user wants to find a color Postscript printer in his/her enterprise
- which will print transparencies. The client, directory service, and
- printer are all behind the same corporate firewall. Because color
- foils are expensive, printers of this type are access controlled and
- require an account to be established so that printing can be billed
- back to the using department. Note the request to find a printer
- usable by Dept. J15. Drivers for all supported printers are
- available from the server they are associated with. A help desk is
- provided for end user support. The printer is unattended.
-
- Client Directory Service
-
- +---------------------------------------------------------- >
- Find a printer with these characteristics
- - prints color, prints transparencies
- - prints Postscript
- - is in building 003
- - accessible by the client
-
- < ----------------------------------------------------------+
- Printer "Color-A"
- - prints color, prints transparencies
- - prints Postscript
- - in room H-6, building 003
- - driver ABC-Postscript-V1.3 required, here is URI
- - cost is $.45 per page for color transparencies
- - limit is 10 pages per job
- - authentication required to use printer
- - printer is unattended
- - help desk at x5001
-
- Printer "Color-B"
- - prints color, prints transparencies
- - prints Postscript
- - in room J-10, building 003
-
-
-
-Wright Experimental [Page 20]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- - driver XYZ-Postscript-V2.4 required, here is URI
- - cost is $1.25 page for color transparencies
- - limit is 5 pages per job
- - authentication is required to use printer
- - printer is unattended
- - help desk at x5001
-
-10.2. PRINTER DISCOVERY ACROSS ENTERPRISES
-
- A user in Company A wants to find a public printer in a business
- partner's enterprise (Company B) on which to print a purchase order.
- The client is behind one corporate firewall and the directory service
- and the printer are behind a different corporate firewall. Drivers
- for all supported printers are available from the server they are
- associated with. A web page is provided for end user support for
- public printers.
-
- Client Company B Directory Service
-
- +---------------------------------------------------------- >
- Find a printer with these characteristics
- - prints black and white
- - is in El Segundo, building A
- - is a public printer
-
- < ----------------------------------------------------------+
- Printer "Public-A"
- - prints black and white
- - prints Postscript
- - in El Segundo, room H-6, building A
- - driver ABC-Postscript-V1.3 required, here is URI
- - printer is public
- - help available at http://xerox/elSegundo/publicPrinters
-
- Printer "Public-B"
- - prints black and white
- - prints PCL/5e
- - is in El Segundo, room J-10, building A
- - driver XYZ-PCL-V2.4 required, here is URI
- - printer is public
- - help available at http://xerox/elSegundo/publicPrinters
-
-10.3. PRINTER DISCOVERY ON THE INTERNET -LOGICAL OPERATIONS
-
- A student wants to print a paper on a printer at his neighborhood
- Ink-o's print shop. The report was written using Microsoft Word. The
- student is interested in the cost of printing since his budget is
- limited. Note the use of logical operators to find this information.
-
-
-
-Wright Experimental [Page 21]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- Client Ink-o's Directory Service
-
- +---------------------------------------------------------- >
- Find a Printer with these characteristics
- - prints color or black and white
- - costs less than $.50 per page
- - tell me about resolution and marking technology
-
- < ----------------------------------------------------------+
- Printer "Color-A"
- - prints color
- - 600 dpi laser printer
- - prints Postscript
- - driver ABC-Postscript-V1.3 required, here is URI
- - cost is $.50 per page for color
- - payment required prior to submitting print job
- - here is URI for more information on Ink-o's
-
- Printer "Mono-B"
- - prints black and white
- - 300 dpi inkjet printer
- - prints Postscript
- - driver XYZ-Postscript-V2.4 required, here is URI
- - cost is $0.35 page for black and white
- - payment required prior to submitting print job
- - here is URI for more information on Ink-o's
-
-10.4. PRINTER DISCOVERY ON THE INTERNET - AUTHENTICATION
-
- An executive in her hotel room is finishing an important presentation
- on her laptop computer. She connects to a local print shop through
- the web to get a copy of her charts printed for tomorrow's
- presentation. She must find a print shop that is convenient to her
- hotel and can print color transparencies. She wants to be sure that
- the printer can be authenticated and can accept encrypted data.
-
- Client SirZippy Directory Service
-
- +---------------------------------------------------------- >
- Find a Printer with these characteristics
- - prints color transparencies
- - is in Boulder, Colorado
- - Printer can be authenticated
- - Printer supports encryption
-
-
-
-
-
-
-
-Wright Experimental [Page 22]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- Tell me when you are open for business
-
- < ----------------------------------------------------------+
- Printer "Color-A"
- - prints color transparencies
- - prints Postscript
- - driver ABC-Postscript-V1.3 required, here is URI
- - payment required prior to submitting print job
- - Printer can be authenticated
- - Data can be encrypted
- - Located at 1670 Pearl Street, Boulder, CO
- - This Branch is open 24 hours a day
-
-
- Printer "Color-B"
- - prints color transparencies
- - prints Postscript
- - driver ABC-Postscript-V1.3 required, here is URI
- - payment required prior to submitting print job
- - Printer can be authenticated
- - Data can be encrypted
- - Located at 1220 Arapahoe, Boulder, CO
- - This Branch is open from 9:00 am to 6:30 pm
-
-10.5. DRIVER DOWNLOAD
-
- An end user in an enterprise wants to print a lengthy report on a
- newly installed high speed PostScript printer. Since she will likely
- use this printer often, she would like to download a driver and
- install it on her workstation. She is running Windows 95. Note:
- Driver download is not a V1.0 design goal.
-
- Client IPP Printer
-
- +---------------------------------------------------------- >
- Tell me where to find print drivers for you
-
-
-
- < ----------------------------------------------------------+
- Driver install file is at
- http://www.ibm.com/drivers/NP12a/Win95
-
-
-
-
-
-
-
-
-
-Wright Experimental [Page 23]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
-10.6. SUBMITTING A PRINT JOB AS A FILE
-
- An end-user wants to submit a print job. The print file already
- exists on his workstation. The client and printer are behind the same
- corporate firewall. The printer is available to anyone behind the
- firewall and no authorization or authentication is required. The data
- is pushed to the printer. The printer is capable of spooling the
- output. No errors occur.
-
- Client IPP Printer
-
- +---------------------------------------------------------- >
- Here is a print job
- - job name = MyJob
- - notify me by email when done printing
- - print on iso-a4-white paper
- - print on both sides of the paper
- - return status of the printer in response
- - document is in Postscript format
- - here is the document to print
-
- < ----------------------------------------------------------+
- Print job accepted and spooled
- - job id = #12345
- - current state of print job = spooled
- - submission time = 02/12/97, 15:35
- - printer state = printing
-
-10.7. SUBMITTING A PRINT JOB WITH TWO DOCUMENTS
-
- An end-user wants to submit a print job. The print file already
- exists on his workstation. The client and printer are behind the same
- corporate firewall. The printer is available to anyone behind the
- firewall and no authorization or authentication is required. The data
- is pushed to the printer. The job consists of two separate documents.
- The printer is capable of spooling the output. No errors occur.
-
- Client IPP Printer
-
- +---------------------------------------------------------- >
- Here is a print job
- - job name = MyJob
- - notify me by email when done printing
- - print on iso-a4-white paper
- - print on both sides of the paper
- - return status of the printer in response
-
- < ----------------------------------------------------------+
-
-
-
-Wright Experimental [Page 24]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- Print job accepted and spooled
- - job id = #12345
- - submission time = 02/12/97, 15:35
- +---------------------------------------------------------- >
- - here is the document to print
-
- < ----------------------------------------------------------+
- - OK
-
- +---------------------------------------------------------- >
- - here is the document to print, it is the last document.
-
- < ----------------------------------------------------------+
- - OK
-
-10.8. SUBMITTING A PRINT JOB AS A FILE, PRINTING FAILS
-
- An end-user wants to submit a print job. The print file already
- exists on his workstation. The client and printer are behind the same
- corporate firewall. The printer is available to anyone behind the
- firewall and no authorization or authentication is required. The data
- is pushed to the printer. The printer is not capable of spooling the
- output so it begins printing while still receiving the file. An error
- occurs and the printer cannot complete printing (in this case the
- user requires A4 paper and that paper size is not available on the
- printer.)
-
- Client IPP Printer
-
- +---------------------------------------------------------- >
- Here is a print job
- - job name = MyJob
- - notify me by email when done printing
- - print on iso-a4-white paper
- - print on both sides of the paper
- - return status of the printer in response
- - document is in Postscript format
- - here is the document to print
-
- < ----------------------------------------------------------+
- Print job accepted
-
- - printing failed
- - current state of print job = canceled (A4 not available)
- - submission time = 02/12/97, 15:35
- - printer state = ready
-
-
-
-
-
-Wright Experimental [Page 25]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
-10.9. SUBMITTING A PRINT JOB WITH AUTHENTICATION, PRIVACY AND PAYMENT
-
- A traveling executive needs to print a set of transparencies for an
- important business meeting. The charts are in Lotus Freelance format
- on his notebook computer. He has located a SirZippy print shop near
- his hotel that will print color transparencies. Because the
- information on the charts is sensitive, he wants to be sure that his
- data is sent to the Printer in an encrypted format. He also wants to
- authenticate the Printer. The Printer also authenticates the user.
- Payment occurs across the Internet.
-
- Client IPP Printer
-
- +---------------------------------------------------------- >
- < ----------------------------------------------------------+
-
- Mutual authentication and exchange of secret keys
-
- +---------------------------------------------------------- >
- Here is a print job (encrypted)
- - job name = MyJob
- - notify me by email when done printing
- - print on iso-a4-white paper
- - print on both sides of the paper
- - return status of the printer in response
- - tell me where to pick up output
- - document is in Postscript format
- - here is the document to print
-
- < ----------------------------------------------------------+
- Print job accepted and spooled (encrypted)
- - job id = #12345
- - current state of print job = spooled
- - submission time = 02/12/97, 15:35
- - printer state = printing
- - payment required to proceed with job
- - pick up at 230 East Main after 3:30 pm today
-
- +---------------------------------------------------------- >
- < ----------------------------------------------------------+
- Payment transaction
-
-
-
-
-
-
-
-
-
-
-Wright Experimental [Page 26]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
-10.10. SUBMITTING A PRINT JOB WITH DECRYPTION ERROR
-
- A traveling executive needs to print a set of transparencies for an
- important business meeting. The charts are in Lotus Freelance format
- on his notebook computer. He has located a SirZippy print shop near
- his hotel that will print color transparencies. Because the
- information on the charts is sensitive, he wants to be sure that his
- data is sent to the printer in an encrypted format. He also wants to
- authenticate the printer. The printer also authenticates the user.
- Payment occurs across the Internet. An error occurs during
- decryption.
-
- Client IPP Printer
-
- +---------------------------------------------------------- >
- < ----------------------------------------------------------+
- Mutual authentication and exchange of secret keys
-
-
- +---------------------------------------------------------- >
- Here is a print job (encrypted)
- - job name = MyJob
- - notify me by email when done printing
- - print on iso-a4-white paper
- - print on both sides of the paper
- - return status of the printer in response
- - tell me where to pick up output
- - document is in Postscript format
- - here is the document to print
-
- < ----------------------------------------------------------+
- Print job accepted and spooled (encrypted)
- - job id = #12345
- - current state of print job = spooled
- - submission time = 02/12/97, 15:35
- - printer state = printing
- - payment required to proceed with job
- - pick up at 230 East Main after 3:30 pm today
-
- +---------------------------------------------------------- >
- < ----------------------------------------------------------+
- Payment transaction
- .
- .
- .
- < ----------------------------------------------------------+
- Asynchronous response (email in this case)
- - decryption failed on job #12345
-
-
-
-Wright Experimental [Page 27]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- - no pages printed
- - current state of job = aborted
-
-10.11. SUBMITTING A PRINT JOB WITH AUTHENTICATION
-
- An end-user wants to submit a print job. The print file already
- exists on his workstation. The client and printer are behind the same
- corporate firewall. The printer is available to anyone behind the
- firewall but authentication and authorization is required.
- Authorization takes place using the authenticated end-user's name.
- The data is pushed to the printer. The printer is capable of spooling
- the output.
-
- Client IPP Printer
-
- +---------------------------------------------------------- >
- < ----------------------------------------------------------+
- Authentication
-
- Note: An authentication failure would end the transaction at
- this point.
-
- +---------------------------------------------------------- >
- Here is a print job
- - job name = MyJob
- - notify me by email when done printing
- - print on iso-a4-white paper
- - print on both sides of the paper
- - return status of the printer in response
- - tell me where to pick up output
- - document is in Postscript format
- - here is the document to print
-
- < ----------------------------------------------------------+
- Print job accepted and spooled
- - job id = #12345
- - current state of print job = spooled
- - submission time = 02/12/97, 15:35
- - printer state = printing
-
-
-
-
-
-
-
-
-
-
-
-
-Wright Experimental [Page 28]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
-10.12. SUBMITTING A PRINT JOB GENERATED DYNAMICALLY
-
- An end-user wants to submit a print job. The print data is generated
- dynamically and is being transmitted by a printer driver on the
- client workstation as available. The client and printer are behind
- the same corporate firewall. The printer is available to anyone
- behind the firewall and no authentication and authorization is
- required. The data is pushed to the printer. The printer is capable
- of spooling the output. No error occurs.
-
- Client IPP Printer
-
- +---------------------------------------------------------- >
- Here is a print job
- - job name = MyJob
- - notify me by email when done printing
- - print on iso-a4-white paper
- - print on both sides of the paper
- - return status of the printer in response
- - document is in Postscript format
- - here is the print job
-
-
- < ----------------------------------------------------------+
- Print data accepted and spooling started
- - job id = #12345
- - current job state = spooled
- - submission time = 02/12/97, 15:35
- - printer state = printing
-
-10.13. SUBMITTING A PRINT JOB WITH A PRINTER JAM - CANCELED
-
- An end-user wants to submit a print job. The print data is generated
- dynamically and is being transmitted by a printer driver on the
- client workstation as available. The client and printer are behind
- the same corporate firewall. The printer is available to anyone
- behind the firewall and no authentication and authorization is
- required. The data is pushed to the printer. The printer is not
- capable of spooling the output. The printer jams notifies the user
- and the user chooses to cancel the job.
-
- Client IPP Printer
- +---------------------------------------------------------- >
- Here is a print job
- - job name = MyJob
- - notify me by email when done printing
- - print on iso-a4-white paper
- - print on both sides of the paper
-
-
-
-Wright Experimental [Page 29]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- - return status of the printer in response
- - document is in Postscript format
- - here is the document to print
-
- < ----------------------------------------------------------+
- Print data accepted and printing started
- - job id = #12345
-
- +---------------------------------------------------------- >
- - What is the status of print job #12345?
-
- < --------------------------------------------------------- +
- - Job #12345 accepted but printer jammed, cannot continue
-
- +---------------------------------------------------------- >
- - Cancel job #12345
-
- * Printer flushes remaining data
- < ----------------------------------------------------------+
- Print job terminated
- - current job state = canceled
- - submission time = 02/12/97, 15:35
- - printer state = jammed
-
-10.14. SUBMITTING A PRINT JOB WITH A PRINTER JAM - RECOVERED
-
- An end-user wants to submit a print job. The print data is generated
- dynamically and is being transmitted by a printer driver on the
- client workstation as available. The client and printer are behind
- the same corporate firewall. The printer is available to anyone
- behind the firewall and no authentication and authorization is
- required. The data is pushed to the printer. The printer is not
- capable of spooling the output. The printer jams, notifies the user
- and the user clears the jam and elects to continue.
-
- Client IPP Printer
-
- +---------------------------------------------------------- >
- Here is a print job
- - job name = MyJob
- - notify me by email when done printing
- - print on iso-a4-white paper
- - print on both sides of the paper
- - return status of the printer in response
- - document is in Postscript format
- - here is the document to print
-
- < ----------------------------------------------------------+
-
-
-
-Wright Experimental [Page 30]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- Print data accepted and printing started
- - job id = #12345
-
- < --------------------------------------------------------- +
- - Notification: printer jammed, cannot continue
-
- * Jam is clear by human intervention, printing continues
-
- +---------------------------------------------------------- >
- Here is the last part of the document to print
-
- < ----------------------------------------------------------+
- Print job received
- - current job state = printing
- - submission time = 02/12/97, 15:35
- - printer state = printing
-
-10.15. SUBMITTING A PRINT JOB WITH SERVER PULL
-
- An end-user wants to submit a print job. The print data is in a file
- and is publicly available. It is pulled by the printer. The client
- and printer are behind the same corporate firewall. The printer is
- available to anyone behind the firewall and no authentication and
- authorization is required. The printer is capable of spooling the
- output. Printing may start before the entire job has been pulled.
-
- Client IPP Printer
-
- +---------------------------------------------------------- >
- Here is a print job
-
- - job name = MyJob
- - notify me by email when done printing
- - print on iso-a4-white paper
- - print on both sides of the paper
- - return status of the printer in response
- - here is a reference to the data to be printed
-
- < ----------------------------------------------------------+
- Print data accepted and printing started
- - job id = #12345
- - current state of job = spooled
- - submission time = 02/12/97, 13:15
- - printer state = printing
-
- .
- .
- < ----------------------------------------------------------+
-
-
-
-Wright Experimental [Page 31]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- Get the file to be printed
-
- +---------------------------------------------------------- >
- Here it is
-
- Note: Failure to find the file, would end the transaction
- with an error at this point and an asynchronous
- notification would be send to the Client.
-
- < ----------------------------------------------------------+
- Data received
-
-10.16. SUBMITTING A PRINT JOB WITH REFERENCED RESOURCES
-
- An end-user wants to submit a print job. Part of the print data is
- on a file on the user's workstation. It is pushed by the client, but
- the print job requires some resource not included in the print file.
- The client and printer are behind the same corporate firewall. The
- printer is available to anyone behind the firewall and no
- authentication and authorization is required. The printer is capable
- of spooling the output. No errors occur.
-
- Client IPP Printer
-
- +---------------------------------------------------------- >
- Here is a print job
- - job name = MyJob
- - notify me by email when done printing
- - print on iso-a4-white paper
- - print on both sides of the paper
- - return status of the printer in response
-
- < ----------------------------------------------------------+
- Print job accepted and spooled
- - job id = #12345
- - submission time = 02/12/97, 15:35
-
- +---------------------------------------------------------- >
- - here is the document to print
-
- < ----------------------------------------------------------+
- - OK
-
- +---------------------------------------------------------- >
- - here is the URI to print, it is the last document.
-
- < ----------------------------------------------------------+
- - OK
-
-
-
-Wright Experimental [Page 32]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- < ----------------------------------------------------------+
- Get the external resource
-
- +---------------------------------------------------------- >
- Here it is
-
-10.17. GETTING CAPABILITIES
-
-10.17.1. Submission Attributes
-
- An end-user wants to get the production and scheduling attributes
- that are supported or required when submitting jobs to this printer.
- The client will use these attributes when forming the subsequent
- print request.
-
- Client IPP Printer
- +---------------------------------------------------------- >
- I'm going to submit a Postscript job
- give me your job submission attributes
-
- < ----------------------------------------------------------+
- Postscript production attributes for this Printer are:
- - medium-select = us-letter-white, us-legal-white
- - default is us-letter-white
- - copies = 1,2,3,4,5
- - default is 1
- - print-quality = draft, normal, high
- - default is draft
- - sides = 1-sided, 2-sided-long-edge
- - default is 2-sided-long-edge
- - Job scheduling attributes for this Printer are:
- - job-priority = 1,2,3
- - default = 3
-
-10.17.2. Printer Capabilities
-
- An end-user wants to determine the resolution, marking technology,
- and PDLs supported by the printer.
-
- Client IPP Printer
- +---------------------------------------------------------- >
- Please tell me the
- - resolution of the printer
- - the marking technology of the printer
- - PDLs supported
- < ----------------------------------------------------------+
- Printer resolution = 600 dpi
- Marking Technology = laser
-
-
-
-Wright Experimental [Page 33]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- PDLs supported = Postscript level 2, PCL/6
-
-10.18. GETTING STATUS
-
-10.18.1. Printer State/Status
-
- An end-user wants to determine the state or status of the printer.
-
- Client IPP Printer
-
- +---------------------------------------------------------- >
- What is the state of the printer?
-
- < ----------------------------------------------------------+
- Printer state = out-of-paper
-
-10.18.2. Job Status
-
- An end user wants to get the status of a job he has submitted.
-
- Client IPP Printer
-
- +---------------------------------------------------------- >
- Please tell me the status of job #12345
-
- < ----------------------------------------------------------+
- Job #12345 is queued
- it is number 3 in the queue
- printer state = printing
-
-10.18.3. Status of All My Jobs
-
- An end user wants to get a list of all of the jobs he has submitted
- to this Printer.
-
- Client IPP Printer
-
- +---------------------------------------------------------- >
- Please tell me the status of my jobs
-
- < ----------------------------------------------------------+
- Job #00012 is complete
- Printed at 12:35 on 01/23/97
-
- Job #09876 is printing
-
- Job #12345 is queued
- it is number 3 in the queue
-
-
-
-Wright Experimental [Page 34]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- Job #34567 is queued
- it is number 7 in the queue
-
-10.19. ASYNCHRONOUS NOTIFICATION
-
-10.19.1. Job Completion
-
- An end-user wants to get notification of events that affect his print
- jobs. Print job completes without error.
-
- Client IPP Printer
-
- < ----------------------------------------------------------+
- Print job #123 completed
-
-10.19.2. Job Complete with Data
-
- An end-user wants to get notification of events that affect his print
- jobs. Print job completes, users asked for all end of job
- information.
-
- Client IPP Printer
-
- < ----------------------------------------------------------+
- Print job #123 completed
- - total pages printed = 15
- - number of copies printed = 3
- - total cost to print = $7.45
- - pick up copies in room H-6, building 005
-
-10.19.3. Print Job Fails
-
- An end-user wants to get notification of events that affect his print
- jobs. Print job fails. Printer is unattended.
-
- Client IPP Printer
-
- < ----------------------------------------------------------+
- Print job #123 failed
- - total pages printed = 15
- - number of pages submitted = 25
- - printer-state = jammed
-
-
-
-
-
-
-
-
-
-Wright Experimental [Page 35]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
-10.20. CANCEL A JOB
-
- The end-user submits a print job and later decides to cancel it.
-
- Client IPP Printer
-
- +---------------------------------------------------------- >
- < ----------------------------------------------------------+
- Authentication.
-
-
- +---------------------------------------------------------- >
- Cancel job #1234
-
- < ----------------------------------------------------------+
- Job #1234 Canceled
-
-
-10.21. END TO END SCENARIO - WITHIN AN ENTERPRISE
-
- An office worker prints on shared departmental printers. All printers
- in the office are public, that is, no authentication or authorization
- is required. Printers are protected from external access by a
- firewall. No billing or accounting is required. Most printing is done
- from desktop applications. A help desk is provided for printing
- problems. Standard operating systems and applications are used.
- Drivers are available, but are installed manually by support
- personnel. This scenario assumes that drivers have been installed and
- that drivers are not IPP aware, that is, they cannot communicate
- across an IPP connection to obtain status and capabilities. IPP
- printers appear in application pull-down menus. Printer
- configuration data is hard wired into the driver.
-
- End-user selects print from the application pull down menu. An IPP
- printer is selected from the list of Printers offered
-
- The driver puts up a dialogue with hard-wired set of options for this
- printer. The end-user makes choices and submits job.
-
- Client IPP Printer
- +---------------------------------------------------------- >
- Here is a print job
- - job-name = memo-to-boss
- - notify me by email when job is complete
- - print on us-letter-white paper
- - print 1 copy
- - print at normal quality
- - print on 1 side
-
-
-
-Wright Experimental [Page 36]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- - give me the state of the printer in response
-
- The driver generates the print data and passes it to the IPP driver a
- piece at a time as it is generated.
-
- +---------------------------------------------------------- >
- Here is the print data
-
-
- < ----------------------------------------------------------+
- Print data received, file is spooled
- - printer state = printing
- - time submitted = 2/12/97, 15:35
- - current job state = spooled
-
- Client adds this job to list of current jobs. List of jobs and state
- of each is available on a pull-down menu on the client.
-
- End-user selects job #1234 from list and clicks on it to see its
- status.
-
- +---------------------------------------------------------- >
- Give me the state of job #1234
- and the state of the Printer
-
- < ----------------------------------------------------------+
- Job #1234 state = spooled
- - it is number 3 in the queue
- - printer state = printing
-
- The job completes without error
-
- < ----------------------------------------------------------+
- Job #1234 completed
- 12 of 12 pages printed
-
-10.22. END TO END SCENARIO - ACROSS ENTERPRISES
-
- An office worker in Company A needs to print an office document on a
- "public" printer at Company B, a business partner. Both companies
- have corporate firewalls so the print request must flow out of A's
- firewall and into B's firewall. The office worker can look at public
- printers in Company B's directory service. The document is generated
- by a desktop application. Since the printer is "public" no
- authentication or authorization is required. A driver is downloaded.
- The driver is IPP aware, that is, it can communicate dynamically
- through the IPP protocol layer to obtain information about the
- printer.
-
-
-
-Wright Experimental [Page 37]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- Client Company B's Directory Service
-
- End user connects to B's Directory service
-
- +---------------------------------------------------------- >
- Find a Printer with these characteristics
- - public (no authorization or authentication required)
- - is in Lexington, building 004
- - prints black and white
-
- < ----------------------------------------------------------+
- Printer "Public-A"
- - http://www.lexmark.com/pubprinter/a
-
- Printer "Public-B"
- - http://www.lexmark.com/pubprinter/b
-
- End user selects Public-A
-
- Client Public-A
-
- +---------------------------------------------------------- >
- Where can I find a driver for you?
-
- < ----------------------------------------------------------+
- Drivers at http://www.lexmark.com/pubprinters/a/os245
-
- End user gets driver and installs it on his PC.
-
- End-user selects print from the application pull down menu. "Public-
- A" is selected from the list of Printers offered
-
- +---------------------------------------------------------- >
- I'm going to submit a print job
- give me your job submission attributes
-
- < ----------------------------------------------------------+
-
- Production attributes for this Printer are:
- - medium-select = us-letter-white, us-legal-white
- - default is us-letter-white
- - copies = 1,2,3,4,5
- - default is 1
- - print-quality = draft, normal, high
- - default is draft
- - sides = 1-sided, 2-sided-long-edge
- - default is 2-sided-long-edge
-
-
-
-
-Wright Experimental [Page 38]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- Job scheduling attributes for this Printer are:
- - job-priority = 1,2,3
- default = 3
-
- Driver puts up dialogue with available options and fills in the
- defaults.
-
- End-user makes choices and submits job
-
- +---------------------------------------------------------- >
- Here is a print job
- - job-name = memo-to-Don-Wright
- - notify me by email when job is complete
- - print on us-letter-white paper
- - print 1 copy
- - print at normal quality
- - print on 1 side
- - give me the state of the printer in response
-
-
- The driver generates the print data and passes it to the IPP driver a
- piece at a time.
-
- +---------------------------------------------------------- >
- Here is the print data
-
- < ----------------------------------------------------------+
- Print data received, and spooling started
- print job id = #1234
-
- Print data received, file is spooled
-
- - printer state = printing
- - time submitted = 2/12/97, 15:35
- - current job state = spooled
-
- Client adds this job to list of current jobs. List of jobs and state
- of each is available on a pull-down menu on the client.
-
- End-user selects job #1234 from list and clicks on it to see its
- status.
-
- +---------------------------------------------------------- >
- Give me the state of job #1234
- and the state of the Printer
-
- < ----------------------------------------------------------+
- Job #1234 state = spooled
-
-
-
-Wright Experimental [Page 39]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- - it is number 3 in the queue
- - printer state = printing
-
- * The job completes without error
- < ----------------------------------------------------------+
- Job #1234 completed
- 12 of 12 pages printed
-
-10.23. END TO END SCENARIO - ON THE INTERNET
-
- An executive in her hotel room is finishing an important presentation
- on her laptop computer. She connects to a local print shop through
- the web to get a copy of her charts printed for tomorrow's
- presentation. She must find a print shop that is convenient and can
- print color transparencies. She must download and temporarily install
- a driver in order to generate the PDL required by the print shop.
- Mutual authentication is required by the print shop and payment must
- be made in advance. The job is encrypted on the wire to prevent
- eavesdropping.
-
- End-user completes presentation. She goes to the web and connects to
- the SirZippy home page.
-
- Client SirZippy Directory Service
- +---------------------------------------------------------- >
-
- Find me a printer with these characteristics
- - Near Market Street in San Jose
- - Prints color transparencies
- - drivers can be downloaded
- - supports privacy (encryption)
- -
-
- Available Printers matching these characteristics are looked up in the
- Directory Service
-
- < ----------------------------------------------------------+
-
- Printer "Color-A"
- - located at 123 First Street in San Jose
- - URI is http://www.SirZippy.com/FirstStreet/Color-A
- - prints color transparencies
- - 600 dpi laser
- - driver ABC-Postscript-V1.3 available at this URI
- - cost = $.75 per page
- - authentication required to use printer
- - payment required prior to printing
-
-
-
-
-Wright Experimental [Page 40]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- Printer "Color-B"
- - located at 67 San Carlos Street, San Jose
- - URI is http://www.SirZippy.com/SanCarlos/Color-B
- - prints color transparencies
- - 1200 dpi laser
- - driver XYZ-PostScript-V4.3 available at this URI
- - cost = $1.25 per page
- - authentication required to use printer
- - payment required prior to printing
- - more information at this URI
-
- The user decides to use the first printer because it is closer. She
- connects to the URI given to get a driver.
-
- Client Driver URI
-
- +---------------------------------------------------------- >
- I need a driver for "Color-A"
-
-
- < ----------------------------------------------------------+
- Driver installer is at http://www.xerox.com/prtdrvrs
-
- Driver is installed
-
- User connects to
- "Color-A"
-
- Client IPP Printer "Color-A"
-
- +---------------------------------------------------------- >
- < ----------------------------------------------------------+
- Mutual authentication and exchange of secret keys
-
- +---------------------------------------------------------- >
- I'm going to submit a print job
- give me your job submission attributes
-
- < ----------------------------------------------------------+
- Production attributes for this Printer are:
- - medium-select = us-letter-white, us-legal-white
- - default is us-letter-white
- - copies = 1,2,3,4,5
- - default is 1
- - print-quality = draft, normal, high
- - default is draft
- - sides = 1-sided, 2-sided-long-edge
- - default is 2-sided-long-edge
-
-
-
-Wright Experimental [Page 41]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
- Job scheduling attributes for this Printer are:
- - job-priority = 1,2,3
- default = 3
-
- Driver puts up dialogue with available options and fills in the
- defaults.
-
- End-user makes choices and submits job
-
- +---------------------------------------------------------- >
- Here is a print job
-
- - job-name = presentation
- - notify me by email when job is complete
- - print on us-letter-transparency
- - print 1 copy
- - print at high quality
- - print by 9:00 am tomorrow morning
- - give me the state of the printer in response
-
- The driver generates the print data and passes it to the IPP driver a
- piece at a time.
-
- +---------------------------------------------------------- >
- Here is the print data
-
- < ---------------------------------------------------------+
- Print data received, and spooling started
- print job id = #1234
-
- Print data received, file is spooled
- - printer state = printing
- - time submitted = 2/12/97, 15:35
- - current job state = held, waiting for payment
-
- +---------------------------------------------------------- >
- < ----------------------------------------------------------+
- Payment transaction
-
- < ----------------------------------------------------------+
- Job is scheduled to print, pick up after 9:00am tomorrow
- Thank you for using SirZippy
-
-
-
-
-
-
-
-
-
-Wright Experimental [Page 42]
-\f
-RFC 2567 Internet Printing Design Goals April 1999
-
-
-11. Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Wright Experimental [Page 43]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group S. Zilles
-Request for Comments: 2568 Adobe Systems Inc.
-Category: Experimental April 1999
-
-
- Rationale for the Structure of the Model and Protocol
- for the Internet Printing Protocol
-
-Status of this Memo
-
- This memo defines an Experimental Protocol for the Internet
- community. It does not specify an Internet standard of any kind.
- Discussion and suggestions for improvement are requested.
- Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-IESG Note
-
- This document defines an Experimental protocol for the Internet
- community. The IESG expects that a revised version of this protocol
- will be published as Proposed Standard protocol. The Proposed
- Standard, when published, is expected to change from the protocol
- defined in this memo. In particular, it is expected that the
- standards-track version of the protocol will incorporate strong
- authentication and privacy features, and that an "ipp:" URL type will
- be defined which supports those security measures. Other changes to
- the protocol are also possible. Implementors are warned that future
- versions of this protocol may not interoperate with the version of
- IPP defined in this document, or if they do interoperate, that some
- protocol features may not be available.
-
- The IESG encourages experimentation with this protocol, especially in
- combination with Transport Layer Security (TLS) [RFC2246], to help
- determine how TLS may effectively be used as a security layer for
- IPP.
-
-ABSTRACT
-
- This document is one of a set of documents, which together describe
- all aspects of a new Internet Printing Protocol (IPP). IPP is an
- application level protocol that can be used for distributed printing
- using Internet tools and technologies. This document describes IPP
- from a high level view, defines a roadmap for the various documents
- that form the suite of IPP specifications, and gives background and
- rationale for the IETF working group's major decisions.
-
-
-
-Zilles Experimental [Page 1]
-\f
-RFC 2568 Rationale for IPP April 1999
-
-
- The full set of IPP documents includes:
-
- Design Goals for an Internet Printing Protocol [RFC2567]
- Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol (this document)
- Internet Printing Protocol/1.0: Model and Semantics [RFC2566]
- Internet Printing Protocol/1.0: Encoding and Transport [RFC2565]
- Internet Printing Protocol/1.0: Implementer's Guide [ipp-iig]
- Mapping between LPD and IPP Protocols [RFC2569]
-
- The "Design Goals for an Internet Printing Protocol" document takes a
- broad look at distributed printing functionality, and it enumerates
- real-life scenarios that help to clarify the features that need to be
- included in a printing protocol for the Internet. It identifies
- requirements for three types of users: end users, operators, and
- administrators. The Design Goals document calls out a subset of end
- user requirements that are satisfied in IPP/1.0. Operator and
- administrator requirements are out of scope for version 1.0.
-
- The "Internet Printing Protocol/1.0: Model and Semantics" document
- describes a simplified model consisting of abstract objects, their
- attributes, and their operations that is independent of encoding and
- transport. The model consists of a Printer and a Job object. The
- Job optionally supports multiple documents. This document also
- addresses security, internationalization, and directory issues.
-
- The "Internet Printing Protocol/1.0: Encoding and Transport" document
- is a formal mapping of the abstract operations and attributes defined
- in the model document onto HTTP/1.1. It defines the encoding rules
- for a new Internet media type called "application/ipp".
-
- The "Internet Printing Protocol/1.0: Implementer's Guide" document
- gives insight and advice to implementers of IPP clients and IPP
- objects. It is intended to help them understand IPP/1.0 and some of
- the considerations that may assist them in the design of their client
- and/or IPP object implementations. For example, a typical order of
- processing requests is given, including error checking. Motivation
- for some of the specification decisions is also included.
-
- The "Mapping between LPD and IPP Protocols" document gives some
- advice to implementers of gateways between IPP and LPD (Line Printer
- Daemon) implementations.
-
-1. ARCHITECTURAL OVERVIEW
-
- The Internet Printing Protocol (IPP) is an application level protocol
- that can be used for distributed printing on the Internet. This
- protocol defines interactions between a client and a server. The
-
-
-
-Zilles Experimental [Page 2]
-\f
-RFC 2568 Rationale for IPP April 1999
-
-
- protocol allows a client to inquire about capabilities of a printer,
- to submit print jobs and to inquire about and cancel print jobs. The
- server for these requests is the Printer; the Printer is an
- abstraction of a generic document output device and/or a print
- service provider. Thus, the Printer could be a real printing device,
- such as a computer printer or fax output device, or it could be a
- service that interfaced with output devices.
-
- The protocol is heavily influenced by the printing model introduced
- in the Document Printing Application (DPA) [ISO10175] standard.
- Although DPA specifies both end user and administrative features, IPP
- version 1.0 (IPP/1.0) focuses only on end user functionality.
-
- The architecture for IPP defines (in the Model and Semantics document
- [RFC2566]) an abstract Model for the data which is used to control
- the printing process and to provide information about the process and
- the capabilities of the Printer. This abstract Model is hierarchical
- in nature and reflects the structure of the Printer and the Jobs that
- may be being processed by the Printer.
-
- The Internet provides a channel between the client and the
- server/Printer. Use of this channel requires flattening and
- sequencing the hierarchical Model data. Therefore, the IPP also
- defines (in the Encoding and Transport document [RFC2565]) an
- encoding of the data in the model for transfer between the client and
- server. This transfer of data may be either a request or the
- response to a request.
-
- Finally, the IPP defines (in the Encoding and Transport document
- [RFC2565]) a protocol for transferring the encoded request and
- response data between the client and the server/Printer.
-
- An example of a typical interaction would be a request from the
- client to create a print job. The client would assemble the Model
- data to be associated with that job, such as the name of the job, the
- media to use, the number of pages to place on each media instance,
- etc. This data would then be encoded according to the Protocol and
- would be transmitted according to the Protocol. The server/Printer
- would receive the encoded Model data, decode it into a form
- understood by the server/Printer and, based on that data, do one of
- two things: (1) accept the job or (2) reject the job. In either case,
- the server must construct a response in terms of the Model data,
- encode that response according to the Protocol and transmit that
- encoded Model data as the response to the request using the Protocol.
-
- Another part of the IPP architecture is the Directory Schema
- described in the model document. The role of a Directory Schema is to
- provide a standard set of attributes which might be used to query a
-
-
-
-Zilles Experimental [Page 3]
-\f
-RFC 2568 Rationale for IPP April 1999
-
-
- directory service for the URI of a Printer that is likely to meet the
- needs of the client. The IPP architecture also addresses security
- issues such as control of access to server/Printers and secure
- transmissions of requests, response and the data to be printed.
-
-2. THE PRINTER
-
- Because the (abstract) server/Printer encompasses a wide range of
- implementations, it is necessary to make some assumptions about a
- minimal implementation. The most likely minimal implementation is one
- that is embedded in an output device running a specialized real time
- operating system and with limited processing, memory and storage
- capabilities. This printer will be connected to the Internet and will
- have at least a TCP/IP capability with (likely) SNMP [RFC1905,
- RFC1906] support for the Internet connection. In addition, it is
- likely the the Printer will be an HTML/HTTP server to allow direct
- user access to information about the printer.
-
-3. RATIONALE FOR THE MODEL
-
- The Model [RFC2566] is defined independently of any encoding of the
- Model data both to support the likely uses of IPP and to be robust
- with respect to the possibility of alternate encoding.
-
- It is expected that a client or server/Printer would represent the
- Model data in some data structure within the applications/servers
- that support IPP. Therefore, the Model was designed to make that
- representation straightforward. Typically a parser or formatter would
- be used to convert from or to the encoded data format. Once in an
- internal form suitable to a product, the data can be manipulated by
- the product. For example, the data sent with a Print Job can be used
- to control the processing of that Print Job.
-
- The semantics of IPP are attached to the (abstract) Model.
- Therefore, the application/server is not dependent on the encoding of
- the Model data, and it is possible to consider alternative mechanisms
- and formats by which the data could be transmitted from a client to a
- server; for example, a server could have a direct, client-less GUI
- interface that might be used to accept some kinds of Print Jobs. This
- independence would also allow a different encoding and/or
- transmission mechanism to be used if the ones adopted here were shown
- to be overly limiting in the future. Such a change could be migrated
- into new products as an alternate protocol stack/parser for the Model
- data.
-
-
-
-
-
-
-
-Zilles Experimental [Page 4]
-\f
-RFC 2568 Rationale for IPP April 1999
-
-
- Having an abstract Model also allows the Model data to be aligned
- with the (abstract) model used in the Printer [RFC1759], Job and Host
- Resources MIBs. This provides consistency in interpretation of the
- data obtained independently of how the data is accessed, whether via
- IPP or via SNMP [RFC1905, RFC1906] and the Printer/Job MIBs.
-
- There is one aspect of the Model that deserves some extra
- explanation. There are two ways for identifying a Job object: (a)
- with a Job URI and (b) using a combination of the Printer URI and a
- Job ID (a 32 bit positive integer). Allowing Job objects to have URIs
- allows for flexibility and scalability. For example a job could be
- moved from a printer with a large backlog to one with a smaller load
- and the job identification, the Job object URI, need not change.
- However, many existing printing systems have local models or
- interface constraints that force Job objects to be identified using
- only a 32-bit positive integer rather than a URI. This numeric Job
- ID is only unique within the context of the Printer object to which
- the create request was originally submitted. In order to allow both
- types of client access to Jobs (either by Job URI or by numeric Job
- ID), when the Printer object successfully processes a create request
- and creates a new Job, the Printer object generates both a Job URI
- and a Job ID for the new Job object. This requirement allows all
- clients to access Printer objects and Job objects independent of any
- local constraints imposed on the client implementation.
-
-4. RATIONALE FOR THE PROTOCOL
-
- There are two parts to the Protocol: (1) the encoding of the Model
- data and (2) the mechanism for transmitting the model data between
- client and server.
-
-4.1 The Encoding
-
- To make it simpler to develop embedded printers, a very simple binary
- encoding has been chosen. This encoding is adequate to represent the
- kinds of data that occur within the Model. It has a simple structure
- consisting of sequences of attributes. Each attribute has a name,
- prefixed by a name length, and a value. The names are strings
- constrained to characters from a subset of ASCII. The values are
- either scalars or a sequence of scalars. Each scalar value has a
- length specification and a value tag which indicates the type of the
- value. The value type has two parts: a major class part, such as
- integer or string, and a minor class part which distinguishes the
- usage of the major class, such as dateTime string. Tagging of the
- values with type information allows for introducing new value types
- at some future time.
-
-
-
-
-
-Zilles Experimental [Page 5]
-\f
-RFC 2568 Rationale for IPP April 1999
-
-
- A fully encoded request/response has a version number, an operation
- (for a request) or a status and optionally a status message (for a
- response), associated parameters and attributes which are encoded
- Model data and, optionally (for a request), print data following the
- Model data.
-
-4.2 The Transmission Mechanism
-
- The chosen mechanism for transmitting the encoded Model data is HTTP
- 1.1 Post (and associated response). No modifications to HTTP 1.1 are
- proposed or required. The sole role of the Transmission Mechanism is
- to provide a transfer of encoded Model data from/to the client
- to/from the server. This could be done using any data delivery
- mechanism. The key reasons why HTTP 1.1 Post is used are given below.
- The most important of these is the first. With perhaps this
- exception, these reasons could be satisfied by other mechanisms.
- There is no claim that this list uniquely determines a choice of
- mechanism.
-
- 1. HTTP 1.0 is already widely deployed and, based on the recent
- evidence, HTTP 1.1 is being widely deployed as the manufacturers
- release new products. The performance benefits of HTTP 1.1 have
- been shown and manufactures are reacting positively.
-
- Wide deployment has meant that many of the problems of making a
- protocol work in a wide range of environments from local net to
- Intranet to Internet have been solved and will stay solved with
- HTTP 1.1 deployment.
-
- 2. HTTP 1.1 solves most of the problems that might have required a
- new protocol to be developed. HTTP 1.1 allows persistent
- connections that make a multi-message protocol be more efficient;
- for example it is practical to have separate Create-Job and Send-
- Document messages. Chunking allows the transmission of large print
- files without having to pre-scan the file to determine the file
- length. The accept headers allow the client's protocol and
- localization desires to be transmitted with the IPP operations and
- data. If the Model were to provide for the redirection of Job
- requests, such as Cancel-Job, when a Job is moved, the HTTP
- redirect response allows a client to be informed when a Job he is
- interested in is moved to another server/Printer for any reason.
-
- 3. Most network Printers will be implementing HTTP servers for
- reasons other than IPP. These network attached Printers want to
- provide information on how to use the printer, its current state,
- HELP information, etc. in HTML. This requires having an HTTP
- server which would be available to do IPP functions as well.
-
-
-
-
-Zilles Experimental [Page 6]
-\f
-RFC 2568 Rationale for IPP April 1999
-
-
- 4. Most of the complexity of HTTP 1.1 is concerned with the
- implementation of HTTP proxies and not the implementation of HTTP
- clients and/or servers. Work is proceeding in the HTTP Working
- Group to help identify what must be done by a server. As the
- Encoding and Transport document shows, that is not very much.
-
- 5. HTTP implementations provide support for handling URLs that
- would have to be provided if a new protocol were defined.
-
- 6. An HTTP based solution fits well with the Internet security
- mechanisms that are currently deployed or being deployed. HTTP
- will run over SSL3. The digest access authentication mechanism of
- HTTP 1.1 provides an adequate level of access control. These
- solutions are deployed and in practical use; a new solution would
- require extensive use to have the same degree of confidence in its
- security. Note: SSL3 is not on the IETF standards track.
-
- 7. HTTP provides an extensibility model that a new protocol would
- have to develop independently. In particular, the headers,
- intent-types (via Internet Media Types) and error codes have wide
- acceptance and a useful set of definitions and methods for
- extension.
-
- 8. Although not strictly a reason why IPP should use HTTP as the
- transmission protocol, it is extremely helpful that there are many
- prototyping tools that work with HTTP and that CGI scripts can be
- used to test and debug parts of the protocol.
-
- 9. Finally, the POST method was chosen to carry the print data
- because its usage for data transmission has been established, it
- works and the results are available via CGI scripts or servlets.
- Creating a new method would have better identified the intended
- use of the POSTed data, but a new method would be more difficult
- to deploy. Assigning a new default port for IPP provided the
- necessary identification with minimal impact to installed
- infrastructure, so was chosen instead.
-
-5. RATIONALE FOR THE DIRECTORY SCHEMA
-
- Successful use of IPP depends on the client finding a suitable IPP
- enabled Printer to which to send a IPP requests, such as print a
- job. This task is simplified if there is a Directory Service which
- can be queried for a suitable Printer. The purpose of the
- Directory Schema is to have a standard description of Printer
- attributes that can be associated the URI for the printer. These
- attributes are a subset of the Model attributes and can be encoded
- in the appropriate query syntax for the Directory Service being
- used by the client.
-
-
-
-Zilles Experimental [Page 7]
-\f
-RFC 2568 Rationale for IPP April 1999
-
-
-6. SECURITY CONSIDERATIONS - RATIONALE FOR SECURITY
-
- Security is an area of active work on the Internet. Complete
- solutions to a wide range of security concerns are not yet
- available. Therefore, in the design of IPP, the focus has been on
- identifying a set of security protocols/features that are
- implemented (or currently implementable) and solve real problems
- with distributed printing. The two areas that seem appropriate to
- support are: (1) authorization to use a Printer and (2) secure
- interaction with a printer. The chosen mechanisms are the digest
- authentication mechanism of HTTP 1.1 and SSL3 [SSL] secure
- communication mechanism.
-
-7. REFERENCES
-
- [ipp-iig] Hastings, T. and C. Manros, "Internet Printing
- Protocol/1.0:Implementer's Guide", Work in Progress.
-
- [RFC2569] Herriot, R., Hastings, T., Jacobs, N. and J. Martin,
- "Mapping between LPD and IPP Protocols", RFC 2569, April
- 1999.
-
- [RFC2566] deBry, R., Isaacson, S., Hastings, T., Herriot, R. and P.
- Powell, "Internet Printing Protocol/1.0: Model and
- Semantics", RFC 2566, April 1999.
-
- [RFC2565] Herriot, R., Butler, S., Moore, P. and R. Tuner, "Internet
- Printing Protocol/1.0: Encoding and Transport", RFC 2565,
- April 1999.
-
- [RFC2567] Wright, D., "Design Goals for an Internet Printing
- Protocol", RFC 2567, April 1999.
-
- [ISO10175] ISO/IEC 10175 "Document Printing Application (DPA)", June
- 1996.
-
- [RFC1759] Smith, R., Wright, F., Hastings, T., Zilles, S. and J.
- Gyllenskog, "Printer MIB", RFC 1759, March 1995.
-
- [RFC1905] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser,
- "Protocol Operations for Version 2 of the Simple Network
- Management Protocol (SNMPv2)", RFC 1905, January 1996.
-
- [RFC1906] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser,
- "Transport Mappings for Version 2 of the Simple Network
- Management Protocol (SNMPv2)", RFC 1906, January 1996.
-
-
-
-
-
-Zilles Experimental [Page 8]
-\f
-RFC 2568 Rationale for IPP April 1999
-
-
- [SSL] Netscape, The SSL Protocol, Version 3, (Text version
- 3.02), November 1996.
-
-8. AUTHOR'S ADDRESS
-
- Stephen Zilles
- Adobe Systems Incorporated
- 345 Park Avenue
- MailStop W14
- San Jose, CA 95110-2704
-
- Phone: +1 408 536-4766
- Fax: +1 408 537-4042
- EMail: szilles@adobe.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Zilles Experimental [Page 9]
-\f
-RFC 2568 Rationale for IPP April 1999
-
-
-9. Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Zilles Experimental [Page 10]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group R. Herriot
-Request For Comments: 2569 Xerox Corporation
-Category: Experimental N. Jacobs
- Sun Microsystems, Inc.
- T. Hastings
- Xerox Corporation
- J. Martin
- Underscore, Inc.
- April 1999
-
-
- Mapping between LPD and IPP Protocols
-
-Status of this Memo
-
- This memo defines an Experimental Protocol for the Internet
- community. It does not specify an Internet standard of any kind.
- Discussion and suggestions for improvement are requested.
- Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-IESG Note
-
- This document defines an Experimental protocol for the Internet
- community. The IESG expects that a revised version of this protocol
- will be published as Proposed Standard protocol. The Proposed
- Standard, when published, is expected to change from the protocol
- defined in this memo. In particular, it is expected that the
- standards-track version of the protocol will incorporate strong
- authentication and privacy features, and that an "ipp:" URL type will
- be defined which supports those security measures. Other changes to
- the protocol are also possible. Implementors are warned that future
- versions of this protocol may not interoperate with the version of
- IPP defined in this document, or if they do interoperate, that some
- protocol features may not be available.
-
- The IESG encourages experimentation with this protocol, especially in
- combination with Transport Layer Security (TLS) [RFC 2246], to help
- determine how TLS may effectively be used as a security layer for
- IPP.
-
-
-
-
-
-
-
-
-Herriot, et al. Experimental [Page 1]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
-Abstract
-
- This document is one of a set of documents, which together describe
- all aspects of a new Internet Printing Protocol (IPP). IPP is an
- application level protocol that can be used for distributed printing
- using Internet tools and technologies. This document gives some
- advice to implementers of gateways between IPP and LPD (Line Printer
- Daemon). This document describes the mapping between (1) the commands
- and operands of the 'Line Printer Daemon (LPD) Protocol' specified in
- RFC 1179 and (2) the operations, operation attributes and job
- template attributes of the Internet Printing Protocol/1.0 (IPP). One
- of the purposes of this document is to compare the functionality of
- the two protocols. Another purpose is to facilitate implementation
- of gateways between LPD and IPP.
-
- WARNING: RFC 1179 was not on the IETF standards track. While RFC
- 1179 was intended to record existing practice, it fell short in some
- areas. However, this specification maps between (1) the actual
- current practice of RFC 1179 and (2) IPP. This document does not
- attempt to map the numerous divergent extensions to the LPD protocol
- that have been made by many implementers.
-
- The full set of IPP documents includes:
-
- Design Goals for an Internet Printing Protocol [RFC2567]
- Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol [RFC2568]
- Internet Printing Protocol/1.0: Model and Semantics [RFC2566]
- Internet Printing Protocol/1.0: Encoding and Transport [RFC2565]
- Internet Printing Protocol/1.0: Implementors Guide [ipp-iig]
- Mapping between LPD and IPP Protocols (this document)
-
- The document, "Design Goals for an Internet Printing Protocol", takes
- a broad look at distributed printing functionality, and it enumerates
- real-life scenarios that help to clarify the features that need to be
- included in a printing protocol for the Internet. It identifies
- requirements for three types of users: end users, operators, and
- administrators. It calls out a subset of end user requirements that
- are satisfied in IPP/1.0. Operator and administrator requirements are
- out of scope for version 1.0.
-
- The document, "Rationale for the Structure and Model and Protocol for
- the Internet Printing Protocol", describes IPP from a high level
- view, defines a roadmap for the various documents that form the suite
- of IPP specifications, and gives background and rationale for the
- IETF working group's major decisions.
-
-
-
-
-
-Herriot, et al. Experimental [Page 2]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
- The document, "Internet Printing Protocol/1.0: Model and Semantics",
- describes a simplified model with abstract objects, their attributes,
- and their operations. It introduces a Printer and a Job object. The
- Job object supports multiple documents per Job. It also addresses
- security, internationalization, and directory issues.
-
- The document, "Internet Printing Protocol/1.0: Encoding and
- Transport", is a formal mapping of the abstract operations and
- attributes defined in the model document onto HTTP/1.1. It defines
- the encoding rules for a new Internet media type called '
- application/ipp'.
-
- This document "Internet Printing Protocol/1.0: Implementer's Guide",
- gives advice to implementers of IPP clients and IPP objects.
-
-TABLE OF CONTENTS
-
- 1. Introduction.....................................................4
- 2. Terminology......................................................5
- 3. Mapping from LPD Commands to IPP Operations......................5
- 3.1 Print any waiting jobs..........................................6
- 3.2 Receive a printer job...........................................6
- 3.2.1 Abort job.....................................................7
- 3.2.2 Receive control file..........................................7
- 3.2.3 Receive data file.............................................8
- 3.3 Send queue state (short)........................................8
- 3.4 Send queue state (long)........................................10
- 3.5 Remove jobs....................................................12
- 4. Mapping of LPD Control File Lines to IPP Operation and Job
- Template Attributes.............................................13
- 4.1 Required Job Functions.........................................13
- 4.2 Optional Job Functions.........................................14
- 4.3 Required Document Functions....................................14
- 4.4 Recommended Document Functions.................................16
- 5. Mapping from IPP operations to LPD commands.....................16
- 5.1 Print-Job......................................................16
- 5.2 Print-URI......................................................18
- 5.3 Validate-Job...................................................18
- 5.4 Create-Job.....................................................18
- 5.5 Send-Document..................................................18
- 5.6 Send-URI.......................................................18
- 5.7 Cancel-Job.....................................................18
- 5.8 Get-Printer-Attributes.........................................19
- 5.9 Get-Job-Attributes.............................................19
- 5.10 Get-Jobs......................................................20
- 6. Mapping of IPP Attributes to LPD Control File Lines.............20
- 6.1 Required Job Functions.........................................21
- 6.2 Optional Job Functions.........................................21
-
-
-
-Herriot, et al. Experimental [Page 3]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
- 6.3 Required Document Functions....................................22
- 7. Security Considerations.........................................23
- 8. References......................................................23
- 9. Authors' Addresses..............................................24
- 10.Appendix A: ABNF Syntax for response of Send-queue-state (short)25
- 11.Appendix B: ABNF Syntax for response of Send-queue-state (long) 26
- 12.Appendix C: Unsupported LPD functions...........................27
- 13.Full Copyright Statement........................................28
-
-1. Introduction
-
- The reader of this specification is expected to be familiar with the
- IPP Model and Semantics specification [RFC2566], the IPP Encoding and
- Transport [RF2565], and the Line Printer Daemon (LPD) protocol
- specification [RFC1179] as described in RFC 1179.
-
- RFC 1179 was written in 1990 in an attempt to document existing LPD
- protocol implementations. Since then, a number of undocumented
- extensions have been made by vendors to support functionality
- specific to their printing solutions. All of these extensions
- consist of additional control file commands. This document does not
- address any of these vendor extensions. Rather it addresses existing
- practice within the context of the features described by RFC 1179.
- Deviations of existing practice from RFC 1179 are so indicated.
-
- Other LPD control file commands in RFC 1179 are obsolete. They are
- intended to work on "text" only formats and are inappropriate for
- many contemporary document formats that completely specify each page.
- This document does not address the support of these obsolete
- features.
-
- In the area of document formats, also known as page description
- languages (PDL), RFC 1179 defines a fixed set with no capability for
- extension. Consequently, some new PDL's are not supported, and some
- of those that are supported are sufficiently unimportant now that
- they have not been registered for use with the Printer MIB [RFC1759]
- and IPP [RFC2566] [RFC2565], though they could be registered if
- desired. See the Printer MIB specification [RFC1759] and/or the IPP
- Model specification [RFC2566] for instructions for registration of
- document-formats with IANA. IANA lists the registered document-
- formats as "printer languages".
-
- This document addresses the protocol mapping for both directions:
- mapping of the LPD protocol to the IPP protocol and mapping of the
- IPP protocol to the LPD protocol. The former is called the "LPD-to-
- IPP mapper" and the latter is called the "IPP-to-LPD mapper".
-
-
-
-
-
-Herriot, et al. Experimental [Page 4]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
- This document is an informational document that is not on the
- standards track. It is intended to help implementers of gateways
- between IPP and LPD. It also provides an example, which gives
- additional insight into IPP.
-
-2. Terminology
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in RFC 2119 [RFC2119].
-
- RFC 1179 uses the word "command" in two contexts: for over-the-wire
- operations and for command file functions. This document SHALL use
- the word "command" for the former and the phrase "functions" for the
- latter. The syntax of the LPD commands is given using ABNF
- [RFC2234].
-
- The following tokens are used in order to make the syntax more
- readable:
-
- LF stands for %x0A (linefeed)
- SP stands for %x20. (space)
- DIGIT stands for %x30-39 ("0" to "9")
-
-3. Mapping from LPD Commands to IPP Operations
-
- This section describes the mapping from LPD commands to IPP
- operations. Each of the following sub-sections appear as sub-
- sections of section 5 of RFC 1179.
-
- The following table summarizes the IPP operation that the mapper uses
- when it receives an LPD command. Each section below gives more
- detail:
-
- LPD command IPP operation
-
-
- print-any-waiting-jobs ignore
- receive-a-printer-job Print-Job or Create-Job/Send-Document
- send queue state Get-Printer-Attributes and Get-Jobs
- (short or long)
- remove-jobs Cancel-Job
-
-
-
-
-
-
-
-
-
-Herriot, et al. Experimental [Page 5]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
-3.1 Print any waiting jobs
-
- Command syntax:
-
- print-waiting-jobs = %x01 printer-name LF
-
- This command causes the LPD daemon check its queue and print any
- waiting jobs. An IPP printer handles waiting jobs without such a
- nudge.
-
- If the mapper receives this LPD command, it SHALL ignore it and send
- no IPP operation.
-
-3.2 Receive a printer job
-
- Command syntax:
-
- receive-job = %x02 printer-name LF
-
- The control file and data files mentioned in the following paragraphs
- are received via LPD sub-commands that follow this command. Their
- mapping to IPP commands and attributes is described later in this
- section.
-
- The mapper maps the 'Receive a printer job' command to either:
-
- - the Print-Job operation which includes a single data file or
- - the Create-Job operation followed by one Send-Document operation
- for each data file.
-
- If the IPP printer supports both Create-Job and Send-Document, and if
- a job consists of:
-
- - a single data file, the mapper SHOULD use the Print-Job
- operation, but MAY use the Create-Job and Send-Document
- operations.
- - more than one data file, the mapper SHALL use Create-Job
- followed by one Send-Document for each received LPD data file.
-
- If the IPP printer does not support both Create-Job and Send-
- Document, and if a job consists of:
-
- - a single data file, the mapper SHALL use the PrintJob
- operation.
- - more than one data file, the mapper SHALL submit each received
- LPD data file as a separate Print-Job operation (thereby
- converting a single LPD job into multiple IPP jobs).
-
-
-
-
-Herriot, et al. Experimental [Page 6]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
- If the mapper uses Create-Job and Send-Document, it MUST send the
- Create-Job operation before it sends any Send-Document operations
- whether the LPD control file, which supplies attributes for Create-
- Job, arrives before or after all LPD data files.
-
- NOTE: This specification does not specify how the mapper maps: the
- LPD Printer-name operand to the IPP "printer-uri" operation
- attribute.
-
- The following three sub-sections gives further details about the
- mapping from LPD receive-a-printer-job sub-commands. Each of the
- following subsections appear as sub-sections of section 6 of RFC
- 1179.
-
-3.2.1 Abort job
-
- Sub-command syntax:
-
- abort-job = %x1 LF
-
- This sub-command of receive-a-printer-job is intended to abort any
- job transfer in process.
-
- If the mapper receives this sub-command, it SHALL cancel the job that
- it is in the process of transmitting.
-
- If the mapper is in the process of sending a Print-Job or Create-Job
- operation, it terminates the job either by closing the connection, or
- performing the Cancel-Job operation with the job-uri that it received
- from the Print-Job or Create-Job operation.
-
- NOTE: This sub-command is implied if at any time the connection
- between the LPD client and server is terminated before an entire
- print job has been transferred via an LPD Receive-a-printer-job
- request.
-
-3.2.2 Receive control file
-
- Sub-command syntax:
-
- receive-control-file = %x2 number-of-bytes SP name-of-control-file LF
- number-of-bytes = 1*DIGIT
- name-of-control-file = "cfA" job-number client-host-name
- ; e.g. "cfA123woden"
- job-number = 3DIGIT
- client-host-name = <a host name>
-
-
-
-
-
-Herriot, et al. Experimental [Page 7]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
- This sub-command is roughly equivalent to the IPP Create-Job
- operation.
-
- The mapper SHALL use the contents of the received LPD control file to
- create IPP operation attribute and job template attribute values to
- transmit with the Print-Job or Create-Job operation.
-
-3.2.3 Receive data file
-
-Sub-command syntax: %x3 number-of-bytes-in-data-file Name-of-data-file
-
- receive-data-file = %x03 number-of-bytes SP name-of-data-file LF
- number-of-bytes = 1*DIGIT
- name-of-data-file = "df" letter job-number client-host-name
- ; e.g. "dfA123woden for the first file
- letter = %x41-5A / %x61-7A ; "A" to "Z", "a" to "z"
- ; first file is "A",
- ; second "B", and 52nd file is "z"
- job-number = 3DIGIT
- client-host-name = <a host name>
-
- This sub-command is roughly equivalent to the IPP Send-Document
- operation.
-
- The mapper SHALL use the contents of the received LPD data file as
- the data to transmit with the IPP Print-Job or Send-Document
- operation.
-
- Although RFC 1179 alludes to a method for passing an unspecified
- length data file by using an octet-count of zero, no implementations
- support this feature. The mapper SHALL reject a job that has a value
- of 0 in the number-of-bytes field.
-
-3.3 Send queue state (short)
-
- Command syntax:
-
-send-queue-short = %x03 printer-name *(SP(user-name / job-number)) LF
-
- The mapper's response to this command includes information about the
- printer and its jobs. RFC 1179 specifies neither the information nor
- the format of its response. This document requires the mapper to
- follow existing practice as specified in this document.
-
- The mapper SHALL produce a response in the following format which
- consists of a printer-status line optionally followed by a heading
- line, and a list of jobs. This format is defined by examples below.
- Appendix A contains the ABNF syntax.
-
-
-
-Herriot, et al. Experimental [Page 8]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
- For an printer with no jobs, the response starts in column 1 and is:
-
- no entries
-
- For a printer with jobs, an example of the response is:
-
- killtree is ready and printing
- Rank Owner Job Files Total Size
- active fred 123 stuff 1204 bytes
- 1st smith 124 resume, foo 34576 bytes
- 2nd fred 125 more 99 bytes
- 3rd mary 126 mydoc 378 bytes
- 4th jones 127 statistics.ps 4567 bytes
- 5th fred 128 data.txt 9 bytes
-
- The column numbers of above headings and job entries are:
-
- | | | | |
- 01 08 19 35 63
-
- The mapper SHALL produce each field above from the following IPP
- attribute:
-
- LPD field IPP attribute special conversion details
-
- printer- printer-state and For a printer-state of idle or
- status printer-state-reasons processing, the mapper SHALL use
- the formats above. For stopped,
- the mapper SHALL use printer-
- state-reasons to produce an
- unspecified format for the error.
- rank number-of- the mapper SHALL the format above
- intervening-jobs
- owner job-originating-user- unspecified conversion; job-
- name originating-user-name may be the
- mapper's user-name
- job job-id the mapper shall use the job-id
- files document-name the mapper shall create a comma
- separated list of the document-
- names and then truncate this list
- to the first 24 characters
- total- job-k- the mapper shall multiple the
- size octets*copies*1024 value of job-k-octets by 1024 and
- by the value of the "copies"
- attribute.
-
-
-
-
-
-
-Herriot, et al. Experimental [Page 9]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
- A mapper SHOULD use the job attribute number-of-intervening-jobs
- rather than the job's position in a list of jobs to determine 'rank'
- because a Printer may omit jobs that it wants to keep secret. If a
- printer doesn't support the job attribute number-of-intervening-jobs,
- a mapper MAY use the job's position.
-
- Note: a Printer may set the value of job-originating-user-name to the
- authenticated user or to the value of "requesting-user-name",
- depending on the implementation and configuration. For a gateway, the
- authenticated user is the user-id of the gateway, but the
- "requesting-user-name" may contain the name of the user who is the
- gateway's client.
-
- In order to obtain the information specified above, The LPD-to-IPP
- mapper SHALL use the Get-Printer-Attributes operation to get
- printer-status and SHOULD use the Get-Jobs operation to get
- information about all of the jobs. If the LPD command contains job-
- numbers or user-names, the mapper MAY handle the filtering of the
- response. If the LPD command contains job-numbers but no user-names,
- the mapper MAY use Get-Job-Attributes on each converted job-number
- rather than Get-Jobs. If the LPD command contains a single user-name
- but no job-numbers, the mapper MAY use Get-Jobs with the my-jobs
- option if the server supports this option and if the server allows
- the client to be a proxy for the LPD user.
-
- NOTE: This specification does not define how the mapper maps the LPD
- Printer-name operand to the IPP "printer-uri" operation attribute.
-
-3.4 Send queue state (long)
-
- Command syntax:
-
- send-queue-long = %x04 printer-name *(SP(user-name / job-number)) LF
-
- The mapper's response to this command includes information about the
- printer and its jobs. RFC 1179 specifies neither the information nor
- the format of its response. This document requires the mapper to
- follow existing practice as specified in this document.
-
- The mapper SHALL produce a response in the following format which
- consists of a printer-status line optionally followed a list of jobs,
- where each job consists of a blank line, a description line, and one
- line for each file. The description line contains the user-name,
- rank, job-number and host. This format is defined by examples below.
- Appendix B contain the ABNF syntax.
-
-
-
-
-
-
-Herriot, et al. Experimental [Page 10]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
- For an printer with no jobs the response is:
-
- no entries
-
- For a printer with jobs, an example of the response is:
-
- killtree is ready and printing
-
- fred: active [job 123 tiger]
- 2 copies of stuff 602 bytes
-
- smith: 1st [job 124 snail]
- 2 copies of resume 7088 bytes
- 2 copies of foo 10200 bytes
-
- fred: 2nd [job 125 tiger]
- more 99 bytes
-
- The column numbers of above headings and job entries are:
-
- | | |
- 01 09 41
-
- Although the format of the long form is different from the format of
- the short form, their fields are identical except for a) the copies
- and host fields which are only in the long form, and b) the "size"
- field contains the single copy size of each file. Thus the sum of
- the file sizes in the "size" field times the value of the "copies"
- field produces the value for the "Total Size" field in the short
- form. For fields other than the host and copies fields, see the
- preceding section. For the host field see the table below.
-
- LPD field IPP attribute special conversion details
-
- host unspecified conversion; job-
- originating-host may be the
- mapper's host
- copies copies the mapper shall assume the
- value of copies precedes the
- string "copies of "; otherwise,
- the value of copies is 1.
-
- NOTE: This specification does not define how the mapper maps the LPD
- Printer-name operand to the IPP printer-uri operation attribute.
-
-
-
-
-
-
-
-Herriot, et al. Experimental [Page 11]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
-3.5 Remove jobs
-
- Command syntax:
-
- remove-jobs = %x05 printer-name SP agent
- *(SP(user-name / job-number)) LF
-
- The agent operand is the user-name of the user initiating the
- remove-jobs command. The special user-name 'root' indicates a
- privileged user who can remove jobs whose user-name differs from the
- agent.
-
- The mapper SHALL issue one Cancel-Job operation for each job
- referenced by the remove-jobs command. Each job-number in the
- remove-jobs command references a single job. Each user-name in the
- remove-jobs command implicitly references all jobs owned by the
- specified user. The active job is implicitly referenced when the
- remove-jobs command contains neither job-numbers nor user-names. The
- mapper MAY use Get-Jobs to determine the job-uri of implicitly
- referenced jobs.
-
- The mapper SHALL not use the agent name of 'root' when end-users
- cancel their own jobs. Violation of this rule creates a potential
- security violation, and it may cause the printer to issue a
- notification that misleads a user into thinking that some other
- person canceled the job.
-
- If the agent of a remove-jobs command for a job J is the same as the
- user name specified with the 'P' function in the control file for job
- J, then the mapper SHALL ensure that the initiator of the Cancel-Job
- command for job J is the same as job-originating-user for job J.
-
- Note: This requirement means that a mapper must be consistent in who
- the receiver perceives as the initiator of IPP operations. The mapper
- either acts as itself or acts on behalf of another user. The latter
- is preferable if it is possible. This consistency is necessary
- between Print-Job/Create-Job and Cancel-Job in order for Cancel-Job
- to work, but it is also desirable for other operations. For example,
- Get-Jobs may give more information about job submitted by the
- initiator of this operation.
-
- NOTE: This specification does not define how the mapper maps: (1) the
- LPD printer-name to the IPP "printer-uri" or (2) the LPD job-number
- to the IPP "job-uri".
-
- NOTE: This specification does not specify how the mapper maps the LPD
- user-name to the IPP job-originating-user because the mapper may use
- its own user-name with jobs.
-
-
-
-Herriot, et al. Experimental [Page 12]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
-4. Mapping of LPD Control File Lines to IPP Operation and Job Template
- Attributes
-
- This section describes the mapping from LPD control file lines
- (called 'functions') to IPP operation attributes and job template
- attributes. The mapper receives the control file lines via the LPD
- receive-control-file sub-command. Each of the LPD functions appear
- as sub-sections of section 7 of RFC 1179.
-
- In LPD control file lines, the text operands have a maximum length of
- 31 or 99 while IPP operation attribute and job template attribute
- values have a maximum of 255 or 1023 octets, depending on the
- attribute syntax. Therefore, no data is lost.
-
- The mapper converts each supported LPD function to its corresponding
- IPP operation or job template attribute as defined by tables in the
- subsections that follow. These subsections group functions according
- to whether they are:
-
- - required with a job,
- - optional with a job
- - required with each document.
-
- In the tables below, each LPD value is given a name, such as 'h'. If
- an IPP value uses the LPD value, then the IPP value column contains
- the LPD name, such as 'h' to denote this. Otherwise, the IPP value
- column specifies the literal value.
-
-4.1 Required Job Functions
-
- The following LPD functions MUST be in a received LPD job. The mapper
- SHALL receive each of the following LPD functions and SHALL include
- the information as a operation or job template attribute with each
- IPP job. The functions SHOULD be in the order 'H', 'P' and they
- SHOULD be the first two functions in the control file, but they MAY
- be anywhere in the control file and in any order:
-
- LPD function IPP
- name value description name value
-
- H h Originating Host h (in security layer)
- P u User identification requesting- u (and in security
- user-name layer)
- none ipp- 'true'
- attribute-
- fidelity
-
-
-
-
-
-Herriot, et al. Experimental [Page 13]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
- A mapper MAY send its own host rather than the client's host, and a
- mapper MAY send its own user-name as user identification rather than
- the client user. But in any case, the values sent SHALL be compatible
- with the Cancel-Job operation. The IPP operation MAY have no way to
- specify an originating host-name.
-
- The mapper SHALL include ipp-attribute-fidelity = true so that it
- doesn't have to determine which attributes a printer supports.
-
-4.2 Optional Job Functions
-
- The following LPD functions MAY be present in a received job. These
- functions SHOULD follow the required job functions and precede the
- document functions, but they MAY be anywhere in the control file.
-
- If the mapper receives such an LPD function, the mapper SHALL include
- the corresponding IPP attribute with the value converted as specified
- in the table below. If the mapper does not receive such an LPD
- attribute, the mapper SHALL NOT include the corresponding IPP
- attribute, except the 'L' LPD function whose absence has a special
- meaning as noted in the table.
-
- LPD function IPP
- name value description name value
-
- J j Job name for job-name j
- banner page
- L l Print banner page job-sheets 'standard' if 'L' is
- present
- 'none' if 'L' is present
- M m Mail When Printed IPP has no notification
- mechanism. To support
- this LPD feature, the
- gateway must poll using
- the Get-Job-Attributes
- operation.
-
-4.3 Required Document Functions
-
- The mapper SHALL receive one set of the required document functions
- with each copy of a document, and SHALL include the converted
- information as operation or job template attributes with each IPP
- document.
-
- If the control file contains required and recommended document
- functions, the required functions SHOULD precede the recommended ones
- and if the job contains multiple documents, all the functions for
-
-
-
-
-Herriot, et al. Experimental [Page 14]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
- each document are grouped together as shown in the example of section
- 6.3 "Required Document Functions". However, the document functions
- MAY be in any order.
-
- LPD function IPP
- name value description name value
-
- f fff Print formatted document-format 'application/octet-
- file stream'
- l fff Print file leaving document-format 'application/octet-
- control characters stream'
- o fff Print Postscript document-format 'application/PostScri
- output file pt'
- copies see note
-
- Note: In practice, the 'f' LPD function is often overloaded. It is
- often used with any format of document data including PostScript and
- PCL data.
-
- Note: In practice, the 'l' LPD function is often used as a rough
- equivalent to the 'f' function.
-
- Note: When RFC 1179 was written, no implementation supported the 'o'
- function; instead 'f' was used for PostScript. Windows NT now sends '
- o' function for a PostScript file.
-
- Note: the value 'fff' of the 'f', 'l' and 'o' functions is the name
- of the data file as transferred, e.g. "dfA123woden".
-
- If the mapper receives any other lower case letter, the mapper SHALL
- reject the job because the document contains a format that the mapper
- does not support.
-
- The mapper determines the number of copies by counting the number of
- occurrences of each 'fff' file with one of the lower-case functions
- above. For example, if 'f dfA123woden' occurs 4 times, then copies
- has a value of 4. Although the LPD protocol allows the value of
- copies to be different for each document, the commands and the
- receiving print systems don't support this.
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot, et al. Experimental [Page 15]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
-4.4 Recommended Document Functions
-
- The mapper SHOULD receive one set of the recommended document
- functions with each document, and SHOULD include the converted
- information as an operation or job template attribute with each IPP
- document. The functions SHOULD be received in the order 'U' and 'N',
- but they MAY arrive in any order.
-
- LPD function IPP
- name value description name value
-
- U fff ignored
- N n Name of source file document-name n
-
- Note: the value 'fff' of the 'U' function is the name of the data
- file as transferred, e.g. "dfA123woden".
-
-5. Mapping from IPP operations to LPD commands
-
- If the IPP-to-LPD mapper receives an IPP operation, the following
- table summarizes the LPD command that it uses. Each section below
- gives the detail. Each of the following sub-sections appear as sub-
- sections of section 3 in the document "Internet Printing
- Protocol/1.0: Model and Semantics" [RFC2566].
-
- IPP operation LPD command
-
- Print-Job or Print-URI or receive-a-printer-job
- Create-Job/Send-Document/Send-URI and then print-any-waiting-jobs
- Validate-Job implemented by the mapper
- Cancel-Job remove-jobs
- Get-Printer-Attributes, Get-Job- send queue state (short or long)
- Attributes or Get-Jobs
-
-5.1 Print-Job
-
- The mapper SHALL send the following commands in the order listed
- below:
-
- - receive-a-printer-job command
- - both receive-control-file sub-command and receive-data-file
- sub-command (unspecified order, see Note below)
- - print-any-waiting-jobs command, except that if the mapper is
- sending a sequence of receive a printer-job commands, it MAY
- omit sending print-any-waiting-jobs after any receive a
- printer-job command that is neither the first nor last command
- in this sequence
-
-
-
-
-Herriot, et al. Experimental [Page 16]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
- Note: it is recommended that the order of the receive-control-file
- subcommand and the receive-data-file sub-command be configurable
- because either order fails for some print systems. Some print systems
- assume that the control file follows all data files and start
- printing immediately on receipt of the control file. When such a
- print system tries to print a data file that has not arrived, it
- produces an error. Other print systems assume that the control file
- arrives before the data files and start printing when the first data
- file arrives. Such a system ignores the control information, such as
- banner page or copies.
-
- NOTE: This specification does not define the mapping between the IPP
- printer-uri and the LPD printer-name.
-
- The mapper SHALL send the IPP operation attributes and job template
- attributes received from the operation to the LPD printer by using
- the LPD receive-control-file sub-command. The mapper SHALL create the
- LPD job-number for use in the control file name, but the receiving
- printer MAY, in some circumstances, assign a different job-number to
- the job. The mapper SHALL create the IPP job-id and IPP job-uri
- returned in the Print-Job response.
-
- NOTE: This specification does not specify how the mapper determines
- the LPD job-number, the IPP job-id or the IPP job-uri of a job that
- it creates nor does it specify the relationship between the IPP job-
- uri, IPP the job-id and the LPD job-number, both of which the mapper
- creates. However, it is likely that the mapper will use the same
- integer value for both the LPD job-number and the IPP job-id, and
- that the IPP Job-uri is the printer's URI with the job-id
- concatenated on the end.
-
- The mapper SHALL send data received in the IPP operation to the LPD
- printer by using the LPD receive-data-file sub-command. The mapper
- SHALL specify the exact number of bytes being transmitted in the
- number-of-bytes field of the receive-data-file sub-command. It SHALL
- NOT use a value of 0 in this field.
-
- If the mapper, while it is transmitting a receive-a-printer-job
- command or sub-command, either detects that its IPP connection has
- closed or receives a Cancel-Job operation, the mapper SHALL terminate
- the LPD job either with the abort sub-command or the remove-jobs
- command.
-
- This document does not address error code conversion.
-
-
-
-
-
-
-
-Herriot, et al. Experimental [Page 17]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
-5.2 Print-URI
-
- The mapper SHALL handle this operation in the same way as a Print-Job
- operation except that it SHALL obtain data referenced by the
- "document-uri" operation attribute and SHALL then treat that data as
- if it had been received via a Print-Job operation.
-
-5.3 Validate-Job
-
- The mapper SHALL perform this operation directly. Because LPD
- supports very few attributes, this operation doesn't have much to
- check.
-
-5.4 Create-Job
-
- The mapper SHALL handle this operation like Print-Job, except:
-
- - the mapper SHALL send the control file after it has received the
- last Send-Document or Send-URI operation because the control
- file contains all the document-name and document-format values
- specified in the Send-Document and Send-URI operations.
- - the mapper SHALL perform one receive-data-file sub-command for
- each Send-Document or Send-URI operation received and in the
- same order received.
- - the mapper SHALL send the control file either before all data
- files or after all data files. (See the note in the section on
- Print-Job about the dilemma of sending the control file either
- before or after the data files.
-
-5.5 Send-Document
-
- The mapper performs a receive-data-file sub-command on the received
- data. See the preceding section 5.4 "Create-Job" for the details.
-
-5.6 Send-URI
-
- The mapper SHALL obtain the data referenced by the "document-uri"
- operation attribute, and SHALL then treat that data as if it had been
- received via a Send-Document operation. See the preceding section 5.5
- "Send-Document" for the details.
-
-5.7 Cancel-Job
-
- The mapper SHALL perform a remove-jobs command with the following
- operation attributes:
-
-
-
-
-
-
-Herriot, et al. Experimental [Page 18]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
- - the printer is the one to which the job was submitted, that is
- the IPP printer-uri is mapped to an LPD printer-name by the same
- mechanism as for all commands
- - the agent is the authenticated user-name of the IPP client
- - the job-number is the job-id returned by the Print-Job command,
- that is, the LPD job-number has the same value as the IPP job-id
- for likely implementations
-
-5.8 Get-Printer-Attributes
-
- LPD severely limits the set of attributes that the mapper is able to
- return in its response for this operation. The mapper SHALL support,
- at most, the following printer attributes:
-
- - printer-state
- - printer-state-reasons
-
- The mapper uses either the long or short form of the "send queue
- state" command.
-
- The mapper SHALL assume that the LPD response that it receives has
- the format and information specified in section 3.3 "Send queue state
- (short)" and section 3.4 "Send queue state (long)". The mapper SHALL
- determine the value of each requested attribute by using the inverse
- of the mapping specified in the two aforementioned sections.
-
- Note: the mapper can determine the response from the printer-status
- line without examining the rest of the LPD response.
-
-5.9 Get-Job-Attributes
-
- LPD severely limits the set of attributes that the mapper is able to
- return in its response for this operation. The mapper SHALL support,
- at most, the following job attributes:
-
- - number-of-intervening-jobs
- - job-originating-user-name
- - job-id
- - document-name
- - job-k-octets
- - copies
-
- The mapper uses either the long or short form of the "send queue
- state" command. If it receives a request for the "job-k-octets" or
- "copies" and supports the attribute it SHALL use the long form;
- otherwise, it SHALL use the short form.
-
-
-
-
-
-Herriot, et al. Experimental [Page 19]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
- Note: the value of job-k-octets is the value in the short form
- divided by the number of "copies" which is on the long form only. Its
- value can also be determined by adding the "size" field values for
- each document in the job in the long form.
-
- The mapper SHALL assume that the LPD response that it receives has
- the format and information specified in section 3.3 "Send queue state
- (short)" and section 3.4 "Send queue state (long)". The mapper SHALL
- determine the value of each requested attribute by using the inverse
- of the mapping specified in the two aforementioned sections.
-
- Note: when the mapper uses the LPD short form, it can determine the
- response from the single LPD line that pertains to the job specified
- by the Get-Job-Attributes operation.
-
- Note: the mapper can use its correspondence between the IPP job-id,
- job-uri and the LPD job-number.
-
-5.10 Get-Jobs
-
- The mapper SHALL perform this operation in the same way as Get-Job-
- Attributes except that the mapper converts all the LPD job-lines, and
- the IPP response contains one job object for each job-line in the LPD
- response.
-
-6. Mapping of IPP Attributes to LPD Control File Lines
-
- This section describes the mapping from IPP operation attributes and
- job template attributes to LPD control file lines (called '
- functions'). The mapper receives the IPP operation attributes and job
- template atributes via the IPP operation. Each of the IPP operation
- attributes and job template attributes appear as sub-sections of
- section 3 and 4.2 in the IPP model document [RFC2566].
-
- In the context of LPD control file lines, the text operands have a
- maximum length of 31 or 99 while IPP operation attributes and job
- template attributes have a maximum of 255 or 1023 octets, depending
- on the attribute syntax. Therefore, there may be some data loss if
- the IPP operation attribute and job template attribute values exceed
- the maximum length of the LPD equivalent operands.
-
- The mapper converts each supported IPP operation attribute and job
- template attribute to its corresponding LPD function as defined by
- tables in the subsections that follow. These subsections group
- functions according to whether they are:
-
-
-
-
-
-
-Herriot, et al. Experimental [Page 20]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
- - required with a job,
- - optional with a job
- - required with each document.
-
- In the tables below, each IPP value is given a name, such as 'h'. If
- an LPD value uses the IPP value, then the LPD value column contains
- the IPP name, such as 'h' to denote this. Otherwise, the LPD value
- column specifies the literal value.
-
-6.1 Required Job Functions
-
- The mapper SHALL include the following LPD functions with each job,
- and they SHALL have the specified value. They SHALL be the first
- functions in the control file and they SHALL be in the order "H" and
- then "P".
-
- IPP LPD function
- name value name value description
-
- (perhaps in security h H gateway host Originating Host
- layer)
- requesting-user-name u P u User identification
- and in the security
- layer
-
- A mapper SHALL sends its own host rather than the client's host,
- because some LPD systems require that it be the same as the host from
- which the remove-jobs command comes. A mapper MAY send its own user
- name as user identification rather than the client user. But in any
- case, the values sent SHALL be compatible with the LPD remove-jobs
- operation.
-
-6.2 Optional Job Functions
-
- The mapper MAY include the following LPD functions with each job.
- They SHALL have the specified value if they are sent. These
- functions, if present, SHALL follow the require job functions, and
- they SHALL precede the required document functions.
-
- IPP attribute LPD function
- name value name value description
-
- job-name j J j Job name for banner
- page
- job-sheets 'standard' L u Print banner page
- job-sheets 'none' omit 'L' function
-
-
-
-
-
-Herriot, et al. Experimental [Page 21]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
- Note: 'L' has special meaning when it is omitted. If 'J' is omitted,
- some undefined behavior occurs with respect to the banner page.
-
-6.3 Required Document Functions
-
- The mapper SHALL include one set of the following LPD functions with
- each document, and they SHALL have the specified values. For each
- document, the order of the functions SHALL be 'f', 'U' and then 'N',
- where 'f' is replicated once for each copy.
-
- IPP attribute LPD function
-
- name value name value description
-
- document- 'application/octet- f fff Print formatted file
- format stream' or
- 'application/PostScript'
- copies c replicate 'f' 'c'
- times
- none U fff Unlink data file
- document- n N n Name of source file
- name
-
- Note: the value 'fff' of the 'f' and 'U' functions is the name of the
- data file as transferred, e.g. "dfA123woden".
-
- Note: the mapper SHALL not send the 'o' function
-
- ISSUE: should we register DVI, troff or ditroff?
-
- If the mapper receives no "ipp-attribute-fidelitybest-effort" or it
- has a value of false, then the mapper SHALL reject the job if it
- specifies attributes or attribute values that are not among those
- supported in the above tables.
-
- Below is an example of the minimal control file for a job with three
- copies of two files 'foo' and 'bar':
-
- H tiger
- P jones
- f dfA123woden
- f dfA123woden
- f dfA123woden
- U dfA123woden
- N foo
- f dfB123woden
- f dfB123woden
- f dfB123woden
-
-
-
-Herriot, et al. Experimental [Page 22]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
- U dfB123woden
- N bar
-
-7. Security Considerations
-
- There are no security issues beyond those covered in the IPP Encoding
- and Transport document [RFC2565], the IPP model document [RFC2566]
- and the LPD document [RFC1179].
-
-8. References
-
- [ipp-iig] Hasting, T., et al., "Internet Printing Protocol/1.0:
- Implementer's Guide", Work in Progress.
-
- [RFC1759] Smith, R., Wright, F., Hastings, T., Zilles, S., and J.
- Gyllenskog, "Printer MIB", RFC 1759, March 1995.
-
- [RFC1179] McLaughlin, L., "Line Printer Daemon Protocol", RFC 1179,
- August 1990.
-
- [RFC2119] Bradner, S. "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2234] D. Crocker et al., "Augmented BNF for Syntax
- Specifications: ABNF", RFC 2234, November 1997.
-
- [RFC2565] Herriot, R., Butler, S., Moore, P. and R. Tuner, "Internet
- Printing Protocol/1.0: Encoding and Transport", RFC 2565,
- April 1999.
-
- [RFC2566] deBry, R., Hastings, T., Herriot, R., Isaacson, S., and P.
- Powell, "Internet Printing Protocol/1.0: Model and
- Semantics", RFC 2566, April 1999.
-
- [RFC2567] Wright, D., "Design Goals for an Internet Printing
- Protocol", RFC 2567, April 1999.
-
- [RFC2568] Zilles, S., "Rationale for the Structure and Model and
- Protocol for the Internet Printing Protocol", RFC 2568,
- April 1999.
-
-
-
-
-
-
-
-
-
-
-
-Herriot, et al. Experimental [Page 23]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
-9. Authors' Addresses
-
- Robert Herriot (Editor)
- Xerox Corporation
- 3400 Hillview Ave., Bldg #1
- Palo Alto, CA 94304
-
- Phone: 650-813-7696
- Fax: 650-813-6860
- EMail: rherriot@pahv.xerox.com
-
-
- Norm Jacobs
- Sun Microsystems Inc.
- 1430 Owl Ridge Rd.
- Colorado Springs, CO 80919
-
- Phone: 719-532-9927
- Fax: 719-535-0956
- EMail: Norm.Jacobs@Central.sun.com
-
-
- Thomas N. Hastings
- Xerox Corporation
- 701 S. Aviation Blvd., ESAE-231
- El Segundo, CA 90245
-
- Phone: 310-333-6413
- Fax: 310-333-5514
- EMail: hastings@cp10.es.xerox.com
-
-
- Jay Martin
- Underscore, Inc.
- 41-C Sagamore Park Road
- Hudson, NH 03051-4915
-
- Phone: 603-889-7000
- Fax: 603-889-2699
- EMail: jkm@underscore.com
-
-
-
-
-
-
-
-
-
-
-
-Herriot, et al. Experimental [Page 24]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
-10. Appendix A: ABNF Syntax for response of Send-queue-state (short)
-
- The syntax in ABNF for the response to the LPD command 'send-queue-
- state (long)' is:
-
- status-response = empty-queue / nonempty-queue
- empty-queue = "no-entries" LF
- nonempty-queue = printer-status LF heading LF *(job LF)
- printer-status = OK-status / error-status
- OK-status = printer-name SP "ready and printing" LF
- error-status = < implementation dependent status information >
- heading = "Rank" 3SP "Owner" 6SP "Job" 13SP "Files"
- 23SP "Total Size" LF
- ; the column headings and their values below begin
- at the columns
- ; 1, 8, 19, 35 and 63
- job = rank *SP owner *SP job *SP files *SP total-size "bytes"
- ; jobs are in order of oldest to newest
- rank = "active" / "1st" / "2nd" / "3rd" / integer "th"
- ; job that is printing is "active"
- ; other values show position in the queue
- owner = <user name of person who submitted the job>
- job = 1*3DIGIT ; job-number
- files = <file name> *( "," <file name>) ; truncated to 24 characters
- total-size = 1*DIGIT ; combined size in bytes of all documents
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot, et al. Experimental [Page 25]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
-11. Appendix B: ABNF Syntax for response of Send-queue-state (long)
-
- The syntax in ABNF for the response to the LPD command 'send-queue-
- state (long)' is:
-
- status-response = empty-queue / nonempty-queue
- empty-queue = "no-entries" LF
- nonempty-queue = printer-status LF *job
- printer-status = OK-status / error-status
- OK-status = printer-name SP "ready and printing" LF
- error-status = < implementation dependent status information >
- job = LF line-1 LF line-2 LF
- line-1 = owner ":" SP rank 1*SP "[job" job SP host "]"
- line-2 = file-name 1*SP document-size "bytes"
- ; jobs are in order of oldest to newest
- rank = "active" / "1st" / "2nd" / "3rd" / integer "th"
- ; job that is printing is "active"
- ; other values show position in the queue
- owner = <user name of person who submitted the job>
- job = 1*3DIGIT
- file-name = [ 1*DIGIT "copies of" SP ] <file name>
- ; truncated to 24 characters
- document-size = 1*DIGIT ;size of single copy of the document.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot, et al. Experimental [Page 26]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
-12. Appendix C: Unsupported LPD functions
-
- The follow LPD functions have no IPP equivalent. The LPD-to-IPP
- mapper ignores them and the IPP-to-LPD mapper does not send them.
-
- LPD command
- name description
-
- C Class for banner page
- I Indent Printing
- H Host of client
- M Mail when printed
- S Symbolic link data
- T Title for pr
- W Width of output
- 1 troff R font
- 2 troff I font
- 3 troff B font
- 4 troff S font
-
- The follow LPD functions specify document-formats which have no IPP
- equivalent, unless someone registers them. The LPD-to-IPP mapper
- rejects jobs that request such a document format, and the IPP-to-LPD
- mapper does not send them.
-
- LPD command
- name description
-
- c Plot CIF file
- d Print DVI file
- g Plot file
- k reserved for Kerberized clients and servers
- n Print ditroff output file
- p Print file with 'pr' format
- r File to print with FORTRAN carriage control
- t Print troff output file
- v Print raster file
- z reserved for future use with the Palladium
- print system
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot, et al. Experimental [Page 27]
-\f
-RFC 2569 Mapping between LPD and IPP Protocols April 1999
-
-
-13. Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot, et al. Experimental [Page 28]
-\f
+++ /dev/null
-
-
-
-
-
-
-
-Network Working Group Editors of this version:
-Request for Comments: 2578 K. McCloghrie
-STD: 58 Cisco Systems
-Obsoletes: 1902 D. Perkins
-Category: Standards Track SNMPinfo
- J. Schoenwaelder
- TU Braunschweig
- Authors of previous version:
- J. Case
- SNMP Research
- K. McCloghrie
- Cisco Systems
- M. Rose
- First Virtual Holdings
- S. Waldbusser
- International Network Services
- April 1999
-
-
- Structure of Management Information Version 2 (SMIv2)
-
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-
-Table of Contents
-
- 1 Introduction .................................................3
- 1.1 A Note on Terminology ......................................4
- 2 Definitions ..................................................4
- 2.1 The MODULE-IDENTITY macro ..................................5
- 2.2 Object Names and Syntaxes ..................................5
- 2.3 The OBJECT-TYPE macro ......................................8
- 2.5 The NOTIFICATION-TYPE macro ...............................10
- 2.6 Administrative Identifiers ................................11
- 3 Information Modules .........................................11
- 3.1 Macro Invocation ..........................................12
- 3.1.1 Textual Values and Strings ..............................13
-
-
-McCloghrie, et al. Standards Track [Page 1]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- 3.2 IMPORTing Symbols .........................................14
- 3.3 Exporting Symbols .........................................14
- 3.4 ASN.1 Comments ............................................14
- 3.5 OBJECT IDENTIFIER values ..................................15
- 3.6 OBJECT IDENTIFIER usage ...................................15
- 3.7 Reserved Keywords .........................................16
- 4 Naming Hierarchy ............................................16
- 5 Mapping of the MODULE-IDENTITY macro ........................17
- 5.1 Mapping of the LAST-UPDATED clause ........................17
- 5.2 Mapping of the ORGANIZATION clause ........................17
- 5.3 Mapping of the CONTACT-INFO clause ........................18
- 5.4 Mapping of the DESCRIPTION clause .........................18
- 5.5 Mapping of the REVISION clause ............................18
- 5.5.1 Mapping of the DESCRIPTION sub-clause ...................18
- 5.6 Mapping of the MODULE-IDENTITY value ......................18
- 5.7 Usage Example .............................................18
- 6 Mapping of the OBJECT-IDENTITY macro ........................19
- 6.1 Mapping of the STATUS clause ..............................19
- 6.2 Mapping of the DESCRIPTION clause .........................20
- 6.3 Mapping of the REFERENCE clause ...........................20
- 6.4 Mapping of the OBJECT-IDENTITY value ......................20
- 6.5 Usage Example .............................................20
- 7 Mapping of the OBJECT-TYPE macro ............................20
- 7.1 Mapping of the SYNTAX clause ..............................21
- 7.1.1 Integer32 and INTEGER ...................................21
- 7.1.2 OCTET STRING ............................................21
- 7.1.3 OBJECT IDENTIFIER .......................................22
- 7.1.4 The BITS construct ......................................22
- 7.1.5 IpAddress ...............................................22
- 7.1.6 Counter32 ...............................................23
- 7.1.7 Gauge32 .................................................23
- 7.1.8 TimeTicks ...............................................24
- 7.1.9 Opaque ..................................................24
- 7.1.10 Counter64 ..............................................24
- 7.1.11 Unsigned32 .............................................25
- 7.1.12 Conceptual Tables ......................................25
- 7.1.12.1 Creation and Deletion of Conceptual Rows .............26
- 7.2 Mapping of the UNITS clause ...............................26
- 7.3 Mapping of the MAX-ACCESS clause ..........................26
- 7.4 Mapping of the STATUS clause ..............................27
- 7.5 Mapping of the DESCRIPTION clause .........................27
- 7.6 Mapping of the REFERENCE clause ...........................27
- 7.7 Mapping of the INDEX clause ...............................27
- 7.8 Mapping of the AUGMENTS clause ............................29
- 7.8.1 Relation between INDEX and AUGMENTS clauses .............30
- 7.9 Mapping of the DEFVAL clause ..............................30
- 7.10 Mapping of the OBJECT-TYPE value .........................31
- 7.11 Usage Example ............................................32
-
-
-McCloghrie, et al. Standards Track [Page 2]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- 8 Mapping of the NOTIFICATION-TYPE macro ......................34
- 8.1 Mapping of the OBJECTS clause .............................34
- 8.2 Mapping of the STATUS clause ..............................34
- 8.3 Mapping of the DESCRIPTION clause .........................35
- 8.4 Mapping of the REFERENCE clause ...........................35
- 8.5 Mapping of the NOTIFICATION-TYPE value ....................35
- 8.6 Usage Example .............................................35
- 9 Refined Syntax ..............................................36
- 10 Extending an Information Module ............................37
- 10.1 Object Assignments .......................................37
- 10.2 Object Definitions .......................................38
- 10.3 Notification Definitions .................................39
- 11 Appendix A: Detailed Sub-typing Rules ......................40
- 11.1 Syntax Rules .............................................40
- 11.2 Examples .................................................41
- 12 Security Considerations ....................................41
- 13 Editors' Addresses .........................................41
- 14 References .................................................42
- 15 Full Copyright Statement ...................................43
-
-1. Introduction
-
- Management information is viewed as a collection of managed objects,
- residing in a virtual information store, termed the Management
- Information Base (MIB). Collections of related objects are defined
- in MIB modules. These modules are written using an adapted subset of
- OSI's Abstract Syntax Notation One, ASN.1 (1988) [1]. It is the
- purpose of this document, the Structure of Management Information
- (SMI), to define that adapted subset, and to assign a set of
- associated administrative values.
-
- The SMI is divided into three parts: module definitions, object
- definitions, and, notification definitions.
-
-(1) Module definitions are used when describing information modules.
- An ASN.1 macro, MODULE-IDENTITY, is used to concisely convey the
- semantics of an information module.
-
-(2) Object definitions are used when describing managed objects. An
- ASN.1 macro, OBJECT-TYPE, is used to concisely convey the syntax
- and semantics of a managed object.
-
-(3) Notification definitions are used when describing unsolicited
- transmissions of management information. An ASN.1 macro,
- NOTIFICATION-TYPE, is used to concisely convey the syntax and
- semantics of a notification.
-
-
-
-
-McCloghrie, et al. Standards Track [Page 3]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
-1.1. A Note on Terminology
-
- For the purpose of exposition, the original Structure of Management
- Information, as described in RFCs 1155 (STD 16), 1212 (STD 16), and
- RFC 1215, is termed the SMI version 1 (SMIv1). The current version
- of the Structure of Management Information is termed SMI version 2
- (SMIv2).
-
-2. Definitions
-
-SNMPv2-SMI DEFINITIONS ::= BEGIN
-
-
--- the path to the root
-
-org OBJECT IDENTIFIER ::= { iso 3 } -- "iso" = 1
-dod OBJECT IDENTIFIER ::= { org 6 }
-internet OBJECT IDENTIFIER ::= { dod 1 }
-
-directory OBJECT IDENTIFIER ::= { internet 1 }
-
-mgmt OBJECT IDENTIFIER ::= { internet 2 }
-mib-2 OBJECT IDENTIFIER ::= { mgmt 1 }
-transmission OBJECT IDENTIFIER ::= { mib-2 10 }
-
-experimental OBJECT IDENTIFIER ::= { internet 3 }
-
-private OBJECT IDENTIFIER ::= { internet 4 }
-enterprises OBJECT IDENTIFIER ::= { private 1 }
-
-security OBJECT IDENTIFIER ::= { internet 5 }
-
-snmpV2 OBJECT IDENTIFIER ::= { internet 6 }
-
--- transport domains
-snmpDomains OBJECT IDENTIFIER ::= { snmpV2 1 }
-
--- transport proxies
-snmpProxys OBJECT IDENTIFIER ::= { snmpV2 2 }
-
--- module identities
-snmpModules OBJECT IDENTIFIER ::= { snmpV2 3 }
-
--- Extended UTCTime, to allow dates with four-digit years
--- (Note that this definition of ExtUTCTime is not to be IMPORTed
--- by MIB modules.)
-ExtUTCTime ::= OCTET STRING(SIZE(11 | 13))
- -- format is YYMMDDHHMMZ or YYYYMMDDHHMMZ
-
-
-McCloghrie, et al. Standards Track [Page 4]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- -- where: YY - last two digits of year (only years
- -- between 1900-1999)
- -- YYYY - last four digits of the year (any year)
- -- MM - month (01 through 12)
- -- DD - day of month (01 through 31)
- -- HH - hours (00 through 23)
- -- MM - minutes (00 through 59)
- -- Z - denotes GMT (the ASCII character Z)
- --
- -- For example, "9502192015Z" and "199502192015Z" represent
- -- 8:15pm GMT on 19 February 1995. Years after 1999 must use
- -- the four digit year format. Years 1900-1999 may use the
- -- two or four digit format.
-
--- definitions for information modules
-
-MODULE-IDENTITY MACRO ::=
-BEGIN
- TYPE NOTATION ::=
- "LAST-UPDATED" value(Update ExtUTCTime)
- "ORGANIZATION" Text
- "CONTACT-INFO" Text
- "DESCRIPTION" Text
- RevisionPart
-
- VALUE NOTATION ::=
- value(VALUE OBJECT IDENTIFIER)
-
- RevisionPart ::=
- Revisions
- | empty
- Revisions ::=
- Revision
- | Revisions Revision
- Revision ::=
- "REVISION" value(Update ExtUTCTime)
- "DESCRIPTION" Text
-
- -- a character string as defined in section 3.1.1
- Text ::= value(IA5String)
-END
-
-
-OBJECT-IDENTITY MACRO ::=
-BEGIN
- TYPE NOTATION ::=
- "STATUS" Status
- "DESCRIPTION" Text
-
-
-McCloghrie, et al. Standards Track [Page 5]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- ReferPart
-
- VALUE NOTATION ::=
- value(VALUE OBJECT IDENTIFIER)
-
- Status ::=
- "current"
- | "deprecated"
- | "obsolete"
-
- ReferPart ::=
- "REFERENCE" Text
- | empty
-
- -- a character string as defined in section 3.1.1
- Text ::= value(IA5String)
-END
-
-
--- names of objects
--- (Note that these definitions of ObjectName and NotificationName
--- are not to be IMPORTed by MIB modules.)
-
-ObjectName ::=
- OBJECT IDENTIFIER
-
-NotificationName ::=
- OBJECT IDENTIFIER
-
--- syntax of objects
-
--- the "base types" defined here are:
--- 3 built-in ASN.1 types: INTEGER, OCTET STRING, OBJECT IDENTIFIER
--- 8 application-defined types: Integer32, IpAddress, Counter32,
--- Gauge32, Unsigned32, TimeTicks, Opaque, and Counter64
-
-ObjectSyntax ::=
- CHOICE {
- simple
- SimpleSyntax,
-
- -- note that SEQUENCEs for conceptual tables and
- -- rows are not mentioned here...
-
- application-wide
- ApplicationSyntax
- }
-
-
-
-McCloghrie, et al. Standards Track [Page 6]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
--- built-in ASN.1 types
-
-SimpleSyntax ::=
- CHOICE {
- -- INTEGERs with a more restrictive range
- -- may also be used
- integer-value -- includes Integer32
- INTEGER (-2147483648..2147483647),
-
- -- OCTET STRINGs with a more restrictive size
- -- may also be used
- string-value
- OCTET STRING (SIZE (0..65535)),
-
- objectID-value
- OBJECT IDENTIFIER
- }
-
--- indistinguishable from INTEGER, but never needs more than
--- 32-bits for a two's complement representation
-Integer32 ::=
- INTEGER (-2147483648..2147483647)
-
-
--- application-wide types
-
-ApplicationSyntax ::=
- CHOICE {
- ipAddress-value
- IpAddress,
-
- counter-value
- Counter32,
-
- timeticks-value
- TimeTicks,
-
- arbitrary-value
- Opaque,
-
- big-counter-value
- Counter64,
-
- unsigned-integer-value -- includes Gauge32
- Unsigned32
- }
-
--- in network-byte order
-
-
-McCloghrie, et al. Standards Track [Page 7]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
--- (this is a tagged type for historical reasons)
-IpAddress ::=
- [APPLICATION 0]
- IMPLICIT OCTET STRING (SIZE (4))
-
--- this wraps
-Counter32 ::=
- [APPLICATION 1]
- IMPLICIT INTEGER (0..4294967295)
-
--- this doesn't wrap
-Gauge32 ::=
- [APPLICATION 2]
- IMPLICIT INTEGER (0..4294967295)
-
--- an unsigned 32-bit quantity
--- indistinguishable from Gauge32
-Unsigned32 ::=
- [APPLICATION 2]
- IMPLICIT INTEGER (0..4294967295)
-
--- hundredths of seconds since an epoch
-TimeTicks ::=
- [APPLICATION 3]
- IMPLICIT INTEGER (0..4294967295)
-
--- for backward-compatibility only
-Opaque ::=
- [APPLICATION 4]
- IMPLICIT OCTET STRING
-
--- for counters that wrap in less than one hour with only 32 bits
-Counter64 ::=
- [APPLICATION 6]
- IMPLICIT INTEGER (0..18446744073709551615)
-
-
--- definition for objects
-
-OBJECT-TYPE MACRO ::=
-BEGIN
- TYPE NOTATION ::=
- "SYNTAX" Syntax
- UnitsPart
- "MAX-ACCESS" Access
- "STATUS" Status
- "DESCRIPTION" Text
- ReferPart
-
-
-McCloghrie, et al. Standards Track [Page 8]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- IndexPart
- DefValPart
-
- VALUE NOTATION ::=
- value(VALUE ObjectName)
-
- Syntax ::= -- Must be one of the following:
- -- a base type (or its refinement),
- -- a textual convention (or its refinement), or
- -- a BITS pseudo-type
- type
- | "BITS" "{" NamedBits "}"
-
- NamedBits ::= NamedBit
- | NamedBits "," NamedBit
-
- NamedBit ::= identifier "(" number ")" -- number is nonnegative
-
- UnitsPart ::=
- "UNITS" Text
- | empty
-
- Access ::=
- "not-accessible"
- | "accessible-for-notify"
- | "read-only"
- | "read-write"
- | "read-create"
-
- Status ::=
- "current"
- | "deprecated"
- | "obsolete"
-
- ReferPart ::=
- "REFERENCE" Text
- | empty
-
- IndexPart ::=
- "INDEX" "{" IndexTypes "}"
- | "AUGMENTS" "{" Entry "}"
- | empty
- IndexTypes ::=
- IndexType
- | IndexTypes "," IndexType
- IndexType ::=
- "IMPLIED" Index
- | Index
-
-
-McCloghrie, et al. Standards Track [Page 9]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- Index ::=
- -- use the SYNTAX value of the
- -- correspondent OBJECT-TYPE invocation
- value(ObjectName)
- Entry ::=
- -- use the INDEX value of the
- -- correspondent OBJECT-TYPE invocation
- value(ObjectName)
-
- DefValPart ::= "DEFVAL" "{" Defvalue "}"
- | empty
-
- Defvalue ::= -- must be valid for the type specified in
- -- SYNTAX clause of same OBJECT-TYPE macro
- value(ObjectSyntax)
- | "{" BitsValue "}"
-
- BitsValue ::= BitNames
- | empty
-
- BitNames ::= BitName
- | BitNames "," BitName
-
- BitName ::= identifier
-
- -- a character string as defined in section 3.1.1
- Text ::= value(IA5String)
-END
-
-
--- definitions for notifications
-
-NOTIFICATION-TYPE MACRO ::=
-BEGIN
- TYPE NOTATION ::=
- ObjectsPart
- "STATUS" Status
- "DESCRIPTION" Text
- ReferPart
-
- VALUE NOTATION ::=
- value(VALUE NotificationName)
-
- ObjectsPart ::=
- "OBJECTS" "{" Objects "}"
- | empty
- Objects ::=
- Object
-
-
-McCloghrie, et al. Standards Track [Page 10]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- | Objects "," Object
- Object ::=
- value(ObjectName)
-
- Status ::=
- "current"
- | "deprecated"
- | "obsolete"
-
- ReferPart ::=
- "REFERENCE" Text
- | empty
-
- -- a character string as defined in section 3.1.1
- Text ::= value(IA5String)
-END
-
--- definitions of administrative identifiers
-
-zeroDotZero OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "A value used for null identifiers."
- ::= { 0 0 }
-
-END
-
-3. Information Modules
-
- An "information module" is an ASN.1 module defining information
- relating to network management.
-
- The SMI describes how to use an adapted subset of ASN.1 (1988) to
- define an information module. Further, additional restrictions are
- placed on "standard" information modules. It is strongly recommended
- that "enterprise-specific" information modules also adhere to these
- restrictions.
-
- Typically, there are three kinds of information modules:
-
-(1) MIB modules, which contain definitions of inter-related managed
- objects, make use of the OBJECT-TYPE and NOTIFICATION-TYPE macros;
-
-(2) compliance statements for MIB modules, which make use of the
- MODULE-COMPLIANCE and OBJECT-GROUP macros [2]; and,
-
-(3) capability statements for agent implementations which make use of
- the AGENT-CAPABILITIES macros [2].
-
-
-McCloghrie, et al. Standards Track [Page 11]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- This classification scheme does not imply a rigid taxonomy. For
- example, a "standard" information module will normally include
- definitions of managed objects and a compliance statement.
- Similarly, an "enterprise-specific" information module might include
- definitions of managed objects and a capability statement. Of
- course, a "standard" information module may not contain capability
- statements.
-
- The constructs of ASN.1 allowed in SMIv2 information modules include:
- the IMPORTS clause, value definitions for OBJECT IDENTIFIERs, type
- definitions for SEQUENCEs (with restrictions), ASN.1 type assignments
- of the restricted ASN.1 types allowed in SMIv2, and instances of
- ASN.1 macros defined in this document and its companion documents [2,
- 3]. Additional ASN.1 macros must not be defined in SMIv2 information
- modules. SMIv1 macros must not be used in SMIv2 information modules.
-
- The names of all standard information modules must be unique (but
- different versions of the same information module should have the
- same name). Developers of enterprise information modules are
- encouraged to choose names for their information modules that will
- have a low probability of colliding with standard or other enterprise
- information modules. An information module may not use the ASN.1
- construct of placing an object identifier value between the module
- name and the "DEFINITIONS" keyword. For the purposes of this
- specification, an ASN.1 module name begins with an upper-case letter
- and continues with zero or more letters, digits, or hyphens, except
- that a hyphen can not be the last character, nor can there be two
- consecutive hyphens.
-
- All information modules start with exactly one invocation of the
- MODULE-IDENTITY macro, which provides contact information as well as
- revision history to distinguish between versions of the same
- information module. This invocation must appear immediately after
- any IMPORTs statements.
-
-3.1. Macro Invocation
-
- Within an information module, each macro invocation appears as:
-
- <descriptor> <macro> <clauses> ::= <value>
-
- where <descriptor> corresponds to an ASN.1 identifier, <macro> names
- the macro being invoked, and <clauses> and <value> depend on the
- definition of the macro. (Note that this definition of a descriptor
- applies to all macros defined in this memo and in [2].)
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 12]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- For the purposes of this specification, an ASN.1 identifier consists
- of one or more letters or digits, and its initial character must be a
- lower-case letter. Note that hyphens are not allowed by this
- specification (except for use by information modules converted from
- SMIv1 which did allow hyphens).
-
- For all descriptors appearing in an information module, the
- descriptor shall be unique and mnemonic, and shall not exceed 64
- characters in length. (However, descriptors longer than 32
- characters are not recommended.) This promotes a common language for
- humans to use when discussing the information module and also
- facilitates simple table mappings for user-interfaces.
-
- The set of descriptors defined in all "standard" information modules
- shall be unique.
-
- Finally, by convention, if the descriptor refers to an object with a
- SYNTAX clause value of either Counter32 or Counter64, then the
- descriptor used for the object should denote plurality.
-
-3.1.1. Textual Values and Strings
-
- Some clauses in a macro invocation may take a character string as a
- textual value (e.g., the DESCRIPTION clause). Other clauses take
- binary or hexadecimal strings (in any position where a non-negative
- number is allowed).
-
- A character string is preceded and followed by the quote character
- ("), and consists of an arbitrary number (possibly zero) of:
-
- - any 7-bit displayable ASCII characters except quote ("),
- - tab characters,
- - spaces, and
- - line terminator characters (\n or \r\n).
-
- The value of a character string is interpreted as ASCII.
-
- A binary string consists of a number (possibly zero) of zeros and
- ones preceded by a single (') and followed by either the pair ('B) or
- ('b), where the number is a multiple of eight.
-
- A hexadecimal string consists of an even number (possibly zero) of
- hexadecimal digits, preceded by a single (') and followed by either
- the pair ('H) or ('h). Digits specified via letters can be in upper
- or lower case.
-
- Note that ASN.1 comments can not be enclosed inside any of these
- types of strings.
-
-
-McCloghrie, et al. Standards Track [Page 13]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
-3.2. IMPORTing Symbols
-
- To reference an external object, the IMPORTS statement must be used
- to identify both the descriptor and the module in which the
- descriptor is defined, where the module is identified by its ASN.1
- module name.
-
- Note that when symbols from "enterprise-specific" information modules
- are referenced (e.g., a descriptor), there is the possibility of
- collision. As such, if different objects with the same descriptor
- are IMPORTed, then this ambiguity is resolved by prefixing the
- descriptor with the name of the information module and a dot ("."),
- i.e.,
-
- "module.descriptor"
-
- (All descriptors must be unique within any information module.)
-
- Of course, this notation can be used to refer to objects even when
- there is no collision when IMPORTing symbols.
-
- Finally, if any of the ASN.1 named types and macros defined in this
- document, specifically:
-
- Counter32, Counter64, Gauge32, Integer32, IpAddress, MODULE-
- IDENTITY, NOTIFICATION-TYPE, Opaque, OBJECT-TYPE, OBJECT-
- IDENTITY, TimeTicks, Unsigned32,
-
- or any of those defined in [2] or [3], are used in an information
- module, then they must be imported using the IMPORTS statement.
- However, the following must not be included in an IMPORTS statement:
-
- - named types defined by ASN.1 itself, specifically: INTEGER,
- OCTET STRING, OBJECT IDENTIFIER, SEQUENCE, SEQUENCE OF type,
- - the BITS construct.
-
-3.3. Exporting Symbols
-
- The ASN.1 EXPORTS statement is not allowed in SMIv2 information
- modules. All items defined in an information module are
- automatically exported.
-
-3.4. ASN.1 Comments
-
- ASN.1 comments can be included in an information module. However, it
- is recommended that all substantive descriptions be placed within an
- appropriate DESCRIPTION clause.
-
-
-
-McCloghrie, et al. Standards Track [Page 14]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- ASN.1 comments commence with a pair of adjacent hyphens and end with
- the next pair of adjacent hyphens or at the end of the line,
- whichever occurs first. Comments ended by a pair of hyphens have the
- effect of a single space character.
-
-3.5. OBJECT IDENTIFIER values
-
- An OBJECT IDENTIFIER value is an ordered list of non-negative
- numbers. For the SMIv2, each number in the list is referred to as a
- sub-identifier, there are at most 128 sub-identifiers in a value, and
- each sub-identifier has a maximum value of 2^32-1 (4294967295
- decimal).
-
- All OBJECT IDENTIFIER values have at least two sub-identifiers, where
- the value of the first sub-identifier is one of the following well-
- known names:
-
- Value Name
- 0 ccitt
- 1 iso
- 2 joint-iso-ccitt
-
- (Note that this SMI does not recognize "new" well-known names, e.g.,
- as defined when the CCITT became the ITU.)
-
-3.6. OBJECT IDENTIFIER usage
-
- OBJECT IDENTIFIERs are used in information modules in two ways:
-
-(1) registration: the definition of a particular item is registered as
- a particular OBJECT IDENTIFIER value, and associated with a
- particular descriptor. After such a registration, the semantics
- thereby associated with the value are not allowed to change, the
- OBJECT IDENTIFIER can not be used for any other registration, and
- the descriptor can not be changed nor associated with any other
- registration. The following macros result in a registration:
-
- OBJECT-TYPE, MODULE-IDENTITY, NOTIFICATION-TYPE, OBJECT-GROUP,
- OBJECT-IDENTITY, NOTIFICATION-GROUP, MODULE-COMPLIANCE,
- AGENT-CAPABILITIES.
-
-(2) assignment: a descriptor can be assigned to a particular OBJECT
- IDENTIFIER value. For this usage, the semantics associated with
- the OBJECT IDENTIFIER value is not allowed to change, and a
- descriptor assigned to a particular OBJECT IDENTIFIER value cannot
- subsequently be assigned to another. However, multiple descriptors
- can be assigned to the same OBJECT IDENTIFIER value. Such
- assignments are specified in the following manner:
-
-
-McCloghrie, et al. Standards Track [Page 15]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- mib OBJECT IDENTIFIER ::= { mgmt 1 } -- from RFC1156
- mib-2 OBJECT IDENTIFIER ::= { mgmt 1 } -- from RFC1213
- fredRouter OBJECT IDENTIFIER ::= { flintStones 1 1 }
- barneySwitch OBJECT IDENTIFIER ::= { flintStones bedrock(2) 1 }
-
- Note while the above examples are legal, the following is not:
-
- dinoHost OBJECT IDENTIFIER ::= { flintStones bedrock 2 }
-
- A descriptor is allowed to be associated with both a registration and
- an assignment, providing both are associated with the same OBJECT
- IDENTIFIER value and semantics.
-
-3.7. Reserved Keywords
-
- The following are reserved keywords which must not be used as
- descriptors or module names:
-
- ABSENT ACCESS AGENT-CAPABILITIES ANY APPLICATION AUGMENTS BEGIN
- BIT BITS BOOLEAN BY CHOICE COMPONENT COMPONENTS CONTACT-INFO
- CREATION-REQUIRES Counter32 Counter64 DEFAULT DEFINED
- DEFINITIONS DEFVAL DESCRIPTION DISPLAY-HINT END ENUMERATED
- ENTERPRISE EXPLICIT EXPORTS EXTERNAL FALSE FROM GROUP Gauge32
- IDENTIFIER IMPLICIT IMPLIED IMPORTS INCLUDES INDEX INTEGER
- Integer32 IpAddress LAST-UPDATED MANDATORY-GROUPS MAX MAX-ACCESS
- MIN MIN-ACCESS MINUS-INFINITY MODULE MODULE-COMPLIANCE MODULE-
- IDENTITY NOTIFICATION-GROUP NOTIFICATION-TYPE NOTIFICATIONS NULL
- OBJECT OBJECT-GROUP OBJECT-IDENTITY OBJECT-TYPE OBJECTS OCTET OF
- OPTIONAL ORGANIZATION Opaque PLUS-INFINITY PRESENT PRIVATE
- PRODUCT-RELEASE REAL REFERENCE REVISION SEQUENCE SET SIZE STATUS
- STRING SUPPORTS SYNTAX TAGS TEXTUAL-CONVENTION TRAP-TYPE TRUE
- TimeTicks UNITS UNIVERSAL Unsigned32 VARIABLES VARIATION WITH
- WRITE-SYNTAX
-
-4. Naming Hierarchy
-
- The root of the subtree administered by the Internet Assigned Numbers
- Authority (IANA) for the Internet is:
-
- internet OBJECT IDENTIFIER ::= { iso 3 6 1 }
-
- That is, the Internet subtree of OBJECT IDENTIFIERs starts with the
- prefix:
-
- 1.3.6.1.
-
- Several branches underneath this subtree are used for network
- management:
-
-
-McCloghrie, et al. Standards Track [Page 16]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- mgmt OBJECT IDENTIFIER ::= { internet 2 }
- experimental OBJECT IDENTIFIER ::= { internet 3 }
- private OBJECT IDENTIFIER ::= { internet 4 }
- enterprises OBJECT IDENTIFIER ::= { private 1 }
-
- However, the SMI does not prohibit the definition of objects in other
- portions of the object tree.
-
- The mgmt(2) subtree is used to identify "standard" objects.
-
- The experimental(3) subtree is used to identify objects being
- designed by working groups of the IETF. If an information module
- produced by a working group becomes a "standard" information module,
- then at the very beginning of its entry onto the Internet standards
- track, the objects are moved under the mgmt(2) subtree.
-
- The private(4) subtree is used to identify objects defined
- unilaterally. The enterprises(1) subtree beneath private is used,
- among other things, to permit providers of networking subsystems to
- register models of their products.
-
-5. Mapping of the MODULE-IDENTITY macro
-
- The MODULE-IDENTITY macro is used to provide contact and revision
- history for each information module. It must appear exactly once in
- every information module. It should be noted that the expansion of
- the MODULE-IDENTITY macro is something which conceptually happens
- during implementation and not during run-time.
-
- Note that reference in an IMPORTS clause or in clauses of SMIv2
- macros to an information module is NOT through the use of the
- 'descriptor' of a MODULE-IDENTITY macro; rather, an information
- module is referenced through specifying its module name.
-
-5.1. Mapping of the LAST-UPDATED clause
-
- The LAST-UPDATED clause, which must be present, contains the date and
- time that this information module was last edited.
-
-5.2. Mapping of the ORGANIZATION clause
-
- The ORGANIZATION clause, which must be present, contains a textual
- description of the organization under whose auspices this information
- module was developed.
-
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 17]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
-5.3. Mapping of the CONTACT-INFO clause
-
- The CONTACT-INFO clause, which must be present, contains the name,
- postal address, telephone number, and electronic mail address of the
- person to whom technical queries concerning this information module
- should be sent.
-
-5.4. Mapping of the DESCRIPTION clause
-
- The DESCRIPTION clause, which must be present, contains a high-level
- textual description of the contents of this information module.
-
-5.5. Mapping of the REVISION clause
-
- The REVISION clause, which need not be present, is repeatedly used to
- describe the revisions (including the initial version) made to this
- information module, in reverse chronological order (i.e., most recent
- first). Each instance of this clause contains the date and time of
- the revision.
-
-5.5.1. Mapping of the DESCRIPTION sub-clause
-
- The DESCRIPTION sub-clause, which must be present for each REVISION
- clause, contains a high-level textual description of the revision
- identified in that REVISION clause.
-
-5.6. Mapping of the MODULE-IDENTITY value
-
- The value of an invocation of the MODULE-IDENTITY macro is an OBJECT
- IDENTIFIER. As such, this value may be authoritatively used when
- specifying an OBJECT IDENTIFIER value to refer to the information
- module containing the invocation.
-
- Note that it is a common practice to use the value of the MODULE-
- IDENTITY macro as a subtree under which other OBJECT IDENTIFIER
- values assigned within the module are defined. However, it is legal
- (and occasionally necessary) for the other OBJECT IDENTIFIER values
- assigned within the module to be unrelated to the OBJECT IDENTIFIER
- value of the MODULE-IDENTITY macro.
-
-5.7. Usage Example
-
- Consider how a skeletal MIB module might be constructed: e.g.,
-
- FIZBIN-MIB DEFINITIONS ::= BEGIN
-
- IMPORTS
- MODULE-IDENTITY, OBJECT-TYPE, experimental
-
-
-McCloghrie, et al. Standards Track [Page 18]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- FROM SNMPv2-SMI;
-
-
- fizbin MODULE-IDENTITY
- LAST-UPDATED "199505241811Z"
- ORGANIZATION "IETF SNMPv2 Working Group"
- CONTACT-INFO
- " Marshall T. Rose
-
- Postal: Dover Beach Consulting, Inc.
- 420 Whisman Court
- Mountain View, CA 94043-2186
- US
-
- Tel: +1 415 968 1052
- Fax: +1 415 968 2510
-
- E-mail: mrose@dbc.mtview.ca.us"
-
- DESCRIPTION
- "The MIB module for entities implementing the xxxx
- protocol."
- REVISION "9505241811Z"
- DESCRIPTION
- "The latest version of this MIB module."
- REVISION "9210070433Z"
- DESCRIPTION
- "The initial version of this MIB module, published in
- RFC yyyy."
- -- contact IANA for actual number
- ::= { experimental xx }
-
- END
-
-6. Mapping of the OBJECT-IDENTITY macro
-
- The OBJECT-IDENTITY macro is used to define information about an
- OBJECT IDENTIFIER assignment. All administrative OBJECT IDENTIFIER
- assignments which define a type identification value (see
- AutonomousType, a textual convention defined in [3]) should be
- defined via the OBJECT-IDENTITY macro. It should be noted that the
- expansion of the OBJECT-IDENTITY macro is something which
- conceptually happens during implementation and not during run-time.
-
-6.1. Mapping of the STATUS clause
-
- The STATUS clause, which must be present, indicates whether this
- definition is current or historic.
-
-
-McCloghrie, et al. Standards Track [Page 19]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- The value "current" means that the definition is current and valid.
- The value "obsolete" means the definition is obsolete and should not
- be implemented and/or can be removed if previously implemented.
- While the value "deprecated" also indicates an obsolete definition,
- it permits new/continued implementation in order to foster
- interoperability with older/existing implementations.
-
-6.2. Mapping of the DESCRIPTION clause
-
- The DESCRIPTION clause, which must be present, contains a textual
- description of the object assignment.
-
-6.3. Mapping of the REFERENCE clause
-
- The REFERENCE clause, which need not be present, contains a textual
- cross-reference to some other document, either another information
- module which defines a related assignment, or some other document
- which provides additional information relevant to this definition.
-
-6.4. Mapping of the OBJECT-IDENTITY value
-
- The value of an invocation of the OBJECT-IDENTITY macro is an OBJECT
- IDENTIFIER.
-
-6.5. Usage Example
-
- Consider how an OBJECT IDENTIFIER assignment might be made: e.g.,
-
- fizbin69 OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The authoritative identity of the Fizbin 69 chipset."
- ::= { fizbinChipSets 1 }
-
-7. Mapping of the OBJECT-TYPE macro
-
- The OBJECT-TYPE macro is used to define a type of managed object. It
- should be noted that the expansion of the OBJECT-TYPE macro is
- something which conceptually happens during implementation and not
- during run-time.
-
- For leaf objects which are not columnar objects (i.e., not contained
- within a conceptual table), instances of the object are identified by
- appending a sub-identifier of zero to the name of that object.
- Otherwise, the INDEX clause of the conceptual row object superior to
- a columnar object defines instance identification information.
-
-
-
-
-McCloghrie, et al. Standards Track [Page 20]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
-7.1. Mapping of the SYNTAX clause
-
- The SYNTAX clause, which must be present, defines the abstract data
- structure corresponding to that object. The data structure must be
- one of the following: a base type, the BITS construct, or a textual
- convention. (SEQUENCE OF and SEQUENCE are also possible for
- conceptual tables, see section 7.1.12). The base types are those
- defined in the ObjectSyntax CHOICE. A textual convention is a
- newly-defined type defined as a sub-type of a base type [3].
-
- An extended subset of the full capabilities of ASN.1 (1988) sub-
- typing is allowed, as appropriate to the underlying ASN.1 type. Any
- such restriction on size, range or enumerations specified in this
- clause represents the maximal level of support which makes "protocol
- sense". Restrictions on sub-typing are specified in detail in
- Section 9 and Appendix A of this memo.
-
- The semantics of ObjectSyntax are now described.
-
-7.1.1. Integer32 and INTEGER
-
- The Integer32 type represents integer-valued information between
- -2^31 and 2^31-1 inclusive (-2147483648 to 2147483647 decimal). This
- type is indistinguishable from the INTEGER type. Both the INTEGER
- and Integer32 types may be sub-typed to be more constrained than the
- Integer32 type.
-
- The INTEGER type (but not the Integer32 type) may also be used to
- represent integer-valued information as named-number enumerations.
- In this case, only those named-numbers so enumerated may be present
- as a value. Note that although it is recommended that enumerated
- values start at 1 and be numbered contiguously, any valid value for
- Integer32 is allowed for an enumerated value and, further, enumerated
- values needn't be contiguously assigned.
-
- Finally, a label for a named-number enumeration must consist of one
- or more letters or digits, up to a maximum of 64 characters, and the
- initial character must be a lower-case letter. (However, labels
- longer than 32 characters are not recommended.) Note that hyphens
- are not allowed by this specification (except for use by information
- modules converted from SMIv1 which did allow hyphens).
-
-7.1.2. OCTET STRING
-
- The OCTET STRING type represents arbitrary binary or textual data.
- Although the SMI-specified size limitation for this type is 65535
- octets, MIB designers should realize that there may be implementation
- and interoperability limitations for sizes in excess of 255 octets.
-
-
-McCloghrie, et al. Standards Track [Page 21]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
-7.1.3. OBJECT IDENTIFIER
-
- The OBJECT IDENTIFIER type represents administratively assigned
- names. Any instance of this type may have at most 128 sub-
- identifiers. Further, each sub-identifier must not exceed the value
- 2^32-1 (4294967295 decimal).
-
-7.1.4. The BITS construct
-
- The BITS construct represents an enumeration of named bits. This
- collection is assigned non-negative, contiguous (but see below)
- values, starting at zero. Only those named-bits so enumerated may be
- present in a value. (Thus, enumerations must be assigned to
- consecutive bits; however, see Section 9 for refinements of an object
- with this syntax.)
-
- As part of updating an information module, for an object defined
- using the BITS construct, new enumerations can be added or existing
- enumerations can have new labels assigned to them. After an
- enumeration is added, it might not be possible to distinguish between
- an implementation of the updated object for which the new enumeration
- is not asserted, and an implementation of the object prior to the
- addition. Depending on the circumstances, such an ambiguity could
- either be desirable or could be undesirable. The means to avoid such
- an ambiguity is dependent on the encoding of values on the wire;
- however, one possibility is to define new enumerations starting at
- the next multiple of eight bits. (Of course, this can also result in
- the enumerations no longer being contiguous.)
-
- Although there is no SMI-specified limitation on the number of
- enumerations (and therefore on the length of a value), except as may
- be imposed by the limit on the length of an OCTET STRING, MIB
- designers should realize that there may be implementation and
- interoperability limitations for sizes in excess of 128 bits.
-
- Finally, a label for a named-number enumeration must consist of one
- or more letters or digits, up to a maximum of 64 characters, and the
- initial character must be a lower-case letter. (However, labels
- longer than 32 characters are not recommended.) Note that hyphens
- are not allowed by this specification.
-
-7.1.5. IpAddress
-
- The IpAddress type represents a 32-bit internet address. It is
- represented as an OCTET STRING of length 4, in network byte-order.
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 22]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- Note that the IpAddress type is a tagged type for historical reasons.
- Network addresses should be represented using an invocation of the
- TEXTUAL-CONVENTION macro [3].
-
-7.1.6. Counter32
-
- The Counter32 type represents a non-negative integer which
- monotonically increases until it reaches a maximum value of 2^32-1
- (4294967295 decimal), when it wraps around and starts increasing
- again from zero.
-
- Counters have no defined "initial" value, and thus, a single value of
- a Counter has (in general) no information content. Discontinuities
- in the monotonically increasing value normally occur at re-
- initialization of the management system, and at other times as
- specified in the description of an object-type using this ASN.1 type.
- If such other times can occur, for example, the creation of an object
- instance at times other than re-initialization, then a corresponding
- object should be defined, with an appropriate SYNTAX clause, to
- indicate the last discontinuity. Examples of appropriate SYNTAX
- clause include: TimeStamp (a textual convention defined in [3]),
- DateAndTime (another textual convention from [3]) or TimeTicks.
-
- The value of the MAX-ACCESS clause for objects with a SYNTAX clause
- value of Counter32 is either "read-only" or "accessible-for-notify".
-
- A DEFVAL clause is not allowed for objects with a SYNTAX clause value
- of Counter32.
-
-7.1.7. Gauge32
-
- The Gauge32 type represents a non-negative integer, which may
- increase or decrease, but shall never exceed a maximum value, nor
- fall below a minimum value. The maximum value can not be greater
- than 2^32-1 (4294967295 decimal), and the minimum value can not be
- smaller than 0. The value of a Gauge32 has its maximum value
- whenever the information being modeled is greater than or equal to
- its maximum value, and has its minimum value whenever the information
- being modeled is smaller than or equal to its minimum value. If the
- information being modeled subsequently decreases below (increases
- above) the maximum (minimum) value, the Gauge32 also decreases
- (increases). (Note that despite of the use of the term "latched" in
- the original definition of this type, it does not become "stuck" at
- its maximum or minimum value.)
-
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 23]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
-7.1.8. TimeTicks
-
- The TimeTicks type represents a non-negative integer which represents
- the time, modulo 2^32 (4294967296 decimal), in hundredths of a second
- between two epochs. When objects are defined which use this ASN.1
- type, the description of the object identifies both of the reference
- epochs.
-
- For example, [3] defines the TimeStamp textual convention which is
- based on the TimeTicks type. With a TimeStamp, the first reference
- epoch is defined as the time when sysUpTime [5] was zero, and the
- second reference epoch is defined as the current value of sysUpTime.
-
- The TimeTicks type may not be sub-typed.
-
-7.1.9. Opaque
-
- The Opaque type is provided solely for backward-compatibility, and
- shall not be used for newly-defined object types.
-
- The Opaque type supports the capability to pass arbitrary ASN.1
- syntax. A value is encoded using the ASN.1 Basic Encoding Rules [4]
- into a string of octets. This, in turn, is encoded as an OCTET
- STRING, in effect "double-wrapping" the original ASN.1 value.
-
- Note that a conforming implementation need only be able to accept and
- recognize opaquely-encoded data. It need not be able to unwrap the
- data and then interpret its contents.
-
- A requirement on "standard" MIB modules is that no object may have a
- SYNTAX clause value of Opaque.
-
-7.1.10. Counter64
-
- The Counter64 type represents a non-negative integer which
- monotonically increases until it reaches a maximum value of 2^64-1
- (18446744073709551615 decimal), when it wraps around and starts
- increasing again from zero.
-
- Counters have no defined "initial" value, and thus, a single value of
- a Counter has (in general) no information content. Discontinuities
- in the monotonically increasing value normally occur at re-
- initialization of the management system, and at other times as
- specified in the description of an object-type using this ASN.1 type.
- If such other times can occur, for example, the creation of an object
- instance at times other than re-initialization, then a corresponding
- object should be defined, with an appropriate SYNTAX clause, to
- indicate the last discontinuity. Examples of appropriate SYNTAX
-
-
-McCloghrie, et al. Standards Track [Page 24]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- clause are: TimeStamp (a textual convention defined in [3]),
- DateAndTime (another textual convention from [3]) or TimeTicks.
-
- The value of the MAX-ACCESS clause for objects with a SYNTAX clause
- value of Counter64 is either "read-only" or "accessible-for-notify".
-
- A requirement on "standard" MIB modules is that the Counter64 type
- may be used only if the information being modeled would wrap in less
- than one hour if the Counter32 type was used instead.
-
- A DEFVAL clause is not allowed for objects with a SYNTAX clause value
- of Counter64.
-
-7.1.11. Unsigned32
-
- The Unsigned32 type represents integer-valued information between 0
- and 2^32-1 inclusive (0 to 4294967295 decimal).
-
-7.1.12. Conceptual Tables
-
- Management operations apply exclusively to scalar objects. However,
- it is sometimes convenient for developers of management applications
- to impose an imaginary, tabular structure on an ordered collection of
- objects within the MIB. Each such conceptual table contains zero or
- more rows, and each row may contain one or more scalar objects,
- termed columnar objects. This conceptualization is formalized by
- using the OBJECT-TYPE macro to define both an object which
- corresponds to a table and an object which corresponds to a row in
- that table. A conceptual table has SYNTAX of the form:
-
- SEQUENCE OF <EntryType>
-
- where <EntryType> refers to the SEQUENCE type of its subordinate
- conceptual row. A conceptual row has SYNTAX of the form:
-
- <EntryType>
-
- where <EntryType> is a SEQUENCE type defined as follows:
-
- <EntryType> ::= SEQUENCE { <type1>, ... , <typeN> }
-
- where there is one <type> for each subordinate object, and each
- <type> is of the form:
-
- <descriptor> <syntax>
-
- where <descriptor> is the descriptor naming a subordinate object, and
- <syntax> has the value of that subordinate object's SYNTAX clause,
-
-
-McCloghrie, et al. Standards Track [Page 25]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- except that both sub-typing information and the named values for
- enumerated integers or the named bits for the BITS construct, are
- omitted from <syntax>.
-
- Further, a <type> is always present for every subordinate object.
- (The ASN.1 DEFAULT and OPTIONAL clauses are disallowed in the
- SEQUENCE definition.) The MAX-ACCESS clause for conceptual tables
- and rows is "not-accessible".
-
-7.1.12.1. Creation and Deletion of Conceptual Rows
-
- For newly-defined conceptual rows which allow the creation of new
- object instances and/or the deletion of existing object instances,
- there should be one columnar object with a SYNTAX clause value of
- RowStatus (a textual convention defined in [3]) and a MAX-ACCESS
- clause value of read-create. By convention, this is termed the
- status column for the conceptual row.
-
-7.2. Mapping of the UNITS clause
-
- This UNITS clause, which need not be present, contains a textual
- definition of the units associated with that object.
-
-7.3. Mapping of the MAX-ACCESS clause
-
- The MAX-ACCESS clause, which must be present, defines whether it
- makes "protocol sense" to read, write and/or create an instance of
- the object, or to include its value in a notification. This is the
- maximal level of access for the object. (This maximal level of
- access is independent of any administrative authorization policy.)
-
- The value "read-write" indicates that read and write access make
- "protocol sense", but create does not. The value "read-create"
- indicates that read, write and create access make "protocol sense".
- The value "not-accessible" indicates an auxiliary object (see Section
- 7.7). The value "accessible-for-notify" indicates an object which is
- accessible only via a notification (e.g., snmpTrapOID [5]).
-
- These values are ordered, from least to greatest: "not-accessible",
- "accessible-for-notify", "read-only", "read-write", "read-create".
-
- If any columnar object in a conceptual row has "read-create" as its
- maximal level of access, then no other columnar object of the same
- conceptual row may have a maximal access of "read-write". (Note that
- "read-create" is a superset of "read-write".)
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 26]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
-7.4. Mapping of the STATUS clause
-
- The STATUS clause, which must be present, indicates whether this
- definition is current or historic.
-
- The value "current" means that the definition is current and valid.
- The value "obsolete" means the definition is obsolete and should not
- be implemented and/or can be removed if previously implemented.
- While the value "deprecated" also indicates an obsolete definition,
- it permits new/continued implementation in order to foster
- interoperability with older/existing implementations.
-
-7.5. Mapping of the DESCRIPTION clause
-
- The DESCRIPTION clause, which must be present, contains a textual
- definition of that object which provides all semantic definitions
- necessary for implementation, and should embody any information which
- would otherwise be communicated in any ASN.1 commentary annotations
- associated with the object.
-
-7.6. Mapping of the REFERENCE clause
-
- The REFERENCE clause, which need not be present, contains a textual
- cross-reference to some other document, either another information
- module which defines a related assignment, or some other document
- which provides additional information relevant to this definition.
-
-7.7. Mapping of the INDEX clause
-
- The INDEX clause, which must be present if that object corresponds to
- a conceptual row (unless an AUGMENTS clause is present instead), and
- must be absent otherwise, defines instance identification information
- for the columnar objects subordinate to that object.
-
- The instance identification information in an INDEX clause must
- specify object(s) such that value(s) of those object(s) will
- unambiguously distinguish a conceptual row. The objects can be
- columnar objects from the same and/or another conceptual table, but
- must not be scalar objects. Multiple occurrences of the same object
- in a single INDEX clause is strongly discouraged.
-
- The syntax of the objects in the INDEX clause indicate how to form
- the instance-identifier:
-
-(1) integer-valued (i.e., having INTEGER as its underlying primitive
- type): a single sub-identifier taking the integer value (this
- works only for non-negative integers);
-
-
-
-McCloghrie, et al. Standards Track [Page 27]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
-(2) string-valued, fixed-length strings (or variable-length preceded by
- the IMPLIED keyword): `n' sub-identifiers, where `n' is the length
- of the string (each octet of the string is encoded in a separate
- sub-identifier);
-
-(3) string-valued, variable-length strings (not preceded by the IMPLIED
- keyword): `n+1' sub-identifiers, where `n' is the length of the
- string (the first sub-identifier is `n' itself, following this,
- each octet of the string is encoded in a separate sub-identifier);
-
-(4) object identifier-valued (when preceded by the IMPLIED keyword):
- `n' sub-identifiers, where `n' is the number of sub-identifiers in
- the value (each sub-identifier of the value is copied into a
- separate sub-identifier);
-
-(5) object identifier-valued (when not preceded by the IMPLIED
- keyword): `n+1' sub-identifiers, where `n' is the number of sub-
- identifiers in the value (the first sub-identifier is `n' itself,
- following this, each sub-identifier in the value is copied);
-
-(6) IpAddress-valued: 4 sub-identifiers, in the familiar a.b.c.d
- notation.
-
- Note that the IMPLIED keyword can only be present for an object
- having a variable-length syntax (e.g., variable-length strings or
- object identifier-valued objects), Further, the IMPLIED keyword can
- only be associated with the last object in the INDEX clause.
- Finally, the IMPLIED keyword may not be used on a variable-length
- string object if that string might have a value of zero-length.
-
- Since a single value of a Counter has (in general) no information
- content (see section 7.1.6 and 7.1.10), objects defined using the
- syntax, Counter32 or Counter64, must not be specified in an INDEX
-
- clause. If an object defined using the BITS construct is used in an
- INDEX clause, it is considered a variable-length string.
-
- Instances identified by use of integer-valued objects should be
- numbered starting from one (i.e., not from zero). The use of zero as
- a value for an integer-valued index object should be avoided, except
- in special cases.
-
- Objects which are both specified in the INDEX clause of a conceptual
- row and also columnar objects of the same conceptual row are termed
- auxiliary objects. The MAX-ACCESS clause for auxiliary objects is
- "not-accessible", except in the following circumstances:
-
-
-
-
-McCloghrie, et al. Standards Track [Page 28]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
-(1) within a MIB module originally written to conform to SMIv1, and
- later converted to conform to SMIv2; or
-
-(2) a conceptual row must contain at least one columnar object which is
- not an auxiliary object. In the event that all of a conceptual
- row's columnar objects are also specified in its INDEX clause, then
- one of them must be accessible, i.e., have a MAX-ACCESS clause of
- "read-only". (Note that this situation does not arise for a
- conceptual row allowing create access, since such a row will have a
- status column which will not be an auxiliary object.)
-
- Note that objects specified in a conceptual row's INDEX clause need
- not be columnar objects of that conceptual row. In this situation,
- the DESCRIPTION clause of the conceptual row must include a textual
- explanation of how the objects which are included in the INDEX clause
- but not columnar objects of that conceptual row, are used in uniquely
- identifying instances of the conceptual row's columnar objects.
-
-7.8. Mapping of the AUGMENTS clause
-
- The AUGMENTS clause, which must not be present unless the object
- corresponds to a conceptual row, is an alternative to the INDEX
- clause. Every object corresponding to a conceptual row has either an
- INDEX clause or an AUGMENTS clause.
-
- If an object corresponding to a conceptual row has an INDEX clause,
- that row is termed a base conceptual row; alternatively, if the
- object has an AUGMENTS clause, the row is said to be a conceptual row
- augmentation, where the AUGMENTS clause names the object
- corresponding to the base conceptual row which is augmented by this
- conceptual row augmentation. (Thus, a conceptual row augmentation
- cannot itself be augmented.) Instances of subordinate columnar
- objects of a conceptual row augmentation are identified according to
- the INDEX clause of the base conceptual row corresponding to the
- object named in the AUGMENTS clause. Further, instances of
- subordinate columnar objects of a conceptual row augmentation exist
- according to the same semantics as instances of subordinate columnar
- objects of the base conceptual row being augmented. As such, note
- that creation of a base conceptual row implies the correspondent
- creation of any conceptual row augmentations.
-
- For example, a MIB designer might wish to define additional columns
- in an "enterprise-specific" MIB which logically extend a conceptual
- row in a "standard" MIB. The "standard" MIB definition of the
- conceptual row would include the INDEX clause and the "enterprise-
- specific" MIB would contain the definition of a conceptual row using
- the AUGMENTS clause. On the other hand, it would be incorrect to use
- the AUGMENTS clause for the relationship between RFC 2233's ifTable
-
-
-McCloghrie, et al. Standards Track [Page 29]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- and the many media-specific MIBs which extend it for specific media
- (e.g., the dot3Table in RFC 2358), since not all interfaces are of
- the same media.
-
- Note that a base conceptual row may be augmented by multiple
- conceptual row augmentations.
-
-7.8.1. Relation between INDEX and AUGMENTS clauses
-
- When defining instance identification information for a conceptual
- table:
-
-(1) If there is a one-to-one correspondence between the conceptual rows
- of this table and an existing table, then the AUGMENTS clause
- should be used.
-
-(2) Otherwise, if there is a sparse relationship between the conceptual
- rows of this table and an existing table, then an INDEX clause
- should be used which is identical to that in the existing table.
- For example, the relationship between RFC 2233's ifTable and a
- media-specific MIB which extends the ifTable for a specific media
- (e.g., the dot3Table in RFC 2358), is a sparse relationship.
-
-(3) Otherwise, if no existing objects have the required syntax and
- semantics, then auxiliary objects should be defined within the
- conceptual row for the new table, and those objects should be used
- within the INDEX clause for the conceptual row.
-
-7.9. Mapping of the DEFVAL clause
-
- The DEFVAL clause, which need not be present, defines an acceptable
- default value which may be used at the discretion of an agent when an
- object instance is created. That is, the value is a "hint" to
- implementors.
-
- During conceptual row creation, if an instance of a columnar object
- is not present as one of the operands in the correspondent management
- protocol set operation, then the value of the DEFVAL clause, if
- present, indicates an acceptable default value that an agent might
- use (especially for a read-only object).
-
- Note that with this definition of the DEFVAL clause, it is
- appropriate to use it for any columnar object of a read-create table.
- It is also permitted to use it for scalar objects dynamically created
- by an agent, or for columnar objects of a read-write table
- dynamically created by an agent.
-
-
-
-
-McCloghrie, et al. Standards Track [Page 30]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- The value of the DEFVAL clause must, of course, correspond to the
- SYNTAX clause for the object. If the value is an OBJECT IDENTIFIER,
- then it must be expressed as a single ASN.1 identifier, and not as a
- collection of sub-identifiers.
-
- Note that if an operand to the management protocol set operation is
- an instance of a read-only object, then the error `notWritable' [6]
- will be returned. As such, the DEFVAL clause can be used to provide
- an acceptable default value that an agent might use.
-
- By way of example, consider the following possible DEFVAL clauses:
-
- ObjectSyntax DEFVAL clause
- ---------------- ------------
- Integer32 DEFVAL { 1 }
- -- same for Gauge32, TimeTicks, Unsigned32
- INTEGER DEFVAL { valid } -- enumerated value
- OCTET STRING DEFVAL { 'ffffffffffff'H }
- DisplayString DEFVAL { "SNMP agent" }
- IpAddress DEFVAL { 'c0210415'H } -- 192.33.4.21
- OBJECT IDENTIFIER DEFVAL { sysDescr }
- BITS DEFVAL { { primary, secondary } }
- -- enumerated values that are set
- BITS DEFVAL { { } }
- -- no enumerated values are set
-
- A binary string used in a DEFVAL clause for an OCTET STRING must be
- either an integral multiple of eight or zero bits in length;
- similarly, a hexadecimal string must be an even number of hexadecimal
- digits. The value of a character string used in a DEFVAL clause must
- not contain tab characters or line terminator characters.
-
- Object types with SYNTAX of Counter32 and Counter64 may not have
- DEFVAL clauses, since they do not have defined initial values.
- However, it is recommended that they be initialized to zero.
-
-7.10. Mapping of the OBJECT-TYPE value
-
- The value of an invocation of the OBJECT-TYPE macro is the name of
- the object, which is an OBJECT IDENTIFIER, an administratively
- assigned name.
-
- When an OBJECT IDENTIFIER is assigned to an object:
-
-(1) If the object corresponds to a conceptual table, then only a single
- assignment, that for a conceptual row, is present immediately
- beneath that object. The administratively assigned name for the
- conceptual row object is derived by appending a sub-identifier of
-
-
-McCloghrie, et al. Standards Track [Page 31]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- "1" to the administratively assigned name for the conceptual table.
-
-(2) If the object corresponds to a conceptual row, then at least one
- assignment, one for each column in the conceptual row, is present
- beneath that object. The administratively assigned name for each
- column is derived by appending a unique, positive sub-identifier to
- the administratively assigned name for the conceptual row.
-
-(3) Otherwise, no other OBJECT IDENTIFIERs which are subordinate to the
- object may be assigned.
-
- Note that the final sub-identifier of any administratively assigned
- name for an object shall be positive. A zero-valued final sub-
- identifier is reserved for future use.
-
-7.11. Usage Example
-
- Consider how one might define a conceptual table and its
- subordinates. (This example uses the RowStatus textual convention
- defined in [3].)
-
- evalSlot OBJECT-TYPE
- SYNTAX Integer32 (0..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The index number of the first unassigned entry in the
- evaluation table, or the value of zero indicating that
- all entries are assigned.
-
- A management station should create new entries in the
- evaluation table using this algorithm: first, issue a
- management protocol retrieval operation to determine the
- value of evalSlot; and, second, issue a management
- protocol set operation to create an instance of the
- evalStatus object setting its value to createAndGo(4) or
- createAndWait(5). If this latter operation succeeds,
- then the management station may continue modifying the
- instances corresponding to the newly created conceptual
- row, without fear of collision with other management
- stations."
- ::= { eval 1 }
-
- evalTable OBJECT-TYPE
- SYNTAX SEQUENCE OF EvalEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
-
-
-McCloghrie, et al. Standards Track [Page 32]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- "The (conceptual) evaluation table."
- ::= { eval 2 }
-
- evalEntry OBJECT-TYPE
- SYNTAX EvalEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "An entry (conceptual row) in the evaluation table."
- INDEX { evalIndex }
- ::= { evalTable 1 }
-
- EvalEntry ::=
- SEQUENCE {
- evalIndex Integer32,
- evalString DisplayString,
- evalValue Integer32,
- evalStatus RowStatus
- }
-
- evalIndex OBJECT-TYPE
- SYNTAX Integer32 (1..2147483647)
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The auxiliary variable used for identifying instances of
- the columnar objects in the evaluation table."
- ::= { evalEntry 1 }
-
- evalString OBJECT-TYPE
- SYNTAX DisplayString
- MAX-ACCESS read-create
- STATUS current
- DESCRIPTION
- "The string to evaluate."
- ::= { evalEntry 2 }
-
- evalValue OBJECT-TYPE
- SYNTAX Integer32
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The value when evalString was last evaluated, or zero if
- no such value is available."
- DEFVAL { 0 }
- ::= { evalEntry 3 }
-
- evalStatus OBJECT-TYPE
-
-
-McCloghrie, et al. Standards Track [Page 33]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- SYNTAX RowStatus
- MAX-ACCESS read-create
- STATUS current
- DESCRIPTION
- "The status column used for creating, modifying, and
- deleting instances of the columnar objects in the
- evaluation table."
- DEFVAL { active }
- ::= { evalEntry 4 }
-
-8. Mapping of the NOTIFICATION-TYPE macro
-
- The NOTIFICATION-TYPE macro is used to define the information
- contained within an unsolicited transmission of management
- information (i.e., within either a SNMPv2-Trap-PDU or InformRequest-
- PDU). It should be noted that the expansion of the NOTIFICATION-TYPE
- macro is something which conceptually happens during implementation
- and not during run-time.
-
-8.1. Mapping of the OBJECTS clause
-
- The OBJECTS clause, which need not be present, defines an ordered
- sequence of MIB object types. One and only one object instance for
- each occurrence of each object type must be present, and in the
- specified order, in every instance of the notification. If the same
- object type occurs multiple times in a notification's ordered
- sequence, then an object instance is present for each of them. An
- object type specified in this clause must not have an MAX-ACCESS
- clause of "not-accessible". The notification's DESCRIPTION clause
- must specify the information/meaning conveyed by each occurrence of
- each object type in the sequence. The DESCRIPTION clause must also
- specify which object instance is present for each object type in the
- notification.
-
- Note that an agent is allowed, at its own discretion, to append as
- many additional objects as it considers useful to the end of the
- notification (i.e., after the objects defined by the OBJECTS clause).
-
-8.2. Mapping of the STATUS clause
-
- The STATUS clause, which must be present, indicates whether this
- definition is current or historic.
-
- The value "current" means that the definition is current and valid.
- The value "obsolete" means the definition is obsolete and should not
- be implemented and/or can be removed if previously implemented.
- While the value "deprecated" also indicates an obsolete definition,
- it permits new/continued implementation in order to foster
-
-
-McCloghrie, et al. Standards Track [Page 34]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- interoperability with older/existing implementations.
-
-8.3. Mapping of the DESCRIPTION clause
-
- The DESCRIPTION clause, which must be present, contains a textual
- definition of the notification which provides all semantic
- definitions necessary for implementation, and should embody any
- information which would otherwise be communicated in any ASN.1
- commentary annotations associated with the notification. In
- particular, the DESCRIPTION clause should document which instances of
- the objects mentioned in the OBJECTS clause should be contained
- within notifications of this type.
-
-8.4. Mapping of the REFERENCE clause
-
- The REFERENCE clause, which need not be present, contains a textual
- cross-reference to some other document, either another information
- module which defines a related assignment, or some other document
- which provides additional information relevant to this definition.
-
-8.5. Mapping of the NOTIFICATION-TYPE value
-
- The value of an invocation of the NOTIFICATION-TYPE macro is the name
- of the notification, which is an OBJECT IDENTIFIER, an
- administratively assigned name. In order to achieve compatibility
- with SNMPv1 traps, both when converting SMIv1 information modules
- to/from this SMI, and in the procedures employed by multi-lingual
- systems and proxy forwarding applications, the next to last sub-
- identifier in the name of any newly-defined notification must have
- the value zero.
-
- Sections 4.2.6 and 4.2.7 of [6] describe how the NOTIFICATION-TYPE
- macro is used to generate a SNMPv2-Trap-PDU or InformRequest-PDU,
- respectively.
-
-8.6. Usage Example
-
- Consider how a configuration change notification might be described:
-
- entityMIBTraps OBJECT IDENTIFIER ::= { entityMIB 2 }
- entityMIBTrapPrefix OBJECT IDENTIFIER ::= { entityMIBTraps 0 }
-
- entConfigChange NOTIFICATION-TYPE
- STATUS current
- DESCRIPTION
- "An entConfigChange trap is sent when the value of
- entLastChangeTime changes. It can be utilized by an NMS to
- trigger logical/physical entity table maintenance polls.
-
-
-McCloghrie, et al. Standards Track [Page 35]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
-
- An agent must not generate more than one entConfigChange
- 'trap-event' in a five second period, where a 'trap-event'
- is the transmission of a single trap PDU to a list of
- trap destinations. If additional configuration changes
- occur within the five second 'throttling' period, then
- these trap-events should be suppressed by the agent. An
- NMS should periodically check the value of
- entLastChangeTime to detect any missed entConfigChange
- trap-events, e.g. due to throttling or transmission loss."
- ::= { entityMIBTrapPrefix 1 }
-
- According to this invocation, the notification authoritatively
- identified as
-
- { entityMIBTrapPrefix 1 }
-
- is used to report a particular type of configuration change.
-
-9. Refined Syntax
-
- Some macros have clauses which allows syntax to be refined,
- specifically: the SYNTAX clause of the OBJECT-TYPE macro, and the
- SYNTAX/WRITE-SYNTAX clauses of the MODULE-COMPLIANCE and AGENT-
- CAPABILITIES macros [2]. However, not all refinements of syntax are
- appropriate. In particular, the object's primitive or application
- type must not be changed.
-
- Further, the following restrictions apply:
-
- Restrictions to Refinement of
- object syntax range enumeration size
- ----------------- ----- ----------- ----
- INTEGER (1) (2) -
- Integer32 (1) - -
- Unsigned32 (1) - -
- OCTET STRING - - (3)
- OBJECT IDENTIFIER - - -
- BITS - (2) -
- IpAddress - - -
- Counter32 - - -
- Counter64 - - -
- Gauge32 (1) - -
- TimeTicks - - -
-
- where:
-
-
-
-
-McCloghrie, et al. Standards Track [Page 36]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
-(1) the range of permitted values may be refined by raising the lower-
- bounds, by reducing the upper-bounds, and/or by reducing the
- alternative value/range choices;
-
-(2) the enumeration of named-values may be refined by removing one or
- more named-values (note that for BITS, a refinement may cause the
- enumerations to no longer be contiguous); or,
-
-(3) the size in octets of the value may be refined by raising the
- lower-bounds, by reducing the upper-bounds, and/or by reducing the
- alternative size choices.
-
- No other types of refinements can be specified in the SYNTAX clause.
- However, the DESCRIPTION clause is available to specify additional
- restrictions which can not be expressed in the SYNTAX clause.
- Further details on (and examples of) sub-typing are provided in
- Appendix A.
-
-10. Extending an Information Module
-
- As experience is gained with an information module, it may be
- desirable to revise that information module. However, changes are
- not allowed if they have any potential to cause interoperability
- problems "over the wire" between an implementation using an original
- specification and an implementation using an updated
- specification(s).
-
- For any change, the invocation of the MODULE-IDENTITY macro must be
- updated to include information about the revision: specifically,
- updating the LAST-UPDATED clause, adding a pair of REVISION and
- DESCRIPTION clauses (see section 5.5), and making any necessary
- changes to existing clauses, including the ORGANIZATION and CONTACT-
- INFO clauses.
-
- Note that any definition contained in an information module is
- available to be IMPORT-ed by any other information module, and is
- referenced in an IMPORTS clause via the module name. Thus, a module
- name should not be changed. Specifically, the module name (e.g.,
- "FIZBIN-MIB" in the example of Section 5.7) should not be changed
- when revising an information module (except to correct typographical
- errors), and definitions should not be moved from one information
- module to another.
-
- Also note that obsolete definitions must not be removed from MIB
- modules since their descriptors may still be referenced by other
- information modules, and the OBJECT IDENTIFIERs used to name them
- must never be re-assigned.
-
-
-
-McCloghrie, et al. Standards Track [Page 37]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
-10.1. Object Assignments
-
- If any non-editorial change is made to any clause of a object
- assignment, then the OBJECT IDENTIFIER value associated with that
- object assignment must also be changed, along with its associated
- descriptor.
-
-10.2. Object Definitions
-
- An object definition may be revised in any of the following ways:
-
-(1) A SYNTAX clause containing an enumerated INTEGER may have new
- enumerations added or existing labels changed. Similarly, named
- bits may be added or existing labels changed for the BITS
- construct.
-
-(2) The value of a SYNTAX clause may be replaced by a textual
- convention, providing the textual convention is defined to use the
- same primitive ASN.1 type, has the same set of values, and has
- identical semantics.
-
-(3) A STATUS clause value of "current" may be revised as "deprecated"
- or "obsolete". Similarly, a STATUS clause value of "deprecated"
- may be revised as "obsolete". When making such a change, the
- DESCRIPTION clause should be updated to explain the rationale.
-
-(4) A DEFVAL clause may be added or updated.
-
-(5) A REFERENCE clause may be added or updated.
-
-(6) A UNITS clause may be added.
-
-(7) A conceptual row may be augmented by adding new columnar objects at
- the end of the row, and making the corresponding update to the
- SEQUENCE definition.
-
-(8) Clarifications and additional information may be included in the
- DESCRIPTION clause.
-
-(9) Entirely new objects may be defined, named with previously
- unassigned OBJECT IDENTIFIER values.
-
- Otherwise, if the semantics of any previously defined object are
- changed (i.e., if a non-editorial change is made to any clause other
- than those specifically allowed above), then the OBJECT IDENTIFIER
- value associated with that object must also be changed.
-
-
-
-
-McCloghrie, et al. Standards Track [Page 38]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- Note that changing the descriptor associated with an existing object
- is considered a semantic change, as these strings may be used in an
- IMPORTS statement.
-
-10.3. Notification Definitions
-
- A notification definition may be revised in any of the following
- ways:
-
-(1) A REFERENCE clause may be added or updated.
-
-(2) A STATUS clause value of "current" may be revised as "deprecated"
- or "obsolete". Similarly, a STATUS clause value of "deprecated"
- may be revised as "obsolete". When making such a change, the
- DESCRIPTION clause should be updated to explain the rationale.
-
-(3) A DESCRIPTION clause may be clarified.
-
- Otherwise, if the semantics of any previously defined notification
- are changed (i.e., if a non-editorial change is made to any clause
- other those specifically allowed above), then the OBJECT IDENTIFIER
- value associated with that notification must also be changed.
-
- Note that changing the descriptor associated with an existing
- notification is considered a semantic change, as these strings may be
- used in an IMPORTS statement.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 39]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
-11. Appendix A: Detailed Sub-typing Rules
-
-
-11.1. Syntax Rules
-
- The syntax rules for sub-typing are given below. Note that while
- this syntax is based on ASN.1, it includes some extensions beyond
- what is allowed in ASN.1, and a number of ASN.1 constructs are not
- allowed by this syntax.
-
- <integerSubType>
- ::= <empty>
- | "(" <range> ["|" <range>]... ")"
-
- <octetStringSubType>
- ::= <empty>
- | "(" "SIZE" "(" <range> ["|" <range>]... ")" ")"
-
- <range>
- ::= <value>
- | <value> ".." <value>
-
- <value>
- ::= "-" <number>
- | <number>
- | <hexString>
- | <binString>
-
- where:
- <empty> is the empty string
- <number> is a non-negative integer
- <hexString> is a hexadecimal string (e.g., '0F0F'H)
- <binString> is a binary string (e.g, '1010'B)
-
- <range> is further restricted as follows:
- - any <value> used in a SIZE clause must be non-negative.
- - when a pair of values is specified, the first value
- must be less than the second value.
- - when multiple ranges are specified, the ranges may
- not overlap but may touch. For example, (1..4 | 4..9)
- is invalid, and (1..4 | 5..9) is valid.
- - the ranges must be a subset of the maximum range of the
- base type.
-
-
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 40]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
-11.2. Examples
-
- Some examples of legal sub-typing:
-
- Integer32 (-20..100)
- Integer32 (0..100 | 300..500)
- Integer32 (300..500 | 0..100)
- Integer32 (0 | 2 | 4 | 6 | 8 | 10)
- OCTET STRING (SIZE(0..100))
- OCTET STRING (SIZE(0..100 | 300..500))
- OCTET STRING (SIZE(0 | 2 | 4 | 6 | 8 | 10))
- SYNTAX TimeInterval (0..100)
- SYNTAX DisplayString (SIZE(0..32))
-
- (Note the last two examples above are not valid in a TEXTUAL
- CONVENTION, see [3].)
-
- Some examples of illegal sub-typing:
-
- Integer32 (150..100) -- first greater than second
- Integer32 (0..100 | 50..500) -- ranges overlap
- Integer32 (0 | 2 | 0 ) -- value duplicated
- Integer32 (MIN..-1 | 1..MAX) -- MIN and MAX not allowed
- Integer32 (SIZE (0..34)) -- must not use SIZE
- OCTET STRING (0..100) -- must use SIZE
- OCTET STRING (SIZE(-10..100)) -- negative SIZE
-
-12. Security Considerations
-
- This document defines a language with which to write and read
- descriptions of management information. The language itself has no
- security impact on the Internet.
-
-
-
-13. Editors' Addresses
-
- Keith McCloghrie
- Cisco Systems, Inc.
- 170 West Tasman Drive
- San Jose, CA 95134-1706
- USA
- Phone: +1 408 526 5260
- EMail: kzm@cisco.com
-
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 41]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
- David Perkins
- SNMPinfo
- 3763 Benton Street
- Santa Clara, CA 95051
- USA
- Phone: +1 408 221-8702
- EMail: dperkins@snmpinfo.com
-
- Juergen Schoenwaelder
- TU Braunschweig
- Bueltenweg 74/75
- 38106 Braunschweig
- Germany
- Phone: +49 531 391-3283
- EMail: schoenw@ibr.cs.tu-bs.de
-
-
-14. References
-
-[1] Information processing systems - Open Systems Interconnection -
- Specification of Abstract Syntax Notation One (ASN.1),
- International Organization for Standardization. International
- Standard 8824, (December, 1987).
-
-[2] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M.
- and S. Waldbusser, "Conformance Statements for SMIv2", STD 58,
- RFC 2580, April 1999.
-
-[3] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M.
- and S. Waldbusser, "Textual Conventions for SMIv2", STD 58,
- RFC 2579, April 1999.
-
-[4] Information processing systems - Open Systems Interconnection -
- Specification of Basic Encoding Rules for Abstract Syntax Notation
- One (ASN.1), International Organization for Standardization.
- International Standard 8825, (December, 1987).
-
-[5] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M. and
- S. Waldbusser, "Management Information Base for Version 2 of the
- Simple Network Management Protocol (SNMPv2)", RFC 1907, January
- 1996.
-
-[6] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M. and
- S. Waldbusser, "Protocol Operations for Version 2 of the Simple
- Network Management Protocol (SNMPv2)", RFC 1905, January 1996.
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 42]
-\f
-
-
-
-
-RFC 2578 SMIv2 April 1999
-
-
-15. Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 43]
-
-
-
-
-
+++ /dev/null
-
-
-
-
-
-
-
-Network Working Group Editors of this version:
-Request for Comments: 2579 K. McCloghrie
-STD: 58 Cisco Systems
-Obsoletes: 1903 D. Perkins
-Category: Standards Track SNMPinfo
- J. Schoenwaelder
- TU Braunschweig
- Authors of previous version:
- J. Case
- SNMP Research
- K. McCloghrie
- Cisco Systems
- M. Rose
- First Virtual Holdings
- S. Waldbusser
- International Network Services
- April 1999
-
-
- Textual Conventions for SMIv2
-
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-
-Table of Contents
-
- 1 Introduction ..................................................2
- 1.1 A Note on Terminology .......................................2
- 2 Definitions ...................................................2
- 3 Mapping of the TEXTUAL-CONVENTION macro ......................20
- 3.1 Mapping of the DISPLAY-HINT clause .........................21
- 3.2 Mapping of the STATUS clause ...............................22
- 3.3 Mapping of the DESCRIPTION clause ..........................23
- 3.4 Mapping of the REFERENCE clause ............................23
- 3.5 Mapping of the SYNTAX clause ...............................23
- 4 Sub-typing of Textual Conventions ............................23
- 5 Revising a Textual Convention Definition .....................23
-
-
-McCloghrie, et al. Standards Track [Page 1]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- 6 Security Considerations ......................................24
- 7 Editors' Addresses ...........................................25
- 8 References ...................................................25
- 9 Full Copyright Statement .....................................26
-
-1. Introduction
-
- Management information is viewed as a collection of managed objects,
- residing in a virtual information store, termed the Management
- Information Base (MIB). Collections of related objects are defined
- in MIB modules. These modules are written using an adapted subset of
- OSI's Abstract Syntax Notation One, ASN.1 (1988) [1], termed the
- Structure of Management Information (SMI) [2].
-
- When designing a MIB module, it is often useful to define new types
- similar to those defined in the SMI. In comparison to a type defined
- in the SMI, each of these new types has a different name, a similar
- syntax, but a more precise semantics. These newly defined types are
- termed textual conventions, and are used for the convenience of
- humans reading the MIB module. It is the purpose of this document to
- define the initial set of textual conventions available to all MIB
- modules.
-
- Objects defined using a textual convention are always encoded by
- means of the rules that define their primitive type. However,
- textual conventions often have special semantics associated with
- them. As such, an ASN.1 macro, TEXTUAL-CONVENTION, is used to
- concisely convey the syntax and semantics of a textual convention.
-
-1.1. A Note on Terminology
-
- For the purpose of exposition, the original Structure of Management
- Information, as described in RFCs 1155 (STD 16), 1212 (STD 16), and
- RFC 1215, is termed the SMI version 1 (SMIv1). The current version
- of the Structure of Management Information is termed SMI version 2
- (SMIv2).
-
-2. Definitions
-
-SNMPv2-TC DEFINITIONS ::= BEGIN
-
-IMPORTS
- TimeTicks FROM SNMPv2-SMI;
-
-
--- definition of textual conventions
-
-TEXTUAL-CONVENTION MACRO ::=
-
-
-McCloghrie, et al. Standards Track [Page 2]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
-BEGIN
- TYPE NOTATION ::=
- DisplayPart
- "STATUS" Status
- "DESCRIPTION" Text
- ReferPart
- "SYNTAX" Syntax
-
- VALUE NOTATION ::=
- value(VALUE Syntax) -- adapted ASN.1
-
- DisplayPart ::=
- "DISPLAY-HINT" Text
- | empty
-
- Status ::=
- "current"
- | "deprecated"
- | "obsolete"
-
- ReferPart ::=
- "REFERENCE" Text
- | empty
-
- -- a character string as defined in [2]
- Text ::= value(IA5String)
-
- Syntax ::= -- Must be one of the following:
- -- a base type (or its refinement), or
- -- a BITS pseudo-type
- type
- | "BITS" "{" NamedBits "}"
-
- NamedBits ::= NamedBit
- | NamedBits "," NamedBit
-
- NamedBit ::= identifier "(" number ")" -- number is nonnegative
-
-END
-
-
-
-
-DisplayString ::= TEXTUAL-CONVENTION
- DISPLAY-HINT "255a"
- STATUS current
- DESCRIPTION
- "Represents textual information taken from the NVT ASCII
-
-
-McCloghrie, et al. Standards Track [Page 3]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- character set, as defined in pages 4, 10-11 of RFC 854.
-
- To summarize RFC 854, the NVT ASCII repertoire specifies:
-
- - the use of character codes 0-127 (decimal)
-
- - the graphics characters (32-126) are interpreted as
- US ASCII
-
- - NUL, LF, CR, BEL, BS, HT, VT and FF have the special
- meanings specified in RFC 854
-
- - the other 25 codes have no standard interpretation
-
- - the sequence 'CR LF' means newline
-
- - the sequence 'CR NUL' means carriage-return
-
- - an 'LF' not preceded by a 'CR' means moving to the
- same column on the next line.
-
- - the sequence 'CR x' for any x other than LF or NUL is
- illegal. (Note that this also means that a string may
- end with either 'CR LF' or 'CR NUL', but not with CR.)
-
- Any object defined using this syntax may not exceed 255
- characters in length."
- SYNTAX OCTET STRING (SIZE (0..255))
-
-PhysAddress ::= TEXTUAL-CONVENTION
- DISPLAY-HINT "1x:"
- STATUS current
- DESCRIPTION
- "Represents media- or physical-level addresses."
- SYNTAX OCTET STRING
-
-
-MacAddress ::= TEXTUAL-CONVENTION
- DISPLAY-HINT "1x:"
- STATUS current
- DESCRIPTION
- "Represents an 802 MAC address represented in the
- `canonical' order defined by IEEE 802.1a, i.e., as if it
- were transmitted least significant bit first, even though
- 802.5 (in contrast to other 802.x protocols) requires MAC
- addresses to be transmitted most significant bit first."
- SYNTAX OCTET STRING (SIZE (6))
-
-
-
-McCloghrie, et al. Standards Track [Page 4]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
-TruthValue ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "Represents a boolean value."
- SYNTAX INTEGER { true(1), false(2) }
-
-TestAndIncr ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "Represents integer-valued information used for atomic
- operations. When the management protocol is used to specify
- that an object instance having this syntax is to be
- modified, the new value supplied via the management protocol
- must precisely match the value presently held by the
- instance. If not, the management protocol set operation
- fails with an error of `inconsistentValue'. Otherwise, if
- the current value is the maximum value of 2^31-1 (2147483647
- decimal), then the value held by the instance is wrapped to
- zero; otherwise, the value held by the instance is
- incremented by one. (Note that regardless of whether the
- management protocol set operation succeeds, the variable-
- binding in the request and response PDUs are identical.)
-
- The value of the ACCESS clause for objects having this
- syntax is either `read-write' or `read-create'. When an
- instance of a columnar object having this syntax is created,
- any value may be supplied via the management protocol.
-
- When the network management portion of the system is re-
- initialized, the value of every object instance having this
- syntax must either be incremented from its value prior to
- the re-initialization, or (if the value prior to the re-
- initialization is unknown) be set to a pseudo-randomly
- generated value."
- SYNTAX INTEGER (0..2147483647)
-
-AutonomousType ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "Represents an independently extensible type identification
- value. It may, for example, indicate a particular sub-tree
- with further MIB definitions, or define a particular type of
- protocol or hardware."
- SYNTAX OBJECT IDENTIFIER
-
-
-InstancePointer ::= TEXTUAL-CONVENTION
- STATUS obsolete
-
-
-McCloghrie, et al. Standards Track [Page 5]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- DESCRIPTION
- "A pointer to either a specific instance of a MIB object or
- a conceptual row of a MIB table in the managed device. In
- the latter case, by convention, it is the name of the
- particular instance of the first accessible columnar object
- in the conceptual row.
-
- The two uses of this textual convention are replaced by
- VariablePointer and RowPointer, respectively."
- SYNTAX OBJECT IDENTIFIER
-
-
-VariablePointer ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "A pointer to a specific object instance. For example,
- sysContact.0 or ifInOctets.3."
- SYNTAX OBJECT IDENTIFIER
-
-
-RowPointer ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "Represents a pointer to a conceptual row. The value is the
- name of the instance of the first accessible columnar object
- in the conceptual row.
-
- For example, ifIndex.3 would point to the 3rd row in the
- ifTable (note that if ifIndex were not-accessible, then
- ifDescr.3 would be used instead)."
- SYNTAX OBJECT IDENTIFIER
-
-RowStatus ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "The RowStatus textual convention is used to manage the
- creation and deletion of conceptual rows, and is used as the
- value of the SYNTAX clause for the status column of a
- conceptual row (as described in Section 7.7.1 of [2].)
-
-
-
-
-
-
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 6]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- The status column has six defined values:
-
- - `active', which indicates that the conceptual row is
- available for use by the managed device;
-
- - `notInService', which indicates that the conceptual
- row exists in the agent, but is unavailable for use by
- the managed device (see NOTE below); 'notInService' has
- no implication regarding the internal consistency of
- the row, availability of resources, or consistency with
- the current state of the managed device;
-
- - `notReady', which indicates that the conceptual row
- exists in the agent, but is missing information
- necessary in order to be available for use by the
- managed device (i.e., one or more required columns in
- the conceptual row have not been instanciated);
-
- - `createAndGo', which is supplied by a management
- station wishing to create a new instance of a
- conceptual row and to have its status automatically set
- to active, making it available for use by the managed
- device;
-
- - `createAndWait', which is supplied by a management
- station wishing to create a new instance of a
- conceptual row (but not make it available for use by
- the managed device); and,
-
- - `destroy', which is supplied by a management station
- wishing to delete all of the instances associated with
- an existing conceptual row.
-
- Whereas five of the six values (all except `notReady') may
- be specified in a management protocol set operation, only
- three values will be returned in response to a management
- protocol retrieval operation: `notReady', `notInService' or
- `active'. That is, when queried, an existing conceptual row
- has only three states: it is either available for use by
- the managed device (the status column has value `active');
- it is not available for use by the managed device, though
- the agent has sufficient information to attempt to make it
- so (the status column has value `notInService'); or, it is
- not available for use by the managed device, and an attempt
- to make it so would fail because the agent has insufficient
- information (the state column has value `notReady').
-
-
-
-
-McCloghrie, et al. Standards Track [Page 7]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- NOTE WELL
-
- This textual convention may be used for a MIB table,
- irrespective of whether the values of that table's
- conceptual rows are able to be modified while it is
- active, or whether its conceptual rows must be taken
- out of service in order to be modified. That is, it is
- the responsibility of the DESCRIPTION clause of the
- status column to specify whether the status column must
- not be `active' in order for the value of some other
- column of the same conceptual row to be modified. If
- such a specification is made, affected columns may be
- changed by an SNMP set PDU if the RowStatus would not
- be equal to `active' either immediately before or after
- processing the PDU. In other words, if the PDU also
- contained a varbind that would change the RowStatus
- value, the column in question may be changed if the
- RowStatus was not equal to `active' as the PDU was
- received, or if the varbind sets the status to a value
- other than 'active'.
-
-
- Also note that whenever any elements of a row exist, the
- RowStatus column must also exist.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 8]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- To summarize the effect of having a conceptual row with a
- status column having a SYNTAX clause value of RowStatus,
- consider the following state diagram:
-
-
- STATE
- +--------------+-----------+-------------+-------------
- | A | B | C | D
- | |status col.|status column|
- |status column | is | is |status column
- ACTION |does not exist| notReady | notInService| is active
---------------+--------------+-----------+-------------+-------------
-set status |noError ->D|inconsist- |inconsistent-|inconsistent-
-column to | or | entValue| Value| Value
-createAndGo |inconsistent- | | |
- | Value| | |
---------------+--------------+-----------+-------------+-------------
-set status |noError see 1|inconsist- |inconsistent-|inconsistent-
-column to | or | entValue| Value| Value
-createAndWait |wrongValue | | |
---------------+--------------+-----------+-------------+-------------
-set status |inconsistent- |inconsist- |noError |noError
-column to | Value| entValue| |
-active | | | |
- | | or | |
- | | | |
- | |see 2 ->D|see 8 ->D| ->D
---------------+--------------+-----------+-------------+-------------
-set status |inconsistent- |inconsist- |noError |noError ->C
-column to | Value| entValue| |
-notInService | | | |
- | | or | | or
- | | | |
- | |see 3 ->C| ->C|see 6
---------------+--------------+-----------+-------------+-------------
-set status |noError |noError |noError |noError ->A
-column to | | | | or
-destroy | ->A| ->A| ->A|see 7
---------------+--------------+-----------+-------------+-------------
-set any other |see 4 |noError |noError |see 5
-column to some| | | |
-value | | see 1| ->C| ->D
---------------+--------------+-----------+-------------+-------------
-
- (1) goto B or C, depending on information available to the
- agent.
-
- (2) if other variable bindings included in the same PDU,
-
-
-McCloghrie, et al. Standards Track [Page 9]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- provide values for all columns which are missing but
- required, and all columns have acceptable values, then
- return noError and goto D.
-
- (3) if other variable bindings included in the same PDU,
- provide legal values for all columns which are missing but
- required, then return noError and goto C.
-
- (4) at the discretion of the agent, the return value may be
- either:
-
- inconsistentName: because the agent does not choose to
- create such an instance when the corresponding
- RowStatus instance does not exist, or
-
- inconsistentValue: if the supplied value is
- inconsistent with the state of some other MIB object's
- value, or
-
- noError: because the agent chooses to create the
- instance.
-
- If noError is returned, then the instance of the status
- column must also be created, and the new state is B or C,
- depending on the information available to the agent. If
- inconsistentName or inconsistentValue is returned, the row
- remains in state A.
-
- (5) depending on the MIB definition for the column/table,
- either noError or inconsistentValue may be returned.
-
- (6) the return value can indicate one of the following
- errors:
-
- wrongValue: because the agent does not support
- notInService (e.g., an agent which does not support
- createAndWait), or
-
- inconsistentValue: because the agent is unable to take
- the row out of service at this time, perhaps because it
- is in use and cannot be de-activated.
-
- (7) the return value can indicate the following error:
-
- inconsistentValue: because the agent is unable to
- remove the row at this time, perhaps because it is in
- use and cannot be de-activated.
-
-
-
-McCloghrie, et al. Standards Track [Page 10]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- (8) the transition to D can fail, e.g., if the values of the
- conceptual row are inconsistent, then the error code would
- be inconsistentValue.
-
- NOTE: Other processing of (this and other varbinds of) the
- set request may result in a response other than noError
- being returned, e.g., wrongValue, noCreation, etc.
-
-
- Conceptual Row Creation
-
- There are four potential interactions when creating a
- conceptual row: selecting an instance-identifier which is
- not in use; creating the conceptual row; initializing any
- objects for which the agent does not supply a default; and,
- making the conceptual row available for use by the managed
- device.
-
- Interaction 1: Selecting an Instance-Identifier
-
- The algorithm used to select an instance-identifier varies
- for each conceptual row. In some cases, the instance-
- identifier is semantically significant, e.g., the
- destination address of a route, and a management station
- selects the instance-identifier according to the semantics.
-
- In other cases, the instance-identifier is used solely to
- distinguish conceptual rows, and a management station
- without specific knowledge of the conceptual row might
- examine the instances present in order to determine an
- unused instance-identifier. (This approach may be used, but
- it is often highly sub-optimal; however, it is also a
- questionable practice for a naive management station to
- attempt conceptual row creation.)
-
- Alternately, the MIB module which defines the conceptual row
- might provide one or more objects which provide assistance
- in determining an unused instance-identifier. For example,
- if the conceptual row is indexed by an integer-value, then
- an object having an integer-valued SYNTAX clause might be
- defined for such a purpose, allowing a management station to
- issue a management protocol retrieval operation. In order
- to avoid unnecessary collisions between competing management
- stations, `adjacent' retrievals of this object should be
- different.
-
- Finally, the management station could select a pseudo-random
- number to use as the index. In the event that this index
-
-
-McCloghrie, et al. Standards Track [Page 11]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- was already in use and an inconsistentValue was returned in
- response to the management protocol set operation, the
- management station should simply select a new pseudo-random
- number and retry the operation.
-
- A MIB designer should choose between the two latter
- algorithms based on the size of the table (and therefore the
- efficiency of each algorithm). For tables in which a large
- number of entries are expected, it is recommended that a MIB
- object be defined that returns an acceptable index for
- creation. For tables with small numbers of entries, it is
- recommended that the latter pseudo-random index mechanism be
- used.
-
- Interaction 2: Creating the Conceptual Row
-
- Once an unused instance-identifier has been selected, the
- management station determines if it wishes to create and
- activate the conceptual row in one transaction or in a
- negotiated set of interactions.
-
- Interaction 2a: Creating and Activating the Conceptual Row
-
- The management station must first determine the column
- requirements, i.e., it must determine those columns for
- which it must or must not provide values. Depending on the
- complexity of the table and the management station's
- knowledge of the agent's capabilities, this determination
- can be made locally by the management station. Alternately,
- the management station issues a management protocol get
- operation to examine all columns in the conceptual row that
- it wishes to create. In response, for each column, there
- are three possible outcomes:
-
- - a value is returned, indicating that some other
- management station has already created this conceptual
- row. We return to interaction 1.
-
- - the exception `noSuchInstance' is returned,
- indicating that the agent implements the object-type
- associated with this column, and that this column in at
- least one conceptual row would be accessible in the MIB
- view used by the retrieval were it to exist. For those
- columns to which the agent provides read-create access,
- the `noSuchInstance' exception tells the management
- station that it should supply a value for this column
- when the conceptual row is to be created.
-
-
-
-McCloghrie, et al. Standards Track [Page 12]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- - the exception `noSuchObject' is returned, indicating
- that the agent does not implement the object-type
- associated with this column or that there is no
- conceptual row for which this column would be
- accessible in the MIB view used by the retrieval. As
- such, the management station can not issue any
- management protocol set operations to create an
- instance of this column.
-
- Once the column requirements have been determined, a
- management protocol set operation is accordingly issued.
- This operation also sets the new instance of the status
- column to `createAndGo'.
-
- When the agent processes the set operation, it verifies that
- it has sufficient information to make the conceptual row
- available for use by the managed device. The information
- available to the agent is provided by two sources: the
- management protocol set operation which creates the
- conceptual row, and, implementation-specific defaults
- supplied by the agent (note that an agent must provide
- implementation-specific defaults for at least those objects
- which it implements as read-only). If there is sufficient
- information available, then the conceptual row is created, a
- `noError' response is returned, the status column is set to
- `active', and no further interactions are necessary (i.e.,
- interactions 3 and 4 are skipped). If there is insufficient
- information, then the conceptual row is not created, and the
- set operation fails with an error of `inconsistentValue'.
- On this error, the management station can issue a management
- protocol retrieval operation to determine if this was
- because it failed to specify a value for a required column,
- or, because the selected instance of the status column
- already existed. In the latter case, we return to
- interaction 1. In the former case, the management station
- can re-issue the set operation with the additional
- information, or begin interaction 2 again using
- `createAndWait' in order to negotiate creation of the
- conceptual row.
-
-
-
-
-
-
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 13]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- NOTE WELL
-
- Regardless of the method used to determine the column
- requirements, it is possible that the management
- station might deem a column necessary when, in fact,
- the agent will not allow that particular columnar
- instance to be created or written. In this case, the
- management protocol set operation will fail with an
- error such as `noCreation' or `notWritable'. In this
- case, the management station decides whether it needs
- to be able to set a value for that particular columnar
- instance. If not, the management station re-issues the
- management protocol set operation, but without setting
- a value for that particular columnar instance;
- otherwise, the management station aborts the row
- creation algorithm.
-
- Interaction 2b: Negotiating the Creation of the Conceptual
- Row
-
- The management station issues a management protocol set
- operation which sets the desired instance of the status
- column to `createAndWait'. If the agent is unwilling to
- process a request of this sort, the set operation fails with
- an error of `wrongValue'. (As a consequence, such an agent
- must be prepared to accept a single management protocol set
- operation, i.e., interaction 2a above, containing all of the
- columns indicated by its column requirements.) Otherwise,
- the conceptual row is created, a `noError' response is
- returned, and the status column is immediately set to either
- `notInService' or `notReady', depending on whether it has
- sufficient information to (attempt to) make the conceptual
- row available for use by the managed device. If there is
- sufficient information available, then the status column is
- set to `notInService'; otherwise, if there is insufficient
- information, then the status column is set to `notReady'.
- Regardless, we proceed to interaction 3.
-
- Interaction 3: Initializing non-defaulted Objects
-
- The management station must now determine the column
- requirements. It issues a management protocol get operation
- to examine all columns in the created conceptual row. In
- the response, for each column, there are three possible
- outcomes:
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 14]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- - a value is returned, indicating that the agent
- implements the object-type associated with this column
- and had sufficient information to provide a value. For
- those columns to which the agent provides read-create
- access (and for which the agent allows their values to
- be changed after their creation), a value return tells
- the management station that it may issue additional
- management protocol set operations, if it desires, in
- order to change the value associated with this column.
-
- - the exception `noSuchInstance' is returned,
- indicating that the agent implements the object-type
- associated with this column, and that this column in at
- least one conceptual row would be accessible in the MIB
- view used by the retrieval were it to exist. However,
- the agent does not have sufficient information to
- provide a value, and until a value is provided, the
- conceptual row may not be made available for use by the
- managed device. For those columns to which the agent
- provides read-create access, the `noSuchInstance'
- exception tells the management station that it must
- issue additional management protocol set operations, in
- order to provide a value associated with this column.
-
- - the exception `noSuchObject' is returned, indicating
- that the agent does not implement the object-type
- associated with this column or that there is no
- conceptual row for which this column would be
- accessible in the MIB view used by the retrieval. As
- such, the management station can not issue any
- management protocol set operations to create an
- instance of this column.
-
- If the value associated with the status column is
- `notReady', then the management station must first deal with
- all `noSuchInstance' columns, if any. Having done so, the
- value of the status column becomes `notInService', and we
- proceed to interaction 4.
-
-
-
-
-
-
-
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 15]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- Interaction 4: Making the Conceptual Row Available
-
- Once the management station is satisfied with the values
- associated with the columns of the conceptual row, it issues
- a management protocol set operation to set the status column
- to `active'. If the agent has sufficient information to
- make the conceptual row available for use by the managed
- device, the management protocol set operation succeeds (a
- `noError' response is returned). Otherwise, the management
- protocol set operation fails with an error of
- `inconsistentValue'.
-
- NOTE WELL
-
- A conceptual row having a status column with value
- `notInService' or `notReady' is unavailable to the
- managed device. As such, it is possible for the
- managed device to create its own instances during the
- time between the management protocol set operation
- which sets the status column to `createAndWait' and the
- management protocol set operation which sets the status
- column to `active'. In this case, when the management
- protocol set operation is issued to set the status
- column to `active', the values held in the agent
- supersede those used by the managed device.
-
- If the management station is prevented from setting the
- status column to `active' (e.g., due to management station
- or network failure) the conceptual row will be left in the
- `notInService' or `notReady' state, consuming resources
- indefinitely. The agent must detect conceptual rows that
- have been in either state for an abnormally long period of
- time and remove them. It is the responsibility of the
- DESCRIPTION clause of the status column to indicate what an
- abnormally long period of time would be. This period of
- time should be long enough to allow for human response time
- (including `think time') between the creation of the
- conceptual row and the setting of the status to `active'.
- In the absence of such information in the DESCRIPTION
- clause, it is suggested that this period be approximately 5
- minutes in length. This removal action applies not only to
- newly-created rows, but also to previously active rows which
- are set to, and left in, the notInService state for a
- prolonged period exceeding that which is considered normal
- for such a conceptual row.
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 16]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- Conceptual Row Suspension
-
- When a conceptual row is `active', the management station
- may issue a management protocol set operation which sets the
- instance of the status column to `notInService'. If the
- agent is unwilling to do so, the set operation fails with an
- error of `wrongValue' or `inconsistentValue'. Otherwise,
- the conceptual row is taken out of service, and a `noError'
- response is returned. It is the responsibility of the
- DESCRIPTION clause of the status column to indicate under
- what circumstances the status column should be taken out of
- service (e.g., in order for the value of some other column
- of the same conceptual row to be modified).
-
-
- Conceptual Row Deletion
-
- For deletion of conceptual rows, a management protocol set
- operation is issued which sets the instance of the status
- column to `destroy'. This request may be made regardless of
- the current value of the status column (e.g., it is possible
- to delete conceptual rows which are either `notReady',
- `notInService' or `active'.) If the operation succeeds,
- then all instances associated with the conceptual row are
- immediately removed."
- SYNTAX INTEGER {
- -- the following two values are states:
- -- these values may be read or written
- active(1),
- notInService(2),
-
- -- the following value is a state:
- -- this value may be read, but not written
- notReady(3),
-
- -- the following three values are
- -- actions: these values may be written,
- -- but are never read
- createAndGo(4),
- createAndWait(5),
- destroy(6)
- }
-
-TimeStamp ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "The value of the sysUpTime object at which a specific
- occurrence happened. The specific occurrence must be
-
-
-McCloghrie, et al. Standards Track [Page 17]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- defined in the description of any object defined using this
- type.
-
- If sysUpTime is reset to zero as a result of a re-
- initialization of the network management (sub)system, then
- the values of all TimeStamp objects are also reset.
- However, after approximately 497 days without a re-
- initialization, the sysUpTime object will reach 2^^32-1 and
- then increment around to zero; in this case, existing values
- of TimeStamp objects do not change. This can lead to
- ambiguities in the value of TimeStamp objects."
- SYNTAX TimeTicks
-
-
-TimeInterval ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "A period of time, measured in units of 0.01 seconds."
- SYNTAX INTEGER (0..2147483647)
-
-DateAndTime ::= TEXTUAL-CONVENTION
- DISPLAY-HINT "2d-1d-1d,1d:1d:1d.1d,1a1d:1d"
- STATUS current
- DESCRIPTION
- "A date-time specification.
-
- field octets contents range
- ----- ------ -------- -----
- 1 1-2 year* 0..65536
- 2 3 month 1..12
- 3 4 day 1..31
- 4 5 hour 0..23
- 5 6 minutes 0..59
- 6 7 seconds 0..60
- (use 60 for leap-second)
- 7 8 deci-seconds 0..9
- 8 9 direction from UTC '+' / '-'
- 9 10 hours from UTC* 0..13
- 10 11 minutes from UTC 0..59
-
- * Notes:
- - the value of year is in network-byte order
- - daylight saving time in New Zealand is +13
-
- For example, Tuesday May 26, 1992 at 1:30:15 PM EDT would be
- displayed as:
-
- 1992-5-26,13:30:15.0,-4:0
-
-
-McCloghrie, et al. Standards Track [Page 18]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- Note that if only local time is known, then timezone
- information (fields 8-10) is not present."
- SYNTAX OCTET STRING (SIZE (8 | 11))
-
-
-StorageType ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "Describes the memory realization of a conceptual row. A
- row which is volatile(2) is lost upon reboot. A row which
- is either nonVolatile(3), permanent(4) or readOnly(5), is
- backed up by stable storage. A row which is permanent(4)
- can be changed but not deleted. A row which is readOnly(5)
- cannot be changed nor deleted.
-
- If the value of an object with this syntax is either
- permanent(4) or readOnly(5), it cannot be written.
- Conversely, if the value is either other(1), volatile(2) or
- nonVolatile(3), it cannot be modified to be permanent(4) or
- readOnly(5). (All illegal modifications result in a
- 'wrongValue' error.)
-
- Every usage of this textual convention is required to
- specify the columnar objects which a permanent(4) row must
- at a minimum allow to be writable."
- SYNTAX INTEGER {
- other(1), -- eh?
- volatile(2), -- e.g., in RAM
- nonVolatile(3), -- e.g., in NVRAM
- permanent(4), -- e.g., partially in ROM
- readOnly(5) -- e.g., completely in ROM
- }
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 19]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
-TDomain ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "Denotes a kind of transport service.
-
- Some possible values, such as snmpUDPDomain, are defined in
- the SNMPv2-TM MIB module. Other possible values are defined
- in other MIB modules."
- REFERENCE "The SNMPv2-TM MIB module is defined in RFC 1906."
- SYNTAX OBJECT IDENTIFIER
-
-
-TAddress ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "Denotes a transport service address.
-
- A TAddress value is always interpreted within the context of a
- TDomain value. Thus, each definition of a TDomain value must
- be accompanied by a definition of a textual convention for use
- with that TDomain. Some possible textual conventions, such as
- SnmpUDPAddress for snmpUDPDomain, are defined in the SNMPv2-TM
- MIB module. Other possible textual conventions are defined in
- other MIB modules."
- REFERENCE "The SNMPv2-TM MIB module is defined in RFC 1906."
- SYNTAX OCTET STRING (SIZE (1..255))
-
-
-END
-
-3. Mapping of the TEXTUAL-CONVENTION macro
-
- The TEXTUAL-CONVENTION macro is used to convey the syntax and
- semantics associated with a textual convention. It should be noted
- that the expansion of the TEXTUAL-CONVENTION macro is something which
- conceptually happens during implementation and not during run-time.
-
- The name of a textual convention must consist of one or more letters
- or digits, with the initial character being an upper case letter.
- The name must not conflict with any of the reserved words listed in
- section 3.7 of [2], should not consist of all upper case letters, and
- shall not exceed 64 characters in length. (However, names longer
- than 32 characters are not recommended.) The hyphen is not allowed
- in the name of a textual convention (except for use in information
- modules converted from SMIv1 which allowed hyphens in ASN.1 type
- assignments). Further, all names used for the textual conventions
- defined in all "standard" information modules shall be unique.
-
-
-
-McCloghrie, et al. Standards Track [Page 20]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
-3.1. Mapping of the DISPLAY-HINT clause
-
- The DISPLAY-HINT clause, which need not be present, gives a hint as
- to how the value of an instance of an object with the syntax defined
- using this textual convention might be displayed. The DISPLAY-HINT
- clause must not be present if the Textual Convention is defined with
- a syntax of: OBJECT IDENTIFIER, IpAddress, Counter32, Counter64, or
- any enumerated syntax (BITS or INTEGER). The determination of
- whether it makes sense for other syntax types is dependent on the
- specific definition of the Textual Convention.
-
- When the syntax has an underlying primitive type of INTEGER, the hint
- consists of an integer-format specification, containing two parts.
- The first part is a single character suggesting a display format,
- either: `x' for hexadecimal, or `d' for decimal, or `o' for octal, or
- `b' for binary. For all types, when rendering the value, leading
- zeros are omitted, and for negative values, a minus sign is rendered
- immediately before the digits. The second part is always omitted for
- `x', `o' and `b', and need not be present for `d'. If present, the
- second part starts with a hyphen and is followed by a decimal number,
- which defines the implied decimal point when rendering the value.
- For example:
-
- Hundredths ::= TEXTUAL-CONVENTION
- DISPLAY-HINT "d-2"
- ...
- SYNTAX INTEGER (0..10000)
-
- suggests that a Hundredths value of 1234 be rendered as "12.34"
-
-
- When the syntax has an underlying primitive type of OCTET STRING, the
- hint consists of one or more octet-format specifications. Each
- specification consists of five parts, with each part using and
- removing zero or more of the next octets from the value and producing
- the next zero or more characters to be displayed. The octets within
- the value are processed in order of significance, most significant
- first.
-
- The five parts of a octet-format specification are:
-
-(1) the (optional) repeat indicator; if present, this part is a `*',
- and indicates that the current octet of the value is to be used as
- the repeat count. The repeat count is an unsigned integer (which
- may be zero) which specifies how many times the remainder of this
- octet-format specification should be successively applied. If the
- repeat indicator is not present, the repeat count is one.
-
-
-
-McCloghrie, et al. Standards Track [Page 21]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
-(2) the octet length: one or more decimal digits specifying the number
- of octets of the value to be used and formatted by this octet-
- specification. Note that the octet length can be zero. If less
- than this number of octets remain in the value, then the lesser
- number of octets are used.
-
-(3) the display format, either: `x' for hexadecimal, `d' for decimal,
- `o' for octal, `a' for ascii, or `t' for UTF-8. If the octet
- length part is greater than one, and the display format part refers
- to a numeric format, then network-byte ordering (big-endian
- encoding) is used interpreting the octets in the value. The octets
- processed by the `t' display format do not necessarily form an
- integral number of UTF-8 characters. Trailing octets which do not
- form a valid UTF-8 encoded character are discarded.
-
-(4) the (optional) display separator character; if present, this part
- is a single character which is produced for display after each
- application of this octet-specification; however, this character is
- not produced for display if it would be immediately followed by the
- display of the repeat terminator character for this octet-
- specification. This character can be any character other than a
- decimal digit and a `*'.
-
-(5) the (optional) repeat terminator character, which can be present
- only if the display separator character is present and this octet-
- specification begins with a repeat indicator; if present, this part
- is a single character which is produced after all the zero or more
- repeated applications (as given by the repeat count) of this
- octet-specification. This character can be any character other
- than a decimal digit and a `*'.
-
- Output of a display separator character or a repeat terminator
- character is suppressed if it would occur as the last character of
- the display.
-
- If the octets of the value are exhausted before all the octet-format
- specification have been used, then the excess specifications are
- ignored. If additional octets remain in the value after interpreting
- all the octet-format specifications, then the last octet-format
- specification is re-interpreted to process the additional octets,
- until no octets remain in the value.
-
-3.2. Mapping of the STATUS clause
-
- The STATUS clause, which must be present, indicates whether this
- definition is current or historic.
-
- The value "current" means that the definition is current and valid.
-
-
-McCloghrie, et al. Standards Track [Page 22]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- The value "obsolete" means the definition is obsolete and should not
- be implemented and/or can be removed if previously implemented.
- While the value "deprecated" also indicates an obsolete definition,
- it permits new/continued implementation in order to foster
- interoperability with older/existing implementations.
-
-3.3. Mapping of the DESCRIPTION clause
-
- The DESCRIPTION clause, which must be present, contains a textual
- definition of the textual convention, which provides all semantic
- definitions necessary for implementation, and should embody any
- information which would otherwise be communicated in any ASN.1
- commentary annotations associated with the object.
-
-3.4. Mapping of the REFERENCE clause
-
- The REFERENCE clause, which need not be present, contains a textual
- cross-reference to some other document, either another information
- module which defines a related assignment, or some other document
- which provides additional information relevant to this definition.
-
-3.5. Mapping of the SYNTAX clause
-
- The SYNTAX clause, which must be present, defines abstract data
- structure corresponding to the textual convention. The data
- structure must be one of the alternatives defined in the ObjectSyntax
- CHOICE or the BITS construct (see section 7.1 in [2]). Note that
- this means that the SYNTAX clause of a Textual Convention can not
- refer to a previously defined Textual Convention.
-
- An extended subset of the full capabilities of ASN.1 (1988) sub-
- typing is allowed, as appropriate to the underlying ASN.1 type. Any
- such restriction on size, range or enumerations specified in this
- clause represents the maximal level of support which makes "protocol
- sense". Restrictions on sub-typing are specified in detail in
- Section 9 and Appendix A of [2].
-
-4. Sub-typing of Textual Conventions
-
- The SYNTAX clause of a TEXTUAL CONVENTION macro may be sub-typed in
- the same way as the SYNTAX clause of an OBJECT-TYPE macro (see
- section 11 of [2]).
-
-5. Revising a Textual Convention Definition
-
- It may be desirable to revise the definition of a textual convention
- after experience is gained with it. However, changes are not allowed
- if they have any potential to cause interoperability problems "over
-
-
-McCloghrie, et al. Standards Track [Page 23]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
- the wire" between an implementation using an original specification
- and an implementation using an updated specification(s). Such
- changes can only be accommodated by defining a new textual convention
- (i.e., a new name).
-
- The following revisions are allowed:
-
-(1) A SYNTAX clause containing an enumerated INTEGER may have new
- enumerations added or existing labels changed. Similarly, named
- bits may be added or existing labels changed for the BITS
- construct.
-
-(2) A STATUS clause value of "current" may be revised as "deprecated"
- or "obsolete". Similarly, a STATUS clause value of "deprecated"
- may be revised as "obsolete". When making such a change, the
- DESCRIPTION clause should be updated to explain the rationale.
-
-(3) A REFERENCE clause may be added or updated.
-
-(4) A DISPLAY-HINTS clause may be added or updated.
-
-(5) Clarifications and additional information may be included in the
- DESCRIPTION clause.
-
-(6) Any editorial change.
-
- Note that with the introduction of the TEXTUAL-CONVENTION macro,
- there is no longer any need to define types in the following manner:
-
- DisplayString ::= OCTET STRING (SIZE (0..255))
-
- When revising an information module containing a definition such as
- this, that definition should be replaced by a TEXTUAL-CONVENTION
- macro.
-
-6. Security Considerations
-
- This document defines the means to define new data types for the
- language used to write and read descriptions of management
- information. These data types have no security impact on the
- Internet.
-
-
-
-
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 24]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
-7. Editors' Addresses
-
- Keith McCloghrie
- Cisco Systems, Inc.
- 170 West Tasman Drive
- San Jose, CA 95134-1706
- USA
- Phone: +1 408 526 5260
- EMail: kzm@cisco.com
-
- David Perkins
- SNMPinfo
- 3763 Benton Street
- Santa Clara, CA 95051
- USA
- Phone: +1 408 221-8702
- EMail: dperkins@snmpinfo.com
-
- Juergen Schoenwaelder
- TU Braunschweig
- Bueltenweg 74/75
- 38106 Braunschweig
- Germany
- Phone: +49 531 391-3283
- EMail: schoenw@ibr.cs.tu-bs.de
-
-
-8. References
-
-[1] Information processing systems - Open Systems Interconnection -
- Specification of Abstract Syntax Notation One (ASN.1),
- International Organization for Standardization. International
- Standard 8824, (December, 1987).
-
-[2] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M.
- and S. Waldbusser, "Structure of Management Information Version 2
- (SMIv2)", STD 58, RFC 2578, April 1999.
-
-[3] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M. and
- Waldbusser, S., "Transport Mappings for Version 2 of the" Simple
- Network Management Protocol (SNMPv2)", RFC 1906, January 1996.
-
-
-
-
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 25]
-\f
-
-
-
-
-RFC 2579 Textual Conventions for SMIv2 April 1999
-
-
-9. Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-McCloghrie, et al. Standards Track [Page 26]
+++ /dev/null
-
-
-
-
-
-
-Network Working Group C. Newman
-Request for Comments: 2595 Innosoft
-Category: Standards Track June 1999
-
-
- Using TLS with IMAP, POP3 and ACAP
-
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-1. Motivation
-
- The TLS protocol (formerly known as SSL) provides a way to secure an
- application protocol from tampering and eavesdropping. The option of
- using such security is desirable for IMAP, POP and ACAP due to common
- connection eavesdropping and hijacking attacks [AUTH]. Although
- advanced SASL authentication mechanisms can provide a lightweight
- version of this service, TLS is complimentary to simple
- authentication-only SASL mechanisms or deployed clear-text password
- login commands.
-
- Many sites have a high investment in authentication infrastructure
- (e.g., a large database of a one-way-function applied to user
- passwords), so a privacy layer which is not tightly bound to user
- authentication can protect against network eavesdropping attacks
- without requiring a new authentication infrastructure and/or forcing
- all users to change their password. Recognizing that such sites will
- desire simple password authentication in combination with TLS
- encryption, this specification defines the PLAIN SASL mechanism for
- use with protocols which lack a simple password authentication
- command such as ACAP and SMTP. (Note there is a separate RFC for the
- STARTTLS command in SMTP [SMTPTLS].)
-
- There is a strong desire in the IETF to eliminate the transmission of
- clear-text passwords over unencrypted channels. While SASL can be
- used for this purpose, TLS provides an additional tool with different
- deployability characteristics. A server supporting both TLS with
-
-
-
-
-Newman Standards Track [Page 1]
-\f
-RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
-
-
- simple passwords and a challenge/response SASL mechanism is likely to
- interoperate with a wide variety of clients without resorting to
- unencrypted clear-text passwords.
-
- The STARTTLS command rectifies a number of the problems with using a
- separate port for a "secure" protocol variant. Some of these are
- mentioned in section 7.
-
-1.1. Conventions Used in this Document
-
- The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD NOT",
- "MAY", and "OPTIONAL" in this document are to be interpreted as
- described in "Key words for use in RFCs to Indicate Requirement
- Levels" [KEYWORDS].
-
- Terms related to authentication are defined in "On Internet
- Authentication" [AUTH].
-
- Formal syntax is defined using ABNF [ABNF].
-
- In examples, "C:" and "S:" indicate lines sent by the client and
- server respectively.
-
-2. Basic Interoperability and Security Requirements
-
- The following requirements apply to all implementations of the
- STARTTLS extension for IMAP, POP3 and ACAP.
-
-2.1. Cipher Suite Requirements
-
- Implementation of the TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA [TLS] cipher
- suite is REQUIRED. This is important as it assures that any two
- compliant implementations can be configured to interoperate.
-
- All other cipher suites are OPTIONAL.
-
-2.2. Privacy Operational Mode Security Requirements
-
- Both clients and servers SHOULD have a privacy operational mode which
- refuses authentication unless successful activation of an encryption
- layer (such as that provided by TLS) occurs prior to or at the time
- of authentication and which will terminate the connection if that
- encryption layer is deactivated. Implementations are encouraged to
- have flexability with respect to the minimal encryption strength or
- cipher suites permitted. A minimalist approach to this
- recommendation would be an operational mode where the
- TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA cipher suite is mandatory prior to
- permitting authentication.
-
-
-
-Newman Standards Track [Page 2]
-\f
-RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
-
-
- Clients MAY have an operational mode which uses encryption only when
- it is advertised by the server, but authentication continues
- regardless. For backwards compatibility, servers SHOULD have an
- operational mode where only the authentication mechanisms required by
- the relevant base protocol specification are needed to successfully
- authenticate.
-
-2.3. Clear-Text Password Requirements
-
- Clients and servers which implement STARTTLS MUST be configurable to
- refuse all clear-text login commands or mechanisms (including both
- standards-track and nonstandard mechanisms) unless an encryption
- layer of adequate strength is active. Servers which allow
- unencrypted clear-text logins SHOULD be configurable to refuse
- clear-text logins both for the entire server, and on a per-user
- basis.
-
-2.4. Server Identity Check
-
- During the TLS negotiation, the client MUST check its understanding
- of the server hostname against the server's identity as presented in
- the server Certificate message, in order to prevent man-in-the-middle
- attacks. Matching is performed according to these rules:
-
- - The client MUST use the server hostname it used to open the
- connection as the value to compare against the server name as
- expressed in the server certificate. The client MUST NOT use any
- form of the server hostname derived from an insecure remote source
- (e.g., insecure DNS lookup). CNAME canonicalization is not done.
-
- - If a subjectAltName extension of type dNSName is present in the
- certificate, it SHOULD be used as the source of the server's
- identity.
-
- - Matching is case-insensitive.
-
- - A "*" wildcard character MAY be used as the left-most name
- component in the certificate. For example, *.example.com would
- match a.example.com, foo.example.com, etc. but would not match
- example.com.
-
- - If the certificate contains multiple names (e.g. more than one
- dNSName field), then a match with any one of the fields is
- considered acceptable.
-
- If the match fails, the client SHOULD either ask for explicit user
- confirmation, or terminate the connection and indicate the server's
- identity is suspect.
-
-
-
-Newman Standards Track [Page 3]
-\f
-RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
-
-
-2.5. TLS Security Policy Check
-
- Both the client and server MUST check the result of the STARTTLS
- command and subsequent TLS negotiation to see whether acceptable
- authentication or privacy was achieved. Ignoring this step
- completely invalidates using TLS for security. The decision about
- whether acceptable authentication or privacy was achieved is made
- locally, is implementation-dependent, and is beyond the scope of this
- document.
-
-3. IMAP STARTTLS extension
-
- When the TLS extension is present in IMAP, "STARTTLS" is listed as a
- capability in response to the CAPABILITY command. This extension
- adds a single command, "STARTTLS" to the IMAP protocol which is used
- to begin a TLS negotiation.
-
-3.1. STARTTLS Command
-
- Arguments: none
-
- Responses: no specific responses for this command
-
- Result: OK - begin TLS negotiation
- BAD - command unknown or arguments invalid
-
- A TLS negotiation begins immediately after the CRLF at the end of
- the tagged OK response from the server. Once a client issues a
- STARTTLS command, it MUST NOT issue further commands until a
- server response is seen and the TLS negotiation is complete.
-
- The STARTTLS command is only valid in non-authenticated state.
- The server remains in non-authenticated state, even if client
- credentials are supplied during the TLS negotiation. The SASL
- [SASL] EXTERNAL mechanism MAY be used to authenticate once TLS
- client credentials are successfully exchanged, but servers
- supporting the STARTTLS command are not required to support the
- EXTERNAL mechanism.
-
- Once TLS has been started, the client MUST discard cached
- information about server capabilities and SHOULD re-issue the
- CAPABILITY command. This is necessary to protect against
- man-in-the-middle attacks which alter the capabilities list prior
- to STARTTLS. The server MAY advertise different capabilities
- after STARTTLS.
-
- The formal syntax for IMAP is amended as follows:
-
-
-
-
-Newman Standards Track [Page 4]
-\f
-RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
-
-
- command_any =/ "STARTTLS"
-
- Example: C: a001 CAPABILITY
- S: * CAPABILITY IMAP4rev1 STARTTLS LOGINDISABLED
- S: a001 OK CAPABILITY completed
- C: a002 STARTTLS
- S: a002 OK Begin TLS negotiation now
- <TLS negotiation, further commands are under TLS layer>
- C: a003 CAPABILITY
- S: * CAPABILITY IMAP4rev1 AUTH=EXTERNAL
- S: a003 OK CAPABILITY completed
- C: a004 LOGIN joe password
- S: a004 OK LOGIN completed
-
-3.2. IMAP LOGINDISABLED capability
-
- The current IMAP protocol specification (RFC 2060) requires the
- implementation of the LOGIN command which uses clear-text passwords.
- Many sites may choose to disable this command unless encryption is
- active for security reasons. An IMAP server MAY advertise that the
- LOGIN command is disabled by including the LOGINDISABLED capability
- in the capability response. Such a server will respond with a tagged
- "NO" response to any attempt to use the LOGIN command.
-
- An IMAP server which implements STARTTLS MUST implement support for
- the LOGINDISABLED capability on unencrypted connections.
-
- An IMAP client which complies with this specification MUST NOT issue
- the LOGIN command if this capability is present.
-
- This capability is useful to prevent clients compliant with this
- specification from sending an unencrypted password in an environment
- subject to passive attacks. It has no impact on an environment
- subject to active attacks as a man-in-the-middle attacker can remove
- this capability. Therefore this does not relieve clients of the need
- to follow the privacy mode recommendation in section 2.2.
-
- Servers advertising this capability will fail to interoperate with
- many existing compliant IMAP clients and will be unable to prevent
- those clients from disclosing the user's password.
-
-4. POP3 STARTTLS extension
-
- The POP3 STARTTLS extension adds the STLS command to POP3 servers.
- If this is implemented, the POP3 extension mechanism [POP3EXT] MUST
- also be implemented to avoid the need for client probing of multiple
- commands. The capability name "STLS" indicates this command is
- present and permitted in the current state.
-
-
-
-Newman Standards Track [Page 5]
-\f
-RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
-
-
- STLS
-
- Arguments: none
-
- Restrictions:
- Only permitted in AUTHORIZATION state.
-
- Discussion:
- A TLS negotiation begins immediately after the CRLF at the
- end of the +OK response from the server. A -ERR response
- MAY result if a security layer is already active. Once a
- client issues a STLS command, it MUST NOT issue further
- commands until a server response is seen and the TLS
- negotiation is complete.
-
- The STLS command is only permitted in AUTHORIZATION state
- and the server remains in AUTHORIZATION state, even if
- client credentials are supplied during the TLS negotiation.
- The AUTH command [POP-AUTH] with the EXTERNAL mechanism
- [SASL] MAY be used to authenticate once TLS client
- credentials are successfully exchanged, but servers
- supporting the STLS command are not required to support the
- EXTERNAL mechanism.
-
- Once TLS has been started, the client MUST discard cached
- information about server capabilities and SHOULD re-issue
- the CAPA command. This is necessary to protect against
- man-in-the-middle attacks which alter the capabilities list
- prior to STLS. The server MAY advertise different
- capabilities after STLS.
-
- Possible Responses:
- +OK -ERR
-
- Examples:
- C: STLS
- S: +OK Begin TLS negotiation
- <TLS negotiation, further commands are under TLS layer>
- ...
- C: STLS
- S: -ERR Command not permitted when TLS active
-
-
-
-
-
-
-
-
-
-
-Newman Standards Track [Page 6]
-\f
-RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
-
-
-5. ACAP STARTTLS extension
-
- When the TLS extension is present in ACAP, "STARTTLS" is listed as a
- capability in the ACAP greeting. No arguments to this capability are
- defined at this time. This extension adds a single command,
- "STARTTLS" to the ACAP protocol which is used to begin a TLS
- negotiation.
-
-5.1. STARTTLS Command
-
- Arguments: none
-
- Responses: no specific responses for this command
-
- Result: OK - begin TLS negotiation
- BAD - command unknown or arguments invalid
-
- A TLS negotiation begins immediately after the CRLF at the end of
- the tagged OK response from the server. Once a client issues a
- STARTTLS command, it MUST NOT issue further commands until a
- server response is seen and the TLS negotiation is complete.
-
- The STARTTLS command is only valid in non-authenticated state.
- The server remains in non-authenticated state, even if client
- credentials are supplied during the TLS negotiation. The SASL
- [SASL] EXTERNAL mechanism MAY be used to authenticate once TLS
- client credentials are successfully exchanged, but servers
- supporting the STARTTLS command are not required to support the
- EXTERNAL mechanism.
-
- After the TLS layer is established, the server MUST re-issue an
- untagged ACAP greeting. This is necessary to protect against
- man-in-the-middle attacks which alter the capabilities list prior
- to STARTTLS. The client MUST discard cached capability
- information and replace it with the information from the new ACAP
- greeting. The server MAY advertise different capabilities after
- STARTTLS.
-
- The formal syntax for ACAP is amended as follows:
-
- command_any =/ "STARTTLS"
-
- Example: S: * ACAP (SASL "CRAM-MD5") (STARTTLS)
- C: a002 STARTTLS
- S: a002 OK "Begin TLS negotiation now"
- <TLS negotiation, further commands are under TLS layer>
- S: * ACAP (SASL "CRAM-MD5" "PLAIN" "EXTERNAL")
-
-
-
-
-Newman Standards Track [Page 7]
-\f
-RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
-
-
-6. PLAIN SASL mechanism
-
- Clear-text passwords are simple, interoperate with almost all
- existing operating system authentication databases, and are useful
- for a smooth transition to a more secure password-based
- authentication mechanism. The drawback is that they are unacceptable
- for use over an unencrypted network connection.
-
- This defines the "PLAIN" SASL mechanism for use with ACAP and other
- protocols with no clear-text login command. The PLAIN SASL mechanism
- MUST NOT be advertised or used unless a strong encryption layer (such
- as the provided by TLS) is active or backwards compatibility dictates
- otherwise.
-
- The mechanism consists of a single message from the client to the
- server. The client sends the authorization identity (identity to
- login as), followed by a US-ASCII NUL character, followed by the
- authentication identity (identity whose password will be used),
- followed by a US-ASCII NUL character, followed by the clear-text
- password. The client may leave the authorization identity empty to
- indicate that it is the same as the authentication identity.
-
- The server will verify the authentication identity and password with
- the system authentication database and verify that the authentication
- credentials permit the client to login as the authorization identity.
- If both steps succeed, the user is logged in.
-
- The server MAY also use the password to initialize any new
- authentication database, such as one suitable for CRAM-MD5
- [CRAM-MD5].
-
- Non-US-ASCII characters are permitted as long as they are represented
- in UTF-8 [UTF-8]. Use of non-visible characters or characters which
- a user may be unable to enter on some keyboards is discouraged.
-
- The formal grammar for the client message using Augmented BNF [ABNF]
- follows.
-
- message = [authorize-id] NUL authenticate-id NUL password
- authenticate-id = 1*UTF8-SAFE ; MUST accept up to 255 octets
- authorize-id = 1*UTF8-SAFE ; MUST accept up to 255 octets
- password = 1*UTF8-SAFE ; MUST accept up to 255 octets
- NUL = %x00
- UTF8-SAFE = %x01-09 / %x0B-0C / %x0E-7F / UTF8-2 /
- UTF8-3 / UTF8-4 / UTF8-5 / UTF8-6
- UTF8-1 = %x80-BF
- UTF8-2 = %xC0-DF UTF8-1
- UTF8-3 = %xE0-EF 2UTF8-1
-
-
-
-Newman Standards Track [Page 8]
-\f
-RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
-
-
- UTF8-4 = %xF0-F7 3UTF8-1
- UTF8-5 = %xF8-FB 4UTF8-1
- UTF8-6 = %xFC-FD 5UTF8-1
-
- Here is an example of how this might be used to initialize a CRAM-MD5
- authentication database for ACAP:
-
- Example: S: * ACAP (SASL "CRAM-MD5") (STARTTLS)
- C: a001 AUTHENTICATE "CRAM-MD5"
- S: + "<1896.697170952@postoffice.reston.mci.net>"
- C: "tim b913a602c7eda7a495b4e6e7334d3890"
- S: a001 NO (TRANSITION-NEEDED)
- "Please change your password, or use TLS to login"
- C: a002 STARTTLS
- S: a002 OK "Begin TLS negotiation now"
- <TLS negotiation, further commands are under TLS layer>
- S: * ACAP (SASL "CRAM-MD5" "PLAIN" "EXTERNAL")
- C: a003 AUTHENTICATE "PLAIN" {21+}
- C: <NUL>tim<NUL>tanstaaftanstaaf
- S: a003 OK CRAM-MD5 password initialized
-
- Note: In this example, <NUL> represents a single ASCII NUL octet.
-
-7. imaps and pop3s ports
-
- Separate "imaps" and "pop3s" ports were registered for use with SSL.
- Use of these ports is discouraged in favor of the STARTTLS or STLS
- commands.
-
- A number of problems have been observed with separate ports for
- "secure" variants of protocols. This is an attempt to enumerate some
- of those problems.
-
- - Separate ports lead to a separate URL scheme which intrudes into
- the user interface in inappropriate ways. For example, many web
- pages use language like "click here if your browser supports SSL."
- This is a decision the browser is often more capable of making than
- the user.
-
- - Separate ports imply a model of either "secure" or "not secure."
- This can be misleading in a number of ways. First, the "secure"
- port may not in fact be acceptably secure as an export-crippled
- cipher suite might be in use. This can mislead users into a false
- sense of security. Second, the normal port might in fact be
- secured by using a SASL mechanism which includes a security layer.
- Thus the separate port distinction makes the complex topic of
- security policy even more confusing. One common result of this
- confusion is that firewall administrators are often misled into
-
-
-
-Newman Standards Track [Page 9]
-\f
-RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
-
-
- permitting the "secure" port and blocking the standard port. This
- could be a poor choice given the common use of SSL with a 40-bit
- key encryption layer and plain-text password authentication is less
- secure than strong SASL mechanisms such as GSSAPI with Kerberos 5.
-
- - Use of separate ports for SSL has caused clients to implement only
- two security policies: use SSL or don't use SSL. The desirable
- security policy "use TLS when available" would be cumbersome with
- the separate port model, but is simple with STARTTLS.
-
- - Port numbers are a limited resource. While they are not yet in
- short supply, it is unwise to set a precedent that could double (or
- worse) the speed of their consumption.
-
-
-8. IANA Considerations
-
- This constitutes registration of the "STARTTLS" and "LOGINDISABLED"
- IMAP capabilities as required by section 7.2.1 of RFC 2060 [IMAP].
-
- The registration for the POP3 "STLS" capability follows:
-
- CAPA tag: STLS
- Arguments: none
- Added commands: STLS
- Standard commands affected: May enable USER/PASS as a side-effect.
- CAPA command SHOULD be re-issued after successful completion.
- Announced states/Valid states: AUTHORIZATION state only.
- Specification reference: this memo
-
- The registration for the ACAP "STARTTLS" capability follows:
-
- Capability name: STARTTLS
- Capability keyword: STARTTLS
- Capability arguments: none
- Published Specification(s): this memo
- Person and email address for further information:
- see author's address section below
-
- The registration for the PLAIN SASL mechanism follows:
-
- SASL mechanism name: PLAIN
- Security Considerations: See section 9 of this memo
- Published specification: this memo
- Person & email address to contact for further information:
- see author's address section below
- Intended usage: COMMON
- Author/Change controller: see author's address section below
-
-
-
-Newman Standards Track [Page 10]
-\f
-RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
-
-
-9. Security Considerations
-
- TLS only provides protection for data sent over a network connection.
- Messages transferred over IMAP or POP3 are still available to server
- administrators and usually subject to eavesdropping, tampering and
- forgery when transmitted through SMTP or NNTP. TLS is no substitute
- for an end-to-end message security mechanism using MIME security
- multiparts [MIME-SEC].
-
- A man-in-the-middle attacker can remove STARTTLS from the capability
- list or generate a failure response to the STARTTLS command. In
- order to detect such an attack, clients SHOULD warn the user when
- session privacy is not active and/or be configurable to refuse to
- proceed without an acceptable level of security.
-
- A man-in-the-middle attacker can always cause a down-negotiation to
- the weakest authentication mechanism or cipher suite available. For
- this reason, implementations SHOULD be configurable to refuse weak
- mechanisms or cipher suites.
-
- Any protocol interactions prior to the TLS handshake are performed in
- the clear and can be modified by a man-in-the-middle attacker. For
- this reason, clients MUST discard cached information about server
- capabilities advertised prior to the start of the TLS handshake.
-
- Clients are encouraged to clearly indicate when the level of
- encryption active is known to be vulnerable to attack using modern
- hardware (such as encryption keys with 56 bits of entropy or less).
-
- The LOGINDISABLED IMAP capability (discussed in section 3.2) only
- reduces the potential for passive attacks, it provides no protection
- against active attacks. The responsibility remains with the client
- to avoid sending a password over a vulnerable channel.
-
- The PLAIN mechanism relies on the TLS encryption layer for security.
- When used without TLS, it is vulnerable to a common network
- eavesdropping attack. Therefore PLAIN MUST NOT be advertised or used
- unless a suitable TLS encryption layer is active or backwards
- compatibility dictates otherwise.
-
- When the PLAIN mechanism is used, the server gains the ability to
- impersonate the user to all services with the same password
- regardless of any encryption provided by TLS or other network privacy
- mechanisms. While many other authentication mechanisms have similar
- weaknesses, stronger SASL mechanisms such as Kerberos address this
- issue. Clients are encouraged to have an operational mode where all
- mechanisms which are likely to reveal the user's password to the
- server are disabled.
-
-
-
-Newman Standards Track [Page 11]
-\f
-RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
-
-
- The security considerations for TLS apply to STARTTLS and the
- security considerations for SASL apply to the PLAIN mechanism.
- Additional security requirements are discussed in section 2.
-
-10. References
-
- [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", RFC 2234, November 1997.
-
- [ACAP] Newman, C. and J. Myers, "ACAP -- Application
- Configuration Access Protocol", RFC 2244, November 1997.
-
- [AUTH] Haller, N. and R. Atkinson, "On Internet Authentication",
- RFC 1704, October 1994.
-
- [CRAM-MD5] Klensin, J., Catoe, R. and P. Krumviede, "IMAP/POP
- AUTHorize Extension for Simple Challenge/Response", RFC
- 2195, September 1997.
-
- [IMAP] Crispin, M., "Internet Message Access Protocol - Version
- 4rev1", RFC 2060, December 1996.
-
- [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [MIME-SEC] Galvin, J., Murphy, S., Crocker, S. and N. Freed,
- "Security Multiparts for MIME: Multipart/Signed and
- Multipart/Encrypted", RFC 1847, October 1995.
-
- [POP3] Myers, J. and M. Rose, "Post Office Protocol - Version 3",
- STD 53, RFC 1939, May 1996.
-
- [POP3EXT] Gellens, R., Newman, C. and L. Lundblade, "POP3 Extension
- Mechanism", RFC 2449, November 1998.
-
- [POP-AUTH] Myers, J., "POP3 AUTHentication command", RFC 1734,
- December 1994.
-
- [SASL] Myers, J., "Simple Authentication and Security Layer
- (SASL)", RFC 2222, October 1997.
-
- [SMTPTLS] Hoffman, P., "SMTP Service Extension for Secure SMTP over
- TLS", RFC 2487, January 1999.
-
- [TLS] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
- RFC 2246, January 1999.
-
-
-
-
-
-Newman Standards Track [Page 12]
-\f
-RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
-
-
- [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
- 10646", RFC 2279, January 1998.
-
-
-11. Author's Address
-
- Chris Newman
- Innosoft International, Inc.
- 1050 Lakes Drive
- West Covina, CA 91790 USA
-
- EMail: chris.newman@innosoft.com
-
-
-A. Appendix -- Compliance Checklist
-
- An implementation is not compliant if it fails to satisfy one or more
- of the MUST requirements for the protocols it implements. An
- implementation that satisfies all the MUST and all the SHOULD
- requirements for its protocols is said to be "unconditionally
- compliant"; one that satisfies all the MUST requirements but not all
- the SHOULD requirements for its protocols is said to be
- "conditionally compliant".
-
- Rules Section
- ----- -------
- Mandatory-to-implement Cipher Suite 2.1
- SHOULD have mode where encryption required 2.2
- server SHOULD have mode where TLS not required 2.2
- MUST be configurable to refuse all clear-text login
- commands or mechanisms 2.3
- server SHOULD be configurable to refuse clear-text
- login commands on entire server and on per-user basis 2.3
- client MUST check server identity 2.4
- client MUST use hostname used to open connection 2.4
- client MUST NOT use hostname from insecure remote lookup 2.4
- client SHOULD support subjectAltName of dNSName type 2.4
- client SHOULD ask for confirmation or terminate on fail 2.4
- MUST check result of STARTTLS for acceptable privacy 2.5
- client MUST NOT issue commands after STARTTLS
- until server response and negotiation done 3.1,4,5.1
- client MUST discard cached information 3.1,4,5.1,9
- client SHOULD re-issue CAPABILITY/CAPA command 3.1,4
- IMAP server with STARTTLS MUST implement LOGINDISABLED 3.2
- IMAP client MUST NOT issue LOGIN if LOGINDISABLED 3.2
- POP server MUST implement POP3 extensions 4
- ACAP server MUST re-issue ACAP greeting 5.1
-
-
-
-
-Newman Standards Track [Page 13]
-\f
-RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
-
-
- client SHOULD warn when session privacy not active and/or
- refuse to proceed without acceptable security level 9
- SHOULD be configurable to refuse weak mechanisms or
- cipher suites 9
-
- The PLAIN mechanism is an optional part of this specification.
- However if it is implemented the following rules apply:
-
- Rules Section
- ----- -------
- MUST NOT use PLAIN unless strong encryption active
- or backwards compatibility dictates otherwise 6,9
- MUST use UTF-8 encoding for characters in PLAIN 6
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Newman Standards Track [Page 14]
-\f
-RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Newman Standards Track [Page 15]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group R. Fielding
-Request for Comments: 2616 UC Irvine
-Obsoletes: 2068 J. Gettys
-Category: Standards Track Compaq/W3C
- J. Mogul
- Compaq
- H. Frystyk
- W3C/MIT
- L. Masinter
- Xerox
- P. Leach
- Microsoft
- T. Berners-Lee
- W3C/MIT
- June 1999
-
-
- Hypertext Transfer Protocol -- HTTP/1.1
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-Abstract
-
- The Hypertext Transfer Protocol (HTTP) is an application-level
- protocol for distributed, collaborative, hypermedia information
- systems. It is a generic, stateless, protocol which can be used for
- many tasks beyond its use for hypertext, such as name servers and
- distributed object management systems, through extension of its
- request methods, error codes and headers [47]. A feature of HTTP is
- the typing and negotiation of data representation, allowing systems
- to be built independently of the data being transferred.
-
- HTTP has been in use by the World-Wide Web global information
- initiative since 1990. This specification defines the protocol
- referred to as "HTTP/1.1", and is an update to RFC 2068 [33].
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 1]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-Table of Contents
-
- 1 Introduction ...................................................7
- 1.1 Purpose......................................................7
- 1.2 Requirements .................................................8
- 1.3 Terminology ..................................................8
- 1.4 Overall Operation ...........................................12
- 2 Notational Conventions and Generic Grammar ....................14
- 2.1 Augmented BNF ...............................................14
- 2.2 Basic Rules .................................................15
- 3 Protocol Parameters ...........................................17
- 3.1 HTTP Version ................................................17
- 3.2 Uniform Resource Identifiers ................................18
- 3.2.1 General Syntax ...........................................19
- 3.2.2 http URL .................................................19
- 3.2.3 URI Comparison ...........................................20
- 3.3 Date/Time Formats ...........................................20
- 3.3.1 Full Date ................................................20
- 3.3.2 Delta Seconds ............................................21
- 3.4 Character Sets ..............................................21
- 3.4.1 Missing Charset ..........................................22
- 3.5 Content Codings .............................................23
- 3.6 Transfer Codings ............................................24
- 3.6.1 Chunked Transfer Coding ..................................25
- 3.7 Media Types .................................................26
- 3.7.1 Canonicalization and Text Defaults .......................27
- 3.7.2 Multipart Types ..........................................27
- 3.8 Product Tokens ..............................................28
- 3.9 Quality Values ..............................................29
- 3.10 Language Tags ...............................................29
- 3.11 Entity Tags .................................................30
- 3.12 Range Units .................................................30
- 4 HTTP Message ..................................................31
- 4.1 Message Types ...............................................31
- 4.2 Message Headers .............................................31
- 4.3 Message Body ................................................32
- 4.4 Message Length ..............................................33
- 4.5 General Header Fields .......................................34
- 5 Request .......................................................35
- 5.1 Request-Line ................................................35
- 5.1.1 Method ...................................................36
- 5.1.2 Request-URI ..............................................36
- 5.2 The Resource Identified by a Request ........................38
- 5.3 Request Header Fields .......................................38
- 6 Response ......................................................39
- 6.1 Status-Line .................................................39
- 6.1.1 Status Code and Reason Phrase ............................39
- 6.2 Response Header Fields ......................................41
-
-
-
-Fielding, et al. Standards Track [Page 2]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- 7 Entity ........................................................42
- 7.1 Entity Header Fields ........................................42
- 7.2 Entity Body .................................................43
- 7.2.1 Type .....................................................43
- 7.2.2 Entity Length ............................................43
- 8 Connections ...................................................44
- 8.1 Persistent Connections ......................................44
- 8.1.1 Purpose ..................................................44
- 8.1.2 Overall Operation ........................................45
- 8.1.3 Proxy Servers ............................................46
- 8.1.4 Practical Considerations .................................46
- 8.2 Message Transmission Requirements ...........................47
- 8.2.1 Persistent Connections and Flow Control ..................47
- 8.2.2 Monitoring Connections for Error Status Messages .........48
- 8.2.3 Use of the 100 (Continue) Status .........................48
- 8.2.4 Client Behavior if Server Prematurely Closes Connection ..50
- 9 Method Definitions ............................................51
- 9.1 Safe and Idempotent Methods .................................51
- 9.1.1 Safe Methods .............................................51
- 9.1.2 Idempotent Methods .......................................51
- 9.2 OPTIONS .....................................................52
- 9.3 GET .........................................................53
- 9.4 HEAD ........................................................54
- 9.5 POST ........................................................54
- 9.6 PUT .........................................................55
- 9.7 DELETE ......................................................56
- 9.8 TRACE .......................................................56
- 9.9 CONNECT .....................................................57
- 10 Status Code Definitions ......................................57
- 10.1 Informational 1xx ...........................................57
- 10.1.1 100 Continue .............................................58
- 10.1.2 101 Switching Protocols ..................................58
- 10.2 Successful 2xx ..............................................58
- 10.2.1 200 OK ...................................................58
- 10.2.2 201 Created ..............................................59
- 10.2.3 202 Accepted .............................................59
- 10.2.4 203 Non-Authoritative Information ........................59
- 10.2.5 204 No Content ...........................................60
- 10.2.6 205 Reset Content ........................................60
- 10.2.7 206 Partial Content ......................................60
- 10.3 Redirection 3xx .............................................61
- 10.3.1 300 Multiple Choices .....................................61
- 10.3.2 301 Moved Permanently ....................................62
- 10.3.3 302 Found ................................................62
- 10.3.4 303 See Other ............................................63
- 10.3.5 304 Not Modified .........................................63
- 10.3.6 305 Use Proxy ............................................64
- 10.3.7 306 (Unused) .............................................64
-
-
-
-Fielding, et al. Standards Track [Page 3]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- 10.3.8 307 Temporary Redirect ...................................65
- 10.4 Client Error 4xx ............................................65
- 10.4.1 400 Bad Request .........................................65
- 10.4.2 401 Unauthorized ........................................66
- 10.4.3 402 Payment Required ....................................66
- 10.4.4 403 Forbidden ...........................................66
- 10.4.5 404 Not Found ...........................................66
- 10.4.6 405 Method Not Allowed ..................................66
- 10.4.7 406 Not Acceptable ......................................67
- 10.4.8 407 Proxy Authentication Required .......................67
- 10.4.9 408 Request Timeout .....................................67
- 10.4.10 409 Conflict ............................................67
- 10.4.11 410 Gone ................................................68
- 10.4.12 411 Length Required .....................................68
- 10.4.13 412 Precondition Failed .................................68
- 10.4.14 413 Request Entity Too Large ............................69
- 10.4.15 414 Request-URI Too Long ................................69
- 10.4.16 415 Unsupported Media Type ..............................69
- 10.4.17 416 Requested Range Not Satisfiable .....................69
- 10.4.18 417 Expectation Failed ..................................70
- 10.5 Server Error 5xx ............................................70
- 10.5.1 500 Internal Server Error ................................70
- 10.5.2 501 Not Implemented ......................................70
- 10.5.3 502 Bad Gateway ..........................................70
- 10.5.4 503 Service Unavailable ..................................70
- 10.5.5 504 Gateway Timeout ......................................71
- 10.5.6 505 HTTP Version Not Supported ...........................71
- 11 Access Authentication ........................................71
- 12 Content Negotiation ..........................................71
- 12.1 Server-driven Negotiation ...................................72
- 12.2 Agent-driven Negotiation ....................................73
- 12.3 Transparent Negotiation .....................................74
- 13 Caching in HTTP ..............................................74
- 13.1.1 Cache Correctness ........................................75
- 13.1.2 Warnings .................................................76
- 13.1.3 Cache-control Mechanisms .................................77
- 13.1.4 Explicit User Agent Warnings .............................78
- 13.1.5 Exceptions to the Rules and Warnings .....................78
- 13.1.6 Client-controlled Behavior ...............................79
- 13.2 Expiration Model ............................................79
- 13.2.1 Server-Specified Expiration ..............................79
- 13.2.2 Heuristic Expiration .....................................80
- 13.2.3 Age Calculations .........................................80
- 13.2.4 Expiration Calculations ..................................83
- 13.2.5 Disambiguating Expiration Values .........................84
- 13.2.6 Disambiguating Multiple Responses ........................84
- 13.3 Validation Model ............................................85
- 13.3.1 Last-Modified Dates ......................................86
-
-
-
-Fielding, et al. Standards Track [Page 4]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- 13.3.2 Entity Tag Cache Validators ..............................86
- 13.3.3 Weak and Strong Validators ...............................86
- 13.3.4 Rules for When to Use Entity Tags and Last-Modified Dates.89
- 13.3.5 Non-validating Conditionals ..............................90
- 13.4 Response Cacheability .......................................91
- 13.5 Constructing Responses From Caches ..........................92
- 13.5.1 End-to-end and Hop-by-hop Headers ........................92
- 13.5.2 Non-modifiable Headers ...................................92
- 13.5.3 Combining Headers ........................................94
- 13.5.4 Combining Byte Ranges ....................................95
- 13.6 Caching Negotiated Responses ................................95
- 13.7 Shared and Non-Shared Caches ................................96
- 13.8 Errors or Incomplete Response Cache Behavior ................97
- 13.9 Side Effects of GET and HEAD ................................97
- 13.10 Invalidation After Updates or Deletions ...................97
- 13.11 Write-Through Mandatory ...................................98
- 13.12 Cache Replacement .........................................99
- 13.13 History Lists .............................................99
- 14 Header Field Definitions ....................................100
- 14.1 Accept .....................................................100
- 14.2 Accept-Charset .............................................102
- 14.3 Accept-Encoding ............................................102
- 14.4 Accept-Language ............................................104
- 14.5 Accept-Ranges ..............................................105
- 14.6 Age ........................................................106
- 14.7 Allow ......................................................106
- 14.8 Authorization ..............................................107
- 14.9 Cache-Control ..............................................108
- 14.9.1 What is Cacheable .......................................109
- 14.9.2 What May be Stored by Caches ............................110
- 14.9.3 Modifications of the Basic Expiration Mechanism .........111
- 14.9.4 Cache Revalidation and Reload Controls ..................113
- 14.9.5 No-Transform Directive ..................................115
- 14.9.6 Cache Control Extensions ................................116
- 14.10 Connection ...............................................117
- 14.11 Content-Encoding .........................................118
- 14.12 Content-Language .........................................118
- 14.13 Content-Length ...........................................119
- 14.14 Content-Location .........................................120
- 14.15 Content-MD5 ..............................................121
- 14.16 Content-Range ............................................122
- 14.17 Content-Type .............................................124
- 14.18 Date .....................................................124
- 14.18.1 Clockless Origin Server Operation ......................125
- 14.19 ETag .....................................................126
- 14.20 Expect ...................................................126
- 14.21 Expires ..................................................127
- 14.22 From .....................................................128
-
-
-
-Fielding, et al. Standards Track [Page 5]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- 14.23 Host .....................................................128
- 14.24 If-Match .................................................129
- 14.25 If-Modified-Since ........................................130
- 14.26 If-None-Match ............................................132
- 14.27 If-Range .................................................133
- 14.28 If-Unmodified-Since ......................................134
- 14.29 Last-Modified ............................................134
- 14.30 Location .................................................135
- 14.31 Max-Forwards .............................................136
- 14.32 Pragma ...................................................136
- 14.33 Proxy-Authenticate .......................................137
- 14.34 Proxy-Authorization ......................................137
- 14.35 Range ....................................................138
- 14.35.1 Byte Ranges ...........................................138
- 14.35.2 Range Retrieval Requests ..............................139
- 14.36 Referer ..................................................140
- 14.37 Retry-After ..............................................141
- 14.38 Server ...................................................141
- 14.39 TE .......................................................142
- 14.40 Trailer ..................................................143
- 14.41 Transfer-Encoding..........................................143
- 14.42 Upgrade ..................................................144
- 14.43 User-Agent ...............................................145
- 14.44 Vary .....................................................145
- 14.45 Via ......................................................146
- 14.46 Warning ..................................................148
- 14.47 WWW-Authenticate .........................................150
- 15 Security Considerations .......................................150
- 15.1 Personal Information....................................151
- 15.1.1 Abuse of Server Log Information .........................151
- 15.1.2 Transfer of Sensitive Information .......................151
- 15.1.3 Encoding Sensitive Information in URI's .................152
- 15.1.4 Privacy Issues Connected to Accept Headers ..............152
- 15.2 Attacks Based On File and Path Names .......................153
- 15.3 DNS Spoofing ...............................................154
- 15.4 Location Headers and Spoofing ..............................154
- 15.5 Content-Disposition Issues .................................154
- 15.6 Authentication Credentials and Idle Clients ................155
- 15.7 Proxies and Caching ........................................155
- 15.7.1 Denial of Service Attacks on Proxies....................156
- 16 Acknowledgments .............................................156
- 17 References ..................................................158
- 18 Authors' Addresses ..........................................162
- 19 Appendices ..................................................164
- 19.1 Internet Media Type message/http and application/http ......164
- 19.2 Internet Media Type multipart/byteranges ...................165
- 19.3 Tolerant Applications ......................................166
- 19.4 Differences Between HTTP Entities and RFC 2045 Entities ....167
-
-
-
-Fielding, et al. Standards Track [Page 6]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- 19.4.1 MIME-Version ............................................167
- 19.4.2 Conversion to Canonical Form ............................167
- 19.4.3 Conversion of Date Formats ..............................168
- 19.4.4 Introduction of Content-Encoding ........................168
- 19.4.5 No Content-Transfer-Encoding ............................168
- 19.4.6 Introduction of Transfer-Encoding .......................169
- 19.4.7 MHTML and Line Length Limitations .......................169
- 19.5 Additional Features ........................................169
- 19.5.1 Content-Disposition .....................................170
- 19.6 Compatibility with Previous Versions .......................170
- 19.6.1 Changes from HTTP/1.0 ...................................171
- 19.6.2 Compatibility with HTTP/1.0 Persistent Connections ......172
- 19.6.3 Changes from RFC 2068 ...................................172
- 20 Index .......................................................175
- 21 Full Copyright Statement ....................................176
-
-1 Introduction
-
-1.1 Purpose
-
- The Hypertext Transfer Protocol (HTTP) is an application-level
- protocol for distributed, collaborative, hypermedia information
- systems. HTTP has been in use by the World-Wide Web global
- information initiative since 1990. The first version of HTTP,
- referred to as HTTP/0.9, was a simple protocol for raw data transfer
- across the Internet. HTTP/1.0, as defined by RFC 1945 [6], improved
- the protocol by allowing messages to be in the format of MIME-like
- messages, containing metainformation about the data transferred and
- modifiers on the request/response semantics. However, HTTP/1.0 does
- not sufficiently take into consideration the effects of hierarchical
- proxies, caching, the need for persistent connections, or virtual
- hosts. In addition, the proliferation of incompletely-implemented
- applications calling themselves "HTTP/1.0" has necessitated a
- protocol version change in order for two communicating applications
- to determine each other's true capabilities.
-
- This specification defines the protocol referred to as "HTTP/1.1".
- This protocol includes more stringent requirements than HTTP/1.0 in
- order to ensure reliable implementation of its features.
-
- Practical information systems require more functionality than simple
- retrieval, including search, front-end update, and annotation. HTTP
- allows an open-ended set of methods and headers that indicate the
- purpose of a request [47]. It builds on the discipline of reference
- provided by the Uniform Resource Identifier (URI) [3], as a location
- (URL) [4] or name (URN) [20], for indicating the resource to which a
-
-
-
-
-
-Fielding, et al. Standards Track [Page 7]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- method is to be applied. Messages are passed in a format similar to
- that used by Internet mail [9] as defined by the Multipurpose
- Internet Mail Extensions (MIME) [7].
-
- HTTP is also used as a generic protocol for communication between
- user agents and proxies/gateways to other Internet systems, including
- those supported by the SMTP [16], NNTP [13], FTP [18], Gopher [2],
- and WAIS [10] protocols. In this way, HTTP allows basic hypermedia
- access to resources available from diverse applications.
-
-1.2 Requirements
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in RFC 2119 [34].
-
- An implementation is not compliant if it fails to satisfy one or more
- of the MUST or REQUIRED level requirements for the protocols it
- implements. An implementation that satisfies all the MUST or REQUIRED
- level and all the SHOULD level requirements for its protocols is said
- to be "unconditionally compliant"; one that satisfies all the MUST
- level requirements but not all the SHOULD level requirements for its
- protocols is said to be "conditionally compliant."
-
-1.3 Terminology
-
- This specification uses a number of terms to refer to the roles
- played by participants in, and objects of, the HTTP communication.
-
- connection
- A transport layer virtual circuit established between two programs
- for the purpose of communication.
-
- message
- The basic unit of HTTP communication, consisting of a structured
- sequence of octets matching the syntax defined in section 4 and
- transmitted via the connection.
-
- request
- An HTTP request message, as defined in section 5.
-
- response
- An HTTP response message, as defined in section 6.
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 8]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- resource
- A network data object or service that can be identified by a URI,
- as defined in section 3.2. Resources may be available in multiple
- representations (e.g. multiple languages, data formats, size, and
- resolutions) or vary in other ways.
-
- entity
- The information transferred as the payload of a request or
- response. An entity consists of metainformation in the form of
- entity-header fields and content in the form of an entity-body, as
- described in section 7.
-
- representation
- An entity included with a response that is subject to content
- negotiation, as described in section 12. There may exist multiple
- representations associated with a particular response status.
-
- content negotiation
- The mechanism for selecting the appropriate representation when
- servicing a request, as described in section 12. The
- representation of entities in any response can be negotiated
- (including error responses).
-
- variant
- A resource may have one, or more than one, representation(s)
- associated with it at any given instant. Each of these
- representations is termed a `varriant'. Use of the term `variant'
- does not necessarily imply that the resource is subject to content
- negotiation.
-
- client
- A program that establishes connections for the purpose of sending
- requests.
-
- user agent
- The client which initiates a request. These are often browsers,
- editors, spiders (web-traversing robots), or other end user tools.
-
- server
- An application program that accepts connections in order to
- service requests by sending back responses. Any given program may
- be capable of being both a client and a server; our use of these
- terms refers only to the role being performed by the program for a
- particular connection, rather than to the program's capabilities
- in general. Likewise, any server may act as an origin server,
- proxy, gateway, or tunnel, switching behavior based on the nature
- of each request.
-
-
-
-
-Fielding, et al. Standards Track [Page 9]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- origin server
- The server on which a given resource resides or is to be created.
-
- proxy
- An intermediary program which acts as both a server and a client
- for the purpose of making requests on behalf of other clients.
- Requests are serviced internally or by passing them on, with
- possible translation, to other servers. A proxy MUST implement
- both the client and server requirements of this specification. A
- "transparent proxy" is a proxy that does not modify the request or
- response beyond what is required for proxy authentication and
- identification. A "non-transparent proxy" is a proxy that modifies
- the request or response in order to provide some added service to
- the user agent, such as group annotation services, media type
- transformation, protocol reduction, or anonymity filtering. Except
- where either transparent or non-transparent behavior is explicitly
- stated, the HTTP proxy requirements apply to both types of
- proxies.
-
- gateway
- A server which acts as an intermediary for some other server.
- Unlike a proxy, a gateway receives requests as if it were the
- origin server for the requested resource; the requesting client
- may not be aware that it is communicating with a gateway.
-
- tunnel
- An intermediary program which is acting as a blind relay between
- two connections. Once active, a tunnel is not considered a party
- to the HTTP communication, though the tunnel may have been
- initiated by an HTTP request. The tunnel ceases to exist when both
- ends of the relayed connections are closed.
-
- cache
- A program's local store of response messages and the subsystem
- that controls its message storage, retrieval, and deletion. A
- cache stores cacheable responses in order to reduce the response
- time and network bandwidth consumption on future, equivalent
- requests. Any client or server may include a cache, though a cache
- cannot be used by a server that is acting as a tunnel.
-
- cacheable
- A response is cacheable if a cache is allowed to store a copy of
- the response message for use in answering subsequent requests. The
- rules for determining the cacheability of HTTP responses are
- defined in section 13. Even if a resource is cacheable, there may
- be additional constraints on whether a cache can use the cached
- copy for a particular request.
-
-
-
-
-Fielding, et al. Standards Track [Page 10]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- first-hand
- A response is first-hand if it comes directly and without
- unnecessary delay from the origin server, perhaps via one or more
- proxies. A response is also first-hand if its validity has just
- been checked directly with the origin server.
-
- explicit expiration time
- The time at which the origin server intends that an entity should
- no longer be returned by a cache without further validation.
-
- heuristic expiration time
- An expiration time assigned by a cache when no explicit expiration
- time is available.
-
- age
- The age of a response is the time since it was sent by, or
- successfully validated with, the origin server.
-
- freshness lifetime
- The length of time between the generation of a response and its
- expiration time.
-
- fresh
- A response is fresh if its age has not yet exceeded its freshness
- lifetime.
-
- stale
- A response is stale if its age has passed its freshness lifetime.
-
- semantically transparent
- A cache behaves in a "semantically transparent" manner, with
- respect to a particular response, when its use affects neither the
- requesting client nor the origin server, except to improve
- performance. When a cache is semantically transparent, the client
- receives exactly the same response (except for hop-by-hop headers)
- that it would have received had its request been handled directly
- by the origin server.
-
- validator
- A protocol element (e.g., an entity tag or a Last-Modified time)
- that is used to find out whether a cache entry is an equivalent
- copy of an entity.
-
- upstream/downstream
- Upstream and downstream describe the flow of a message: all
- messages flow from upstream to downstream.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 11]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- inbound/outbound
- Inbound and outbound refer to the request and response paths for
- messages: "inbound" means "traveling toward the origin server",
- and "outbound" means "traveling toward the user agent"
-
-1.4 Overall Operation
-
- The HTTP protocol is a request/response protocol. A client sends a
- request to the server in the form of a request method, URI, and
- protocol version, followed by a MIME-like message containing request
- modifiers, client information, and possible body content over a
- connection with a server. The server responds with a status line,
- including the message's protocol version and a success or error code,
- followed by a MIME-like message containing server information, entity
- metainformation, and possible entity-body content. The relationship
- between HTTP and MIME is described in appendix 19.4.
-
- Most HTTP communication is initiated by a user agent and consists of
- a request to be applied to a resource on some origin server. In the
- simplest case, this may be accomplished via a single connection (v)
- between the user agent (UA) and the origin server (O).
-
- request chain ------------------------>
- UA -------------------v------------------- O
- <----------------------- response chain
-
- A more complicated situation occurs when one or more intermediaries
- are present in the request/response chain. There are three common
- forms of intermediary: proxy, gateway, and tunnel. A proxy is a
- forwarding agent, receiving requests for a URI in its absolute form,
- rewriting all or part of the message, and forwarding the reformatted
- request toward the server identified by the URI. A gateway is a
- receiving agent, acting as a layer above some other server(s) and, if
- necessary, translating the requests to the underlying server's
- protocol. A tunnel acts as a relay point between two connections
- without changing the messages; tunnels are used when the
- communication needs to pass through an intermediary (such as a
- firewall) even when the intermediary cannot understand the contents
- of the messages.
-
- request chain -------------------------------------->
- UA -----v----- A -----v----- B -----v----- C -----v----- O
- <------------------------------------- response chain
-
- The figure above shows three intermediaries (A, B, and C) between the
- user agent and origin server. A request or response message that
- travels the whole chain will pass through four separate connections.
- This distinction is important because some HTTP communication options
-
-
-
-Fielding, et al. Standards Track [Page 12]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- may apply only to the connection with the nearest, non-tunnel
- neighbor, only to the end-points of the chain, or to all connections
- along the chain. Although the diagram is linear, each participant may
- be engaged in multiple, simultaneous communications. For example, B
- may be receiving requests from many clients other than A, and/or
- forwarding requests to servers other than C, at the same time that it
- is handling A's request.
-
- Any party to the communication which is not acting as a tunnel may
- employ an internal cache for handling requests. The effect of a cache
- is that the request/response chain is shortened if one of the
- participants along the chain has a cached response applicable to that
- request. The following illustrates the resulting chain if B has a
- cached copy of an earlier response from O (via C) for a request which
- has not been cached by UA or A.
-
- request chain ---------->
- UA -----v----- A -----v----- B - - - - - - C - - - - - - O
- <--------- response chain
-
- Not all responses are usefully cacheable, and some requests may
- contain modifiers which place special requirements on cache behavior.
- HTTP requirements for cache behavior and cacheable responses are
- defined in section 13.
-
- In fact, there are a wide variety of architectures and configurations
- of caches and proxies currently being experimented with or deployed
- across the World Wide Web. These systems include national hierarchies
- of proxy caches to save transoceanic bandwidth, systems that
- broadcast or multicast cache entries, organizations that distribute
- subsets of cached data via CD-ROM, and so on. HTTP systems are used
- in corporate intranets over high-bandwidth links, and for access via
- PDAs with low-power radio links and intermittent connectivity. The
- goal of HTTP/1.1 is to support the wide diversity of configurations
- already deployed while introducing protocol constructs that meet the
- needs of those who build web applications that require high
- reliability and, failing that, at least reliable indications of
- failure.
-
- HTTP communication usually takes place over TCP/IP connections. The
- default port is TCP 80 [19], but other ports can be used. This does
- not preclude HTTP from being implemented on top of any other protocol
- on the Internet, or on other networks. HTTP only presumes a reliable
- transport; any protocol that provides such guarantees can be used;
- the mapping of the HTTP/1.1 request and response structures onto the
- transport data units of the protocol in question is outside the scope
- of this specification.
-
-
-
-
-Fielding, et al. Standards Track [Page 13]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- In HTTP/1.0, most implementations used a new connection for each
- request/response exchange. In HTTP/1.1, a connection may be used for
- one or more request/response exchanges, although connections may be
- closed for a variety of reasons (see section 8.1).
-
-2 Notational Conventions and Generic Grammar
-
-2.1 Augmented BNF
-
- All of the mechanisms specified in this document are described in
- both prose and an augmented Backus-Naur Form (BNF) similar to that
- used by RFC 822 [9]. Implementors will need to be familiar with the
- notation in order to understand this specification. The augmented BNF
- includes the following constructs:
-
- name = definition
- The name of a rule is simply the name itself (without any
- enclosing "<" and ">") and is separated from its definition by the
- equal "=" character. White space is only significant in that
- indentation of continuation lines is used to indicate a rule
- definition that spans more than one line. Certain basic rules are
- in uppercase, such as SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle
- brackets are used within definitions whenever their presence will
- facilitate discerning the use of rule names.
-
- "literal"
- Quotation marks surround literal text. Unless stated otherwise,
- the text is case-insensitive.
-
- rule1 | rule2
- Elements separated by a bar ("|") are alternatives, e.g., "yes |
- no" will accept yes or no.
-
- (rule1 rule2)
- Elements enclosed in parentheses are treated as a single element.
- Thus, "(elem (foo | bar) elem)" allows the token sequences "elem
- foo elem" and "elem bar elem".
-
- *rule
- The character "*" preceding an element indicates repetition. The
- full form is "<n>*<m>element" indicating at least <n> and at most
- <m> occurrences of element. Default values are 0 and infinity so
- that "*(element)" allows any number, including zero; "1*element"
- requires at least one; and "1*2element" allows one or two.
-
- [rule]
- Square brackets enclose optional elements; "[foo bar]" is
- equivalent to "*1(foo bar)".
-
-
-
-Fielding, et al. Standards Track [Page 14]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- N rule
- Specific repetition: "<n>(element)" is equivalent to
- "<n>*<n>(element)"; that is, exactly <n> occurrences of (element).
- Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three
- alphabetic characters.
-
- #rule
- A construct "#" is defined, similar to "*", for defining lists of
- elements. The full form is "<n>#<m>element" indicating at least
- <n> and at most <m> elements, each separated by one or more commas
- (",") and OPTIONAL linear white space (LWS). This makes the usual
- form of lists very easy; a rule such as
- ( *LWS element *( *LWS "," *LWS element ))
- can be shown as
- 1#element
- Wherever this construct is used, null elements are allowed, but do
- not contribute to the count of elements present. That is,
- "(element), , (element) " is permitted, but counts as only two
- elements. Therefore, where at least one element is required, at
- least one non-null element MUST be present. Default values are 0
- and infinity so that "#element" allows any number, including zero;
- "1#element" requires at least one; and "1#2element" allows one or
- two.
-
- ; comment
- A semi-colon, set off some distance to the right of rule text,
- starts a comment that continues to the end of line. This is a
- simple way of including useful notes in parallel with the
- specifications.
-
- implied *LWS
- The grammar described by this specification is word-based. Except
- where noted otherwise, linear white space (LWS) can be included
- between any two adjacent words (token or quoted-string), and
- between adjacent words and separators, without changing the
- interpretation of a field. At least one delimiter (LWS and/or
-
- separators) MUST exist between any two tokens (for the definition
- of "token" below), since they would otherwise be interpreted as a
- single token.
-
-2.2 Basic Rules
-
- The following rules are used throughout this specification to
- describe basic parsing constructs. The US-ASCII coded character set
- is defined by ANSI X3.4-1986 [21].
-
-
-
-
-
-Fielding, et al. Standards Track [Page 15]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- OCTET = <any 8-bit sequence of data>
- CHAR = <any US-ASCII character (octets 0 - 127)>
- UPALPHA = <any US-ASCII uppercase letter "A".."Z">
- LOALPHA = <any US-ASCII lowercase letter "a".."z">
- ALPHA = UPALPHA | LOALPHA
- DIGIT = <any US-ASCII digit "0".."9">
- CTL = <any US-ASCII control character
- (octets 0 - 31) and DEL (127)>
- CR = <US-ASCII CR, carriage return (13)>
- LF = <US-ASCII LF, linefeed (10)>
- SP = <US-ASCII SP, space (32)>
- HT = <US-ASCII HT, horizontal-tab (9)>
- <"> = <US-ASCII double-quote mark (34)>
-
- HTTP/1.1 defines the sequence CR LF as the end-of-line marker for all
- protocol elements except the entity-body (see appendix 19.3 for
- tolerant applications). The end-of-line marker within an entity-body
- is defined by its associated media type, as described in section 3.7.
-
- CRLF = CR LF
-
- HTTP/1.1 header field values can be folded onto multiple lines if the
- continuation line begins with a space or horizontal tab. All linear
- white space, including folding, has the same semantics as SP. A
- recipient MAY replace any linear white space with a single SP before
- interpreting the field value or forwarding the message downstream.
-
- LWS = [CRLF] 1*( SP | HT )
-
- The TEXT rule is only used for descriptive field contents and values
- that are not intended to be interpreted by the message parser. Words
- of *TEXT MAY contain characters from character sets other than ISO-
- 8859-1 [22] only when encoded according to the rules of RFC 2047
- [14].
-
- TEXT = <any OCTET except CTLs,
- but including LWS>
-
- A CRLF is allowed in the definition of TEXT only as part of a header
- field continuation. It is expected that the folding LWS will be
- replaced with a single SP before interpretation of the TEXT value.
-
- Hexadecimal numeric characters are used in several protocol elements.
-
- HEX = "A" | "B" | "C" | "D" | "E" | "F"
- | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT
-
-
-
-
-
-Fielding, et al. Standards Track [Page 16]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Many HTTP/1.1 header field values consist of words separated by LWS
- or special characters. These special characters MUST be in a quoted
- string to be used within a parameter value (as defined in section
- 3.6).
-
- token = 1*<any CHAR except CTLs or separators>
- separators = "(" | ")" | "<" | ">" | "@"
- | "," | ";" | ":" | "\" | <">
- | "/" | "[" | "]" | "?" | "="
- | "{" | "}" | SP | HT
-
- Comments can be included in some HTTP header fields by surrounding
- the comment text with parentheses. Comments are only allowed in
- fields containing "comment" as part of their field value definition.
- In all other fields, parentheses are considered part of the field
- value.
-
- comment = "(" *( ctext | quoted-pair | comment ) ")"
- ctext = <any TEXT excluding "(" and ")">
-
- A string of text is parsed as a single word if it is quoted using
- double-quote marks.
-
- quoted-string = ( <"> *(qdtext | quoted-pair ) <"> )
- qdtext = <any TEXT except <">>
-
- The backslash character ("\") MAY be used as a single-character
- quoting mechanism only within quoted-string and comment constructs.
-
- quoted-pair = "\" CHAR
-
-3 Protocol Parameters
-
-3.1 HTTP Version
-
- HTTP uses a "<major>.<minor>" numbering scheme to indicate versions
- of the protocol. The protocol versioning policy is intended to allow
- the sender to indicate the format of a message and its capacity for
- understanding further HTTP communication, rather than the features
- obtained via that communication. No change is made to the version
- number for the addition of message components which do not affect
- communication behavior or which only add to extensible field values.
- The <minor> number is incremented when the changes made to the
- protocol add features which do not change the general message parsing
- algorithm, but which may add to the message semantics and imply
- additional capabilities of the sender. The <major> number is
- incremented when the format of a message within the protocol is
- changed. See RFC 2145 [36] for a fuller explanation.
-
-
-
-Fielding, et al. Standards Track [Page 17]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- The version of an HTTP message is indicated by an HTTP-Version field
- in the first line of the message.
-
- HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT
-
- Note that the major and minor numbers MUST be treated as separate
- integers and that each MAY be incremented higher than a single digit.
- Thus, HTTP/2.4 is a lower version than HTTP/2.13, which in turn is
- lower than HTTP/12.3. Leading zeros MUST be ignored by recipients and
- MUST NOT be sent.
-
- An application that sends a request or response message that includes
- HTTP-Version of "HTTP/1.1" MUST be at least conditionally compliant
- with this specification. Applications that are at least conditionally
- compliant with this specification SHOULD use an HTTP-Version of
- "HTTP/1.1" in their messages, and MUST do so for any message that is
- not compatible with HTTP/1.0. For more details on when to send
- specific HTTP-Version values, see RFC 2145 [36].
-
- The HTTP version of an application is the highest HTTP version for
- which the application is at least conditionally compliant.
-
- Proxy and gateway applications need to be careful when forwarding
- messages in protocol versions different from that of the application.
- Since the protocol version indicates the protocol capability of the
- sender, a proxy/gateway MUST NOT send a message with a version
- indicator which is greater than its actual version. If a higher
- version request is received, the proxy/gateway MUST either downgrade
- the request version, or respond with an error, or switch to tunnel
- behavior.
-
- Due to interoperability problems with HTTP/1.0 proxies discovered
- since the publication of RFC 2068[33], caching proxies MUST, gateways
- MAY, and tunnels MUST NOT upgrade the request to the highest version
- they support. The proxy/gateway's response to that request MUST be in
- the same major version as the request.
-
- Note: Converting between versions of HTTP may involve modification
- of header fields required or forbidden by the versions involved.
-
-3.2 Uniform Resource Identifiers
-
- URIs have been known by many names: WWW addresses, Universal Document
- Identifiers, Universal Resource Identifiers [3], and finally the
- combination of Uniform Resource Locators (URL) [4] and Names (URN)
- [20]. As far as HTTP is concerned, Uniform Resource Identifiers are
- simply formatted strings which identify--via name, location, or any
- other characteristic--a resource.
-
-
-
-Fielding, et al. Standards Track [Page 18]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-3.2.1 General Syntax
-
- URIs in HTTP can be represented in absolute form or relative to some
- known base URI [11], depending upon the context of their use. The two
- forms are differentiated by the fact that absolute URIs always begin
- with a scheme name followed by a colon. For definitive information on
- URL syntax and semantics, see "Uniform Resource Identifiers (URI):
- Generic Syntax and Semantics," RFC 2396 [42] (which replaces RFCs
- 1738 [4] and RFC 1808 [11]). This specification adopts the
- definitions of "URI-reference", "absoluteURI", "relativeURI", "port",
- "host","abs_path", "rel_path", and "authority" from that
- specification.
-
- The HTTP protocol does not place any a priori limit on the length of
- a URI. Servers MUST be able to handle the URI of any resource they
- serve, and SHOULD be able to handle URIs of unbounded length if they
- provide GET-based forms that could generate such URIs. A server
- SHOULD return 414 (Request-URI Too Long) status if a URI is longer
- than the server can handle (see section 10.4.15).
-
- Note: Servers ought to be cautious about depending on URI lengths
- above 255 bytes, because some older client or proxy
- implementations might not properly support these lengths.
-
-3.2.2 http URL
-
- The "http" scheme is used to locate network resources via the HTTP
- protocol. This section defines the scheme-specific syntax and
- semantics for http URLs.
-
- http_URL = "http:" "//" host [ ":" port ] [ abs_path [ "?" query ]]
-
- If the port is empty or not given, port 80 is assumed. The semantics
- are that the identified resource is located at the server listening
- for TCP connections on that port of that host, and the Request-URI
- for the resource is abs_path (section 5.1.2). The use of IP addresses
- in URLs SHOULD be avoided whenever possible (see RFC 1900 [24]). If
- the abs_path is not present in the URL, it MUST be given as "/" when
- used as a Request-URI for a resource (section 5.1.2). If a proxy
- receives a host name which is not a fully qualified domain name, it
- MAY add its domain to the host name it received. If a proxy receives
- a fully qualified domain name, the proxy MUST NOT change the host
- name.
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 19]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-3.2.3 URI Comparison
-
- When comparing two URIs to decide if they match or not, a client
- SHOULD use a case-sensitive octet-by-octet comparison of the entire
- URIs, with these exceptions:
-
- - A port that is empty or not given is equivalent to the default
- port for that URI-reference;
-
- - Comparisons of host names MUST be case-insensitive;
-
- - Comparisons of scheme names MUST be case-insensitive;
-
- - An empty abs_path is equivalent to an abs_path of "/".
-
- Characters other than those in the "reserved" and "unsafe" sets (see
- RFC 2396 [42]) are equivalent to their ""%" HEX HEX" encoding.
-
- For example, the following three URIs are equivalent:
-
- http://abc.com:80/~smith/home.html
- http://ABC.com/%7Esmith/home.html
- http://ABC.com:/%7esmith/home.html
-
-3.3 Date/Time Formats
-
-3.3.1 Full Date
-
- HTTP applications have historically allowed three different formats
- for the representation of date/time stamps:
-
- Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123
- Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036
- Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format
-
- The first format is preferred as an Internet standard and represents
- a fixed-length subset of that defined by RFC 1123 [8] (an update to
- RFC 822 [9]). The second format is in common use, but is based on the
- obsolete RFC 850 [12] date format and lacks a four-digit year.
- HTTP/1.1 clients and servers that parse the date value MUST accept
- all three formats (for compatibility with HTTP/1.0), though they MUST
- only generate the RFC 1123 format for representing HTTP-date values
- in header fields. See section 19.3 for further information.
-
- Note: Recipients of date values are encouraged to be robust in
- accepting date values that may have been sent by non-HTTP
- applications, as is sometimes the case when retrieving or posting
- messages via proxies/gateways to SMTP or NNTP.
-
-
-
-Fielding, et al. Standards Track [Page 20]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- All HTTP date/time stamps MUST be represented in Greenwich Mean Time
- (GMT), without exception. For the purposes of HTTP, GMT is exactly
- equal to UTC (Coordinated Universal Time). This is indicated in the
- first two formats by the inclusion of "GMT" as the three-letter
- abbreviation for time zone, and MUST be assumed when reading the
- asctime format. HTTP-date is case sensitive and MUST NOT include
- additional LWS beyond that specifically included as SP in the
- grammar.
-
- HTTP-date = rfc1123-date | rfc850-date | asctime-date
- rfc1123-date = wkday "," SP date1 SP time SP "GMT"
- rfc850-date = weekday "," SP date2 SP time SP "GMT"
- asctime-date = wkday SP date3 SP time SP 4DIGIT
- date1 = 2DIGIT SP month SP 4DIGIT
- ; day month year (e.g., 02 Jun 1982)
- date2 = 2DIGIT "-" month "-" 2DIGIT
- ; day-month-year (e.g., 02-Jun-82)
- date3 = month SP ( 2DIGIT | ( SP 1DIGIT ))
- ; month day (e.g., Jun 2)
- time = 2DIGIT ":" 2DIGIT ":" 2DIGIT
- ; 00:00:00 - 23:59:59
- wkday = "Mon" | "Tue" | "Wed"
- | "Thu" | "Fri" | "Sat" | "Sun"
- weekday = "Monday" | "Tuesday" | "Wednesday"
- | "Thursday" | "Friday" | "Saturday" | "Sunday"
- month = "Jan" | "Feb" | "Mar" | "Apr"
- | "May" | "Jun" | "Jul" | "Aug"
- | "Sep" | "Oct" | "Nov" | "Dec"
-
- Note: HTTP requirements for the date/time stamp format apply only
- to their usage within the protocol stream. Clients and servers are
- not required to use these formats for user presentation, request
- logging, etc.
-
-3.3.2 Delta Seconds
-
- Some HTTP header fields allow a time value to be specified as an
- integer number of seconds, represented in decimal, after the time
- that the message was received.
-
- delta-seconds = 1*DIGIT
-
-3.4 Character Sets
-
- HTTP uses the same definition of the term "character set" as that
- described for MIME:
-
-
-
-
-
-Fielding, et al. Standards Track [Page 21]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- The term "character set" is used in this document to refer to a
- method used with one or more tables to convert a sequence of octets
- into a sequence of characters. Note that unconditional conversion in
- the other direction is not required, in that not all characters may
- be available in a given character set and a character set may provide
- more than one sequence of octets to represent a particular character.
- This definition is intended to allow various kinds of character
- encoding, from simple single-table mappings such as US-ASCII to
- complex table switching methods such as those that use ISO-2022's
- techniques. However, the definition associated with a MIME character
- set name MUST fully specify the mapping to be performed from octets
- to characters. In particular, use of external profiling information
- to determine the exact mapping is not permitted.
-
- Note: This use of the term "character set" is more commonly
- referred to as a "character encoding." However, since HTTP and
- MIME share the same registry, it is important that the terminology
- also be shared.
-
- HTTP character sets are identified by case-insensitive tokens. The
- complete set of tokens is defined by the IANA Character Set registry
- [19].
-
- charset = token
-
- Although HTTP allows an arbitrary token to be used as a charset
- value, any token that has a predefined value within the IANA
- Character Set registry [19] MUST represent the character set defined
- by that registry. Applications SHOULD limit their use of character
- sets to those defined by the IANA registry.
-
- Implementors should be aware of IETF character set requirements [38]
- [41].
-
-3.4.1 Missing Charset
-
- Some HTTP/1.0 software has interpreted a Content-Type header without
- charset parameter incorrectly to mean "recipient should guess."
- Senders wishing to defeat this behavior MAY include a charset
- parameter even when the charset is ISO-8859-1 and SHOULD do so when
- it is known that it will not confuse the recipient.
-
- Unfortunately, some older HTTP/1.0 clients did not deal properly with
- an explicit charset parameter. HTTP/1.1 recipients MUST respect the
- charset label provided by the sender; and those user agents that have
- a provision to "guess" a charset MUST use the charset from the
-
-
-
-
-
-Fielding, et al. Standards Track [Page 22]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- content-type field if they support that charset, rather than the
- recipient's preference, when initially displaying a document. See
- section 3.7.1.
-
-3.5 Content Codings
-
- Content coding values indicate an encoding transformation that has
- been or can be applied to an entity. Content codings are primarily
- used to allow a document to be compressed or otherwise usefully
- transformed without losing the identity of its underlying media type
- and without loss of information. Frequently, the entity is stored in
- coded form, transmitted directly, and only decoded by the recipient.
-
- content-coding = token
-
- All content-coding values are case-insensitive. HTTP/1.1 uses
- content-coding values in the Accept-Encoding (section 14.3) and
- Content-Encoding (section 14.11) header fields. Although the value
- describes the content-coding, what is more important is that it
- indicates what decoding mechanism will be required to remove the
- encoding.
-
- The Internet Assigned Numbers Authority (IANA) acts as a registry for
- content-coding value tokens. Initially, the registry contains the
- following tokens:
-
- gzip An encoding format produced by the file compression program
- "gzip" (GNU zip) as described in RFC 1952 [25]. This format is a
- Lempel-Ziv coding (LZ77) with a 32 bit CRC.
-
- compress
- The encoding format produced by the common UNIX file compression
- program "compress". This format is an adaptive Lempel-Ziv-Welch
- coding (LZW).
-
- Use of program names for the identification of encoding formats
- is not desirable and is discouraged for future encodings. Their
- use here is representative of historical practice, not good
- design. For compatibility with previous implementations of HTTP,
- applications SHOULD consider "x-gzip" and "x-compress" to be
- equivalent to "gzip" and "compress" respectively.
-
- deflate
- The "zlib" format defined in RFC 1950 [31] in combination with
- the "deflate" compression mechanism described in RFC 1951 [29].
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 23]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- identity
- The default (identity) encoding; the use of no transformation
- whatsoever. This content-coding is used only in the Accept-
- Encoding header, and SHOULD NOT be used in the Content-Encoding
- header.
-
- New content-coding value tokens SHOULD be registered; to allow
- interoperability between clients and servers, specifications of the
- content coding algorithms needed to implement a new value SHOULD be
- publicly available and adequate for independent implementation, and
- conform to the purpose of content coding defined in this section.
-
-3.6 Transfer Codings
-
- Transfer-coding values are used to indicate an encoding
- transformation that has been, can be, or may need to be applied to an
- entity-body in order to ensure "safe transport" through the network.
- This differs from a content coding in that the transfer-coding is a
- property of the message, not of the original entity.
-
- transfer-coding = "chunked" | transfer-extension
- transfer-extension = token *( ";" parameter )
-
- Parameters are in the form of attribute/value pairs.
-
- parameter = attribute "=" value
- attribute = token
- value = token | quoted-string
-
- All transfer-coding values are case-insensitive. HTTP/1.1 uses
- transfer-coding values in the TE header field (section 14.39) and in
- the Transfer-Encoding header field (section 14.41).
-
- Whenever a transfer-coding is applied to a message-body, the set of
- transfer-codings MUST include "chunked", unless the message is
- terminated by closing the connection. When the "chunked" transfer-
- coding is used, it MUST be the last transfer-coding applied to the
- message-body. The "chunked" transfer-coding MUST NOT be applied more
- than once to a message-body. These rules allow the recipient to
- determine the transfer-length of the message (section 4.4).
-
- Transfer-codings are analogous to the Content-Transfer-Encoding
- values of MIME [7], which were designed to enable safe transport of
- binary data over a 7-bit transport service. However, safe transport
- has a different focus for an 8bit-clean transfer protocol. In HTTP,
- the only unsafe characteristic of message-bodies is the difficulty in
- determining the exact body length (section 7.2.2), or the desire to
- encrypt data over a shared transport.
-
-
-
-Fielding, et al. Standards Track [Page 24]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- The Internet Assigned Numbers Authority (IANA) acts as a registry for
- transfer-coding value tokens. Initially, the registry contains the
- following tokens: "chunked" (section 3.6.1), "identity" (section
- 3.6.2), "gzip" (section 3.5), "compress" (section 3.5), and "deflate"
- (section 3.5).
-
- New transfer-coding value tokens SHOULD be registered in the same way
- as new content-coding value tokens (section 3.5).
-
- A server which receives an entity-body with a transfer-coding it does
- not understand SHOULD return 501 (Unimplemented), and close the
- connection. A server MUST NOT send transfer-codings to an HTTP/1.0
- client.
-
-3.6.1 Chunked Transfer Coding
-
- The chunked encoding modifies the body of a message in order to
- transfer it as a series of chunks, each with its own size indicator,
- followed by an OPTIONAL trailer containing entity-header fields. This
- allows dynamically produced content to be transferred along with the
- information necessary for the recipient to verify that it has
- received the full message.
-
- Chunked-Body = *chunk
- last-chunk
- trailer
- CRLF
-
- chunk = chunk-size [ chunk-extension ] CRLF
- chunk-data CRLF
- chunk-size = 1*HEX
- last-chunk = 1*("0") [ chunk-extension ] CRLF
-
- chunk-extension= *( ";" chunk-ext-name [ "=" chunk-ext-val ] )
- chunk-ext-name = token
- chunk-ext-val = token | quoted-string
- chunk-data = chunk-size(OCTET)
- trailer = *(entity-header CRLF)
-
- The chunk-size field is a string of hex digits indicating the size of
- the chunk. The chunked encoding is ended by any chunk whose size is
- zero, followed by the trailer, which is terminated by an empty line.
-
- The trailer allows the sender to include additional HTTP header
- fields at the end of the message. The Trailer header field can be
- used to indicate which header fields are included in a trailer (see
- section 14.40).
-
-
-
-
-Fielding, et al. Standards Track [Page 25]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- A server using chunked transfer-coding in a response MUST NOT use the
- trailer for any header fields unless at least one of the following is
- true:
-
- a)the request included a TE header field that indicates "trailers" is
- acceptable in the transfer-coding of the response, as described in
- section 14.39; or,
-
- b)the server is the origin server for the response, the trailer
- fields consist entirely of optional metadata, and the recipient
- could use the message (in a manner acceptable to the origin server)
- without receiving this metadata. In other words, the origin server
- is willing to accept the possibility that the trailer fields might
- be silently discarded along the path to the client.
-
- This requirement prevents an interoperability failure when the
- message is being received by an HTTP/1.1 (or later) proxy and
- forwarded to an HTTP/1.0 recipient. It avoids a situation where
- compliance with the protocol would have necessitated a possibly
- infinite buffer on the proxy.
-
- An example process for decoding a Chunked-Body is presented in
- appendix 19.4.6.
-
- All HTTP/1.1 applications MUST be able to receive and decode the
- "chunked" transfer-coding, and MUST ignore chunk-extension extensions
- they do not understand.
-
-3.7 Media Types
-
- HTTP uses Internet Media Types [17] in the Content-Type (section
- 14.17) and Accept (section 14.1) header fields in order to provide
- open and extensible data typing and type negotiation.
-
- media-type = type "/" subtype *( ";" parameter )
- type = token
- subtype = token
-
- Parameters MAY follow the type/subtype in the form of attribute/value
- pairs (as defined in section 3.6).
-
- The type, subtype, and parameter attribute names are case-
- insensitive. Parameter values might or might not be case-sensitive,
- depending on the semantics of the parameter name. Linear white space
- (LWS) MUST NOT be used between the type and subtype, nor between an
- attribute and its value. The presence or absence of a parameter might
- be significant to the processing of a media-type, depending on its
- definition within the media type registry.
-
-
-
-Fielding, et al. Standards Track [Page 26]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Note that some older HTTP applications do not recognize media type
- parameters. When sending data to older HTTP applications,
- implementations SHOULD only use media type parameters when they are
- required by that type/subtype definition.
-
- Media-type values are registered with the Internet Assigned Number
- Authority (IANA [19]). The media type registration process is
- outlined in RFC 1590 [17]. Use of non-registered media types is
- discouraged.
-
-3.7.1 Canonicalization and Text Defaults
-
- Internet media types are registered with a canonical form. An
- entity-body transferred via HTTP messages MUST be represented in the
- appropriate canonical form prior to its transmission except for
- "text" types, as defined in the next paragraph.
-
- When in canonical form, media subtypes of the "text" type use CRLF as
- the text line break. HTTP relaxes this requirement and allows the
- transport of text media with plain CR or LF alone representing a line
- break when it is done consistently for an entire entity-body. HTTP
- applications MUST accept CRLF, bare CR, and bare LF as being
- representative of a line break in text media received via HTTP. In
- addition, if the text is represented in a character set that does not
- use octets 13 and 10 for CR and LF respectively, as is the case for
- some multi-byte character sets, HTTP allows the use of whatever octet
- sequences are defined by that character set to represent the
- equivalent of CR and LF for line breaks. This flexibility regarding
- line breaks applies only to text media in the entity-body; a bare CR
- or LF MUST NOT be substituted for CRLF within any of the HTTP control
- structures (such as header fields and multipart boundaries).
-
- If an entity-body is encoded with a content-coding, the underlying
- data MUST be in a form defined above prior to being encoded.
-
- The "charset" parameter is used with some media types to define the
- character set (section 3.4) of the data. When no explicit charset
- parameter is provided by the sender, media subtypes of the "text"
- type are defined to have a default charset value of "ISO-8859-1" when
- received via HTTP. Data in character sets other than "ISO-8859-1" or
- its subsets MUST be labeled with an appropriate charset value. See
- section 3.4.1 for compatibility problems.
-
-3.7.2 Multipart Types
-
- MIME provides for a number of "multipart" types -- encapsulations of
- one or more entities within a single message-body. All multipart
- types share a common syntax, as defined in section 5.1.1 of RFC 2046
-
-
-
-Fielding, et al. Standards Track [Page 27]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- [40], and MUST include a boundary parameter as part of the media type
- value. The message body is itself a protocol element and MUST
- therefore use only CRLF to represent line breaks between body-parts.
- Unlike in RFC 2046, the epilogue of any multipart message MUST be
- empty; HTTP applications MUST NOT transmit the epilogue (even if the
- original multipart contains an epilogue). These restrictions exist in
- order to preserve the self-delimiting nature of a multipart message-
- body, wherein the "end" of the message-body is indicated by the
- ending multipart boundary.
-
- In general, HTTP treats a multipart message-body no differently than
- any other media type: strictly as payload. The one exception is the
- "multipart/byteranges" type (appendix 19.2) when it appears in a 206
- (Partial Content) response, which will be interpreted by some HTTP
- caching mechanisms as described in sections 13.5.4 and 14.16. In all
- other cases, an HTTP user agent SHOULD follow the same or similar
- behavior as a MIME user agent would upon receipt of a multipart type.
- The MIME header fields within each body-part of a multipart message-
- body do not have any significance to HTTP beyond that defined by
- their MIME semantics.
-
- In general, an HTTP user agent SHOULD follow the same or similar
- behavior as a MIME user agent would upon receipt of a multipart type.
- If an application receives an unrecognized multipart subtype, the
- application MUST treat it as being equivalent to "multipart/mixed".
-
- Note: The "multipart/form-data" type has been specifically defined
- for carrying form data suitable for processing via the POST
- request method, as described in RFC 1867 [15].
-
-3.8 Product Tokens
-
- Product tokens are used to allow communicating applications to
- identify themselves by software name and version. Most fields using
- product tokens also allow sub-products which form a significant part
- of the application to be listed, separated by white space. By
- convention, the products are listed in order of their significance
- for identifying the application.
-
- product = token ["/" product-version]
- product-version = token
-
- Examples:
-
- User-Agent: CERN-LineMode/2.15 libwww/2.17b3
- Server: Apache/0.8.4
-
-
-
-
-
-Fielding, et al. Standards Track [Page 28]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Product tokens SHOULD be short and to the point. They MUST NOT be
- used for advertising or other non-essential information. Although any
- token character MAY appear in a product-version, this token SHOULD
- only be used for a version identifier (i.e., successive versions of
- the same product SHOULD only differ in the product-version portion of
- the product value).
-
-3.9 Quality Values
-
- HTTP content negotiation (section 12) uses short "floating point"
- numbers to indicate the relative importance ("weight") of various
- negotiable parameters. A weight is normalized to a real number in
- the range 0 through 1, where 0 is the minimum and 1 the maximum
- value. If a parameter has a quality value of 0, then content with
- this parameter is `not acceptable' for the client. HTTP/1.1
- applications MUST NOT generate more than three digits after the
- decimal point. User configuration of these values SHOULD also be
- limited in this fashion.
-
- qvalue = ( "0" [ "." 0*3DIGIT ] )
- | ( "1" [ "." 0*3("0") ] )
-
- "Quality values" is a misnomer, since these values merely represent
- relative degradation in desired quality.
-
-3.10 Language Tags
-
- A language tag identifies a natural language spoken, written, or
- otherwise conveyed by human beings for communication of information
- to other human beings. Computer languages are explicitly excluded.
- HTTP uses language tags within the Accept-Language and Content-
- Language fields.
-
- The syntax and registry of HTTP language tags is the same as that
- defined by RFC 1766 [1]. In summary, a language tag is composed of 1
- or more parts: A primary language tag and a possibly empty series of
- subtags:
-
- language-tag = primary-tag *( "-" subtag )
- primary-tag = 1*8ALPHA
- subtag = 1*8ALPHA
-
- White space is not allowed within the tag and all tags are case-
- insensitive. The name space of language tags is administered by the
- IANA. Example tags include:
-
- en, en-US, en-cockney, i-cherokee, x-pig-latin
-
-
-
-
-Fielding, et al. Standards Track [Page 29]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- where any two-letter primary-tag is an ISO-639 language abbreviation
- and any two-letter initial subtag is an ISO-3166 country code. (The
- last three tags above are not registered tags; all but the last are
- examples of tags which could be registered in future.)
-
-3.11 Entity Tags
-
- Entity tags are used for comparing two or more entities from the same
- requested resource. HTTP/1.1 uses entity tags in the ETag (section
- 14.19), If-Match (section 14.24), If-None-Match (section 14.26), and
- If-Range (section 14.27) header fields. The definition of how they
- are used and compared as cache validators is in section 13.3.3. An
- entity tag consists of an opaque quoted string, possibly prefixed by
- a weakness indicator.
-
- entity-tag = [ weak ] opaque-tag
- weak = "W/"
- opaque-tag = quoted-string
-
- A "strong entity tag" MAY be shared by two entities of a resource
- only if they are equivalent by octet equality.
-
- A "weak entity tag," indicated by the "W/" prefix, MAY be shared by
- two entities of a resource only if the entities are equivalent and
- could be substituted for each other with no significant change in
- semantics. A weak entity tag can only be used for weak comparison.
-
- An entity tag MUST be unique across all versions of all entities
- associated with a particular resource. A given entity tag value MAY
- be used for entities obtained by requests on different URIs. The use
- of the same entity tag value in conjunction with entities obtained by
- requests on different URIs does not imply the equivalence of those
- entities.
-
-3.12 Range Units
-
- HTTP/1.1 allows a client to request that only part (a range of) the
- response entity be included within the response. HTTP/1.1 uses range
- units in the Range (section 14.35) and Content-Range (section 14.16)
- header fields. An entity can be broken down into subranges according
- to various structural units.
-
- range-unit = bytes-unit | other-range-unit
- bytes-unit = "bytes"
- other-range-unit = token
-
- The only range unit defined by HTTP/1.1 is "bytes". HTTP/1.1
- implementations MAY ignore ranges specified using other units.
-
-
-
-Fielding, et al. Standards Track [Page 30]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- HTTP/1.1 has been designed to allow implementations of applications
- that do not depend on knowledge of ranges.
-
-4 HTTP Message
-
-4.1 Message Types
-
- HTTP messages consist of requests from client to server and responses
- from server to client.
-
- HTTP-message = Request | Response ; HTTP/1.1 messages
-
- Request (section 5) and Response (section 6) messages use the generic
- message format of RFC 822 [9] for transferring entities (the payload
- of the message). Both types of message consist of a start-line, zero
- or more header fields (also known as "headers"), an empty line (i.e.,
- a line with nothing preceding the CRLF) indicating the end of the
- header fields, and possibly a message-body.
-
- generic-message = start-line
- *(message-header CRLF)
- CRLF
- [ message-body ]
- start-line = Request-Line | Status-Line
-
- In the interest of robustness, servers SHOULD ignore any empty
- line(s) received where a Request-Line is expected. In other words, if
- the server is reading the protocol stream at the beginning of a
- message and receives a CRLF first, it should ignore the CRLF.
-
- Certain buggy HTTP/1.0 client implementations generate extra CRLF's
- after a POST request. To restate what is explicitly forbidden by the
- BNF, an HTTP/1.1 client MUST NOT preface or follow a request with an
- extra CRLF.
-
-4.2 Message Headers
-
- HTTP header fields, which include general-header (section 4.5),
- request-header (section 5.3), response-header (section 6.2), and
- entity-header (section 7.1) fields, follow the same generic format as
- that given in Section 3.1 of RFC 822 [9]. Each header field consists
- of a name followed by a colon (":") and the field value. Field names
- are case-insensitive. The field value MAY be preceded by any amount
- of LWS, though a single SP is preferred. Header fields can be
- extended over multiple lines by preceding each extra line with at
- least one SP or HT. Applications ought to follow "common form", where
- one is known or indicated, when generating HTTP constructs, since
- there might exist some implementations that fail to accept anything
-
-
-
-Fielding, et al. Standards Track [Page 31]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- beyond the common forms.
-
- message-header = field-name ":" [ field-value ]
- field-name = token
- field-value = *( field-content | LWS )
- field-content = <the OCTETs making up the field-value
- and consisting of either *TEXT or combinations
- of token, separators, and quoted-string>
-
- The field-content does not include any leading or trailing LWS:
- linear white space occurring before the first non-whitespace
- character of the field-value or after the last non-whitespace
- character of the field-value. Such leading or trailing LWS MAY be
- removed without changing the semantics of the field value. Any LWS
- that occurs between field-content MAY be replaced with a single SP
- before interpreting the field value or forwarding the message
- downstream.
-
- The order in which header fields with differing field names are
- received is not significant. However, it is "good practice" to send
- general-header fields first, followed by request-header or response-
- header fields, and ending with the entity-header fields.
-
- Multiple message-header fields with the same field-name MAY be
- present in a message if and only if the entire field-value for that
- header field is defined as a comma-separated list [i.e., #(values)].
- It MUST be possible to combine the multiple header fields into one
- "field-name: field-value" pair, without changing the semantics of the
- message, by appending each subsequent field-value to the first, each
- separated by a comma. The order in which header fields with the same
- field-name are received is therefore significant to the
- interpretation of the combined field value, and thus a proxy MUST NOT
- change the order of these field values when a message is forwarded.
-
-4.3 Message Body
-
- The message-body (if any) of an HTTP message is used to carry the
- entity-body associated with the request or response. The message-body
- differs from the entity-body only when a transfer-coding has been
- applied, as indicated by the Transfer-Encoding header field (section
- 14.41).
-
- message-body = entity-body
- | <entity-body encoded as per Transfer-Encoding>
-
- Transfer-Encoding MUST be used to indicate any transfer-codings
- applied by an application to ensure safe and proper transfer of the
- message. Transfer-Encoding is a property of the message, not of the
-
-
-
-Fielding, et al. Standards Track [Page 32]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- entity, and thus MAY be added or removed by any application along the
- request/response chain. (However, section 3.6 places restrictions on
- when certain transfer-codings may be used.)
-
- The rules for when a message-body is allowed in a message differ for
- requests and responses.
-
- The presence of a message-body in a request is signaled by the
- inclusion of a Content-Length or Transfer-Encoding header field in
- the request's message-headers. A message-body MUST NOT be included in
- a request if the specification of the request method (section 5.1.1)
- does not allow sending an entity-body in requests. A server SHOULD
- read and forward a message-body on any request; if the request method
- does not include defined semantics for an entity-body, then the
- message-body SHOULD be ignored when handling the request.
-
- For response messages, whether or not a message-body is included with
- a message is dependent on both the request method and the response
- status code (section 6.1.1). All responses to the HEAD request method
- MUST NOT include a message-body, even though the presence of entity-
- header fields might lead one to believe they do. All 1xx
- (informational), 204 (no content), and 304 (not modified) responses
- MUST NOT include a message-body. All other responses do include a
- message-body, although it MAY be of zero length.
-
-4.4 Message Length
-
- The transfer-length of a message is the length of the message-body as
- it appears in the message; that is, after any transfer-codings have
- been applied. When a message-body is included with a message, the
- transfer-length of that body is determined by one of the following
- (in order of precedence):
-
- 1.Any response message which "MUST NOT" include a message-body (such
- as the 1xx, 204, and 304 responses and any response to a HEAD
- request) is always terminated by the first empty line after the
- header fields, regardless of the entity-header fields present in
- the message.
-
- 2.If a Transfer-Encoding header field (section 14.41) is present and
- has any value other than "identity", then the transfer-length is
- defined by use of the "chunked" transfer-coding (section 3.6),
- unless the message is terminated by closing the connection.
-
- 3.If a Content-Length header field (section 14.13) is present, its
- decimal value in OCTETs represents both the entity-length and the
- transfer-length. The Content-Length header field MUST NOT be sent
- if these two lengths are different (i.e., if a Transfer-Encoding
-
-
-
-Fielding, et al. Standards Track [Page 33]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- header field is present). If a message is received with both a
- Transfer-Encoding header field and a Content-Length header field,
- the latter MUST be ignored.
-
- 4.If the message uses the media type "multipart/byteranges", and the
- ransfer-length is not otherwise specified, then this self-
- elimiting media type defines the transfer-length. This media type
- UST NOT be used unless the sender knows that the recipient can arse
- it; the presence in a request of a Range header with ultiple byte-
- range specifiers from a 1.1 client implies that the lient can parse
- multipart/byteranges responses.
-
- A range header might be forwarded by a 1.0 proxy that does not
- understand multipart/byteranges; in this case the server MUST
- delimit the message using methods defined in items 1,3 or 5 of
- this section.
-
- 5.By the server closing the connection. (Closing the connection
- cannot be used to indicate the end of a request body, since that
- would leave no possibility for the server to send back a response.)
-
- For compatibility with HTTP/1.0 applications, HTTP/1.1 requests
- containing a message-body MUST include a valid Content-Length header
- field unless the server is known to be HTTP/1.1 compliant. If a
- request contains a message-body and a Content-Length is not given,
- the server SHOULD respond with 400 (bad request) if it cannot
- determine the length of the message, or with 411 (length required) if
- it wishes to insist on receiving a valid Content-Length.
-
- All HTTP/1.1 applications that receive entities MUST accept the
- "chunked" transfer-coding (section 3.6), thus allowing this mechanism
- to be used for messages when the message length cannot be determined
- in advance.
-
- Messages MUST NOT include both a Content-Length header field and a
- non-identity transfer-coding. If the message does include a non-
- identity transfer-coding, the Content-Length MUST be ignored.
-
- When a Content-Length is given in a message where a message-body is
- allowed, its field value MUST exactly match the number of OCTETs in
- the message-body. HTTP/1.1 user agents MUST notify the user when an
- invalid length is received and detected.
-
-4.5 General Header Fields
-
- There are a few header fields which have general applicability for
- both request and response messages, but which do not apply to the
- entity being transferred. These header fields apply only to the
-
-
-
-Fielding, et al. Standards Track [Page 34]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- message being transmitted.
-
- general-header = Cache-Control ; Section 14.9
- | Connection ; Section 14.10
- | Date ; Section 14.18
- | Pragma ; Section 14.32
- | Trailer ; Section 14.40
- | Transfer-Encoding ; Section 14.41
- | Upgrade ; Section 14.42
- | Via ; Section 14.45
- | Warning ; Section 14.46
-
- General-header field names can be extended reliably only in
- combination with a change in the protocol version. However, new or
- experimental header fields may be given the semantics of general
- header fields if all parties in the communication recognize them to
- be general-header fields. Unrecognized header fields are treated as
- entity-header fields.
-
-5 Request
-
- A request message from a client to a server includes, within the
- first line of that message, the method to be applied to the resource,
- the identifier of the resource, and the protocol version in use.
-
- Request = Request-Line ; Section 5.1
- *(( general-header ; Section 4.5
- | request-header ; Section 5.3
- | entity-header ) CRLF) ; Section 7.1
- CRLF
- [ message-body ] ; Section 4.3
-
-5.1 Request-Line
-
- The Request-Line begins with a method token, followed by the
- Request-URI and the protocol version, and ending with CRLF. The
- elements are separated by SP characters. No CR or LF is allowed
- except in the final CRLF sequence.
-
- Request-Line = Method SP Request-URI SP HTTP-Version CRLF
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 35]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-5.1.1 Method
-
- The Method token indicates the method to be performed on the
- resource identified by the Request-URI. The method is case-sensitive.
-
- Method = "OPTIONS" ; Section 9.2
- | "GET" ; Section 9.3
- | "HEAD" ; Section 9.4
- | "POST" ; Section 9.5
- | "PUT" ; Section 9.6
- | "DELETE" ; Section 9.7
- | "TRACE" ; Section 9.8
- | "CONNECT" ; Section 9.9
- | extension-method
- extension-method = token
-
- The list of methods allowed by a resource can be specified in an
- Allow header field (section 14.7). The return code of the response
- always notifies the client whether a method is currently allowed on a
- resource, since the set of allowed methods can change dynamically. An
- origin server SHOULD return the status code 405 (Method Not Allowed)
- if the method is known by the origin server but not allowed for the
- requested resource, and 501 (Not Implemented) if the method is
- unrecognized or not implemented by the origin server. The methods GET
- and HEAD MUST be supported by all general-purpose servers. All other
- methods are OPTIONAL; however, if the above methods are implemented,
- they MUST be implemented with the same semantics as those specified
- in section 9.
-
-5.1.2 Request-URI
-
- The Request-URI is a Uniform Resource Identifier (section 3.2) and
- identifies the resource upon which to apply the request.
-
- Request-URI = "*" | absoluteURI | abs_path | authority
-
- The four options for Request-URI are dependent on the nature of the
- request. The asterisk "*" means that the request does not apply to a
- particular resource, but to the server itself, and is only allowed
- when the method used does not necessarily apply to a resource. One
- example would be
-
- OPTIONS * HTTP/1.1
-
- The absoluteURI form is REQUIRED when the request is being made to a
- proxy. The proxy is requested to forward the request or service it
- from a valid cache, and return the response. Note that the proxy MAY
- forward the request on to another proxy or directly to the server
-
-
-
-Fielding, et al. Standards Track [Page 36]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- specified by the absoluteURI. In order to avoid request loops, a
- proxy MUST be able to recognize all of its server names, including
- any aliases, local variations, and the numeric IP address. An example
- Request-Line would be:
-
- GET http://www.w3.org/pub/WWW/TheProject.html HTTP/1.1
-
- To allow for transition to absoluteURIs in all requests in future
- versions of HTTP, all HTTP/1.1 servers MUST accept the absoluteURI
- form in requests, even though HTTP/1.1 clients will only generate
- them in requests to proxies.
-
- The authority form is only used by the CONNECT method (section 9.9).
-
- The most common form of Request-URI is that used to identify a
- resource on an origin server or gateway. In this case the absolute
- path of the URI MUST be transmitted (see section 3.2.1, abs_path) as
- the Request-URI, and the network location of the URI (authority) MUST
- be transmitted in a Host header field. For example, a client wishing
- to retrieve the resource above directly from the origin server would
- create a TCP connection to port 80 of the host "www.w3.org" and send
- the lines:
-
- GET /pub/WWW/TheProject.html HTTP/1.1
- Host: www.w3.org
-
- followed by the remainder of the Request. Note that the absolute path
- cannot be empty; if none is present in the original URI, it MUST be
- given as "/" (the server root).
-
- The Request-URI is transmitted in the format specified in section
- 3.2.1. If the Request-URI is encoded using the "% HEX HEX" encoding
- [42], the origin server MUST decode the Request-URI in order to
- properly interpret the request. Servers SHOULD respond to invalid
- Request-URIs with an appropriate status code.
-
- A transparent proxy MUST NOT rewrite the "abs_path" part of the
- received Request-URI when forwarding it to the next inbound server,
- except as noted above to replace a null abs_path with "/".
-
- Note: The "no rewrite" rule prevents the proxy from changing the
- meaning of the request when the origin server is improperly using
- a non-reserved URI character for a reserved purpose. Implementors
- should be aware that some pre-HTTP/1.1 proxies have been known to
- rewrite the Request-URI.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 37]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-5.2 The Resource Identified by a Request
-
- The exact resource identified by an Internet request is determined by
- examining both the Request-URI and the Host header field.
-
- An origin server that does not allow resources to differ by the
- requested host MAY ignore the Host header field value when
- determining the resource identified by an HTTP/1.1 request. (But see
- section 19.6.1.1 for other requirements on Host support in HTTP/1.1.)
-
- An origin server that does differentiate resources based on the host
- requested (sometimes referred to as virtual hosts or vanity host
- names) MUST use the following rules for determining the requested
- resource on an HTTP/1.1 request:
-
- 1. If Request-URI is an absoluteURI, the host is part of the
- Request-URI. Any Host header field value in the request MUST be
- ignored.
-
- 2. If the Request-URI is not an absoluteURI, and the request includes
- a Host header field, the host is determined by the Host header
- field value.
-
- 3. If the host as determined by rule 1 or 2 is not a valid host on
- the server, the response MUST be a 400 (Bad Request) error message.
-
- Recipients of an HTTP/1.0 request that lacks a Host header field MAY
- attempt to use heuristics (e.g., examination of the URI path for
- something unique to a particular host) in order to determine what
- exact resource is being requested.
-
-5.3 Request Header Fields
-
- The request-header fields allow the client to pass additional
- information about the request, and about the client itself, to the
- server. These fields act as request modifiers, with semantics
- equivalent to the parameters on a programming language method
- invocation.
-
- request-header = Accept ; Section 14.1
- | Accept-Charset ; Section 14.2
- | Accept-Encoding ; Section 14.3
- | Accept-Language ; Section 14.4
- | Authorization ; Section 14.8
- | Expect ; Section 14.20
- | From ; Section 14.22
- | Host ; Section 14.23
- | If-Match ; Section 14.24
-
-
-
-Fielding, et al. Standards Track [Page 38]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- | If-Modified-Since ; Section 14.25
- | If-None-Match ; Section 14.26
- | If-Range ; Section 14.27
- | If-Unmodified-Since ; Section 14.28
- | Max-Forwards ; Section 14.31
- | Proxy-Authorization ; Section 14.34
- | Range ; Section 14.35
- | Referer ; Section 14.36
- | TE ; Section 14.39
- | User-Agent ; Section 14.43
-
- Request-header field names can be extended reliably only in
- combination with a change in the protocol version. However, new or
- experimental header fields MAY be given the semantics of request-
- header fields if all parties in the communication recognize them to
- be request-header fields. Unrecognized header fields are treated as
- entity-header fields.
-
-6 Response
-
- After receiving and interpreting a request message, a server responds
- with an HTTP response message.
-
- Response = Status-Line ; Section 6.1
- *(( general-header ; Section 4.5
- | response-header ; Section 6.2
- | entity-header ) CRLF) ; Section 7.1
- CRLF
- [ message-body ] ; Section 7.2
-
-6.1 Status-Line
-
- The first line of a Response message is the Status-Line, consisting
- of the protocol version followed by a numeric status code and its
- associated textual phrase, with each element separated by SP
- characters. No CR or LF is allowed except in the final CRLF sequence.
-
- Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF
-
-6.1.1 Status Code and Reason Phrase
-
- The Status-Code element is a 3-digit integer result code of the
- attempt to understand and satisfy the request. These codes are fully
- defined in section 10. The Reason-Phrase is intended to give a short
- textual description of the Status-Code. The Status-Code is intended
- for use by automata and the Reason-Phrase is intended for the human
- user. The client is not required to examine or display the Reason-
- Phrase.
-
-
-
-Fielding, et al. Standards Track [Page 39]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- The first digit of the Status-Code defines the class of response. The
- last two digits do not have any categorization role. There are 5
- values for the first digit:
-
- - 1xx: Informational - Request received, continuing process
-
- - 2xx: Success - The action was successfully received,
- understood, and accepted
-
- - 3xx: Redirection - Further action must be taken in order to
- complete the request
-
- - 4xx: Client Error - The request contains bad syntax or cannot
- be fulfilled
-
- - 5xx: Server Error - The server failed to fulfill an apparently
- valid request
-
- The individual values of the numeric status codes defined for
- HTTP/1.1, and an example set of corresponding Reason-Phrase's, are
- presented below. The reason phrases listed here are only
- recommendations -- they MAY be replaced by local equivalents without
- affecting the protocol.
-
- Status-Code =
- "100" ; Section 10.1.1: Continue
- | "101" ; Section 10.1.2: Switching Protocols
- | "200" ; Section 10.2.1: OK
- | "201" ; Section 10.2.2: Created
- | "202" ; Section 10.2.3: Accepted
- | "203" ; Section 10.2.4: Non-Authoritative Information
- | "204" ; Section 10.2.5: No Content
- | "205" ; Section 10.2.6: Reset Content
- | "206" ; Section 10.2.7: Partial Content
- | "300" ; Section 10.3.1: Multiple Choices
- | "301" ; Section 10.3.2: Moved Permanently
- | "302" ; Section 10.3.3: Found
- | "303" ; Section 10.3.4: See Other
- | "304" ; Section 10.3.5: Not Modified
- | "305" ; Section 10.3.6: Use Proxy
- | "307" ; Section 10.3.8: Temporary Redirect
- | "400" ; Section 10.4.1: Bad Request
- | "401" ; Section 10.4.2: Unauthorized
- | "402" ; Section 10.4.3: Payment Required
- | "403" ; Section 10.4.4: Forbidden
- | "404" ; Section 10.4.5: Not Found
- | "405" ; Section 10.4.6: Method Not Allowed
- | "406" ; Section 10.4.7: Not Acceptable
-
-
-
-Fielding, et al. Standards Track [Page 40]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- | "407" ; Section 10.4.8: Proxy Authentication Required
- | "408" ; Section 10.4.9: Request Time-out
- | "409" ; Section 10.4.10: Conflict
- | "410" ; Section 10.4.11: Gone
- | "411" ; Section 10.4.12: Length Required
- | "412" ; Section 10.4.13: Precondition Failed
- | "413" ; Section 10.4.14: Request Entity Too Large
- | "414" ; Section 10.4.15: Request-URI Too Large
- | "415" ; Section 10.4.16: Unsupported Media Type
- | "416" ; Section 10.4.17: Requested range not satisfiable
- | "417" ; Section 10.4.18: Expectation Failed
- | "500" ; Section 10.5.1: Internal Server Error
- | "501" ; Section 10.5.2: Not Implemented
- | "502" ; Section 10.5.3: Bad Gateway
- | "503" ; Section 10.5.4: Service Unavailable
- | "504" ; Section 10.5.5: Gateway Time-out
- | "505" ; Section 10.5.6: HTTP Version not supported
- | extension-code
-
- extension-code = 3DIGIT
- Reason-Phrase = *<TEXT, excluding CR, LF>
-
- HTTP status codes are extensible. HTTP applications are not required
- to understand the meaning of all registered status codes, though such
- understanding is obviously desirable. However, applications MUST
- understand the class of any status code, as indicated by the first
- digit, and treat any unrecognized response as being equivalent to the
- x00 status code of that class, with the exception that an
- unrecognized response MUST NOT be cached. For example, if an
- unrecognized status code of 431 is received by the client, it can
- safely assume that there was something wrong with its request and
- treat the response as if it had received a 400 status code. In such
- cases, user agents SHOULD present to the user the entity returned
- with the response, since that entity is likely to include human-
- readable information which will explain the unusual status.
-
-6.2 Response Header Fields
-
- The response-header fields allow the server to pass additional
- information about the response which cannot be placed in the Status-
- Line. These header fields give information about the server and about
- further access to the resource identified by the Request-URI.
-
- response-header = Accept-Ranges ; Section 14.5
- | Age ; Section 14.6
- | ETag ; Section 14.19
- | Location ; Section 14.30
- | Proxy-Authenticate ; Section 14.33
-
-
-
-Fielding, et al. Standards Track [Page 41]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- | Retry-After ; Section 14.37
- | Server ; Section 14.38
- | Vary ; Section 14.44
- | WWW-Authenticate ; Section 14.47
-
- Response-header field names can be extended reliably only in
- combination with a change in the protocol version. However, new or
- experimental header fields MAY be given the semantics of response-
- header fields if all parties in the communication recognize them to
- be response-header fields. Unrecognized header fields are treated as
- entity-header fields.
-
-7 Entity
-
- Request and Response messages MAY transfer an entity if not otherwise
- restricted by the request method or response status code. An entity
- consists of entity-header fields and an entity-body, although some
- responses will only include the entity-headers.
-
- In this section, both sender and recipient refer to either the client
- or the server, depending on who sends and who receives the entity.
-
-7.1 Entity Header Fields
-
- Entity-header fields define metainformation about the entity-body or,
- if no body is present, about the resource identified by the request.
- Some of this metainformation is OPTIONAL; some might be REQUIRED by
- portions of this specification.
-
- entity-header = Allow ; Section 14.7
- | Content-Encoding ; Section 14.11
- | Content-Language ; Section 14.12
- | Content-Length ; Section 14.13
- | Content-Location ; Section 14.14
- | Content-MD5 ; Section 14.15
- | Content-Range ; Section 14.16
- | Content-Type ; Section 14.17
- | Expires ; Section 14.21
- | Last-Modified ; Section 14.29
- | extension-header
-
- extension-header = message-header
-
- The extension-header mechanism allows additional entity-header fields
- to be defined without changing the protocol, but these fields cannot
- be assumed to be recognizable by the recipient. Unrecognized header
- fields SHOULD be ignored by the recipient and MUST be forwarded by
- transparent proxies.
-
-
-
-Fielding, et al. Standards Track [Page 42]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-7.2 Entity Body
-
- The entity-body (if any) sent with an HTTP request or response is in
- a format and encoding defined by the entity-header fields.
-
- entity-body = *OCTET
-
- An entity-body is only present in a message when a message-body is
- present, as described in section 4.3. The entity-body is obtained
- from the message-body by decoding any Transfer-Encoding that might
- have been applied to ensure safe and proper transfer of the message.
-
-7.2.1 Type
-
- When an entity-body is included with a message, the data type of that
- body is determined via the header fields Content-Type and Content-
- Encoding. These define a two-layer, ordered encoding model:
-
- entity-body := Content-Encoding( Content-Type( data ) )
-
- Content-Type specifies the media type of the underlying data.
- Content-Encoding may be used to indicate any additional content
- codings applied to the data, usually for the purpose of data
- compression, that are a property of the requested resource. There is
- no default encoding.
-
- Any HTTP/1.1 message containing an entity-body SHOULD include a
- Content-Type header field defining the media type of that body. If
- and only if the media type is not given by a Content-Type field, the
- recipient MAY attempt to guess the media type via inspection of its
- content and/or the name extension(s) of the URI used to identify the
- resource. If the media type remains unknown, the recipient SHOULD
- treat it as type "application/octet-stream".
-
-7.2.2 Entity Length
-
- The entity-length of a message is the length of the message-body
- before any transfer-codings have been applied. Section 4.4 defines
- how the transfer-length of a message-body is determined.
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 43]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-8 Connections
-
-8.1 Persistent Connections
-
-8.1.1 Purpose
-
- Prior to persistent connections, a separate TCP connection was
- established to fetch each URL, increasing the load on HTTP servers
- and causing congestion on the Internet. The use of inline images and
- other associated data often require a client to make multiple
- requests of the same server in a short amount of time. Analysis of
- these performance problems and results from a prototype
- implementation are available [26] [30]. Implementation experience and
- measurements of actual HTTP/1.1 (RFC 2068) implementations show good
- results [39]. Alternatives have also been explored, for example,
- T/TCP [27].
-
- Persistent HTTP connections have a number of advantages:
-
- - By opening and closing fewer TCP connections, CPU time is saved
- in routers and hosts (clients, servers, proxies, gateways,
- tunnels, or caches), and memory used for TCP protocol control
- blocks can be saved in hosts.
-
- - HTTP requests and responses can be pipelined on a connection.
- Pipelining allows a client to make multiple requests without
- waiting for each response, allowing a single TCP connection to
- be used much more efficiently, with much lower elapsed time.
-
- - Network congestion is reduced by reducing the number of packets
- caused by TCP opens, and by allowing TCP sufficient time to
- determine the congestion state of the network.
-
- - Latency on subsequent requests is reduced since there is no time
- spent in TCP's connection opening handshake.
-
- - HTTP can evolve more gracefully, since errors can be reported
- without the penalty of closing the TCP connection. Clients using
- future versions of HTTP might optimistically try a new feature,
- but if communicating with an older server, retry with old
- semantics after an error is reported.
-
- HTTP implementations SHOULD implement persistent connections.
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 44]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-8.1.2 Overall Operation
-
- A significant difference between HTTP/1.1 and earlier versions of
- HTTP is that persistent connections are the default behavior of any
- HTTP connection. That is, unless otherwise indicated, the client
- SHOULD assume that the server will maintain a persistent connection,
- even after error responses from the server.
-
- Persistent connections provide a mechanism by which a client and a
- server can signal the close of a TCP connection. This signaling takes
- place using the Connection header field (section 14.10). Once a close
- has been signaled, the client MUST NOT send any more requests on that
- connection.
-
-8.1.2.1 Negotiation
-
- An HTTP/1.1 server MAY assume that a HTTP/1.1 client intends to
- maintain a persistent connection unless a Connection header including
- the connection-token "close" was sent in the request. If the server
- chooses to close the connection immediately after sending the
- response, it SHOULD send a Connection header including the
- connection-token close.
-
- An HTTP/1.1 client MAY expect a connection to remain open, but would
- decide to keep it open based on whether the response from a server
- contains a Connection header with the connection-token close. In case
- the client does not want to maintain a connection for more than that
- request, it SHOULD send a Connection header including the
- connection-token close.
-
- If either the client or the server sends the close token in the
- Connection header, that request becomes the last one for the
- connection.
-
- Clients and servers SHOULD NOT assume that a persistent connection is
- maintained for HTTP versions less than 1.1 unless it is explicitly
- signaled. See section 19.6.2 for more information on backward
- compatibility with HTTP/1.0 clients.
-
- In order to remain persistent, all messages on the connection MUST
- have a self-defined message length (i.e., one not defined by closure
- of the connection), as described in section 4.4.
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 45]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-8.1.2.2 Pipelining
-
- A client that supports persistent connections MAY "pipeline" its
- requests (i.e., send multiple requests without waiting for each
- response). A server MUST send its responses to those requests in the
- same order that the requests were received.
-
- Clients which assume persistent connections and pipeline immediately
- after connection establishment SHOULD be prepared to retry their
- connection if the first pipelined attempt fails. If a client does
- such a retry, it MUST NOT pipeline before it knows the connection is
- persistent. Clients MUST also be prepared to resend their requests if
- the server closes the connection before sending all of the
- corresponding responses.
-
- Clients SHOULD NOT pipeline requests using non-idempotent methods or
- non-idempotent sequences of methods (see section 9.1.2). Otherwise, a
- premature termination of the transport connection could lead to
- indeterminate results. A client wishing to send a non-idempotent
- request SHOULD wait to send that request until it has received the
- response status for the previous request.
-
-8.1.3 Proxy Servers
-
- It is especially important that proxies correctly implement the
- properties of the Connection header field as specified in section
- 14.10.
-
- The proxy server MUST signal persistent connections separately with
- its clients and the origin servers (or other proxy servers) that it
- connects to. Each persistent connection applies to only one transport
- link.
-
- A proxy server MUST NOT establish a HTTP/1.1 persistent connection
- with an HTTP/1.0 client (but see RFC 2068 [33] for information and
- discussion of the problems with the Keep-Alive header implemented by
- many HTTP/1.0 clients).
-
-8.1.4 Practical Considerations
-
- Servers will usually have some time-out value beyond which they will
- no longer maintain an inactive connection. Proxy servers might make
- this a higher value since it is likely that the client will be making
- more connections through the same server. The use of persistent
- connections places no requirements on the length (or existence) of
- this time-out for either the client or the server.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 46]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- When a client or server wishes to time-out it SHOULD issue a graceful
- close on the transport connection. Clients and servers SHOULD both
- constantly watch for the other side of the transport close, and
- respond to it as appropriate. If a client or server does not detect
- the other side's close promptly it could cause unnecessary resource
- drain on the network.
-
- A client, server, or proxy MAY close the transport connection at any
- time. For example, a client might have started to send a new request
- at the same time that the server has decided to close the "idle"
- connection. From the server's point of view, the connection is being
- closed while it was idle, but from the client's point of view, a
- request is in progress.
-
- This means that clients, servers, and proxies MUST be able to recover
- from asynchronous close events. Client software SHOULD reopen the
- transport connection and retransmit the aborted sequence of requests
- without user interaction so long as the request sequence is
- idempotent (see section 9.1.2). Non-idempotent methods or sequences
- MUST NOT be automatically retried, although user agents MAY offer a
- human operator the choice of retrying the request(s). Confirmation by
- user-agent software with semantic understanding of the application
- MAY substitute for user confirmation. The automatic retry SHOULD NOT
- be repeated if the second sequence of requests fails.
-
- Servers SHOULD always respond to at least one request per connection,
- if at all possible. Servers SHOULD NOT close a connection in the
- middle of transmitting a response, unless a network or client failure
- is suspected.
-
- Clients that use persistent connections SHOULD limit the number of
- simultaneous connections that they maintain to a given server. A
- single-user client SHOULD NOT maintain more than 2 connections with
- any server or proxy. A proxy SHOULD use up to 2*N connections to
- another server or proxy, where N is the number of simultaneously
- active users. These guidelines are intended to improve HTTP response
- times and avoid congestion.
-
-8.2 Message Transmission Requirements
-
-8.2.1 Persistent Connections and Flow Control
-
- HTTP/1.1 servers SHOULD maintain persistent connections and use TCP's
- flow control mechanisms to resolve temporary overloads, rather than
- terminating connections with the expectation that clients will retry.
- The latter technique can exacerbate network congestion.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 47]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-8.2.2 Monitoring Connections for Error Status Messages
-
- An HTTP/1.1 (or later) client sending a message-body SHOULD monitor
- the network connection for an error status while it is transmitting
- the request. If the client sees an error status, it SHOULD
- immediately cease transmitting the body. If the body is being sent
- using a "chunked" encoding (section 3.6), a zero length chunk and
- empty trailer MAY be used to prematurely mark the end of the message.
- If the body was preceded by a Content-Length header, the client MUST
- close the connection.
-
-8.2.3 Use of the 100 (Continue) Status
-
- The purpose of the 100 (Continue) status (see section 10.1.1) is to
- allow a client that is sending a request message with a request body
- to determine if the origin server is willing to accept the request
- (based on the request headers) before the client sends the request
- body. In some cases, it might either be inappropriate or highly
- inefficient for the client to send the body if the server will reject
- the message without looking at the body.
-
- Requirements for HTTP/1.1 clients:
-
- - If a client will wait for a 100 (Continue) response before
- sending the request body, it MUST send an Expect request-header
- field (section 14.20) with the "100-continue" expectation.
-
- - A client MUST NOT send an Expect request-header field (section
- 14.20) with the "100-continue" expectation if it does not intend
- to send a request body.
-
- Because of the presence of older implementations, the protocol allows
- ambiguous situations in which a client may send "Expect: 100-
- continue" without receiving either a 417 (Expectation Failed) status
- or a 100 (Continue) status. Therefore, when a client sends this
- header field to an origin server (possibly via a proxy) from which it
- has never seen a 100 (Continue) status, the client SHOULD NOT wait
- for an indefinite period before sending the request body.
-
- Requirements for HTTP/1.1 origin servers:
-
- - Upon receiving a request which includes an Expect request-header
- field with the "100-continue" expectation, an origin server MUST
- either respond with 100 (Continue) status and continue to read
- from the input stream, or respond with a final status code. The
- origin server MUST NOT wait for the request body before sending
- the 100 (Continue) response. If it responds with a final status
- code, it MAY close the transport connection or it MAY continue
-
-
-
-Fielding, et al. Standards Track [Page 48]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- to read and discard the rest of the request. It MUST NOT
- perform the requested method if it returns a final status code.
-
- - An origin server SHOULD NOT send a 100 (Continue) response if
- the request message does not include an Expect request-header
- field with the "100-continue" expectation, and MUST NOT send a
- 100 (Continue) response if such a request comes from an HTTP/1.0
- (or earlier) client. There is an exception to this rule: for
- compatibility with RFC 2068, a server MAY send a 100 (Continue)
- status in response to an HTTP/1.1 PUT or POST request that does
- not include an Expect request-header field with the "100-
- continue" expectation. This exception, the purpose of which is
- to minimize any client processing delays associated with an
- undeclared wait for 100 (Continue) status, applies only to
- HTTP/1.1 requests, and not to requests with any other HTTP-
- version value.
-
- - An origin server MAY omit a 100 (Continue) response if it has
- already received some or all of the request body for the
- corresponding request.
-
- - An origin server that sends a 100 (Continue) response MUST
- ultimately send a final status code, once the request body is
- received and processed, unless it terminates the transport
- connection prematurely.
-
- - If an origin server receives a request that does not include an
- Expect request-header field with the "100-continue" expectation,
- the request includes a request body, and the server responds
- with a final status code before reading the entire request body
- from the transport connection, then the server SHOULD NOT close
- the transport connection until it has read the entire request,
- or until the client closes the connection. Otherwise, the client
- might not reliably receive the response message. However, this
- requirement is not be construed as preventing a server from
- defending itself against denial-of-service attacks, or from
- badly broken client implementations.
-
- Requirements for HTTP/1.1 proxies:
-
- - If a proxy receives a request that includes an Expect request-
- header field with the "100-continue" expectation, and the proxy
- either knows that the next-hop server complies with HTTP/1.1 or
- higher, or does not know the HTTP version of the next-hop
- server, it MUST forward the request, including the Expect header
- field.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 49]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- - If the proxy knows that the version of the next-hop server is
- HTTP/1.0 or lower, it MUST NOT forward the request, and it MUST
- respond with a 417 (Expectation Failed) status.
-
- - Proxies SHOULD maintain a cache recording the HTTP version
- numbers received from recently-referenced next-hop servers.
-
- - A proxy MUST NOT forward a 100 (Continue) response if the
- request message was received from an HTTP/1.0 (or earlier)
- client and did not include an Expect request-header field with
- the "100-continue" expectation. This requirement overrides the
- general rule for forwarding of 1xx responses (see section 10.1).
-
-8.2.4 Client Behavior if Server Prematurely Closes Connection
-
- If an HTTP/1.1 client sends a request which includes a request body,
- but which does not include an Expect request-header field with the
- "100-continue" expectation, and if the client is not directly
- connected to an HTTP/1.1 origin server, and if the client sees the
- connection close before receiving any status from the server, the
- client SHOULD retry the request. If the client does retry this
- request, it MAY use the following "binary exponential backoff"
- algorithm to be assured of obtaining a reliable response:
-
- 1. Initiate a new connection to the server
-
- 2. Transmit the request-headers
-
- 3. Initialize a variable R to the estimated round-trip time to the
- server (e.g., based on the time it took to establish the
- connection), or to a constant value of 5 seconds if the round-
- trip time is not available.
-
- 4. Compute T = R * (2**N), where N is the number of previous
- retries of this request.
-
- 5. Wait either for an error response from the server, or for T
- seconds (whichever comes first)
-
- 6. If no error response is received, after T seconds transmit the
- body of the request.
-
- 7. If client sees that the connection is closed prematurely,
- repeat from step 1 until the request is accepted, an error
- response is received, or the user becomes impatient and
- terminates the retry process.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 50]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- If at any point an error status is received, the client
-
- - SHOULD NOT continue and
-
- - SHOULD close the connection if it has not completed sending the
- request message.
-
-9 Method Definitions
-
- The set of common methods for HTTP/1.1 is defined below. Although
- this set can be expanded, additional methods cannot be assumed to
- share the same semantics for separately extended clients and servers.
-
- The Host request-header field (section 14.23) MUST accompany all
- HTTP/1.1 requests.
-
-9.1 Safe and Idempotent Methods
-
-9.1.1 Safe Methods
-
- Implementors should be aware that the software represents the user in
- their interactions over the Internet, and should be careful to allow
- the user to be aware of any actions they might take which may have an
- unexpected significance to themselves or others.
-
- In particular, the convention has been established that the GET and
- HEAD methods SHOULD NOT have the significance of taking an action
- other than retrieval. These methods ought to be considered "safe".
- This allows user agents to represent other methods, such as POST, PUT
- and DELETE, in a special way, so that the user is made aware of the
- fact that a possibly unsafe action is being requested.
-
- Naturally, it is not possible to ensure that the server does not
- generate side-effects as a result of performing a GET request; in
- fact, some dynamic resources consider that a feature. The important
- distinction here is that the user did not request the side-effects,
- so therefore cannot be held accountable for them.
-
-9.1.2 Idempotent Methods
-
- Methods can also have the property of "idempotence" in that (aside
- from error or expiration issues) the side-effects of N > 0 identical
- requests is the same as for a single request. The methods GET, HEAD,
- PUT and DELETE share this property. Also, the methods OPTIONS and
- TRACE SHOULD NOT have side effects, and so are inherently idempotent.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 51]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- However, it is possible that a sequence of several requests is non-
- idempotent, even if all of the methods executed in that sequence are
- idempotent. (A sequence is idempotent if a single execution of the
- entire sequence always yields a result that is not changed by a
- reexecution of all, or part, of that sequence.) For example, a
- sequence is non-idempotent if its result depends on a value that is
- later modified in the same sequence.
-
- A sequence that never has side effects is idempotent, by definition
- (provided that no concurrent operations are being executed on the
- same set of resources).
-
-9.2 OPTIONS
-
- The OPTIONS method represents a request for information about the
- communication options available on the request/response chain
- identified by the Request-URI. This method allows the client to
- determine the options and/or requirements associated with a resource,
- or the capabilities of a server, without implying a resource action
- or initiating a resource retrieval.
-
- Responses to this method are not cacheable.
-
- If the OPTIONS request includes an entity-body (as indicated by the
- presence of Content-Length or Transfer-Encoding), then the media type
- MUST be indicated by a Content-Type field. Although this
- specification does not define any use for such a body, future
- extensions to HTTP might use the OPTIONS body to make more detailed
- queries on the server. A server that does not support such an
- extension MAY discard the request body.
-
- If the Request-URI is an asterisk ("*"), the OPTIONS request is
- intended to apply to the server in general rather than to a specific
- resource. Since a server's communication options typically depend on
- the resource, the "*" request is only useful as a "ping" or "no-op"
- type of method; it does nothing beyond allowing the client to test
- the capabilities of the server. For example, this can be used to test
- a proxy for HTTP/1.1 compliance (or lack thereof).
-
- If the Request-URI is not an asterisk, the OPTIONS request applies
- only to the options that are available when communicating with that
- resource.
-
- A 200 response SHOULD include any header fields that indicate
- optional features implemented by the server and applicable to that
- resource (e.g., Allow), possibly including extensions not defined by
- this specification. The response body, if any, SHOULD also include
- information about the communication options. The format for such a
-
-
-
-Fielding, et al. Standards Track [Page 52]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- body is not defined by this specification, but might be defined by
- future extensions to HTTP. Content negotiation MAY be used to select
- the appropriate response format. If no response body is included, the
- response MUST include a Content-Length field with a field-value of
- "0".
-
- The Max-Forwards request-header field MAY be used to target a
- specific proxy in the request chain. When a proxy receives an OPTIONS
- request on an absoluteURI for which request forwarding is permitted,
- the proxy MUST check for a Max-Forwards field. If the Max-Forwards
- field-value is zero ("0"), the proxy MUST NOT forward the message;
- instead, the proxy SHOULD respond with its own communication options.
- If the Max-Forwards field-value is an integer greater than zero, the
- proxy MUST decrement the field-value when it forwards the request. If
- no Max-Forwards field is present in the request, then the forwarded
- request MUST NOT include a Max-Forwards field.
-
-9.3 GET
-
- The GET method means retrieve whatever information (in the form of an
- entity) is identified by the Request-URI. If the Request-URI refers
- to a data-producing process, it is the produced data which shall be
- returned as the entity in the response and not the source text of the
- process, unless that text happens to be the output of the process.
-
- The semantics of the GET method change to a "conditional GET" if the
- request message includes an If-Modified-Since, If-Unmodified-Since,
- If-Match, If-None-Match, or If-Range header field. A conditional GET
- method requests that the entity be transferred only under the
- circumstances described by the conditional header field(s). The
- conditional GET method is intended to reduce unnecessary network
- usage by allowing cached entities to be refreshed without requiring
- multiple requests or transferring data already held by the client.
-
- The semantics of the GET method change to a "partial GET" if the
- request message includes a Range header field. A partial GET requests
- that only part of the entity be transferred, as described in section
- 14.35. The partial GET method is intended to reduce unnecessary
- network usage by allowing partially-retrieved entities to be
- completed without transferring data already held by the client.
-
- The response to a GET request is cacheable if and only if it meets
- the requirements for HTTP caching described in section 13.
-
- See section 15.1.3 for security considerations when used for forms.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 53]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-9.4 HEAD
-
- The HEAD method is identical to GET except that the server MUST NOT
- return a message-body in the response. The metainformation contained
- in the HTTP headers in response to a HEAD request SHOULD be identical
- to the information sent in response to a GET request. This method can
- be used for obtaining metainformation about the entity implied by the
- request without transferring the entity-body itself. This method is
- often used for testing hypertext links for validity, accessibility,
- and recent modification.
-
- The response to a HEAD request MAY be cacheable in the sense that the
- information contained in the response MAY be used to update a
- previously cached entity from that resource. If the new field values
- indicate that the cached entity differs from the current entity (as
- would be indicated by a change in Content-Length, Content-MD5, ETag
- or Last-Modified), then the cache MUST treat the cache entry as
- stale.
-
-9.5 POST
-
- The POST method is used to request that the origin server accept the
- entity enclosed in the request as a new subordinate of the resource
- identified by the Request-URI in the Request-Line. POST is designed
- to allow a uniform method to cover the following functions:
-
- - Annotation of existing resources;
-
- - Posting a message to a bulletin board, newsgroup, mailing list,
- or similar group of articles;
-
- - Providing a block of data, such as the result of submitting a
- form, to a data-handling process;
-
- - Extending a database through an append operation.
-
- The actual function performed by the POST method is determined by the
- server and is usually dependent on the Request-URI. The posted entity
- is subordinate to that URI in the same way that a file is subordinate
- to a directory containing it, a news article is subordinate to a
- newsgroup to which it is posted, or a record is subordinate to a
- database.
-
- The action performed by the POST method might not result in a
- resource that can be identified by a URI. In this case, either 200
- (OK) or 204 (No Content) is the appropriate response status,
- depending on whether or not the response includes an entity that
- describes the result.
-
-
-
-Fielding, et al. Standards Track [Page 54]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- If a resource has been created on the origin server, the response
- SHOULD be 201 (Created) and contain an entity which describes the
- status of the request and refers to the new resource, and a Location
- header (see section 14.30).
-
- Responses to this method are not cacheable, unless the response
- includes appropriate Cache-Control or Expires header fields. However,
- the 303 (See Other) response can be used to direct the user agent to
- retrieve a cacheable resource.
-
- POST requests MUST obey the message transmission requirements set out
- in section 8.2.
-
- See section 15.1.3 for security considerations.
-
-9.6 PUT
-
- The PUT method requests that the enclosed entity be stored under the
- supplied Request-URI. If the Request-URI refers to an already
- existing resource, the enclosed entity SHOULD be considered as a
- modified version of the one residing on the origin server. If the
- Request-URI does not point to an existing resource, and that URI is
- capable of being defined as a new resource by the requesting user
- agent, the origin server can create the resource with that URI. If a
- new resource is created, the origin server MUST inform the user agent
- via the 201 (Created) response. If an existing resource is modified,
- either the 200 (OK) or 204 (No Content) response codes SHOULD be sent
- to indicate successful completion of the request. If the resource
- could not be created or modified with the Request-URI, an appropriate
- error response SHOULD be given that reflects the nature of the
- problem. The recipient of the entity MUST NOT ignore any Content-*
- (e.g. Content-Range) headers that it does not understand or implement
- and MUST return a 501 (Not Implemented) response in such cases.
-
- If the request passes through a cache and the Request-URI identifies
- one or more currently cached entities, those entries SHOULD be
- treated as stale. Responses to this method are not cacheable.
-
- The fundamental difference between the POST and PUT requests is
- reflected in the different meaning of the Request-URI. The URI in a
- POST request identifies the resource that will handle the enclosed
- entity. That resource might be a data-accepting process, a gateway to
- some other protocol, or a separate entity that accepts annotations.
- In contrast, the URI in a PUT request identifies the entity enclosed
- with the request -- the user agent knows what URI is intended and the
- server MUST NOT attempt to apply the request to some other resource.
- If the server desires that the request be applied to a different URI,
-
-
-
-
-Fielding, et al. Standards Track [Page 55]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- it MUST send a 301 (Moved Permanently) response; the user agent MAY
- then make its own decision regarding whether or not to redirect the
- request.
-
- A single resource MAY be identified by many different URIs. For
- example, an article might have a URI for identifying "the current
- version" which is separate from the URI identifying each particular
- version. In this case, a PUT request on a general URI might result in
- several other URIs being defined by the origin server.
-
- HTTP/1.1 does not define how a PUT method affects the state of an
- origin server.
-
- PUT requests MUST obey the message transmission requirements set out
- in section 8.2.
-
- Unless otherwise specified for a particular entity-header, the
- entity-headers in the PUT request SHOULD be applied to the resource
- created or modified by the PUT.
-
-9.7 DELETE
-
- The DELETE method requests that the origin server delete the resource
- identified by the Request-URI. This method MAY be overridden by human
- intervention (or other means) on the origin server. The client cannot
- be guaranteed that the operation has been carried out, even if the
- status code returned from the origin server indicates that the action
- has been completed successfully. However, the server SHOULD NOT
- indicate success unless, at the time the response is given, it
- intends to delete the resource or move it to an inaccessible
- location.
-
- A successful response SHOULD be 200 (OK) if the response includes an
- entity describing the status, 202 (Accepted) if the action has not
- yet been enacted, or 204 (No Content) if the action has been enacted
- but the response does not include an entity.
-
- If the request passes through a cache and the Request-URI identifies
- one or more currently cached entities, those entries SHOULD be
- treated as stale. Responses to this method are not cacheable.
-
-9.8 TRACE
-
- The TRACE method is used to invoke a remote, application-layer loop-
- back of the request message. The final recipient of the request
- SHOULD reflect the message received back to the client as the
- entity-body of a 200 (OK) response. The final recipient is either the
-
-
-
-
-Fielding, et al. Standards Track [Page 56]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- origin server or the first proxy or gateway to receive a Max-Forwards
- value of zero (0) in the request (see section 14.31). A TRACE request
- MUST NOT include an entity.
-
- TRACE allows the client to see what is being received at the other
- end of the request chain and use that data for testing or diagnostic
- information. The value of the Via header field (section 14.45) is of
- particular interest, since it acts as a trace of the request chain.
- Use of the Max-Forwards header field allows the client to limit the
- length of the request chain, which is useful for testing a chain of
- proxies forwarding messages in an infinite loop.
-
- If the request is valid, the response SHOULD contain the entire
- request message in the entity-body, with a Content-Type of
- "message/http". Responses to this method MUST NOT be cached.
-
-9.9 CONNECT
-
- This specification reserves the method name CONNECT for use with a
- proxy that can dynamically switch to being a tunnel (e.g. SSL
- tunneling [44]).
-
-10 Status Code Definitions
-
- Each Status-Code is described below, including a description of which
- method(s) it can follow and any metainformation required in the
- response.
-
-10.1 Informational 1xx
-
- This class of status code indicates a provisional response,
- consisting only of the Status-Line and optional headers, and is
- terminated by an empty line. There are no required headers for this
- class of status code. Since HTTP/1.0 did not define any 1xx status
- codes, servers MUST NOT send a 1xx response to an HTTP/1.0 client
- except under experimental conditions.
-
- A client MUST be prepared to accept one or more 1xx status responses
- prior to a regular response, even if the client does not expect a 100
- (Continue) status message. Unexpected 1xx status responses MAY be
- ignored by a user agent.
-
- Proxies MUST forward 1xx responses, unless the connection between the
- proxy and its client has been closed, or unless the proxy itself
- requested the generation of the 1xx response. (For example, if a
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 57]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- proxy adds a "Expect: 100-continue" field when it forwards a request,
- then it need not forward the corresponding 100 (Continue)
- response(s).)
-
-10.1.1 100 Continue
-
- The client SHOULD continue with its request. This interim response is
- used to inform the client that the initial part of the request has
- been received and has not yet been rejected by the server. The client
- SHOULD continue by sending the remainder of the request or, if the
- request has already been completed, ignore this response. The server
- MUST send a final response after the request has been completed. See
- section 8.2.3 for detailed discussion of the use and handling of this
- status code.
-
-10.1.2 101 Switching Protocols
-
- The server understands and is willing to comply with the client's
- request, via the Upgrade message header field (section 14.42), for a
- change in the application protocol being used on this connection. The
- server will switch protocols to those defined by the response's
- Upgrade header field immediately after the empty line which
- terminates the 101 response.
-
- The protocol SHOULD be switched only when it is advantageous to do
- so. For example, switching to a newer version of HTTP is advantageous
- over older versions, and switching to a real-time, synchronous
- protocol might be advantageous when delivering resources that use
- such features.
-
-10.2 Successful 2xx
-
- This class of status code indicates that the client's request was
- successfully received, understood, and accepted.
-
-10.2.1 200 OK
-
- The request has succeeded. The information returned with the response
- is dependent on the method used in the request, for example:
-
- GET an entity corresponding to the requested resource is sent in
- the response;
-
- HEAD the entity-header fields corresponding to the requested
- resource are sent in the response without any message-body;
-
- POST an entity describing or containing the result of the action;
-
-
-
-
-Fielding, et al. Standards Track [Page 58]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- TRACE an entity containing the request message as received by the
- end server.
-
-10.2.2 201 Created
-
- The request has been fulfilled and resulted in a new resource being
- created. The newly created resource can be referenced by the URI(s)
- returned in the entity of the response, with the most specific URI
- for the resource given by a Location header field. The response
- SHOULD include an entity containing a list of resource
- characteristics and location(s) from which the user or user agent can
- choose the one most appropriate. The entity format is specified by
- the media type given in the Content-Type header field. The origin
- server MUST create the resource before returning the 201 status code.
- If the action cannot be carried out immediately, the server SHOULD
- respond with 202 (Accepted) response instead.
-
- A 201 response MAY contain an ETag response header field indicating
- the current value of the entity tag for the requested variant just
- created, see section 14.19.
-
-10.2.3 202 Accepted
-
- The request has been accepted for processing, but the processing has
- not been completed. The request might or might not eventually be
- acted upon, as it might be disallowed when processing actually takes
- place. There is no facility for re-sending a status code from an
- asynchronous operation such as this.
-
- The 202 response is intentionally non-committal. Its purpose is to
- allow a server to accept a request for some other process (perhaps a
- batch-oriented process that is only run once per day) without
- requiring that the user agent's connection to the server persist
- until the process is completed. The entity returned with this
- response SHOULD include an indication of the request's current status
- and either a pointer to a status monitor or some estimate of when the
- user can expect the request to be fulfilled.
-
-10.2.4 203 Non-Authoritative Information
-
- The returned metainformation in the entity-header is not the
- definitive set as available from the origin server, but is gathered
- from a local or a third-party copy. The set presented MAY be a subset
- or superset of the original version. For example, including local
- annotation information about the resource might result in a superset
- of the metainformation known by the origin server. Use of this
- response code is not required and is only appropriate when the
- response would otherwise be 200 (OK).
-
-
-
-Fielding, et al. Standards Track [Page 59]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-10.2.5 204 No Content
-
- The server has fulfilled the request but does not need to return an
- entity-body, and might want to return updated metainformation. The
- response MAY include new or updated metainformation in the form of
- entity-headers, which if present SHOULD be associated with the
- requested variant.
-
- If the client is a user agent, it SHOULD NOT change its document view
- from that which caused the request to be sent. This response is
- primarily intended to allow input for actions to take place without
- causing a change to the user agent's active document view, although
- any new or updated metainformation SHOULD be applied to the document
- currently in the user agent's active view.
-
- The 204 response MUST NOT include a message-body, and thus is always
- terminated by the first empty line after the header fields.
-
-10.2.6 205 Reset Content
-
- The server has fulfilled the request and the user agent SHOULD reset
- the document view which caused the request to be sent. This response
- is primarily intended to allow input for actions to take place via
- user input, followed by a clearing of the form in which the input is
- given so that the user can easily initiate another input action. The
- response MUST NOT include an entity.
-
-10.2.7 206 Partial Content
-
- The server has fulfilled the partial GET request for the resource.
- The request MUST have included a Range header field (section 14.35)
- indicating the desired range, and MAY have included an If-Range
- header field (section 14.27) to make the request conditional.
-
- The response MUST include the following header fields:
-
- - Either a Content-Range header field (section 14.16) indicating
- the range included with this response, or a multipart/byteranges
- Content-Type including Content-Range fields for each part. If a
- Content-Length header field is present in the response, its
- value MUST match the actual number of OCTETs transmitted in the
- message-body.
-
- - Date
-
- - ETag and/or Content-Location, if the header would have been sent
- in a 200 response to the same request
-
-
-
-
-Fielding, et al. Standards Track [Page 60]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- - Expires, Cache-Control, and/or Vary, if the field-value might
- differ from that sent in any previous response for the same
- variant
-
- If the 206 response is the result of an If-Range request that used a
- strong cache validator (see section 13.3.3), the response SHOULD NOT
- include other entity-headers. If the response is the result of an
- If-Range request that used a weak validator, the response MUST NOT
- include other entity-headers; this prevents inconsistencies between
- cached entity-bodies and updated headers. Otherwise, the response
- MUST include all of the entity-headers that would have been returned
- with a 200 (OK) response to the same request.
-
- A cache MUST NOT combine a 206 response with other previously cached
- content if the ETag or Last-Modified headers do not match exactly,
- see 13.5.4.
-
- A cache that does not support the Range and Content-Range headers
- MUST NOT cache 206 (Partial) responses.
-
-10.3 Redirection 3xx
-
- This class of status code indicates that further action needs to be
- taken by the user agent in order to fulfill the request. The action
- required MAY be carried out by the user agent without interaction
- with the user if and only if the method used in the second request is
- GET or HEAD. A client SHOULD detect infinite redirection loops, since
- such loops generate network traffic for each redirection.
-
- Note: previous versions of this specification recommended a
- maximum of five redirections. Content developers should be aware
- that there might be clients that implement such a fixed
- limitation.
-
-10.3.1 300 Multiple Choices
-
- The requested resource corresponds to any one of a set of
- representations, each with its own specific location, and agent-
- driven negotiation information (section 12) is being provided so that
- the user (or user agent) can select a preferred representation and
- redirect its request to that location.
-
- Unless it was a HEAD request, the response SHOULD include an entity
- containing a list of resource characteristics and location(s) from
- which the user or user agent can choose the one most appropriate. The
- entity format is specified by the media type given in the Content-
- Type header field. Depending upon the format and the capabilities of
-
-
-
-
-Fielding, et al. Standards Track [Page 61]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- the user agent, selection of the most appropriate choice MAY be
- performed automatically. However, this specification does not define
- any standard for such automatic selection.
-
- If the server has a preferred choice of representation, it SHOULD
- include the specific URI for that representation in the Location
- field; user agents MAY use the Location field value for automatic
- redirection. This response is cacheable unless indicated otherwise.
-
-10.3.2 301 Moved Permanently
-
- The requested resource has been assigned a new permanent URI and any
- future references to this resource SHOULD use one of the returned
- URIs. Clients with link editing capabilities ought to automatically
- re-link references to the Request-URI to one or more of the new
- references returned by the server, where possible. This response is
- cacheable unless indicated otherwise.
-
- The new permanent URI SHOULD be given by the Location field in the
- response. Unless the request method was HEAD, the entity of the
- response SHOULD contain a short hypertext note with a hyperlink to
- the new URI(s).
-
- If the 301 status code is received in response to a request other
- than GET or HEAD, the user agent MUST NOT automatically redirect the
- request unless it can be confirmed by the user, since this might
- change the conditions under which the request was issued.
-
- Note: When automatically redirecting a POST request after
- receiving a 301 status code, some existing HTTP/1.0 user agents
- will erroneously change it into a GET request.
-
-10.3.3 302 Found
-
- The requested resource resides temporarily under a different URI.
- Since the redirection might be altered on occasion, the client SHOULD
- continue to use the Request-URI for future requests. This response
- is only cacheable if indicated by a Cache-Control or Expires header
- field.
-
- The temporary URI SHOULD be given by the Location field in the
- response. Unless the request method was HEAD, the entity of the
- response SHOULD contain a short hypertext note with a hyperlink to
- the new URI(s).
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 62]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- If the 302 status code is received in response to a request other
- than GET or HEAD, the user agent MUST NOT automatically redirect the
- request unless it can be confirmed by the user, since this might
- change the conditions under which the request was issued.
-
- Note: RFC 1945 and RFC 2068 specify that the client is not allowed
- to change the method on the redirected request. However, most
- existing user agent implementations treat 302 as if it were a 303
- response, performing a GET on the Location field-value regardless
- of the original request method. The status codes 303 and 307 have
- been added for servers that wish to make unambiguously clear which
- kind of reaction is expected of the client.
-
-10.3.4 303 See Other
-
- The response to the request can be found under a different URI and
- SHOULD be retrieved using a GET method on that resource. This method
- exists primarily to allow the output of a POST-activated script to
- redirect the user agent to a selected resource. The new URI is not a
- substitute reference for the originally requested resource. The 303
- response MUST NOT be cached, but the response to the second
- (redirected) request might be cacheable.
-
- The different URI SHOULD be given by the Location field in the
- response. Unless the request method was HEAD, the entity of the
- response SHOULD contain a short hypertext note with a hyperlink to
- the new URI(s).
-
- Note: Many pre-HTTP/1.1 user agents do not understand the 303
- status. When interoperability with such clients is a concern, the
- 302 status code may be used instead, since most user agents react
- to a 302 response as described here for 303.
-
-10.3.5 304 Not Modified
-
- If the client has performed a conditional GET request and access is
- allowed, but the document has not been modified, the server SHOULD
- respond with this status code. The 304 response MUST NOT contain a
- message-body, and thus is always terminated by the first empty line
- after the header fields.
-
- The response MUST include the following header fields:
-
- - Date, unless its omission is required by section 14.18.1
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 63]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- If a clockless origin server obeys these rules, and proxies and
- clients add their own Date to any response received without one (as
- already specified by [RFC 2068], section 14.19), caches will operate
- correctly.
-
- - ETag and/or Content-Location, if the header would have been sent
- in a 200 response to the same request
-
- - Expires, Cache-Control, and/or Vary, if the field-value might
- differ from that sent in any previous response for the same
- variant
-
- If the conditional GET used a strong cache validator (see section
- 13.3.3), the response SHOULD NOT include other entity-headers.
- Otherwise (i.e., the conditional GET used a weak validator), the
- response MUST NOT include other entity-headers; this prevents
- inconsistencies between cached entity-bodies and updated headers.
-
- If a 304 response indicates an entity not currently cached, then the
- cache MUST disregard the response and repeat the request without the
- conditional.
-
- If a cache uses a received 304 response to update a cache entry, the
- cache MUST update the entry to reflect any new field values given in
- the response.
-
-10.3.6 305 Use Proxy
-
- The requested resource MUST be accessed through the proxy given by
- the Location field. The Location field gives the URI of the proxy.
- The recipient is expected to repeat this single request via the
- proxy. 305 responses MUST only be generated by origin servers.
-
- Note: RFC 2068 was not clear that 305 was intended to redirect a
- single request, and to be generated by origin servers only. Not
- observing these limitations has significant security consequences.
-
-10.3.7 306 (Unused)
-
- The 306 status code was used in a previous version of the
- specification, is no longer used, and the code is reserved.
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 64]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-10.3.8 307 Temporary Redirect
-
- The requested resource resides temporarily under a different URI.
- Since the redirection MAY be altered on occasion, the client SHOULD
- continue to use the Request-URI for future requests. This response
- is only cacheable if indicated by a Cache-Control or Expires header
- field.
-
- The temporary URI SHOULD be given by the Location field in the
- response. Unless the request method was HEAD, the entity of the
- response SHOULD contain a short hypertext note with a hyperlink to
- the new URI(s) , since many pre-HTTP/1.1 user agents do not
- understand the 307 status. Therefore, the note SHOULD contain the
- information necessary for a user to repeat the original request on
- the new URI.
-
- If the 307 status code is received in response to a request other
- than GET or HEAD, the user agent MUST NOT automatically redirect the
- request unless it can be confirmed by the user, since this might
- change the conditions under which the request was issued.
-
-10.4 Client Error 4xx
-
- The 4xx class of status code is intended for cases in which the
- client seems to have erred. Except when responding to a HEAD request,
- the server SHOULD include an entity containing an explanation of the
- error situation, and whether it is a temporary or permanent
- condition. These status codes are applicable to any request method.
- User agents SHOULD display any included entity to the user.
-
- If the client is sending data, a server implementation using TCP
- SHOULD be careful to ensure that the client acknowledges receipt of
- the packet(s) containing the response, before the server closes the
- input connection. If the client continues sending data to the server
- after the close, the server's TCP stack will send a reset packet to
- the client, which may erase the client's unacknowledged input buffers
- before they can be read and interpreted by the HTTP application.
-
-10.4.1 400 Bad Request
-
- The request could not be understood by the server due to malformed
- syntax. The client SHOULD NOT repeat the request without
- modifications.
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 65]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-10.4.2 401 Unauthorized
-
- The request requires user authentication. The response MUST include a
- WWW-Authenticate header field (section 14.47) containing a challenge
- applicable to the requested resource. The client MAY repeat the
- request with a suitable Authorization header field (section 14.8). If
- the request already included Authorization credentials, then the 401
- response indicates that authorization has been refused for those
- credentials. If the 401 response contains the same challenge as the
- prior response, and the user agent has already attempted
- authentication at least once, then the user SHOULD be presented the
- entity that was given in the response, since that entity might
- include relevant diagnostic information. HTTP access authentication
- is explained in "HTTP Authentication: Basic and Digest Access
- Authentication" [43].
-
-10.4.3 402 Payment Required
-
- This code is reserved for future use.
-
-10.4.4 403 Forbidden
-
- The server understood the request, but is refusing to fulfill it.
- Authorization will not help and the request SHOULD NOT be repeated.
- If the request method was not HEAD and the server wishes to make
- public why the request has not been fulfilled, it SHOULD describe the
- reason for the refusal in the entity. If the server does not wish to
- make this information available to the client, the status code 404
- (Not Found) can be used instead.
-
-10.4.5 404 Not Found
-
- The server has not found anything matching the Request-URI. No
- indication is given of whether the condition is temporary or
- permanent. The 410 (Gone) status code SHOULD be used if the server
- knows, through some internally configurable mechanism, that an old
- resource is permanently unavailable and has no forwarding address.
- This status code is commonly used when the server does not wish to
- reveal exactly why the request has been refused, or when no other
- response is applicable.
-
-10.4.6 405 Method Not Allowed
-
- The method specified in the Request-Line is not allowed for the
- resource identified by the Request-URI. The response MUST include an
- Allow header containing a list of valid methods for the requested
- resource.
-
-
-
-
-Fielding, et al. Standards Track [Page 66]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-10.4.7 406 Not Acceptable
-
- The resource identified by the request is only capable of generating
- response entities which have content characteristics not acceptable
- according to the accept headers sent in the request.
-
- Unless it was a HEAD request, the response SHOULD include an entity
- containing a list of available entity characteristics and location(s)
- from which the user or user agent can choose the one most
- appropriate. The entity format is specified by the media type given
- in the Content-Type header field. Depending upon the format and the
- capabilities of the user agent, selection of the most appropriate
- choice MAY be performed automatically. However, this specification
- does not define any standard for such automatic selection.
-
- Note: HTTP/1.1 servers are allowed to return responses which are
- not acceptable according to the accept headers sent in the
- request. In some cases, this may even be preferable to sending a
- 406 response. User agents are encouraged to inspect the headers of
- an incoming response to determine if it is acceptable.
-
- If the response could be unacceptable, a user agent SHOULD
- temporarily stop receipt of more data and query the user for a
- decision on further actions.
-
-10.4.8 407 Proxy Authentication Required
-
- This code is similar to 401 (Unauthorized), but indicates that the
- client must first authenticate itself with the proxy. The proxy MUST
- return a Proxy-Authenticate header field (section 14.33) containing a
- challenge applicable to the proxy for the requested resource. The
- client MAY repeat the request with a suitable Proxy-Authorization
- header field (section 14.34). HTTP access authentication is explained
- in "HTTP Authentication: Basic and Digest Access Authentication"
- [43].
-
-10.4.9 408 Request Timeout
-
- The client did not produce a request within the time that the server
- was prepared to wait. The client MAY repeat the request without
- modifications at any later time.
-
-10.4.10 409 Conflict
-
- The request could not be completed due to a conflict with the current
- state of the resource. This code is only allowed in situations where
- it is expected that the user might be able to resolve the conflict
- and resubmit the request. The response body SHOULD include enough
-
-
-
-Fielding, et al. Standards Track [Page 67]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- information for the user to recognize the source of the conflict.
- Ideally, the response entity would include enough information for the
- user or user agent to fix the problem; however, that might not be
- possible and is not required.
-
- Conflicts are most likely to occur in response to a PUT request. For
- example, if versioning were being used and the entity being PUT
- included changes to a resource which conflict with those made by an
- earlier (third-party) request, the server might use the 409 response
- to indicate that it can't complete the request. In this case, the
- response entity would likely contain a list of the differences
- between the two versions in a format defined by the response
- Content-Type.
-
-10.4.11 410 Gone
-
- The requested resource is no longer available at the server and no
- forwarding address is known. This condition is expected to be
- considered permanent. Clients with link editing capabilities SHOULD
- delete references to the Request-URI after user approval. If the
- server does not know, or has no facility to determine, whether or not
- the condition is permanent, the status code 404 (Not Found) SHOULD be
- used instead. This response is cacheable unless indicated otherwise.
-
- The 410 response is primarily intended to assist the task of web
- maintenance by notifying the recipient that the resource is
- intentionally unavailable and that the server owners desire that
- remote links to that resource be removed. Such an event is common for
- limited-time, promotional services and for resources belonging to
- individuals no longer working at the server's site. It is not
- necessary to mark all permanently unavailable resources as "gone" or
- to keep the mark for any length of time -- that is left to the
- discretion of the server owner.
-
-10.4.12 411 Length Required
-
- The server refuses to accept the request without a defined Content-
- Length. The client MAY repeat the request if it adds a valid
- Content-Length header field containing the length of the message-body
- in the request message.
-
-10.4.13 412 Precondition Failed
-
- The precondition given in one or more of the request-header fields
- evaluated to false when it was tested on the server. This response
- code allows the client to place preconditions on the current resource
- metainformation (header field data) and thus prevent the requested
- method from being applied to a resource other than the one intended.
-
-
-
-Fielding, et al. Standards Track [Page 68]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-10.4.14 413 Request Entity Too Large
-
- The server is refusing to process a request because the request
- entity is larger than the server is willing or able to process. The
- server MAY close the connection to prevent the client from continuing
- the request.
-
- If the condition is temporary, the server SHOULD include a Retry-
- After header field to indicate that it is temporary and after what
- time the client MAY try again.
-
-10.4.15 414 Request-URI Too Long
-
- The server is refusing to service the request because the Request-URI
- is longer than the server is willing to interpret. This rare
- condition is only likely to occur when a client has improperly
- converted a POST request to a GET request with long query
- information, when the client has descended into a URI "black hole" of
- redirection (e.g., a redirected URI prefix that points to a suffix of
- itself), or when the server is under attack by a client attempting to
- exploit security holes present in some servers using fixed-length
- buffers for reading or manipulating the Request-URI.
-
-10.4.16 415 Unsupported Media Type
-
- The server is refusing to service the request because the entity of
- the request is in a format not supported by the requested resource
- for the requested method.
-
-10.4.17 416 Requested Range Not Satisfiable
-
- A server SHOULD return a response with this status code if a request
- included a Range request-header field (section 14.35), and none of
- the range-specifier values in this field overlap the current extent
- of the selected resource, and the request did not include an If-Range
- request-header field. (For byte-ranges, this means that the first-
- byte-pos of all of the byte-range-spec values were greater than the
- current length of the selected resource.)
-
- When this status code is returned for a byte-range request, the
- response SHOULD include a Content-Range entity-header field
- specifying the current length of the selected resource (see section
- 14.16). This response MUST NOT use the multipart/byteranges content-
- type.
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 69]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-10.4.18 417 Expectation Failed
-
- The expectation given in an Expect request-header field (see section
- 14.20) could not be met by this server, or, if the server is a proxy,
- the server has unambiguous evidence that the request could not be met
- by the next-hop server.
-
-10.5 Server Error 5xx
-
- Response status codes beginning with the digit "5" indicate cases in
- which the server is aware that it has erred or is incapable of
- performing the request. Except when responding to a HEAD request, the
- server SHOULD include an entity containing an explanation of the
- error situation, and whether it is a temporary or permanent
- condition. User agents SHOULD display any included entity to the
- user. These response codes are applicable to any request method.
-
-10.5.1 500 Internal Server Error
-
- The server encountered an unexpected condition which prevented it
- from fulfilling the request.
-
-10.5.2 501 Not Implemented
-
- The server does not support the functionality required to fulfill the
- request. This is the appropriate response when the server does not
- recognize the request method and is not capable of supporting it for
- any resource.
-
-10.5.3 502 Bad Gateway
-
- The server, while acting as a gateway or proxy, received an invalid
- response from the upstream server it accessed in attempting to
- fulfill the request.
-
-10.5.4 503 Service Unavailable
-
- The server is currently unable to handle the request due to a
- temporary overloading or maintenance of the server. The implication
- is that this is a temporary condition which will be alleviated after
- some delay. If known, the length of the delay MAY be indicated in a
- Retry-After header. If no Retry-After is given, the client SHOULD
- handle the response as it would for a 500 response.
-
- Note: The existence of the 503 status code does not imply that a
- server must use it when becoming overloaded. Some servers may wish
- to simply refuse the connection.
-
-
-
-
-Fielding, et al. Standards Track [Page 70]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-10.5.5 504 Gateway Timeout
-
- The server, while acting as a gateway or proxy, did not receive a
- timely response from the upstream server specified by the URI (e.g.
- HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed
- to access in attempting to complete the request.
-
- Note: Note to implementors: some deployed proxies are known to
- return 400 or 500 when DNS lookups time out.
-
-10.5.6 505 HTTP Version Not Supported
-
- The server does not support, or refuses to support, the HTTP protocol
- version that was used in the request message. The server is
- indicating that it is unable or unwilling to complete the request
- using the same major version as the client, as described in section
- 3.1, other than with this error message. The response SHOULD contain
- an entity describing why that version is not supported and what other
- protocols are supported by that server.
-
-11 Access Authentication
-
- HTTP provides several OPTIONAL challenge-response authentication
- mechanisms which can be used by a server to challenge a client
- request and by a client to provide authentication information. The
- general framework for access authentication, and the specification of
- "basic" and "digest" authentication, are specified in "HTTP
- Authentication: Basic and Digest Access Authentication" [43]. This
- specification adopts the definitions of "challenge" and "credentials"
- from that specification.
-
-12 Content Negotiation
-
- Most HTTP responses include an entity which contains information for
- interpretation by a human user. Naturally, it is desirable to supply
- the user with the "best available" entity corresponding to the
- request. Unfortunately for servers and caches, not all users have the
- same preferences for what is "best," and not all user agents are
- equally capable of rendering all entity types. For that reason, HTTP
- has provisions for several mechanisms for "content negotiation" --
- the process of selecting the best representation for a given response
- when there are multiple representations available.
-
- Note: This is not called "format negotiation" because the
- alternate representations may be of the same media type, but use
- different capabilities of that type, be in different languages,
- etc.
-
-
-
-
-Fielding, et al. Standards Track [Page 71]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Any response containing an entity-body MAY be subject to negotiation,
- including error responses.
-
- There are two kinds of content negotiation which are possible in
- HTTP: server-driven and agent-driven negotiation. These two kinds of
- negotiation are orthogonal and thus may be used separately or in
- combination. One method of combination, referred to as transparent
- negotiation, occurs when a cache uses the agent-driven negotiation
- information provided by the origin server in order to provide
- server-driven negotiation for subsequent requests.
-
-12.1 Server-driven Negotiation
-
- If the selection of the best representation for a response is made by
- an algorithm located at the server, it is called server-driven
- negotiation. Selection is based on the available representations of
- the response (the dimensions over which it can vary; e.g. language,
- content-coding, etc.) and the contents of particular header fields in
- the request message or on other information pertaining to the request
- (such as the network address of the client).
-
- Server-driven negotiation is advantageous when the algorithm for
- selecting from among the available representations is difficult to
- describe to the user agent, or when the server desires to send its
- "best guess" to the client along with the first response (hoping to
- avoid the round-trip delay of a subsequent request if the "best
- guess" is good enough for the user). In order to improve the server's
- guess, the user agent MAY include request header fields (Accept,
- Accept-Language, Accept-Encoding, etc.) which describe its
- preferences for such a response.
-
- Server-driven negotiation has disadvantages:
-
- 1. It is impossible for the server to accurately determine what
- might be "best" for any given user, since that would require
- complete knowledge of both the capabilities of the user agent
- and the intended use for the response (e.g., does the user want
- to view it on screen or print it on paper?).
-
- 2. Having the user agent describe its capabilities in every
- request can be both very inefficient (given that only a small
- percentage of responses have multiple representations) and a
- potential violation of the user's privacy.
-
- 3. It complicates the implementation of an origin server and the
- algorithms for generating responses to a request.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 72]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- 4. It may limit a public cache's ability to use the same response
- for multiple user's requests.
-
- HTTP/1.1 includes the following request-header fields for enabling
- server-driven negotiation through description of user agent
- capabilities and user preferences: Accept (section 14.1), Accept-
- Charset (section 14.2), Accept-Encoding (section 14.3), Accept-
- Language (section 14.4), and User-Agent (section 14.43). However, an
- origin server is not limited to these dimensions and MAY vary the
- response based on any aspect of the request, including information
- outside the request-header fields or within extension header fields
- not defined by this specification.
-
- The Vary header field can be used to express the parameters the
- server uses to select a representation that is subject to server-
- driven negotiation. See section 13.6 for use of the Vary header field
- by caches and section 14.44 for use of the Vary header field by
- servers.
-
-12.2 Agent-driven Negotiation
-
- With agent-driven negotiation, selection of the best representation
- for a response is performed by the user agent after receiving an
- initial response from the origin server. Selection is based on a list
- of the available representations of the response included within the
- header fields or entity-body of the initial response, with each
- representation identified by its own URI. Selection from among the
- representations may be performed automatically (if the user agent is
- capable of doing so) or manually by the user selecting from a
- generated (possibly hypertext) menu.
-
- Agent-driven negotiation is advantageous when the response would vary
- over commonly-used dimensions (such as type, language, or encoding),
- when the origin server is unable to determine a user agent's
- capabilities from examining the request, and generally when public
- caches are used to distribute server load and reduce network usage.
-
- Agent-driven negotiation suffers from the disadvantage of needing a
- second request to obtain the best alternate representation. This
- second request is only efficient when caching is used. In addition,
- this specification does not define any mechanism for supporting
- automatic selection, though it also does not prevent any such
- mechanism from being developed as an extension and used within
- HTTP/1.1.
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 73]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- HTTP/1.1 defines the 300 (Multiple Choices) and 406 (Not Acceptable)
- status codes for enabling agent-driven negotiation when the server is
- unwilling or unable to provide a varying response using server-driven
- negotiation.
-
-12.3 Transparent Negotiation
-
- Transparent negotiation is a combination of both server-driven and
- agent-driven negotiation. When a cache is supplied with a form of the
- list of available representations of the response (as in agent-driven
- negotiation) and the dimensions of variance are completely understood
- by the cache, then the cache becomes capable of performing server-
- driven negotiation on behalf of the origin server for subsequent
- requests on that resource.
-
- Transparent negotiation has the advantage of distributing the
- negotiation work that would otherwise be required of the origin
- server and also removing the second request delay of agent-driven
- negotiation when the cache is able to correctly guess the right
- response.
-
- This specification does not define any mechanism for transparent
- negotiation, though it also does not prevent any such mechanism from
- being developed as an extension that could be used within HTTP/1.1.
-
-13 Caching in HTTP
-
- HTTP is typically used for distributed information systems, where
- performance can be improved by the use of response caches. The
- HTTP/1.1 protocol includes a number of elements intended to make
- caching work as well as possible. Because these elements are
- inextricable from other aspects of the protocol, and because they
- interact with each other, it is useful to describe the basic caching
- design of HTTP separately from the detailed descriptions of methods,
- headers, response codes, etc.
-
- Caching would be useless if it did not significantly improve
- performance. The goal of caching in HTTP/1.1 is to eliminate the need
- to send requests in many cases, and to eliminate the need to send
- full responses in many other cases. The former reduces the number of
- network round-trips required for many operations; we use an
- "expiration" mechanism for this purpose (see section 13.2). The
- latter reduces network bandwidth requirements; we use a "validation"
- mechanism for this purpose (see section 13.3).
-
- Requirements for performance, availability, and disconnected
- operation require us to be able to relax the goal of semantic
- transparency. The HTTP/1.1 protocol allows origin servers, caches,
-
-
-
-Fielding, et al. Standards Track [Page 74]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- and clients to explicitly reduce transparency when necessary.
- However, because non-transparent operation may confuse non-expert
- users, and might be incompatible with certain server applications
- (such as those for ordering merchandise), the protocol requires that
- transparency be relaxed
-
- - only by an explicit protocol-level request when relaxed by
- client or origin server
-
- - only with an explicit warning to the end user when relaxed by
- cache or client
-
- Therefore, the HTTP/1.1 protocol provides these important elements:
-
- 1. Protocol features that provide full semantic transparency when
- this is required by all parties.
-
- 2. Protocol features that allow an origin server or user agent to
- explicitly request and control non-transparent operation.
-
- 3. Protocol features that allow a cache to attach warnings to
- responses that do not preserve the requested approximation of
- semantic transparency.
-
- A basic principle is that it must be possible for the clients to
- detect any potential relaxation of semantic transparency.
-
- Note: The server, cache, or client implementor might be faced with
- design decisions not explicitly discussed in this specification.
- If a decision might affect semantic transparency, the implementor
- ought to err on the side of maintaining transparency unless a
- careful and complete analysis shows significant benefits in
- breaking transparency.
-
-13.1.1 Cache Correctness
-
- A correct cache MUST respond to a request with the most up-to-date
- response held by the cache that is appropriate to the request (see
- sections 13.2.5, 13.2.6, and 13.12) which meets one of the following
- conditions:
-
- 1. It has been checked for equivalence with what the origin server
- would have returned by revalidating the response with the
- origin server (section 13.3);
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 75]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- 2. It is "fresh enough" (see section 13.2). In the default case,
- this means it meets the least restrictive freshness requirement
- of the client, origin server, and cache (see section 14.9); if
- the origin server so specifies, it is the freshness requirement
- of the origin server alone.
-
- If a stored response is not "fresh enough" by the most
- restrictive freshness requirement of both the client and the
- origin server, in carefully considered circumstances the cache
- MAY still return the response with the appropriate Warning
- header (see section 13.1.5 and 14.46), unless such a response
- is prohibited (e.g., by a "no-store" cache-directive, or by a
- "no-cache" cache-request-directive; see section 14.9).
-
- 3. It is an appropriate 304 (Not Modified), 305 (Proxy Redirect),
- or error (4xx or 5xx) response message.
-
- If the cache can not communicate with the origin server, then a
- correct cache SHOULD respond as above if the response can be
- correctly served from the cache; if not it MUST return an error or
- warning indicating that there was a communication failure.
-
- If a cache receives a response (either an entire response, or a 304
- (Not Modified) response) that it would normally forward to the
- requesting client, and the received response is no longer fresh, the
- cache SHOULD forward it to the requesting client without adding a new
- Warning (but without removing any existing Warning headers). A cache
- SHOULD NOT attempt to revalidate a response simply because that
- response became stale in transit; this might lead to an infinite
- loop. A user agent that receives a stale response without a Warning
- MAY display a warning indication to the user.
-
-13.1.2 Warnings
-
- Whenever a cache returns a response that is neither first-hand nor
- "fresh enough" (in the sense of condition 2 in section 13.1.1), it
- MUST attach a warning to that effect, using a Warning general-header.
- The Warning header and the currently defined warnings are described
- in section 14.46. The warning allows clients to take appropriate
- action.
-
- Warnings MAY be used for other purposes, both cache-related and
- otherwise. The use of a warning, rather than an error status code,
- distinguish these responses from true failures.
-
- Warnings are assigned three digit warn-codes. The first digit
- indicates whether the Warning MUST or MUST NOT be deleted from a
- stored cache entry after a successful revalidation:
-
-
-
-Fielding, et al. Standards Track [Page 76]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- 1xx Warnings that describe the freshness or revalidation status of
- the response, and so MUST be deleted after a successful
- revalidation. 1XX warn-codes MAY be generated by a cache only when
- validating a cached entry. It MUST NOT be generated by clients.
-
- 2xx Warnings that describe some aspect of the entity body or entity
- headers that is not rectified by a revalidation (for example, a
- lossy compression of the entity bodies) and which MUST NOT be
- deleted after a successful revalidation.
-
- See section 14.46 for the definitions of the codes themselves.
-
- HTTP/1.0 caches will cache all Warnings in responses, without
- deleting the ones in the first category. Warnings in responses that
- are passed to HTTP/1.0 caches carry an extra warning-date field,
- which prevents a future HTTP/1.1 recipient from believing an
- erroneously cached Warning.
-
- Warnings also carry a warning text. The text MAY be in any
- appropriate natural language (perhaps based on the client's Accept
- headers), and include an OPTIONAL indication of what character set is
- used.
-
- Multiple warnings MAY be attached to a response (either by the origin
- server or by a cache), including multiple warnings with the same code
- number. For example, a server might provide the same warning with
- texts in both English and Basque.
-
- When multiple warnings are attached to a response, it might not be
- practical or reasonable to display all of them to the user. This
- version of HTTP does not specify strict priority rules for deciding
- which warnings to display and in what order, but does suggest some
- heuristics.
-
-13.1.3 Cache-control Mechanisms
-
- The basic cache mechanisms in HTTP/1.1 (server-specified expiration
- times and validators) are implicit directives to caches. In some
- cases, a server or client might need to provide explicit directives
- to the HTTP caches. We use the Cache-Control header for this purpose.
-
- The Cache-Control header allows a client or server to transmit a
- variety of directives in either requests or responses. These
- directives typically override the default caching algorithms. As a
- general rule, if there is any apparent conflict between header
- values, the most restrictive interpretation is applied (that is, the
- one that is most likely to preserve semantic transparency). However,
-
-
-
-
-Fielding, et al. Standards Track [Page 77]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- in some cases, cache-control directives are explicitly specified as
- weakening the approximation of semantic transparency (for example,
- "max-stale" or "public").
-
- The cache-control directives are described in detail in section 14.9.
-
-13.1.4 Explicit User Agent Warnings
-
- Many user agents make it possible for users to override the basic
- caching mechanisms. For example, the user agent might allow the user
- to specify that cached entities (even explicitly stale ones) are
- never validated. Or the user agent might habitually add "Cache-
- Control: max-stale=3600" to every request. The user agent SHOULD NOT
- default to either non-transparent behavior, or behavior that results
- in abnormally ineffective caching, but MAY be explicitly configured
- to do so by an explicit action of the user.
-
- If the user has overridden the basic caching mechanisms, the user
- agent SHOULD explicitly indicate to the user whenever this results in
- the display of information that might not meet the server's
- transparency requirements (in particular, if the displayed entity is
- known to be stale). Since the protocol normally allows the user agent
- to determine if responses are stale or not, this indication need only
- be displayed when this actually happens. The indication need not be a
- dialog box; it could be an icon (for example, a picture of a rotting
- fish) or some other indicator.
-
- If the user has overridden the caching mechanisms in a way that would
- abnormally reduce the effectiveness of caches, the user agent SHOULD
- continually indicate this state to the user (for example, by a
- display of a picture of currency in flames) so that the user does not
- inadvertently consume excess resources or suffer from excessive
- latency.
-
-13.1.5 Exceptions to the Rules and Warnings
-
- In some cases, the operator of a cache MAY choose to configure it to
- return stale responses even when not requested by clients. This
- decision ought not be made lightly, but may be necessary for reasons
- of availability or performance, especially when the cache is poorly
- connected to the origin server. Whenever a cache returns a stale
- response, it MUST mark it as such (using a Warning header) enabling
- the client software to alert the user that there might be a potential
- problem.
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 78]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- It also allows the user agent to take steps to obtain a first-hand or
- fresh response. For this reason, a cache SHOULD NOT return a stale
- response if the client explicitly requests a first-hand or fresh one,
- unless it is impossible to comply for technical or policy reasons.
-
-13.1.6 Client-controlled Behavior
-
- While the origin server (and to a lesser extent, intermediate caches,
- by their contribution to the age of a response) are the primary
- source of expiration information, in some cases the client might need
- to control a cache's decision about whether to return a cached
- response without validating it. Clients do this using several
- directives of the Cache-Control header.
-
- A client's request MAY specify the maximum age it is willing to
- accept of an unvalidated response; specifying a value of zero forces
- the cache(s) to revalidate all responses. A client MAY also specify
- the minimum time remaining before a response expires. Both of these
- options increase constraints on the behavior of caches, and so cannot
- further relax the cache's approximation of semantic transparency.
-
- A client MAY also specify that it will accept stale responses, up to
- some maximum amount of staleness. This loosens the constraints on the
- caches, and so might violate the origin server's specified
- constraints on semantic transparency, but might be necessary to
- support disconnected operation, or high availability in the face of
- poor connectivity.
-
-13.2 Expiration Model
-
-13.2.1 Server-Specified Expiration
-
- HTTP caching works best when caches can entirely avoid making
- requests to the origin server. The primary mechanism for avoiding
- requests is for an origin server to provide an explicit expiration
- time in the future, indicating that a response MAY be used to satisfy
- subsequent requests. In other words, a cache can return a fresh
- response without first contacting the server.
-
- Our expectation is that servers will assign future explicit
- expiration times to responses in the belief that the entity is not
- likely to change, in a semantically significant way, before the
- expiration time is reached. This normally preserves semantic
- transparency, as long as the server's expiration times are carefully
- chosen.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 79]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- The expiration mechanism applies only to responses taken from a cache
- and not to first-hand responses forwarded immediately to the
- requesting client.
-
- If an origin server wishes to force a semantically transparent cache
- to validate every request, it MAY assign an explicit expiration time
- in the past. This means that the response is always stale, and so the
- cache SHOULD validate it before using it for subsequent requests. See
- section 14.9.4 for a more restrictive way to force revalidation.
-
- If an origin server wishes to force any HTTP/1.1 cache, no matter how
- it is configured, to validate every request, it SHOULD use the "must-
- revalidate" cache-control directive (see section 14.9).
-
- Servers specify explicit expiration times using either the Expires
- header, or the max-age directive of the Cache-Control header.
-
- An expiration time cannot be used to force a user agent to refresh
- its display or reload a resource; its semantics apply only to caching
- mechanisms, and such mechanisms need only check a resource's
- expiration status when a new request for that resource is initiated.
- See section 13.13 for an explanation of the difference between caches
- and history mechanisms.
-
-13.2.2 Heuristic Expiration
-
- Since origin servers do not always provide explicit expiration times,
- HTTP caches typically assign heuristic expiration times, employing
- algorithms that use other header values (such as the Last-Modified
- time) to estimate a plausible expiration time. The HTTP/1.1
- specification does not provide specific algorithms, but does impose
- worst-case constraints on their results. Since heuristic expiration
- times might compromise semantic transparency, they ought to used
- cautiously, and we encourage origin servers to provide explicit
- expiration times as much as possible.
-
-13.2.3 Age Calculations
-
- In order to know if a cached entry is fresh, a cache needs to know if
- its age exceeds its freshness lifetime. We discuss how to calculate
- the latter in section 13.2.4; this section describes how to calculate
- the age of a response or cache entry.
-
- In this discussion, we use the term "now" to mean "the current value
- of the clock at the host performing the calculation." Hosts that use
- HTTP, but especially hosts running origin servers and caches, SHOULD
- use NTP [28] or some similar protocol to synchronize their clocks to
- a globally accurate time standard.
-
-
-
-Fielding, et al. Standards Track [Page 80]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- HTTP/1.1 requires origin servers to send a Date header, if possible,
- with every response, giving the time at which the response was
- generated (see section 14.18). We use the term "date_value" to denote
- the value of the Date header, in a form appropriate for arithmetic
- operations.
-
- HTTP/1.1 uses the Age response-header to convey the estimated age of
- the response message when obtained from a cache. The Age field value
- is the cache's estimate of the amount of time since the response was
- generated or revalidated by the origin server.
-
- In essence, the Age value is the sum of the time that the response
- has been resident in each of the caches along the path from the
- origin server, plus the amount of time it has been in transit along
- network paths.
-
- We use the term "age_value" to denote the value of the Age header, in
- a form appropriate for arithmetic operations.
-
- A response's age can be calculated in two entirely independent ways:
-
- 1. now minus date_value, if the local clock is reasonably well
- synchronized to the origin server's clock. If the result is
- negative, the result is replaced by zero.
-
- 2. age_value, if all of the caches along the response path
- implement HTTP/1.1.
-
- Given that we have two independent ways to compute the age of a
- response when it is received, we can combine these as
-
- corrected_received_age = max(now - date_value, age_value)
-
- and as long as we have either nearly synchronized clocks or all-
- HTTP/1.1 paths, one gets a reliable (conservative) result.
-
- Because of network-imposed delays, some significant interval might
- pass between the time that a server generates a response and the time
- it is received at the next outbound cache or client. If uncorrected,
- this delay could result in improperly low ages.
-
- Because the request that resulted in the returned Age value must have
- been initiated prior to that Age value's generation, we can correct
- for delays imposed by the network by recording the time at which the
- request was initiated. Then, when an Age value is received, it MUST
- be interpreted relative to the time the request was initiated, not
-
-
-
-
-
-Fielding, et al. Standards Track [Page 81]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- the time that the response was received. This algorithm results in
- conservative behavior no matter how much delay is experienced. So, we
- compute:
-
- corrected_initial_age = corrected_received_age
- + (now - request_time)
-
- where "request_time" is the time (according to the local clock) when
- the request that elicited this response was sent.
-
- Summary of age calculation algorithm, when a cache receives a
- response:
-
- /*
- * age_value
- * is the value of Age: header received by the cache with
- * this response.
- * date_value
- * is the value of the origin server's Date: header
- * request_time
- * is the (local) time when the cache made the request
- * that resulted in this cached response
- * response_time
- * is the (local) time when the cache received the
- * response
- * now
- * is the current (local) time
- */
-
- apparent_age = max(0, response_time - date_value);
- corrected_received_age = max(apparent_age, age_value);
- response_delay = response_time - request_time;
- corrected_initial_age = corrected_received_age + response_delay;
- resident_time = now - response_time;
- current_age = corrected_initial_age + resident_time;
-
- The current_age of a cache entry is calculated by adding the amount
- of time (in seconds) since the cache entry was last validated by the
- origin server to the corrected_initial_age. When a response is
- generated from a cache entry, the cache MUST include a single Age
- header field in the response with a value equal to the cache entry's
- current_age.
-
- The presence of an Age header field in a response implies that a
- response is not first-hand. However, the converse is not true, since
- the lack of an Age header field in a response does not imply that the
-
-
-
-
-
-Fielding, et al. Standards Track [Page 82]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- response is first-hand unless all caches along the request path are
- compliant with HTTP/1.1 (i.e., older HTTP caches did not implement
- the Age header field).
-
-13.2.4 Expiration Calculations
-
- In order to decide whether a response is fresh or stale, we need to
- compare its freshness lifetime to its age. The age is calculated as
- described in section 13.2.3; this section describes how to calculate
- the freshness lifetime, and to determine if a response has expired.
- In the discussion below, the values can be represented in any form
- appropriate for arithmetic operations.
-
- We use the term "expires_value" to denote the value of the Expires
- header. We use the term "max_age_value" to denote an appropriate
- value of the number of seconds carried by the "max-age" directive of
- the Cache-Control header in a response (see section 14.9.3).
-
- The max-age directive takes priority over Expires, so if max-age is
- present in a response, the calculation is simply:
-
- freshness_lifetime = max_age_value
-
- Otherwise, if Expires is present in the response, the calculation is:
-
- freshness_lifetime = expires_value - date_value
-
- Note that neither of these calculations is vulnerable to clock skew,
- since all of the information comes from the origin server.
-
- If none of Expires, Cache-Control: max-age, or Cache-Control: s-
- maxage (see section 14.9.3) appears in the response, and the response
- does not include other restrictions on caching, the cache MAY compute
- a freshness lifetime using a heuristic. The cache MUST attach Warning
- 113 to any response whose age is more than 24 hours if such warning
- has not already been added.
-
- Also, if the response does have a Last-Modified time, the heuristic
- expiration value SHOULD be no more than some fraction of the interval
- since that time. A typical setting of this fraction might be 10%.
-
- The calculation to determine if a response has expired is quite
- simple:
-
- response_is_fresh = (freshness_lifetime > current_age)
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 83]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-13.2.5 Disambiguating Expiration Values
-
- Because expiration values are assigned optimistically, it is possible
- for two caches to contain fresh values for the same resource that are
- different.
-
- If a client performing a retrieval receives a non-first-hand response
- for a request that was already fresh in its own cache, and the Date
- header in its existing cache entry is newer than the Date on the new
- response, then the client MAY ignore the response. If so, it MAY
- retry the request with a "Cache-Control: max-age=0" directive (see
- section 14.9), to force a check with the origin server.
-
- If a cache has two fresh responses for the same representation with
- different validators, it MUST use the one with the more recent Date
- header. This situation might arise because the cache is pooling
- responses from other caches, or because a client has asked for a
- reload or a revalidation of an apparently fresh cache entry.
-
-13.2.6 Disambiguating Multiple Responses
-
- Because a client might be receiving responses via multiple paths, so
- that some responses flow through one set of caches and other
- responses flow through a different set of caches, a client might
- receive responses in an order different from that in which the origin
- server sent them. We would like the client to use the most recently
- generated response, even if older responses are still apparently
- fresh.
-
- Neither the entity tag nor the expiration value can impose an
- ordering on responses, since it is possible that a later response
- intentionally carries an earlier expiration time. The Date values are
- ordered to a granularity of one second.
-
- When a client tries to revalidate a cache entry, and the response it
- receives contains a Date header that appears to be older than the one
- for the existing entry, then the client SHOULD repeat the request
- unconditionally, and include
-
- Cache-Control: max-age=0
-
- to force any intermediate caches to validate their copies directly
- with the origin server, or
-
- Cache-Control: no-cache
-
- to force any intermediate caches to obtain a new copy from the origin
- server.
-
-
-
-Fielding, et al. Standards Track [Page 84]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- If the Date values are equal, then the client MAY use either response
- (or MAY, if it is being extremely prudent, request a new response).
- Servers MUST NOT depend on clients being able to choose
- deterministically between responses generated during the same second,
- if their expiration times overlap.
-
-13.3 Validation Model
-
- When a cache has a stale entry that it would like to use as a
- response to a client's request, it first has to check with the origin
- server (or possibly an intermediate cache with a fresh response) to
- see if its cached entry is still usable. We call this "validating"
- the cache entry. Since we do not want to have to pay the overhead of
- retransmitting the full response if the cached entry is good, and we
- do not want to pay the overhead of an extra round trip if the cached
- entry is invalid, the HTTP/1.1 protocol supports the use of
- conditional methods.
-
- The key protocol features for supporting conditional methods are
- those concerned with "cache validators." When an origin server
- generates a full response, it attaches some sort of validator to it,
- which is kept with the cache entry. When a client (user agent or
- proxy cache) makes a conditional request for a resource for which it
- has a cache entry, it includes the associated validator in the
- request.
-
- The server then checks that validator against the current validator
- for the entity, and, if they match (see section 13.3.3), it responds
- with a special status code (usually, 304 (Not Modified)) and no
- entity-body. Otherwise, it returns a full response (including
- entity-body). Thus, we avoid transmitting the full response if the
- validator matches, and we avoid an extra round trip if it does not
- match.
-
- In HTTP/1.1, a conditional request looks exactly the same as a normal
- request for the same resource, except that it carries a special
- header (which includes the validator) that implicitly turns the
- method (usually, GET) into a conditional.
-
- The protocol includes both positive and negative senses of cache-
- validating conditions. That is, it is possible to request either that
- a method be performed if and only if a validator matches or if and
- only if no validators match.
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 85]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Note: a response that lacks a validator may still be cached, and
- served from cache until it expires, unless this is explicitly
- prohibited by a cache-control directive. However, a cache cannot
- do a conditional retrieval if it does not have a validator for the
- entity, which means it will not be refreshable after it expires.
-
-13.3.1 Last-Modified Dates
-
- The Last-Modified entity-header field value is often used as a cache
- validator. In simple terms, a cache entry is considered to be valid
- if the entity has not been modified since the Last-Modified value.
-
-13.3.2 Entity Tag Cache Validators
-
- The ETag response-header field value, an entity tag, provides for an
- "opaque" cache validator. This might allow more reliable validation
- in situations where it is inconvenient to store modification dates,
- where the one-second resolution of HTTP date values is not
- sufficient, or where the origin server wishes to avoid certain
- paradoxes that might arise from the use of modification dates.
-
- Entity Tags are described in section 3.11. The headers used with
- entity tags are described in sections 14.19, 14.24, 14.26 and 14.44.
-
-13.3.3 Weak and Strong Validators
-
- Since both origin servers and caches will compare two validators to
- decide if they represent the same or different entities, one normally
- would expect that if the entity (the entity-body or any entity-
- headers) changes in any way, then the associated validator would
- change as well. If this is true, then we call this validator a
- "strong validator."
-
- However, there might be cases when a server prefers to change the
- validator only on semantically significant changes, and not when
- insignificant aspects of the entity change. A validator that does not
- always change when the resource changes is a "weak validator."
-
- Entity tags are normally "strong validators," but the protocol
- provides a mechanism to tag an entity tag as "weak." One can think of
- a strong validator as one that changes whenever the bits of an entity
- changes, while a weak value changes whenever the meaning of an entity
- changes. Alternatively, one can think of a strong validator as part
- of an identifier for a specific entity, while a weak validator is
- part of an identifier for a set of semantically equivalent entities.
-
- Note: One example of a strong validator is an integer that is
- incremented in stable storage every time an entity is changed.
-
-
-
-Fielding, et al. Standards Track [Page 86]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- An entity's modification time, if represented with one-second
- resolution, could be a weak validator, since it is possible that
- the resource might be modified twice during a single second.
-
- Support for weak validators is optional. However, weak validators
- allow for more efficient caching of equivalent objects; for
- example, a hit counter on a site is probably good enough if it is
- updated every few days or weeks, and any value during that period
- is likely "good enough" to be equivalent.
-
- A "use" of a validator is either when a client generates a request
- and includes the validator in a validating header field, or when a
- server compares two validators.
-
- Strong validators are usable in any context. Weak validators are only
- usable in contexts that do not depend on exact equality of an entity.
- For example, either kind is usable for a conditional GET of a full
- entity. However, only a strong validator is usable for a sub-range
- retrieval, since otherwise the client might end up with an internally
- inconsistent entity.
-
- Clients MAY issue simple (non-subrange) GET requests with either weak
- validators or strong validators. Clients MUST NOT use weak validators
- in other forms of request.
-
- The only function that the HTTP/1.1 protocol defines on validators is
- comparison. There are two validator comparison functions, depending
- on whether the comparison context allows the use of weak validators
- or not:
-
- - The strong comparison function: in order to be considered equal,
- both validators MUST be identical in every way, and both MUST
- NOT be weak.
-
- - The weak comparison function: in order to be considered equal,
- both validators MUST be identical in every way, but either or
- both of them MAY be tagged as "weak" without affecting the
- result.
-
- An entity tag is strong unless it is explicitly tagged as weak.
- Section 3.11 gives the syntax for entity tags.
-
- A Last-Modified time, when used as a validator in a request, is
- implicitly weak unless it is possible to deduce that it is strong,
- using the following rules:
-
- - The validator is being compared by an origin server to the
- actual current validator for the entity and,
-
-
-
-Fielding, et al. Standards Track [Page 87]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- - That origin server reliably knows that the associated entity did
- not change twice during the second covered by the presented
- validator.
-
- or
-
- - The validator is about to be used by a client in an If-
- Modified-Since or If-Unmodified-Since header, because the client
- has a cache entry for the associated entity, and
-
- - That cache entry includes a Date value, which gives the time
- when the origin server sent the original response, and
-
- - The presented Last-Modified time is at least 60 seconds before
- the Date value.
-
- or
-
- - The validator is being compared by an intermediate cache to the
- validator stored in its cache entry for the entity, and
-
- - That cache entry includes a Date value, which gives the time
- when the origin server sent the original response, and
-
- - The presented Last-Modified time is at least 60 seconds before
- the Date value.
-
- This method relies on the fact that if two different responses were
- sent by the origin server during the same second, but both had the
- same Last-Modified time, then at least one of those responses would
- have a Date value equal to its Last-Modified time. The arbitrary 60-
- second limit guards against the possibility that the Date and Last-
- Modified values are generated from different clocks, or at somewhat
- different times during the preparation of the response. An
- implementation MAY use a value larger than 60 seconds, if it is
- believed that 60 seconds is too short.
-
- If a client wishes to perform a sub-range retrieval on a value for
- which it has only a Last-Modified time and no opaque validator, it
- MAY do this only if the Last-Modified time is strong in the sense
- described here.
-
- A cache or origin server receiving a conditional request, other than
- a full-body GET request, MUST use the strong comparison function to
- evaluate the condition.
-
- These rules allow HTTP/1.1 caches and clients to safely perform sub-
- range retrievals on values that have been obtained from HTTP/1.0
-
-
-
-Fielding, et al. Standards Track [Page 88]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- servers.
-
-13.3.4 Rules for When to Use Entity Tags and Last-Modified Dates
-
- We adopt a set of rules and recommendations for origin servers,
- clients, and caches regarding when various validator types ought to
- be used, and for what purposes.
-
- HTTP/1.1 origin servers:
-
- - SHOULD send an entity tag validator unless it is not feasible to
- generate one.
-
- - MAY send a weak entity tag instead of a strong entity tag, if
- performance considerations support the use of weak entity tags,
- or if it is unfeasible to send a strong entity tag.
-
- - SHOULD send a Last-Modified value if it is feasible to send one,
- unless the risk of a breakdown in semantic transparency that
- could result from using this date in an If-Modified-Since header
- would lead to serious problems.
-
- In other words, the preferred behavior for an HTTP/1.1 origin server
- is to send both a strong entity tag and a Last-Modified value.
-
- In order to be legal, a strong entity tag MUST change whenever the
- associated entity value changes in any way. A weak entity tag SHOULD
- change whenever the associated entity changes in a semantically
- significant way.
-
- Note: in order to provide semantically transparent caching, an
- origin server must avoid reusing a specific strong entity tag
- value for two different entities, or reusing a specific weak
- entity tag value for two semantically different entities. Cache
- entries might persist for arbitrarily long periods, regardless of
- expiration times, so it might be inappropriate to expect that a
- cache will never again attempt to validate an entry using a
- validator that it obtained at some point in the past.
-
- HTTP/1.1 clients:
-
- - If an entity tag has been provided by the origin server, MUST
- use that entity tag in any cache-conditional request (using If-
- Match or If-None-Match).
-
- - If only a Last-Modified value has been provided by the origin
- server, SHOULD use that value in non-subrange cache-conditional
- requests (using If-Modified-Since).
-
-
-
-Fielding, et al. Standards Track [Page 89]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- - If only a Last-Modified value has been provided by an HTTP/1.0
- origin server, MAY use that value in subrange cache-conditional
- requests (using If-Unmodified-Since:). The user agent SHOULD
- provide a way to disable this, in case of difficulty.
-
- - If both an entity tag and a Last-Modified value have been
- provided by the origin server, SHOULD use both validators in
- cache-conditional requests. This allows both HTTP/1.0 and
- HTTP/1.1 caches to respond appropriately.
-
- An HTTP/1.1 origin server, upon receiving a conditional request that
- includes both a Last-Modified date (e.g., in an If-Modified-Since or
- If-Unmodified-Since header field) and one or more entity tags (e.g.,
- in an If-Match, If-None-Match, or If-Range header field) as cache
- validators, MUST NOT return a response status of 304 (Not Modified)
- unless doing so is consistent with all of the conditional header
- fields in the request.
-
- An HTTP/1.1 caching proxy, upon receiving a conditional request that
- includes both a Last-Modified date and one or more entity tags as
- cache validators, MUST NOT return a locally cached response to the
- client unless that cached response is consistent with all of the
- conditional header fields in the request.
-
- Note: The general principle behind these rules is that HTTP/1.1
- servers and clients should transmit as much non-redundant
- information as is available in their responses and requests.
- HTTP/1.1 systems receiving this information will make the most
- conservative assumptions about the validators they receive.
-
- HTTP/1.0 clients and caches will ignore entity tags. Generally,
- last-modified values received or used by these systems will
- support transparent and efficient caching, and so HTTP/1.1 origin
- servers should provide Last-Modified values. In those rare cases
- where the use of a Last-Modified value as a validator by an
- HTTP/1.0 system could result in a serious problem, then HTTP/1.1
- origin servers should not provide one.
-
-13.3.5 Non-validating Conditionals
-
- The principle behind entity tags is that only the service author
- knows the semantics of a resource well enough to select an
- appropriate cache validation mechanism, and the specification of any
- validator comparison function more complex than byte-equality would
- open up a can of worms. Thus, comparisons of any other headers
- (except Last-Modified, for compatibility with HTTP/1.0) are never
- used for purposes of validating a cache entry.
-
-
-
-
-Fielding, et al. Standards Track [Page 90]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-13.4 Response Cacheability
-
- Unless specifically constrained by a cache-control (section 14.9)
- directive, a caching system MAY always store a successful response
- (see section 13.8) as a cache entry, MAY return it without validation
- if it is fresh, and MAY return it after successful validation. If
- there is neither a cache validator nor an explicit expiration time
- associated with a response, we do not expect it to be cached, but
- certain caches MAY violate this expectation (for example, when little
- or no network connectivity is available). A client can usually detect
- that such a response was taken from a cache by comparing the Date
- header to the current time.
-
- Note: some HTTP/1.0 caches are known to violate this expectation
- without providing any Warning.
-
- However, in some cases it might be inappropriate for a cache to
- retain an entity, or to return it in response to a subsequent
- request. This might be because absolute semantic transparency is
- deemed necessary by the service author, or because of security or
- privacy considerations. Certain cache-control directives are
- therefore provided so that the server can indicate that certain
- resource entities, or portions thereof, are not to be cached
- regardless of other considerations.
-
- Note that section 14.8 normally prevents a shared cache from saving
- and returning a response to a previous request if that request
- included an Authorization header.
-
- A response received with a status code of 200, 203, 206, 300, 301 or
- 410 MAY be stored by a cache and used in reply to a subsequent
- request, subject to the expiration mechanism, unless a cache-control
- directive prohibits caching. However, a cache that does not support
- the Range and Content-Range headers MUST NOT cache 206 (Partial
- Content) responses.
-
- A response received with any other status code (e.g. status codes 302
- and 307) MUST NOT be returned in a reply to a subsequent request
- unless there are cache-control directives or another header(s) that
- explicitly allow it. For example, these include the following: an
- Expires header (section 14.21); a "max-age", "s-maxage", "must-
- revalidate", "proxy-revalidate", "public" or "private" cache-control
- directive (section 14.9).
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 91]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-13.5 Constructing Responses From Caches
-
- The purpose of an HTTP cache is to store information received in
- response to requests for use in responding to future requests. In
- many cases, a cache simply returns the appropriate parts of a
- response to the requester. However, if the cache holds a cache entry
- based on a previous response, it might have to combine parts of a new
- response with what is held in the cache entry.
-
-13.5.1 End-to-end and Hop-by-hop Headers
-
- For the purpose of defining the behavior of caches and non-caching
- proxies, we divide HTTP headers into two categories:
-
- - End-to-end headers, which are transmitted to the ultimate
- recipient of a request or response. End-to-end headers in
- responses MUST be stored as part of a cache entry and MUST be
- transmitted in any response formed from a cache entry.
-
- - Hop-by-hop headers, which are meaningful only for a single
- transport-level connection, and are not stored by caches or
- forwarded by proxies.
-
- The following HTTP/1.1 headers are hop-by-hop headers:
-
- - Connection
- - Keep-Alive
- - Proxy-Authenticate
- - Proxy-Authorization
- - TE
- - Trailers
- - Transfer-Encoding
- - Upgrade
-
- All other headers defined by HTTP/1.1 are end-to-end headers.
-
- Other hop-by-hop headers MUST be listed in a Connection header,
- (section 14.10) to be introduced into HTTP/1.1 (or later).
-
-13.5.2 Non-modifiable Headers
-
- Some features of the HTTP/1.1 protocol, such as Digest
- Authentication, depend on the value of certain end-to-end headers. A
- transparent proxy SHOULD NOT modify an end-to-end header unless the
- definition of that header requires or specifically allows that.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 92]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- A transparent proxy MUST NOT modify any of the following fields in a
- request or response, and it MUST NOT add any of these fields if not
- already present:
-
- - Content-Location
-
- - Content-MD5
-
- - ETag
-
- - Last-Modified
-
- A transparent proxy MUST NOT modify any of the following fields in a
- response:
-
- - Expires
-
- but it MAY add any of these fields if not already present. If an
- Expires header is added, it MUST be given a field-value identical to
- that of the Date header in that response.
-
- A proxy MUST NOT modify or add any of the following fields in a
- message that contains the no-transform cache-control directive, or in
- any request:
-
- - Content-Encoding
-
- - Content-Range
-
- - Content-Type
-
- A non-transparent proxy MAY modify or add these fields to a message
- that does not include no-transform, but if it does so, it MUST add a
- Warning 214 (Transformation applied) if one does not already appear
- in the message (see section 14.46).
-
- Warning: unnecessary modification of end-to-end headers might
- cause authentication failures if stronger authentication
- mechanisms are introduced in later versions of HTTP. Such
- authentication mechanisms MAY rely on the values of header fields
- not listed here.
-
- The Content-Length field of a request or response is added or deleted
- according to the rules in section 4.4. A transparent proxy MUST
- preserve the entity-length (section 7.2.2) of the entity-body,
- although it MAY change the transfer-length (section 4.4).
-
-
-
-
-
-Fielding, et al. Standards Track [Page 93]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-13.5.3 Combining Headers
-
- When a cache makes a validating request to a server, and the server
- provides a 304 (Not Modified) response or a 206 (Partial Content)
- response, the cache then constructs a response to send to the
- requesting client.
-
- If the status code is 304 (Not Modified), the cache uses the entity-
- body stored in the cache entry as the entity-body of this outgoing
- response. If the status code is 206 (Partial Content) and the ETag or
- Last-Modified headers match exactly, the cache MAY combine the
- contents stored in the cache entry with the new contents received in
- the response and use the result as the entity-body of this outgoing
- response, (see 13.5.4).
-
- The end-to-end headers stored in the cache entry are used for the
- constructed response, except that
-
- - any stored Warning headers with warn-code 1xx (see section
- 14.46) MUST be deleted from the cache entry and the forwarded
- response.
-
- - any stored Warning headers with warn-code 2xx MUST be retained
- in the cache entry and the forwarded response.
-
- - any end-to-end headers provided in the 304 or 206 response MUST
- replace the corresponding headers from the cache entry.
-
- Unless the cache decides to remove the cache entry, it MUST also
- replace the end-to-end headers stored with the cache entry with
- corresponding headers received in the incoming response, except for
- Warning headers as described immediately above. If a header field-
- name in the incoming response matches more than one header in the
- cache entry, all such old headers MUST be replaced.
-
- In other words, the set of end-to-end headers received in the
- incoming response overrides all corresponding end-to-end headers
- stored with the cache entry (except for stored Warning headers with
- warn-code 1xx, which are deleted even if not overridden).
-
- Note: this rule allows an origin server to use a 304 (Not
- Modified) or a 206 (Partial Content) response to update any header
- associated with a previous response for the same entity or sub-
- ranges thereof, although it might not always be meaningful or
- correct to do so. This rule does not allow an origin server to use
- a 304 (Not Modified) or a 206 (Partial Content) response to
- entirely delete a header that it had provided with a previous
- response.
-
-
-
-Fielding, et al. Standards Track [Page 94]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-13.5.4 Combining Byte Ranges
-
- A response might transfer only a subrange of the bytes of an entity-
- body, either because the request included one or more Range
- specifications, or because a connection was broken prematurely. After
- several such transfers, a cache might have received several ranges of
- the same entity-body.
-
- If a cache has a stored non-empty set of subranges for an entity, and
- an incoming response transfers another subrange, the cache MAY
- combine the new subrange with the existing set if both the following
- conditions are met:
-
- - Both the incoming response and the cache entry have a cache
- validator.
-
- - The two cache validators match using the strong comparison
- function (see section 13.3.3).
-
- If either requirement is not met, the cache MUST use only the most
- recent partial response (based on the Date values transmitted with
- every response, and using the incoming response if these values are
- equal or missing), and MUST discard the other partial information.
-
-13.6 Caching Negotiated Responses
-
- Use of server-driven content negotiation (section 12.1), as indicated
- by the presence of a Vary header field in a response, alters the
- conditions and procedure by which a cache can use the response for
- subsequent requests. See section 14.44 for use of the Vary header
- field by servers.
-
- A server SHOULD use the Vary header field to inform a cache of what
- request-header fields were used to select among multiple
- representations of a cacheable response subject to server-driven
- negotiation. The set of header fields named by the Vary field value
- is known as the "selecting" request-headers.
-
- When the cache receives a subsequent request whose Request-URI
- specifies one or more cache entries including a Vary header field,
- the cache MUST NOT use such a cache entry to construct a response to
- the new request unless all of the selecting request-headers present
- in the new request match the corresponding stored request-headers in
- the original request.
-
- The selecting request-headers from two requests are defined to match
- if and only if the selecting request-headers in the first request can
- be transformed to the selecting request-headers in the second request
-
-
-
-Fielding, et al. Standards Track [Page 95]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- by adding or removing linear white space (LWS) at places where this
- is allowed by the corresponding BNF, and/or combining multiple
- message-header fields with the same field name following the rules
- about message headers in section 4.2.
-
- A Vary header field-value of "*" always fails to match and subsequent
- requests on that resource can only be properly interpreted by the
- origin server.
-
- If the selecting request header fields for the cached entry do not
- match the selecting request header fields of the new request, then
- the cache MUST NOT use a cached entry to satisfy the request unless
- it first relays the new request to the origin server in a conditional
- request and the server responds with 304 (Not Modified), including an
- entity tag or Content-Location that indicates the entity to be used.
-
- If an entity tag was assigned to a cached representation, the
- forwarded request SHOULD be conditional and include the entity tags
- in an If-None-Match header field from all its cache entries for the
- resource. This conveys to the server the set of entities currently
- held by the cache, so that if any one of these entities matches the
- requested entity, the server can use the ETag header field in its 304
- (Not Modified) response to tell the cache which entry is appropriate.
- If the entity-tag of the new response matches that of an existing
- entry, the new response SHOULD be used to update the header fields of
- the existing entry, and the result MUST be returned to the client.
-
- If any of the existing cache entries contains only partial content
- for the associated entity, its entity-tag SHOULD NOT be included in
- the If-None-Match header field unless the request is for a range that
- would be fully satisfied by that entry.
-
- If a cache receives a successful response whose Content-Location
- field matches that of an existing cache entry for the same Request-
- ]URI, whose entity-tag differs from that of the existing entry, and
- whose Date is more recent than that of the existing entry, the
- existing entry SHOULD NOT be returned in response to future requests
- and SHOULD be deleted from the cache.
-
-13.7 Shared and Non-Shared Caches
-
- For reasons of security and privacy, it is necessary to make a
- distinction between "shared" and "non-shared" caches. A non-shared
- cache is one that is accessible only to a single user. Accessibility
- in this case SHOULD be enforced by appropriate security mechanisms.
- All other caches are considered to be "shared." Other sections of
-
-
-
-
-
-Fielding, et al. Standards Track [Page 96]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- this specification place certain constraints on the operation of
- shared caches in order to prevent loss of privacy or failure of
- access controls.
-
-13.8 Errors or Incomplete Response Cache Behavior
-
- A cache that receives an incomplete response (for example, with fewer
- bytes of data than specified in a Content-Length header) MAY store
- the response. However, the cache MUST treat this as a partial
- response. Partial responses MAY be combined as described in section
- 13.5.4; the result might be a full response or might still be
- partial. A cache MUST NOT return a partial response to a client
- without explicitly marking it as such, using the 206 (Partial
- Content) status code. A cache MUST NOT return a partial response
- using a status code of 200 (OK).
-
- If a cache receives a 5xx response while attempting to revalidate an
- entry, it MAY either forward this response to the requesting client,
- or act as if the server failed to respond. In the latter case, it MAY
- return a previously received response unless the cached entry
- includes the "must-revalidate" cache-control directive (see section
- 14.9).
-
-13.9 Side Effects of GET and HEAD
-
- Unless the origin server explicitly prohibits the caching of their
- responses, the application of GET and HEAD methods to any resources
- SHOULD NOT have side effects that would lead to erroneous behavior if
- these responses are taken from a cache. They MAY still have side
- effects, but a cache is not required to consider such side effects in
- its caching decisions. Caches are always expected to observe an
- origin server's explicit restrictions on caching.
-
- We note one exception to this rule: since some applications have
- traditionally used GETs and HEADs with query URLs (those containing a
- "?" in the rel_path part) to perform operations with significant side
- effects, caches MUST NOT treat responses to such URIs as fresh unless
- the server provides an explicit expiration time. This specifically
- means that responses from HTTP/1.0 servers for such URIs SHOULD NOT
- be taken from a cache. See section 9.1.1 for related information.
-
-13.10 Invalidation After Updates or Deletions
-
- The effect of certain methods performed on a resource at the origin
- server might cause one or more existing cache entries to become non-
- transparently invalid. That is, although they might continue to be
- "fresh," they do not accurately reflect what the origin server would
- return for a new request on that resource.
-
-
-
-Fielding, et al. Standards Track [Page 97]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- There is no way for the HTTP protocol to guarantee that all such
- cache entries are marked invalid. For example, the request that
- caused the change at the origin server might not have gone through
- the proxy where a cache entry is stored. However, several rules help
- reduce the likelihood of erroneous behavior.
-
- In this section, the phrase "invalidate an entity" means that the
- cache will either remove all instances of that entity from its
- storage, or will mark these as "invalid" and in need of a mandatory
- revalidation before they can be returned in response to a subsequent
- request.
-
- Some HTTP methods MUST cause a cache to invalidate an entity. This is
- either the entity referred to by the Request-URI, or by the Location
- or Content-Location headers (if present). These methods are:
-
- - PUT
-
- - DELETE
-
- - POST
-
- In order to prevent denial of service attacks, an invalidation based
- on the URI in a Location or Content-Location header MUST only be
- performed if the host part is the same as in the Request-URI.
-
- A cache that passes through requests for methods it does not
- understand SHOULD invalidate any entities referred to by the
- Request-URI.
-
-13.11 Write-Through Mandatory
-
- All methods that might be expected to cause modifications to the
- origin server's resources MUST be written through to the origin
- server. This currently includes all methods except for GET and HEAD.
- A cache MUST NOT reply to such a request from a client before having
- transmitted the request to the inbound server, and having received a
- corresponding response from the inbound server. This does not prevent
- a proxy cache from sending a 100 (Continue) response before the
- inbound server has sent its final reply.
-
- The alternative (known as "write-back" or "copy-back" caching) is not
- allowed in HTTP/1.1, due to the difficulty of providing consistent
- updates and the problems arising from server, cache, or network
- failure prior to write-back.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 98]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-13.12 Cache Replacement
-
- If a new cacheable (see sections 14.9.2, 13.2.5, 13.2.6 and 13.8)
- response is received from a resource while any existing responses for
- the same resource are cached, the cache SHOULD use the new response
- to reply to the current request. It MAY insert it into cache storage
- and MAY, if it meets all other requirements, use it to respond to any
- future requests that would previously have caused the old response to
- be returned. If it inserts the new response into cache storage the
- rules in section 13.5.3 apply.
-
- Note: a new response that has an older Date header value than
- existing cached responses is not cacheable.
-
-13.13 History Lists
-
- User agents often have history mechanisms, such as "Back" buttons and
- history lists, which can be used to redisplay an entity retrieved
- earlier in a session.
-
- History mechanisms and caches are different. In particular history
- mechanisms SHOULD NOT try to show a semantically transparent view of
- the current state of a resource. Rather, a history mechanism is meant
- to show exactly what the user saw at the time when the resource was
- retrieved.
-
- By default, an expiration time does not apply to history mechanisms.
- If the entity is still in storage, a history mechanism SHOULD display
- it even if the entity has expired, unless the user has specifically
- configured the agent to refresh expired history documents.
-
- This is not to be construed to prohibit the history mechanism from
- telling the user that a view might be stale.
-
- Note: if history list mechanisms unnecessarily prevent users from
- viewing stale resources, this will tend to force service authors
- to avoid using HTTP expiration controls and cache controls when
- they would otherwise like to. Service authors may consider it
- important that users not be presented with error messages or
- warning messages when they use navigation controls (such as BACK)
- to view previously fetched resources. Even though sometimes such
- resources ought not to cached, or ought to expire quickly, user
- interface considerations may force service authors to resort to
- other means of preventing caching (e.g. "once-only" URLs) in order
- not to suffer the effects of improperly functioning history
- mechanisms.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 99]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-14 Header Field Definitions
-
- This section defines the syntax and semantics of all standard
- HTTP/1.1 header fields. For entity-header fields, both sender and
- recipient refer to either the client or the server, depending on who
- sends and who receives the entity.
-
-14.1 Accept
-
- The Accept request-header field can be used to specify certain media
- types which are acceptable for the response. Accept headers can be
- used to indicate that the request is specifically limited to a small
- set of desired types, as in the case of a request for an in-line
- image.
-
- Accept = "Accept" ":"
- #( media-range [ accept-params ] )
-
- media-range = ( "*/*"
- | ( type "/" "*" )
- | ( type "/" subtype )
- ) *( ";" parameter )
- accept-params = ";" "q" "=" qvalue *( accept-extension )
- accept-extension = ";" token [ "=" ( token | quoted-string ) ]
-
- The asterisk "*" character is used to group media types into ranges,
- with "*/*" indicating all media types and "type/*" indicating all
- subtypes of that type. The media-range MAY include media type
- parameters that are applicable to that range.
-
- Each media-range MAY be followed by one or more accept-params,
- beginning with the "q" parameter for indicating a relative quality
- factor. The first "q" parameter (if any) separates the media-range
- parameter(s) from the accept-params. Quality factors allow the user
- or user agent to indicate the relative degree of preference for that
- media-range, using the qvalue scale from 0 to 1 (section 3.9). The
- default value is q=1.
-
- Note: Use of the "q" parameter name to separate media type
- parameters from Accept extension parameters is due to historical
- practice. Although this prevents any media type parameter named
- "q" from being used with a media range, such an event is believed
- to be unlikely given the lack of any "q" parameters in the IANA
- media type registry and the rare usage of any media type
- parameters in Accept. Future media types are discouraged from
- registering any parameter named "q".
-
-
-
-
-
-Fielding, et al. Standards Track [Page 100]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- The example
-
- Accept: audio/*; q=0.2, audio/basic
-
- SHOULD be interpreted as "I prefer audio/basic, but send me any audio
- type if it is the best available after an 80% mark-down in quality."
-
- If no Accept header field is present, then it is assumed that the
- client accepts all media types. If an Accept header field is present,
- and if the server cannot send a response which is acceptable
- according to the combined Accept field value, then the server SHOULD
- send a 406 (not acceptable) response.
-
- A more elaborate example is
-
- Accept: text/plain; q=0.5, text/html,
- text/x-dvi; q=0.8, text/x-c
-
- Verbally, this would be interpreted as "text/html and text/x-c are
- the preferred media types, but if they do not exist, then send the
- text/x-dvi entity, and if that does not exist, send the text/plain
- entity."
-
- Media ranges can be overridden by more specific media ranges or
- specific media types. If more than one media range applies to a given
- type, the most specific reference has precedence. For example,
-
- Accept: text/*, text/html, text/html;level=1, */*
-
- have the following precedence:
-
- 1) text/html;level=1
- 2) text/html
- 3) text/*
- 4) */*
-
- The media type quality factor associated with a given type is
- determined by finding the media range with the highest precedence
- which matches that type. For example,
-
- Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1,
- text/html;level=2;q=0.4, */*;q=0.5
-
- would cause the following values to be associated:
-
- text/html;level=1 = 1
- text/html = 0.7
- text/plain = 0.3
-
-
-
-Fielding, et al. Standards Track [Page 101]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- image/jpeg = 0.5
- text/html;level=2 = 0.4
- text/html;level=3 = 0.7
-
- Note: A user agent might be provided with a default set of quality
- values for certain media ranges. However, unless the user agent is
- a closed system which cannot interact with other rendering agents,
- this default set ought to be configurable by the user.
-
-14.2 Accept-Charset
-
- The Accept-Charset request-header field can be used to indicate what
- character sets are acceptable for the response. This field allows
- clients capable of understanding more comprehensive or special-
- purpose character sets to signal that capability to a server which is
- capable of representing documents in those character sets.
-
- Accept-Charset = "Accept-Charset" ":"
- 1#( ( charset | "*" )[ ";" "q" "=" qvalue ] )
-
-
- Character set values are described in section 3.4. Each charset MAY
- be given an associated quality value which represents the user's
- preference for that charset. The default value is q=1. An example is
-
- Accept-Charset: iso-8859-5, unicode-1-1;q=0.8
-
- The special value "*", if present in the Accept-Charset field,
- matches every character set (including ISO-8859-1) which is not
- mentioned elsewhere in the Accept-Charset field. If no "*" is present
- in an Accept-Charset field, then all character sets not explicitly
- mentioned get a quality value of 0, except for ISO-8859-1, which gets
- a quality value of 1 if not explicitly mentioned.
-
- If no Accept-Charset header is present, the default is that any
- character set is acceptable. If an Accept-Charset header is present,
- and if the server cannot send a response which is acceptable
- according to the Accept-Charset header, then the server SHOULD send
- an error response with the 406 (not acceptable) status code, though
- the sending of an unacceptable response is also allowed.
-
-14.3 Accept-Encoding
-
- The Accept-Encoding request-header field is similar to Accept, but
- restricts the content-codings (section 3.5) that are acceptable in
- the response.
-
- Accept-Encoding = "Accept-Encoding" ":"
-
-
-
-Fielding, et al. Standards Track [Page 102]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- 1#( codings [ ";" "q" "=" qvalue ] )
- codings = ( content-coding | "*" )
-
- Examples of its use are:
-
- Accept-Encoding: compress, gzip
- Accept-Encoding:
- Accept-Encoding: *
- Accept-Encoding: compress;q=0.5, gzip;q=1.0
- Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0
-
- A server tests whether a content-coding is acceptable, according to
- an Accept-Encoding field, using these rules:
-
- 1. If the content-coding is one of the content-codings listed in
- the Accept-Encoding field, then it is acceptable, unless it is
- accompanied by a qvalue of 0. (As defined in section 3.9, a
- qvalue of 0 means "not acceptable.")
-
- 2. The special "*" symbol in an Accept-Encoding field matches any
- available content-coding not explicitly listed in the header
- field.
-
- 3. If multiple content-codings are acceptable, then the acceptable
- content-coding with the highest non-zero qvalue is preferred.
-
- 4. The "identity" content-coding is always acceptable, unless
- specifically refused because the Accept-Encoding field includes
- "identity;q=0", or because the field includes "*;q=0" and does
- not explicitly include the "identity" content-coding. If the
- Accept-Encoding field-value is empty, then only the "identity"
- encoding is acceptable.
-
- If an Accept-Encoding field is present in a request, and if the
- server cannot send a response which is acceptable according to the
- Accept-Encoding header, then the server SHOULD send an error response
- with the 406 (Not Acceptable) status code.
-
- If no Accept-Encoding field is present in a request, the server MAY
- assume that the client will accept any content coding. In this case,
- if "identity" is one of the available content-codings, then the
- server SHOULD use the "identity" content-coding, unless it has
- additional information that a different content-coding is meaningful
- to the client.
-
- Note: If the request does not include an Accept-Encoding field,
- and if the "identity" content-coding is unavailable, then
- content-codings commonly understood by HTTP/1.0 clients (i.e.,
-
-
-
-Fielding, et al. Standards Track [Page 103]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- "gzip" and "compress") are preferred; some older clients
- improperly display messages sent with other content-codings. The
- server might also make this decision based on information about
- the particular user-agent or client.
-
- Note: Most HTTP/1.0 applications do not recognize or obey qvalues
- associated with content-codings. This means that qvalues will not
- work and are not permitted with x-gzip or x-compress.
-
-14.4 Accept-Language
-
- The Accept-Language request-header field is similar to Accept, but
- restricts the set of natural languages that are preferred as a
- response to the request. Language tags are defined in section 3.10.
-
- Accept-Language = "Accept-Language" ":"
- 1#( language-range [ ";" "q" "=" qvalue ] )
- language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" )
-
- Each language-range MAY be given an associated quality value which
- represents an estimate of the user's preference for the languages
- specified by that range. The quality value defaults to "q=1". For
- example,
-
- Accept-Language: da, en-gb;q=0.8, en;q=0.7
-
- would mean: "I prefer Danish, but will accept British English and
- other types of English." A language-range matches a language-tag if
- it exactly equals the tag, or if it exactly equals a prefix of the
- tag such that the first tag character following the prefix is "-".
- The special range "*", if present in the Accept-Language field,
- matches every tag not matched by any other range present in the
- Accept-Language field.
-
- Note: This use of a prefix matching rule does not imply that
- language tags are assigned to languages in such a way that it is
- always true that if a user understands a language with a certain
- tag, then this user will also understand all languages with tags
- for which this tag is a prefix. The prefix rule simply allows the
- use of prefix tags if this is the case.
-
- The language quality factor assigned to a language-tag by the
- Accept-Language field is the quality value of the longest language-
- range in the field that matches the language-tag. If no language-
- range in the field matches the tag, the language quality factor
- assigned is 0. If no Accept-Language header is present in the
- request, the server
-
-
-
-
-Fielding, et al. Standards Track [Page 104]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- SHOULD assume that all languages are equally acceptable. If an
- Accept-Language header is present, then all languages which are
- assigned a quality factor greater than 0 are acceptable.
-
- It might be contrary to the privacy expectations of the user to send
- an Accept-Language header with the complete linguistic preferences of
- the user in every request. For a discussion of this issue, see
- section 15.1.4.
-
- As intelligibility is highly dependent on the individual user, it is
- recommended that client applications make the choice of linguistic
- preference available to the user. If the choice is not made
- available, then the Accept-Language header field MUST NOT be given in
- the request.
-
- Note: When making the choice of linguistic preference available to
- the user, we remind implementors of the fact that users are not
- familiar with the details of language matching as described above,
- and should provide appropriate guidance. As an example, users
- might assume that on selecting "en-gb", they will be served any
- kind of English document if British English is not available. A
- user agent might suggest in such a case to add "en" to get the
- best matching behavior.
-
-14.5 Accept-Ranges
-
- The Accept-Ranges response-header field allows the server to
- indicate its acceptance of range requests for a resource:
-
- Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges
- acceptable-ranges = 1#range-unit | "none"
-
- Origin servers that accept byte-range requests MAY send
-
- Accept-Ranges: bytes
-
- but are not required to do so. Clients MAY generate byte-range
- requests without having received this header for the resource
- involved. Range units are defined in section 3.12.
-
- Servers that do not accept any kind of range request for a
- resource MAY send
-
- Accept-Ranges: none
-
- to advise the client not to attempt a range request.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 105]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-14.6 Age
-
- The Age response-header field conveys the sender's estimate of the
- amount of time since the response (or its revalidation) was
- generated at the origin server. A cached response is "fresh" if
- its age does not exceed its freshness lifetime. Age values are
- calculated as specified in section 13.2.3.
-
- Age = "Age" ":" age-value
- age-value = delta-seconds
-
- Age values are non-negative decimal integers, representing time in
- seconds.
-
- If a cache receives a value larger than the largest positive
- integer it can represent, or if any of its age calculations
- overflows, it MUST transmit an Age header with a value of
- 2147483648 (2^31). An HTTP/1.1 server that includes a cache MUST
- include an Age header field in every response generated from its
- own cache. Caches SHOULD use an arithmetic type of at least 31
- bits of range.
-
-14.7 Allow
-
- The Allow entity-header field lists the set of methods supported
- by the resource identified by the Request-URI. The purpose of this
- field is strictly to inform the recipient of valid methods
- associated with the resource. An Allow header field MUST be
- present in a 405 (Method Not Allowed) response.
-
- Allow = "Allow" ":" #Method
-
- Example of use:
-
- Allow: GET, HEAD, PUT
-
- This field cannot prevent a client from trying other methods.
- However, the indications given by the Allow header field value
- SHOULD be followed. The actual set of allowed methods is defined
- by the origin server at the time of each request.
-
- The Allow header field MAY be provided with a PUT request to
- recommend the methods to be supported by the new or modified
- resource. The server is not required to support these methods and
- SHOULD include an Allow header in the response giving the actual
- supported methods.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 106]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- A proxy MUST NOT modify the Allow header field even if it does not
- understand all the methods specified, since the user agent might
- have other means of communicating with the origin server.
-
-14.8 Authorization
-
- A user agent that wishes to authenticate itself with a server--
- usually, but not necessarily, after receiving a 401 response--does
- so by including an Authorization request-header field with the
- request. The Authorization field value consists of credentials
- containing the authentication information of the user agent for
- the realm of the resource being requested.
-
- Authorization = "Authorization" ":" credentials
-
- HTTP access authentication is described in "HTTP Authentication:
- Basic and Digest Access Authentication" [43]. If a request is
- authenticated and a realm specified, the same credentials SHOULD
- be valid for all other requests within this realm (assuming that
- the authentication scheme itself does not require otherwise, such
- as credentials that vary according to a challenge value or using
- synchronized clocks).
-
- When a shared cache (see section 13.7) receives a request
- containing an Authorization field, it MUST NOT return the
- corresponding response as a reply to any other request, unless one
- of the following specific exceptions holds:
-
- 1. If the response includes the "s-maxage" cache-control
- directive, the cache MAY use that response in replying to a
- subsequent request. But (if the specified maximum age has
- passed) a proxy cache MUST first revalidate it with the origin
- server, using the request-headers from the new request to allow
- the origin server to authenticate the new request. (This is the
- defined behavior for s-maxage.) If the response includes "s-
- maxage=0", the proxy MUST always revalidate it before re-using
- it.
-
- 2. If the response includes the "must-revalidate" cache-control
- directive, the cache MAY use that response in replying to a
- subsequent request. But if the response is stale, all caches
- MUST first revalidate it with the origin server, using the
- request-headers from the new request to allow the origin server
- to authenticate the new request.
-
- 3. If the response includes the "public" cache-control directive,
- it MAY be returned in reply to any subsequent request.
-
-
-
-
-Fielding, et al. Standards Track [Page 107]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-14.9 Cache-Control
-
- The Cache-Control general-header field is used to specify directives
- that MUST be obeyed by all caching mechanisms along the
- request/response chain. The directives specify behavior intended to
- prevent caches from adversely interfering with the request or
- response. These directives typically override the default caching
- algorithms. Cache directives are unidirectional in that the presence
- of a directive in a request does not imply that the same directive is
- to be given in the response.
-
- Note that HTTP/1.0 caches might not implement Cache-Control and
- might only implement Pragma: no-cache (see section 14.32).
-
- Cache directives MUST be passed through by a proxy or gateway
- application, regardless of their significance to that application,
- since the directives might be applicable to all recipients along the
- request/response chain. It is not possible to specify a cache-
- directive for a specific cache.
-
- Cache-Control = "Cache-Control" ":" 1#cache-directive
-
- cache-directive = cache-request-directive
- | cache-response-directive
-
- cache-request-directive =
- "no-cache" ; Section 14.9.1
- | "no-store" ; Section 14.9.2
- | "max-age" "=" delta-seconds ; Section 14.9.3, 14.9.4
- | "max-stale" [ "=" delta-seconds ] ; Section 14.9.3
- | "min-fresh" "=" delta-seconds ; Section 14.9.3
- | "no-transform" ; Section 14.9.5
- | "only-if-cached" ; Section 14.9.4
- | cache-extension ; Section 14.9.6
-
- cache-response-directive =
- "public" ; Section 14.9.1
- | "private" [ "=" <"> 1#field-name <"> ] ; Section 14.9.1
- | "no-cache" [ "=" <"> 1#field-name <"> ]; Section 14.9.1
- | "no-store" ; Section 14.9.2
- | "no-transform" ; Section 14.9.5
- | "must-revalidate" ; Section 14.9.4
- | "proxy-revalidate" ; Section 14.9.4
- | "max-age" "=" delta-seconds ; Section 14.9.3
- | "s-maxage" "=" delta-seconds ; Section 14.9.3
- | cache-extension ; Section 14.9.6
-
- cache-extension = token [ "=" ( token | quoted-string ) ]
-
-
-
-Fielding, et al. Standards Track [Page 108]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- When a directive appears without any 1#field-name parameter, the
- directive applies to the entire request or response. When such a
- directive appears with a 1#field-name parameter, it applies only to
- the named field or fields, and not to the rest of the request or
- response. This mechanism supports extensibility; implementations of
- future versions of the HTTP protocol might apply these directives to
- header fields not defined in HTTP/1.1.
-
- The cache-control directives can be broken down into these general
- categories:
-
- - Restrictions on what are cacheable; these may only be imposed by
- the origin server.
-
- - Restrictions on what may be stored by a cache; these may be
- imposed by either the origin server or the user agent.
-
- - Modifications of the basic expiration mechanism; these may be
- imposed by either the origin server or the user agent.
-
- - Controls over cache revalidation and reload; these may only be
- imposed by a user agent.
-
- - Control over transformation of entities.
-
- - Extensions to the caching system.
-
-14.9.1 What is Cacheable
-
- By default, a response is cacheable if the requirements of the
- request method, request header fields, and the response status
- indicate that it is cacheable. Section 13.4 summarizes these defaults
- for cacheability. The following Cache-Control response directives
- allow an origin server to override the default cacheability of a
- response:
-
- public
- Indicates that the response MAY be cached by any cache, even if it
- would normally be non-cacheable or cacheable only within a non-
- shared cache. (See also Authorization, section 14.8, for
- additional details.)
-
- private
- Indicates that all or part of the response message is intended for
- a single user and MUST NOT be cached by a shared cache. This
- allows an origin server to state that the specified parts of the
-
-
-
-
-
-Fielding, et al. Standards Track [Page 109]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- response are intended for only one user and are not a valid
- response for requests by other users. A private (non-shared) cache
- MAY cache the response.
-
- Note: This usage of the word private only controls where the
- response may be cached, and cannot ensure the privacy of the
- message content.
-
- no-cache
- If the no-cache directive does not specify a field-name, then a
- cache MUST NOT use the response to satisfy a subsequent request
- without successful revalidation with the origin server. This
- allows an origin server to prevent caching even by caches that
- have been configured to return stale responses to client requests.
-
- If the no-cache directive does specify one or more field-names,
- then a cache MAY use the response to satisfy a subsequent request,
- subject to any other restrictions on caching. However, the
- specified field-name(s) MUST NOT be sent in the response to a
- subsequent request without successful revalidation with the origin
- server. This allows an origin server to prevent the re-use of
- certain header fields in a response, while still allowing caching
- of the rest of the response.
-
- Note: Most HTTP/1.0 caches will not recognize or obey this
- directive.
-
-14.9.2 What May be Stored by Caches
-
- no-store
- The purpose of the no-store directive is to prevent the
- inadvertent release or retention of sensitive information (for
- example, on backup tapes). The no-store directive applies to the
- entire message, and MAY be sent either in a response or in a
- request. If sent in a request, a cache MUST NOT store any part of
- either this request or any response to it. If sent in a response,
- a cache MUST NOT store any part of either this response or the
- request that elicited it. This directive applies to both non-
- shared and shared caches. "MUST NOT store" in this context means
- that the cache MUST NOT intentionally store the information in
- non-volatile storage, and MUST make a best-effort attempt to
- remove the information from volatile storage as promptly as
- possible after forwarding it.
-
- Even when this directive is associated with a response, users
- might explicitly store such a response outside of the caching
- system (e.g., with a "Save As" dialog). History buffers MAY store
- such responses as part of their normal operation.
-
-
-
-Fielding, et al. Standards Track [Page 110]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- The purpose of this directive is to meet the stated requirements
- of certain users and service authors who are concerned about
- accidental releases of information via unanticipated accesses to
- cache data structures. While the use of this directive might
- improve privacy in some cases, we caution that it is NOT in any
- way a reliable or sufficient mechanism for ensuring privacy. In
- particular, malicious or compromised caches might not recognize or
- obey this directive, and communications networks might be
- vulnerable to eavesdropping.
-
-14.9.3 Modifications of the Basic Expiration Mechanism
-
- The expiration time of an entity MAY be specified by the origin
- server using the Expires header (see section 14.21). Alternatively,
- it MAY be specified using the max-age directive in a response. When
- the max-age cache-control directive is present in a cached response,
- the response is stale if its current age is greater than the age
- value given (in seconds) at the time of a new request for that
- resource. The max-age directive on a response implies that the
- response is cacheable (i.e., "public") unless some other, more
- restrictive cache directive is also present.
-
- If a response includes both an Expires header and a max-age
- directive, the max-age directive overrides the Expires header, even
- if the Expires header is more restrictive. This rule allows an origin
- server to provide, for a given response, a longer expiration time to
- an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This might be
- useful if certain HTTP/1.0 caches improperly calculate ages or
- expiration times, perhaps due to desynchronized clocks.
-
- Many HTTP/1.0 cache implementations will treat an Expires value that
- is less than or equal to the response Date value as being equivalent
- to the Cache-Control response directive "no-cache". If an HTTP/1.1
- cache receives such a response, and the response does not include a
- Cache-Control header field, it SHOULD consider the response to be
- non-cacheable in order to retain compatibility with HTTP/1.0 servers.
-
- Note: An origin server might wish to use a relatively new HTTP
- cache control feature, such as the "private" directive, on a
- network including older caches that do not understand that
- feature. The origin server will need to combine the new feature
- with an Expires field whose value is less than or equal to the
- Date value. This will prevent older caches from improperly
- caching the response.
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 111]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- s-maxage
- If a response includes an s-maxage directive, then for a shared
- cache (but not for a private cache), the maximum age specified by
- this directive overrides the maximum age specified by either the
- max-age directive or the Expires header. The s-maxage directive
- also implies the semantics of the proxy-revalidate directive (see
- section 14.9.4), i.e., that the shared cache must not use the
- entry after it becomes stale to respond to a subsequent request
- without first revalidating it with the origin server. The s-
- maxage directive is always ignored by a private cache.
-
- Note that most older caches, not compliant with this specification,
- do not implement any cache-control directives. An origin server
- wishing to use a cache-control directive that restricts, but does not
- prevent, caching by an HTTP/1.1-compliant cache MAY exploit the
- requirement that the max-age directive overrides the Expires header,
- and the fact that pre-HTTP/1.1-compliant caches do not observe the
- max-age directive.
-
- Other directives allow a user agent to modify the basic expiration
- mechanism. These directives MAY be specified on a request:
-
- max-age
- Indicates that the client is willing to accept a response whose
- age is no greater than the specified time in seconds. Unless max-
- stale directive is also included, the client is not willing to
- accept a stale response.
-
- min-fresh
- Indicates that the client is willing to accept a response whose
- freshness lifetime is no less than its current age plus the
- specified time in seconds. That is, the client wants a response
- that will still be fresh for at least the specified number of
- seconds.
-
- max-stale
- Indicates that the client is willing to accept a response that has
- exceeded its expiration time. If max-stale is assigned a value,
- then the client is willing to accept a response that has exceeded
- its expiration time by no more than the specified number of
- seconds. If no value is assigned to max-stale, then the client is
- willing to accept a stale response of any age.
-
- If a cache returns a stale response, either because of a max-stale
- directive on a request, or because the cache is configured to
- override the expiration time of a response, the cache MUST attach a
- Warning header to the stale response, using Warning 110 (Response is
- stale).
-
-
-
-Fielding, et al. Standards Track [Page 112]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- A cache MAY be configured to return stale responses without
- validation, but only if this does not conflict with any "MUST"-level
- requirements concerning cache validation (e.g., a "must-revalidate"
- cache-control directive).
-
- If both the new request and the cached entry include "max-age"
- directives, then the lesser of the two values is used for determining
- the freshness of the cached entry for that request.
-
-14.9.4 Cache Revalidation and Reload Controls
-
- Sometimes a user agent might want or need to insist that a cache
- revalidate its cache entry with the origin server (and not just with
- the next cache along the path to the origin server), or to reload its
- cache entry from the origin server. End-to-end revalidation might be
- necessary if either the cache or the origin server has overestimated
- the expiration time of the cached response. End-to-end reload may be
- necessary if the cache entry has become corrupted for some reason.
-
- End-to-end revalidation may be requested either when the client does
- not have its own local cached copy, in which case we call it
- "unspecified end-to-end revalidation", or when the client does have a
- local cached copy, in which case we call it "specific end-to-end
- revalidation."
-
- The client can specify these three kinds of action using Cache-
- Control request directives:
-
- End-to-end reload
- The request includes a "no-cache" cache-control directive or, for
- compatibility with HTTP/1.0 clients, "Pragma: no-cache". Field
- names MUST NOT be included with the no-cache directive in a
- request. The server MUST NOT use a cached copy when responding to
- such a request.
-
- Specific end-to-end revalidation
- The request includes a "max-age=0" cache-control directive, which
- forces each cache along the path to the origin server to
- revalidate its own entry, if any, with the next cache or server.
- The initial request includes a cache-validating conditional with
- the client's current validator.
-
- Unspecified end-to-end revalidation
- The request includes "max-age=0" cache-control directive, which
- forces each cache along the path to the origin server to
- revalidate its own entry, if any, with the next cache or server.
- The initial request does not include a cache-validating
-
-
-
-
-Fielding, et al. Standards Track [Page 113]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- conditional; the first cache along the path (if any) that holds a
- cache entry for this resource includes a cache-validating
- conditional with its current validator.
-
- max-age
- When an intermediate cache is forced, by means of a max-age=0
- directive, to revalidate its own cache entry, and the client has
- supplied its own validator in the request, the supplied validator
- might differ from the validator currently stored with the cache
- entry. In this case, the cache MAY use either validator in making
- its own request without affecting semantic transparency.
-
- However, the choice of validator might affect performance. The
- best approach is for the intermediate cache to use its own
- validator when making its request. If the server replies with 304
- (Not Modified), then the cache can return its now validated copy
- to the client with a 200 (OK) response. If the server replies with
- a new entity and cache validator, however, the intermediate cache
- can compare the returned validator with the one provided in the
- client's request, using the strong comparison function. If the
- client's validator is equal to the origin server's, then the
- intermediate cache simply returns 304 (Not Modified). Otherwise,
- it returns the new entity with a 200 (OK) response.
-
- If a request includes the no-cache directive, it SHOULD NOT
- include min-fresh, max-stale, or max-age.
-
- only-if-cached
- In some cases, such as times of extremely poor network
- connectivity, a client may want a cache to return only those
- responses that it currently has stored, and not to reload or
- revalidate with the origin server. To do this, the client may
- include the only-if-cached directive in a request. If it receives
- this directive, a cache SHOULD either respond using a cached entry
- that is consistent with the other constraints of the request, or
- respond with a 504 (Gateway Timeout) status. However, if a group
- of caches is being operated as a unified system with good internal
- connectivity, such a request MAY be forwarded within that group of
- caches.
-
- must-revalidate
- Because a cache MAY be configured to ignore a server's specified
- expiration time, and because a client request MAY include a max-
- stale directive (which has a similar effect), the protocol also
- includes a mechanism for the origin server to require revalidation
- of a cache entry on any subsequent use. When the must-revalidate
- directive is present in a response received by a cache, that cache
- MUST NOT use the entry after it becomes stale to respond to a
-
-
-
-Fielding, et al. Standards Track [Page 114]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- subsequent request without first revalidating it with the origin
- server. (I.e., the cache MUST do an end-to-end revalidation every
- time, if, based solely on the origin server's Expires or max-age
- value, the cached response is stale.)
-
- The must-revalidate directive is necessary to support reliable
- operation for certain protocol features. In all circumstances an
- HTTP/1.1 cache MUST obey the must-revalidate directive; in
- particular, if the cache cannot reach the origin server for any
- reason, it MUST generate a 504 (Gateway Timeout) response.
-
- Servers SHOULD send the must-revalidate directive if and only if
- failure to revalidate a request on the entity could result in
- incorrect operation, such as a silently unexecuted financial
- transaction. Recipients MUST NOT take any automated action that
- violates this directive, and MUST NOT automatically provide an
- unvalidated copy of the entity if revalidation fails.
-
- Although this is not recommended, user agents operating under
- severe connectivity constraints MAY violate this directive but, if
- so, MUST explicitly warn the user that an unvalidated response has
- been provided. The warning MUST be provided on each unvalidated
- access, and SHOULD require explicit user confirmation.
-
- proxy-revalidate
- The proxy-revalidate directive has the same meaning as the must-
- revalidate directive, except that it does not apply to non-shared
- user agent caches. It can be used on a response to an
- authenticated request to permit the user's cache to store and
- later return the response without needing to revalidate it (since
- it has already been authenticated once by that user), while still
- requiring proxies that service many users to revalidate each time
- (in order to make sure that each user has been authenticated).
- Note that such authenticated responses also need the public cache
- control directive in order to allow them to be cached at all.
-
-14.9.5 No-Transform Directive
-
- no-transform
- Implementors of intermediate caches (proxies) have found it useful
- to convert the media type of certain entity bodies. A non-
- transparent proxy might, for example, convert between image
- formats in order to save cache space or to reduce the amount of
- traffic on a slow link.
-
- Serious operational problems occur, however, when these
- transformations are applied to entity bodies intended for certain
- kinds of applications. For example, applications for medical
-
-
-
-Fielding, et al. Standards Track [Page 115]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- imaging, scientific data analysis and those using end-to-end
- authentication, all depend on receiving an entity body that is bit
- for bit identical to the original entity-body.
-
- Therefore, if a message includes the no-transform directive, an
- intermediate cache or proxy MUST NOT change those headers that are
- listed in section 13.5.2 as being subject to the no-transform
- directive. This implies that the cache or proxy MUST NOT change
- any aspect of the entity-body that is specified by these headers,
- including the value of the entity-body itself.
-
-14.9.6 Cache Control Extensions
-
- The Cache-Control header field can be extended through the use of one
- or more cache-extension tokens, each with an optional assigned value.
- Informational extensions (those which do not require a change in
- cache behavior) MAY be added without changing the semantics of other
- directives. Behavioral extensions are designed to work by acting as
- modifiers to the existing base of cache directives. Both the new
- directive and the standard directive are supplied, such that
- applications which do not understand the new directive will default
- to the behavior specified by the standard directive, and those that
- understand the new directive will recognize it as modifying the
- requirements associated with the standard directive. In this way,
- extensions to the cache-control directives can be made without
- requiring changes to the base protocol.
-
- This extension mechanism depends on an HTTP cache obeying all of the
- cache-control directives defined for its native HTTP-version, obeying
- certain extensions, and ignoring all directives that it does not
- understand.
-
- For example, consider a hypothetical new response directive called
- community which acts as a modifier to the private directive. We
- define this new directive to mean that, in addition to any non-shared
- cache, any cache which is shared only by members of the community
- named within its value may cache the response. An origin server
- wishing to allow the UCI community to use an otherwise private
- response in their shared cache(s) could do so by including
-
- Cache-Control: private, community="UCI"
-
- A cache seeing this header field will act correctly even if the cache
- does not understand the community cache-extension, since it will also
- see and understand the private directive and thus default to the safe
- behavior.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 116]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Unrecognized cache-directives MUST be ignored; it is assumed that any
- cache-directive likely to be unrecognized by an HTTP/1.1 cache will
- be combined with standard directives (or the response's default
- cacheability) such that the cache behavior will remain minimally
- correct even if the cache does not understand the extension(s).
-
-14.10 Connection
-
- The Connection general-header field allows the sender to specify
- options that are desired for that particular connection and MUST NOT
- be communicated by proxies over further connections.
-
- The Connection header has the following grammar:
-
- Connection = "Connection" ":" 1#(connection-token)
- connection-token = token
-
- HTTP/1.1 proxies MUST parse the Connection header field before a
- message is forwarded and, for each connection-token in this field,
- remove any header field(s) from the message with the same name as the
- connection-token. Connection options are signaled by the presence of
- a connection-token in the Connection header field, not by any
- corresponding additional header field(s), since the additional header
- field may not be sent if there are no parameters associated with that
- connection option.
-
- Message headers listed in the Connection header MUST NOT include
- end-to-end headers, such as Cache-Control.
-
- HTTP/1.1 defines the "close" connection option for the sender to
- signal that the connection will be closed after completion of the
- response. For example,
-
- Connection: close
-
- in either the request or the response header fields indicates that
- the connection SHOULD NOT be considered `persistent' (section 8.1)
- after the current request/response is complete.
-
- HTTP/1.1 applications that do not support persistent connections MUST
- include the "close" connection option in every message.
-
- A system receiving an HTTP/1.0 (or lower-version) message that
- includes a Connection header MUST, for each connection-token in this
- field, remove and ignore any header field(s) from the message with
- the same name as the connection-token. This protects against mistaken
- forwarding of such header fields by pre-HTTP/1.1 proxies. See section
- 19.6.2.
-
-
-
-Fielding, et al. Standards Track [Page 117]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-14.11 Content-Encoding
-
- The Content-Encoding entity-header field is used as a modifier to the
- media-type. When present, its value indicates what additional content
- codings have been applied to the entity-body, and thus what decoding
- mechanisms must be applied in order to obtain the media-type
- referenced by the Content-Type header field. Content-Encoding is
- primarily used to allow a document to be compressed without losing
- the identity of its underlying media type.
-
- Content-Encoding = "Content-Encoding" ":" 1#content-coding
-
- Content codings are defined in section 3.5. An example of its use is
-
- Content-Encoding: gzip
-
- The content-coding is a characteristic of the entity identified by
- the Request-URI. Typically, the entity-body is stored with this
- encoding and is only decoded before rendering or analogous usage.
- However, a non-transparent proxy MAY modify the content-coding if the
- new coding is known to be acceptable to the recipient, unless the
- "no-transform" cache-control directive is present in the message.
-
- If the content-coding of an entity is not "identity", then the
- response MUST include a Content-Encoding entity-header (section
- 14.11) that lists the non-identity content-coding(s) used.
-
- If the content-coding of an entity in a request message is not
- acceptable to the origin server, the server SHOULD respond with a
- status code of 415 (Unsupported Media Type).
-
- If multiple encodings have been applied to an entity, the content
- codings MUST be listed in the order in which they were applied.
- Additional information about the encoding parameters MAY be provided
- by other entity-header fields not defined by this specification.
-
-14.12 Content-Language
-
- The Content-Language entity-header field describes the natural
- language(s) of the intended audience for the enclosed entity. Note
- that this might not be equivalent to all the languages used within
- the entity-body.
-
- Content-Language = "Content-Language" ":" 1#language-tag
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 118]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Language tags are defined in section 3.10. The primary purpose of
- Content-Language is to allow a user to identify and differentiate
- entities according to the user's own preferred language. Thus, if the
- body content is intended only for a Danish-literate audience, the
- appropriate field is
-
- Content-Language: da
-
- If no Content-Language is specified, the default is that the content
- is intended for all language audiences. This might mean that the
- sender does not consider it to be specific to any natural language,
- or that the sender does not know for which language it is intended.
-
- Multiple languages MAY be listed for content that is intended for
- multiple audiences. For example, a rendition of the "Treaty of
- Waitangi," presented simultaneously in the original Maori and English
- versions, would call for
-
- Content-Language: mi, en
-
- However, just because multiple languages are present within an entity
- does not mean that it is intended for multiple linguistic audiences.
- An example would be a beginner's language primer, such as "A First
- Lesson in Latin," which is clearly intended to be used by an
- English-literate audience. In this case, the Content-Language would
- properly only include "en".
-
- Content-Language MAY be applied to any media type -- it is not
- limited to textual documents.
-
-14.13 Content-Length
-
- The Content-Length entity-header field indicates the size of the
- entity-body, in decimal number of OCTETs, sent to the recipient or,
- in the case of the HEAD method, the size of the entity-body that
- would have been sent had the request been a GET.
-
- Content-Length = "Content-Length" ":" 1*DIGIT
-
- An example is
-
- Content-Length: 3495
-
- Applications SHOULD use this field to indicate the transfer-length of
- the message-body, unless this is prohibited by the rules in section
- 4.4.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 119]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Any Content-Length greater than or equal to zero is a valid value.
- Section 4.4 describes how to determine the length of a message-body
- if a Content-Length is not given.
-
- Note that the meaning of this field is significantly different from
- the corresponding definition in MIME, where it is an optional field
- used within the "message/external-body" content-type. In HTTP, it
- SHOULD be sent whenever the message's length can be determined prior
- to being transferred, unless this is prohibited by the rules in
- section 4.4.
-
-14.14 Content-Location
-
- The Content-Location entity-header field MAY be used to supply the
- resource location for the entity enclosed in the message when that
- entity is accessible from a location separate from the requested
- resource's URI. A server SHOULD provide a Content-Location for the
- variant corresponding to the response entity; especially in the case
- where a resource has multiple entities associated with it, and those
- entities actually have separate locations by which they might be
- individually accessed, the server SHOULD provide a Content-Location
- for the particular variant which is returned.
-
- Content-Location = "Content-Location" ":"
- ( absoluteURI | relativeURI )
-
- The value of Content-Location also defines the base URI for the
- entity.
-
- The Content-Location value is not a replacement for the original
- requested URI; it is only a statement of the location of the resource
- corresponding to this particular entity at the time of the request.
- Future requests MAY specify the Content-Location URI as the request-
- URI if the desire is to identify the source of that particular
- entity.
-
- A cache cannot assume that an entity with a Content-Location
- different from the URI used to retrieve it can be used to respond to
- later requests on that Content-Location URI. However, the Content-
- Location can be used to differentiate between multiple entities
- retrieved from a single requested resource, as described in section
- 13.6.
-
- If the Content-Location is a relative URI, the relative URI is
- interpreted relative to the Request-URI.
-
- The meaning of the Content-Location header in PUT or POST requests is
- undefined; servers are free to ignore it in those cases.
-
-
-
-Fielding, et al. Standards Track [Page 120]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-14.15 Content-MD5
-
- The Content-MD5 entity-header field, as defined in RFC 1864 [23], is
- an MD5 digest of the entity-body for the purpose of providing an
- end-to-end message integrity check (MIC) of the entity-body. (Note: a
- MIC is good for detecting accidental modification of the entity-body
- in transit, but is not proof against malicious attacks.)
-
- Content-MD5 = "Content-MD5" ":" md5-digest
- md5-digest = <base64 of 128 bit MD5 digest as per RFC 1864>
-
- The Content-MD5 header field MAY be generated by an origin server or
- client to function as an integrity check of the entity-body. Only
- origin servers or clients MAY generate the Content-MD5 header field;
- proxies and gateways MUST NOT generate it, as this would defeat its
- value as an end-to-end integrity check. Any recipient of the entity-
- body, including gateways and proxies, MAY check that the digest value
- in this header field matches that of the entity-body as received.
-
- The MD5 digest is computed based on the content of the entity-body,
- including any content-coding that has been applied, but not including
- any transfer-encoding applied to the message-body. If the message is
- received with a transfer-encoding, that encoding MUST be removed
- prior to checking the Content-MD5 value against the received entity.
-
- This has the result that the digest is computed on the octets of the
- entity-body exactly as, and in the order that, they would be sent if
- no transfer-encoding were being applied.
-
- HTTP extends RFC 1864 to permit the digest to be computed for MIME
- composite media-types (e.g., multipart/* and message/rfc822), but
- this does not change how the digest is computed as defined in the
- preceding paragraph.
-
- There are several consequences of this. The entity-body for composite
- types MAY contain many body-parts, each with its own MIME and HTTP
- headers (including Content-MD5, Content-Transfer-Encoding, and
- Content-Encoding headers). If a body-part has a Content-Transfer-
- Encoding or Content-Encoding header, it is assumed that the content
- of the body-part has had the encoding applied, and the body-part is
- included in the Content-MD5 digest as is -- i.e., after the
- application. The Transfer-Encoding header field is not allowed within
- body-parts.
-
- Conversion of all line breaks to CRLF MUST NOT be done before
- computing or checking the digest: the line break convention used in
- the text actually transmitted MUST be left unaltered when computing
- the digest.
-
-
-
-Fielding, et al. Standards Track [Page 121]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Note: while the definition of Content-MD5 is exactly the same for
- HTTP as in RFC 1864 for MIME entity-bodies, there are several ways
- in which the application of Content-MD5 to HTTP entity-bodies
- differs from its application to MIME entity-bodies. One is that
- HTTP, unlike MIME, does not use Content-Transfer-Encoding, and
- does use Transfer-Encoding and Content-Encoding. Another is that
- HTTP more frequently uses binary content types than MIME, so it is
- worth noting that, in such cases, the byte order used to compute
- the digest is the transmission byte order defined for the type.
- Lastly, HTTP allows transmission of text types with any of several
- line break conventions and not just the canonical form using CRLF.
-
-14.16 Content-Range
-
- The Content-Range entity-header is sent with a partial entity-body to
- specify where in the full entity-body the partial body should be
- applied. Range units are defined in section 3.12.
-
- Content-Range = "Content-Range" ":" content-range-spec
-
- content-range-spec = byte-content-range-spec
- byte-content-range-spec = bytes-unit SP
- byte-range-resp-spec "/"
- ( instance-length | "*" )
-
- byte-range-resp-spec = (first-byte-pos "-" last-byte-pos)
- | "*"
- instance-length = 1*DIGIT
-
- The header SHOULD indicate the total length of the full entity-body,
- unless this length is unknown or difficult to determine. The asterisk
- "*" character means that the instance-length is unknown at the time
- when the response was generated.
-
- Unlike byte-ranges-specifier values (see section 14.35.1), a byte-
- range-resp-spec MUST only specify one range, and MUST contain
- absolute byte positions for both the first and last byte of the
- range.
-
- A byte-content-range-spec with a byte-range-resp-spec whose last-
- byte-pos value is less than its first-byte-pos value, or whose
- instance-length value is less than or equal to its last-byte-pos
- value, is invalid. The recipient of an invalid byte-content-range-
- spec MUST ignore it and any content transferred along with it.
-
- A server sending a response with status code 416 (Requested range not
- satisfiable) SHOULD include a Content-Range field with a byte-range-
- resp-spec of "*". The instance-length specifies the current length of
-
-
-
-Fielding, et al. Standards Track [Page 122]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- the selected resource. A response with status code 206 (Partial
- Content) MUST NOT include a Content-Range field with a byte-range-
- resp-spec of "*".
-
- Examples of byte-content-range-spec values, assuming that the entity
- contains a total of 1234 bytes:
-
- . The first 500 bytes:
- bytes 0-499/1234
-
- . The second 500 bytes:
- bytes 500-999/1234
-
- . All except for the first 500 bytes:
- bytes 500-1233/1234
-
- . The last 500 bytes:
- bytes 734-1233/1234
-
- When an HTTP message includes the content of a single range (for
- example, a response to a request for a single range, or to a request
- for a set of ranges that overlap without any holes), this content is
- transmitted with a Content-Range header, and a Content-Length header
- showing the number of bytes actually transferred. For example,
-
- HTTP/1.1 206 Partial content
- Date: Wed, 15 Nov 1995 06:25:24 GMT
- Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
- Content-Range: bytes 21010-47021/47022
- Content-Length: 26012
- Content-Type: image/gif
-
- When an HTTP message includes the content of multiple ranges (for
- example, a response to a request for multiple non-overlapping
- ranges), these are transmitted as a multipart message. The multipart
- media type used for this purpose is "multipart/byteranges" as defined
- in appendix 19.2. See appendix 19.6.3 for a compatibility issue.
-
- A response to a request for a single range MUST NOT be sent using the
- multipart/byteranges media type. A response to a request for
- multiple ranges, whose result is a single range, MAY be sent as a
- multipart/byteranges media type with one part. A client that cannot
- decode a multipart/byteranges message MUST NOT ask for multiple
- byte-ranges in a single request.
-
- When a client requests multiple byte-ranges in one request, the
- server SHOULD return them in the order that they appeared in the
- request.
-
-
-
-Fielding, et al. Standards Track [Page 123]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- If the server ignores a byte-range-spec because it is syntactically
- invalid, the server SHOULD treat the request as if the invalid Range
- header field did not exist. (Normally, this means return a 200
- response containing the full entity).
-
- If the server receives a request (other than one including an If-
- Range request-header field) with an unsatisfiable Range request-
- header field (that is, all of whose byte-range-spec values have a
- first-byte-pos value greater than the current length of the selected
- resource), it SHOULD return a response code of 416 (Requested range
- not satisfiable) (section 10.4.17).
-
- Note: clients cannot depend on servers to send a 416 (Requested
- range not satisfiable) response instead of a 200 (OK) response for
- an unsatisfiable Range request-header, since not all servers
- implement this request-header.
-
-14.17 Content-Type
-
- The Content-Type entity-header field indicates the media type of the
- entity-body sent to the recipient or, in the case of the HEAD method,
- the media type that would have been sent had the request been a GET.
-
- Content-Type = "Content-Type" ":" media-type
-
- Media types are defined in section 3.7. An example of the field is
-
- Content-Type: text/html; charset=ISO-8859-4
-
- Further discussion of methods for identifying the media type of an
- entity is provided in section 7.2.1.
-
-14.18 Date
-
- The Date general-header field represents the date and time at which
- the message was originated, having the same semantics as orig-date in
- RFC 822. The field value is an HTTP-date, as described in section
- 3.3.1; it MUST be sent in RFC 1123 [8]-date format.
-
- Date = "Date" ":" HTTP-date
-
- An example is
-
- Date: Tue, 15 Nov 1994 08:12:31 GMT
-
- Origin servers MUST include a Date header field in all responses,
- except in these cases:
-
-
-
-
-Fielding, et al. Standards Track [Page 124]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- 1. If the response status code is 100 (Continue) or 101 (Switching
- Protocols), the response MAY include a Date header field, at
- the server's option.
-
- 2. If the response status code conveys a server error, e.g. 500
- (Internal Server Error) or 503 (Service Unavailable), and it is
- inconvenient or impossible to generate a valid Date.
-
- 3. If the server does not have a clock that can provide a
- reasonable approximation of the current time, its responses
- MUST NOT include a Date header field. In this case, the rules
- in section 14.18.1 MUST be followed.
-
- A received message that does not have a Date header field MUST be
- assigned one by the recipient if the message will be cached by that
- recipient or gatewayed via a protocol which requires a Date. An HTTP
- implementation without a clock MUST NOT cache responses without
- revalidating them on every use. An HTTP cache, especially a shared
- cache, SHOULD use a mechanism, such as NTP [28], to synchronize its
- clock with a reliable external standard.
-
- Clients SHOULD only send a Date header field in messages that include
- an entity-body, as in the case of the PUT and POST requests, and even
- then it is optional. A client without a clock MUST NOT send a Date
- header field in a request.
-
- The HTTP-date sent in a Date header SHOULD NOT represent a date and
- time subsequent to the generation of the message. It SHOULD represent
- the best available approximation of the date and time of message
- generation, unless the implementation has no means of generating a
- reasonably accurate date and time. In theory, the date ought to
- represent the moment just before the entity is generated. In
- practice, the date can be generated at any time during the message
- origination without affecting its semantic value.
-
-14.18.1 Clockless Origin Server Operation
-
- Some origin server implementations might not have a clock available.
- An origin server without a clock MUST NOT assign Expires or Last-
- Modified values to a response, unless these values were associated
- with the resource by a system or user with a reliable clock. It MAY
- assign an Expires value that is known, at or before server
- configuration time, to be in the past (this allows "pre-expiration"
- of responses without storing separate Expires values for each
- resource).
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 125]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-14.19 ETag
-
- The ETag response-header field provides the current value of the
- entity tag for the requested variant. The headers used with entity
- tags are described in sections 14.24, 14.26 and 14.44. The entity tag
- MAY be used for comparison with other entities from the same resource
- (see section 13.3.3).
-
- ETag = "ETag" ":" entity-tag
-
- Examples:
-
- ETag: "xyzzy"
- ETag: W/"xyzzy"
- ETag: ""
-
-14.20 Expect
-
- The Expect request-header field is used to indicate that particular
- server behaviors are required by the client.
-
- Expect = "Expect" ":" 1#expectation
-
- expectation = "100-continue" | expectation-extension
- expectation-extension = token [ "=" ( token | quoted-string )
- *expect-params ]
- expect-params = ";" token [ "=" ( token | quoted-string ) ]
-
-
- A server that does not understand or is unable to comply with any of
- the expectation values in the Expect field of a request MUST respond
- with appropriate error status. The server MUST respond with a 417
- (Expectation Failed) status if any of the expectations cannot be met
- or, if there are other problems with the request, some other 4xx
- status.
-
- This header field is defined with extensible syntax to allow for
- future extensions. If a server receives a request containing an
- Expect field that includes an expectation-extension that it does not
- support, it MUST respond with a 417 (Expectation Failed) status.
-
- Comparison of expectation values is case-insensitive for unquoted
- tokens (including the 100-continue token), and is case-sensitive for
- quoted-string expectation-extensions.
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 126]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- The Expect mechanism is hop-by-hop: that is, an HTTP/1.1 proxy MUST
- return a 417 (Expectation Failed) status if it receives a request
- with an expectation that it cannot meet. However, the Expect
- request-header itself is end-to-end; it MUST be forwarded if the
- request is forwarded.
-
- Many older HTTP/1.0 and HTTP/1.1 applications do not understand the
- Expect header.
-
- See section 8.2.3 for the use of the 100 (continue) status.
-
-14.21 Expires
-
- The Expires entity-header field gives the date/time after which the
- response is considered stale. A stale cache entry may not normally be
- returned by a cache (either a proxy cache or a user agent cache)
- unless it is first validated with the origin server (or with an
- intermediate cache that has a fresh copy of the entity). See section
- 13.2 for further discussion of the expiration model.
-
- The presence of an Expires field does not imply that the original
- resource will change or cease to exist at, before, or after that
- time.
-
- The format is an absolute date and time as defined by HTTP-date in
- section 3.3.1; it MUST be in RFC 1123 date format:
-
- Expires = "Expires" ":" HTTP-date
-
- An example of its use is
-
- Expires: Thu, 01 Dec 1994 16:00:00 GMT
-
- Note: if a response includes a Cache-Control field with the max-
- age directive (see section 14.9.3), that directive overrides the
- Expires field.
-
- HTTP/1.1 clients and caches MUST treat other invalid date formats,
- especially including the value "0", as in the past (i.e., "already
- expired").
-
- To mark a response as "already expired," an origin server sends an
- Expires date that is equal to the Date header value. (See the rules
- for expiration calculations in section 13.2.4.)
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 127]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- To mark a response as "never expires," an origin server sends an
- Expires date approximately one year from the time the response is
- sent. HTTP/1.1 servers SHOULD NOT send Expires dates more than one
- year in the future.
-
- The presence of an Expires header field with a date value of some
- time in the future on a response that otherwise would by default be
- non-cacheable indicates that the response is cacheable, unless
- indicated otherwise by a Cache-Control header field (section 14.9).
-
-14.22 From
-
- The From request-header field, if given, SHOULD contain an Internet
- e-mail address for the human user who controls the requesting user
- agent. The address SHOULD be machine-usable, as defined by "mailbox"
- in RFC 822 [9] as updated by RFC 1123 [8]:
-
- From = "From" ":" mailbox
-
- An example is:
-
- From: webmaster@w3.org
-
- This header field MAY be used for logging purposes and as a means for
- identifying the source of invalid or unwanted requests. It SHOULD NOT
- be used as an insecure form of access protection. The interpretation
- of this field is that the request is being performed on behalf of the
- person given, who accepts responsibility for the method performed. In
- particular, robot agents SHOULD include this header so that the
- person responsible for running the robot can be contacted if problems
- occur on the receiving end.
-
- The Internet e-mail address in this field MAY be separate from the
- Internet host which issued the request. For example, when a request
- is passed through a proxy the original issuer's address SHOULD be
- used.
-
- The client SHOULD NOT send the From header field without the user's
- approval, as it might conflict with the user's privacy interests or
- their site's security policy. It is strongly recommended that the
- user be able to disable, enable, and modify the value of this field
- at any time prior to a request.
-
-14.23 Host
-
- The Host request-header field specifies the Internet host and port
- number of the resource being requested, as obtained from the original
- URI given by the user or referring resource (generally an HTTP URL,
-
-
-
-Fielding, et al. Standards Track [Page 128]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- as described in section 3.2.2). The Host field value MUST represent
- the naming authority of the origin server or gateway given by the
- original URL. This allows the origin server or gateway to
- differentiate between internally-ambiguous URLs, such as the root "/"
- URL of a server for multiple host names on a single IP address.
-
- Host = "Host" ":" host [ ":" port ] ; Section 3.2.2
-
- A "host" without any trailing port information implies the default
- port for the service requested (e.g., "80" for an HTTP URL). For
- example, a request on the origin server for
- <http://www.w3.org/pub/WWW/> would properly include:
-
- GET /pub/WWW/ HTTP/1.1
- Host: www.w3.org
-
- A client MUST include a Host header field in all HTTP/1.1 request
- messages . If the requested URI does not include an Internet host
- name for the service being requested, then the Host header field MUST
- be given with an empty value. An HTTP/1.1 proxy MUST ensure that any
- request message it forwards does contain an appropriate Host header
- field that identifies the service being requested by the proxy. All
- Internet-based HTTP/1.1 servers MUST respond with a 400 (Bad Request)
- status code to any HTTP/1.1 request message which lacks a Host header
- field.
-
- See sections 5.2 and 19.6.1.1 for other requirements relating to
- Host.
-
-14.24 If-Match
-
- The If-Match request-header field is used with a method to make it
- conditional. A client that has one or more entities previously
- obtained from the resource can verify that one of those entities is
- current by including a list of their associated entity tags in the
- If-Match header field. Entity tags are defined in section 3.11. The
- purpose of this feature is to allow efficient updates of cached
- information with a minimum amount of transaction overhead. It is also
- used, on updating requests, to prevent inadvertent modification of
- the wrong version of a resource. As a special case, the value "*"
- matches any current entity of the resource.
-
- If-Match = "If-Match" ":" ( "*" | 1#entity-tag )
-
- If any of the entity tags match the entity tag of the entity that
- would have been returned in the response to a similar GET request
- (without the If-Match header) on that resource, or if "*" is given
-
-
-
-
-Fielding, et al. Standards Track [Page 129]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- and any current entity exists for that resource, then the server MAY
- perform the requested method as if the If-Match header field did not
- exist.
-
- A server MUST use the strong comparison function (see section 13.3.3)
- to compare the entity tags in If-Match.
-
- If none of the entity tags match, or if "*" is given and no current
- entity exists, the server MUST NOT perform the requested method, and
- MUST return a 412 (Precondition Failed) response. This behavior is
- most useful when the client wants to prevent an updating method, such
- as PUT, from modifying a resource that has changed since the client
- last retrieved it.
-
- If the request would, without the If-Match header field, result in
- anything other than a 2xx or 412 status, then the If-Match header
- MUST be ignored.
-
- The meaning of "If-Match: *" is that the method SHOULD be performed
- if the representation selected by the origin server (or by a cache,
- possibly using the Vary mechanism, see section 14.44) exists, and
- MUST NOT be performed if the representation does not exist.
-
- A request intended to update a resource (e.g., a PUT) MAY include an
- If-Match header field to signal that the request method MUST NOT be
- applied if the entity corresponding to the If-Match value (a single
- entity tag) is no longer a representation of that resource. This
- allows the user to indicate that they do not wish the request to be
- successful if the resource has been changed without their knowledge.
- Examples:
-
- If-Match: "xyzzy"
- If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
- If-Match: *
-
- The result of a request having both an If-Match header field and
- either an If-None-Match or an If-Modified-Since header fields is
- undefined by this specification.
-
-14.25 If-Modified-Since
-
- The If-Modified-Since request-header field is used with a method to
- make it conditional: if the requested variant has not been modified
- since the time specified in this field, an entity will not be
- returned from the server; instead, a 304 (not modified) response will
- be returned without any message-body.
-
- If-Modified-Since = "If-Modified-Since" ":" HTTP-date
-
-
-
-Fielding, et al. Standards Track [Page 130]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- An example of the field is:
-
- If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT
-
- A GET method with an If-Modified-Since header and no Range header
- requests that the identified entity be transferred only if it has
- been modified since the date given by the If-Modified-Since header.
- The algorithm for determining this includes the following cases:
-
- a) If the request would normally result in anything other than a
- 200 (OK) status, or if the passed If-Modified-Since date is
- invalid, the response is exactly the same as for a normal GET.
- A date which is later than the server's current time is
- invalid.
-
- b) If the variant has been modified since the If-Modified-Since
- date, the response is exactly the same as for a normal GET.
-
- c) If the variant has not been modified since a valid If-
- Modified-Since date, the server SHOULD return a 304 (Not
- Modified) response.
-
- The purpose of this feature is to allow efficient updates of cached
- information with a minimum amount of transaction overhead.
-
- Note: The Range request-header field modifies the meaning of If-
- Modified-Since; see section 14.35 for full details.
-
- Note: If-Modified-Since times are interpreted by the server, whose
- clock might not be synchronized with the client.
-
- Note: When handling an If-Modified-Since header field, some
- servers will use an exact date comparison function, rather than a
- less-than function, for deciding whether to send a 304 (Not
- Modified) response. To get best results when sending an If-
- Modified-Since header field for cache validation, clients are
- advised to use the exact date string received in a previous Last-
- Modified header field whenever possible.
-
- Note: If a client uses an arbitrary date in the If-Modified-Since
- header instead of a date taken from the Last-Modified header for
- the same request, the client should be aware of the fact that this
- date is interpreted in the server's understanding of time. The
- client should consider unsynchronized clocks and rounding problems
- due to the different encodings of time between the client and
- server. This includes the possibility of race conditions if the
- document has changed between the time it was first requested and
- the If-Modified-Since date of a subsequent request, and the
-
-
-
-Fielding, et al. Standards Track [Page 131]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- possibility of clock-skew-related problems if the If-Modified-
- Since date is derived from the client's clock without correction
- to the server's clock. Corrections for different time bases
- between client and server are at best approximate due to network
- latency.
-
- The result of a request having both an If-Modified-Since header field
- and either an If-Match or an If-Unmodified-Since header fields is
- undefined by this specification.
-
-14.26 If-None-Match
-
- The If-None-Match request-header field is used with a method to make
- it conditional. A client that has one or more entities previously
- obtained from the resource can verify that none of those entities is
- current by including a list of their associated entity tags in the
- If-None-Match header field. The purpose of this feature is to allow
- efficient updates of cached information with a minimum amount of
- transaction overhead. It is also used to prevent a method (e.g. PUT)
- from inadvertently modifying an existing resource when the client
- believes that the resource does not exist.
-
- As a special case, the value "*" matches any current entity of the
- resource.
-
- If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag )
-
- If any of the entity tags match the entity tag of the entity that
- would have been returned in the response to a similar GET request
- (without the If-None-Match header) on that resource, or if "*" is
- given and any current entity exists for that resource, then the
- server MUST NOT perform the requested method, unless required to do
- so because the resource's modification date fails to match that
- supplied in an If-Modified-Since header field in the request.
- Instead, if the request method was GET or HEAD, the server SHOULD
- respond with a 304 (Not Modified) response, including the cache-
- related header fields (particularly ETag) of one of the entities that
- matched. For all other request methods, the server MUST respond with
- a status of 412 (Precondition Failed).
-
- See section 13.3.3 for rules on how to determine if two entities tags
- match. The weak comparison function can only be used with GET or HEAD
- requests.
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 132]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- If none of the entity tags match, then the server MAY perform the
- requested method as if the If-None-Match header field did not exist,
- but MUST also ignore any If-Modified-Since header field(s) in the
- request. That is, if no entity tags match, then the server MUST NOT
- return a 304 (Not Modified) response.
-
- If the request would, without the If-None-Match header field, result
- in anything other than a 2xx or 304 status, then the If-None-Match
- header MUST be ignored. (See section 13.3.4 for a discussion of
- server behavior when both If-Modified-Since and If-None-Match appear
- in the same request.)
-
- The meaning of "If-None-Match: *" is that the method MUST NOT be
- performed if the representation selected by the origin server (or by
- a cache, possibly using the Vary mechanism, see section 14.44)
- exists, and SHOULD be performed if the representation does not exist.
- This feature is intended to be useful in preventing races between PUT
- operations.
-
- Examples:
-
- If-None-Match: "xyzzy"
- If-None-Match: W/"xyzzy"
- If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
- If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz"
- If-None-Match: *
-
- The result of a request having both an If-None-Match header field and
- either an If-Match or an If-Unmodified-Since header fields is
- undefined by this specification.
-
-14.27 If-Range
-
- If a client has a partial copy of an entity in its cache, and wishes
- to have an up-to-date copy of the entire entity in its cache, it
- could use the Range request-header with a conditional GET (using
- either or both of If-Unmodified-Since and If-Match.) However, if the
- condition fails because the entity has been modified, the client
- would then have to make a second request to obtain the entire current
- entity-body.
-
- The If-Range header allows a client to "short-circuit" the second
- request. Informally, its meaning is `if the entity is unchanged, send
- me the part(s) that I am missing; otherwise, send me the entire new
- entity'.
-
- If-Range = "If-Range" ":" ( entity-tag | HTTP-date )
-
-
-
-
-Fielding, et al. Standards Track [Page 133]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- If the client has no entity tag for an entity, but does have a Last-
- Modified date, it MAY use that date in an If-Range header. (The
- server can distinguish between a valid HTTP-date and any form of
- entity-tag by examining no more than two characters.) The If-Range
- header SHOULD only be used together with a Range header, and MUST be
- ignored if the request does not include a Range header, or if the
- server does not support the sub-range operation.
-
- If the entity tag given in the If-Range header matches the current
- entity tag for the entity, then the server SHOULD provide the
- specified sub-range of the entity using a 206 (Partial content)
- response. If the entity tag does not match, then the server SHOULD
- return the entire entity using a 200 (OK) response.
-
-14.28 If-Unmodified-Since
-
- The If-Unmodified-Since request-header field is used with a method to
- make it conditional. If the requested resource has not been modified
- since the time specified in this field, the server SHOULD perform the
- requested operation as if the If-Unmodified-Since header were not
- present.
-
- If the requested variant has been modified since the specified time,
- the server MUST NOT perform the requested operation, and MUST return
- a 412 (Precondition Failed).
-
- If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date
-
- An example of the field is:
-
- If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT
-
- If the request normally (i.e., without the If-Unmodified-Since
- header) would result in anything other than a 2xx or 412 status, the
- If-Unmodified-Since header SHOULD be ignored.
-
- If the specified date is invalid, the header is ignored.
-
- The result of a request having both an If-Unmodified-Since header
- field and either an If-None-Match or an If-Modified-Since header
- fields is undefined by this specification.
-
-14.29 Last-Modified
-
- The Last-Modified entity-header field indicates the date and time at
- which the origin server believes the variant was last modified.
-
- Last-Modified = "Last-Modified" ":" HTTP-date
-
-
-
-Fielding, et al. Standards Track [Page 134]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- An example of its use is
-
- Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
-
- The exact meaning of this header field depends on the implementation
- of the origin server and the nature of the original resource. For
- files, it may be just the file system last-modified time. For
- entities with dynamically included parts, it may be the most recent
- of the set of last-modify times for its component parts. For database
- gateways, it may be the last-update time stamp of the record. For
- virtual objects, it may be the last time the internal state changed.
-
- An origin server MUST NOT send a Last-Modified date which is later
- than the server's time of message origination. In such cases, where
- the resource's last modification would indicate some time in the
- future, the server MUST replace that date with the message
- origination date.
-
- An origin server SHOULD obtain the Last-Modified value of the entity
- as close as possible to the time that it generates the Date value of
- its response. This allows a recipient to make an accurate assessment
- of the entity's modification time, especially if the entity changes
- near the time that the response is generated.
-
- HTTP/1.1 servers SHOULD send Last-Modified whenever feasible.
-
-14.30 Location
-
- The Location response-header field is used to redirect the recipient
- to a location other than the Request-URI for completion of the
- request or identification of a new resource. For 201 (Created)
- responses, the Location is that of the new resource which was created
- by the request. For 3xx responses, the location SHOULD indicate the
- server's preferred URI for automatic redirection to the resource. The
- field value consists of a single absolute URI.
-
- Location = "Location" ":" absoluteURI
-
- An example is:
-
- Location: http://www.w3.org/pub/WWW/People.html
-
- Note: The Content-Location header field (section 14.14) differs
- from Location in that the Content-Location identifies the original
- location of the entity enclosed in the request. It is therefore
- possible for a response to contain header fields for both Location
- and Content-Location. Also see section 13.10 for cache
- requirements of some methods.
-
-
-
-Fielding, et al. Standards Track [Page 135]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-14.31 Max-Forwards
-
- The Max-Forwards request-header field provides a mechanism with the
- TRACE (section 9.8) and OPTIONS (section 9.2) methods to limit the
- number of proxies or gateways that can forward the request to the
- next inbound server. This can be useful when the client is attempting
- to trace a request chain which appears to be failing or looping in
- mid-chain.
-
- Max-Forwards = "Max-Forwards" ":" 1*DIGIT
-
- The Max-Forwards value is a decimal integer indicating the remaining
- number of times this request message may be forwarded.
-
- Each proxy or gateway recipient of a TRACE or OPTIONS request
- containing a Max-Forwards header field MUST check and update its
- value prior to forwarding the request. If the received value is zero
- (0), the recipient MUST NOT forward the request; instead, it MUST
- respond as the final recipient. If the received Max-Forwards value is
- greater than zero, then the forwarded message MUST contain an updated
- Max-Forwards field with a value decremented by one (1).
-
- The Max-Forwards header field MAY be ignored for all other methods
- defined by this specification and for any extension methods for which
- it is not explicitly referred to as part of that method definition.
-
-14.32 Pragma
-
- The Pragma general-header field is used to include implementation-
- specific directives that might apply to any recipient along the
- request/response chain. All pragma directives specify optional
- behavior from the viewpoint of the protocol; however, some systems
- MAY require that behavior be consistent with the directives.
-
- Pragma = "Pragma" ":" 1#pragma-directive
- pragma-directive = "no-cache" | extension-pragma
- extension-pragma = token [ "=" ( token | quoted-string ) ]
-
- When the no-cache directive is present in a request message, an
- application SHOULD forward the request toward the origin server even
- if it has a cached copy of what is being requested. This pragma
- directive has the same semantics as the no-cache cache-directive (see
- section 14.9) and is defined here for backward compatibility with
- HTTP/1.0. Clients SHOULD include both header fields when a no-cache
- request is sent to a server not known to be HTTP/1.1 compliant.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 136]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Pragma directives MUST be passed through by a proxy or gateway
- application, regardless of their significance to that application,
- since the directives might be applicable to all recipients along the
- request/response chain. It is not possible to specify a pragma for a
- specific recipient; however, any pragma directive not relevant to a
- recipient SHOULD be ignored by that recipient.
-
- HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had
- sent "Cache-Control: no-cache". No new Pragma directives will be
- defined in HTTP.
-
- Note: because the meaning of "Pragma: no-cache as a response
- header field is not actually specified, it does not provide a
- reliable replacement for "Cache-Control: no-cache" in a response
-
-14.33 Proxy-Authenticate
-
- The Proxy-Authenticate response-header field MUST be included as part
- of a 407 (Proxy Authentication Required) response. The field value
- consists of a challenge that indicates the authentication scheme and
- parameters applicable to the proxy for this Request-URI.
-
- Proxy-Authenticate = "Proxy-Authenticate" ":" 1#challenge
-
- The HTTP access authentication process is described in "HTTP
- Authentication: Basic and Digest Access Authentication" [43]. Unlike
- WWW-Authenticate, the Proxy-Authenticate header field applies only to
- the current connection and SHOULD NOT be passed on to downstream
- clients. However, an intermediate proxy might need to obtain its own
- credentials by requesting them from the downstream client, which in
- some circumstances will appear as if the proxy is forwarding the
- Proxy-Authenticate header field.
-
-14.34 Proxy-Authorization
-
- The Proxy-Authorization request-header field allows the client to
- identify itself (or its user) to a proxy which requires
- authentication. The Proxy-Authorization field value consists of
- credentials containing the authentication information of the user
- agent for the proxy and/or realm of the resource being requested.
-
- Proxy-Authorization = "Proxy-Authorization" ":" credentials
-
- The HTTP access authentication process is described in "HTTP
- Authentication: Basic and Digest Access Authentication" [43] . Unlike
- Authorization, the Proxy-Authorization header field applies only to
- the next outbound proxy that demanded authentication using the Proxy-
- Authenticate field. When multiple proxies are used in a chain, the
-
-
-
-Fielding, et al. Standards Track [Page 137]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Proxy-Authorization header field is consumed by the first outbound
- proxy that was expecting to receive credentials. A proxy MAY relay
- the credentials from the client request to the next proxy if that is
- the mechanism by which the proxies cooperatively authenticate a given
- request.
-
-14.35 Range
-
-14.35.1 Byte Ranges
-
- Since all HTTP entities are represented in HTTP messages as sequences
- of bytes, the concept of a byte range is meaningful for any HTTP
- entity. (However, not all clients and servers need to support byte-
- range operations.)
-
- Byte range specifications in HTTP apply to the sequence of bytes in
- the entity-body (not necessarily the same as the message-body).
-
- A byte range operation MAY specify a single range of bytes, or a set
- of ranges within a single entity.
-
- ranges-specifier = byte-ranges-specifier
- byte-ranges-specifier = bytes-unit "=" byte-range-set
- byte-range-set = 1#( byte-range-spec | suffix-byte-range-spec )
- byte-range-spec = first-byte-pos "-" [last-byte-pos]
- first-byte-pos = 1*DIGIT
- last-byte-pos = 1*DIGIT
-
- The first-byte-pos value in a byte-range-spec gives the byte-offset
- of the first byte in a range. The last-byte-pos value gives the
- byte-offset of the last byte in the range; that is, the byte
- positions specified are inclusive. Byte offsets start at zero.
-
- If the last-byte-pos value is present, it MUST be greater than or
- equal to the first-byte-pos in that byte-range-spec, or the byte-
- range-spec is syntactically invalid. The recipient of a byte-range-
- set that includes one or more syntactically invalid byte-range-spec
- values MUST ignore the header field that includes that byte-range-
- set.
-
- If the last-byte-pos value is absent, or if the value is greater than
- or equal to the current length of the entity-body, last-byte-pos is
- taken to be equal to one less than the current length of the entity-
- body in bytes.
-
- By its choice of last-byte-pos, a client can limit the number of
- bytes retrieved without knowing the size of the entity.
-
-
-
-
-Fielding, et al. Standards Track [Page 138]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- suffix-byte-range-spec = "-" suffix-length
- suffix-length = 1*DIGIT
-
- A suffix-byte-range-spec is used to specify the suffix of the
- entity-body, of a length given by the suffix-length value. (That is,
- this form specifies the last N bytes of an entity-body.) If the
- entity is shorter than the specified suffix-length, the entire
- entity-body is used.
-
- If a syntactically valid byte-range-set includes at least one byte-
- range-spec whose first-byte-pos is less than the current length of
- the entity-body, or at least one suffix-byte-range-spec with a non-
- zero suffix-length, then the byte-range-set is satisfiable.
- Otherwise, the byte-range-set is unsatisfiable. If the byte-range-set
- is unsatisfiable, the server SHOULD return a response with a status
- of 416 (Requested range not satisfiable). Otherwise, the server
- SHOULD return a response with a status of 206 (Partial Content)
- containing the satisfiable ranges of the entity-body.
-
- Examples of byte-ranges-specifier values (assuming an entity-body of
- length 10000):
-
- - The first 500 bytes (byte offsets 0-499, inclusive): bytes=0-
- 499
-
- - The second 500 bytes (byte offsets 500-999, inclusive):
- bytes=500-999
-
- - The final 500 bytes (byte offsets 9500-9999, inclusive):
- bytes=-500
-
- - Or bytes=9500-
-
- - The first and last bytes only (bytes 0 and 9999): bytes=0-0,-1
-
- - Several legal but not canonical specifications of the second 500
- bytes (byte offsets 500-999, inclusive):
- bytes=500-600,601-999
- bytes=500-700,601-999
-
-14.35.2 Range Retrieval Requests
-
- HTTP retrieval requests using conditional or unconditional GET
- methods MAY request one or more sub-ranges of the entity, instead of
- the entire entity, using the Range request header, which applies to
- the entity returned as the result of the request:
-
- Range = "Range" ":" ranges-specifier
-
-
-
-Fielding, et al. Standards Track [Page 139]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- A server MAY ignore the Range header. However, HTTP/1.1 origin
- servers and intermediate caches ought to support byte ranges when
- possible, since Range supports efficient recovery from partially
- failed transfers, and supports efficient partial retrieval of large
- entities.
-
- If the server supports the Range header and the specified range or
- ranges are appropriate for the entity:
-
- - The presence of a Range header in an unconditional GET modifies
- what is returned if the GET is otherwise successful. In other
- words, the response carries a status code of 206 (Partial
- Content) instead of 200 (OK).
-
- - The presence of a Range header in a conditional GET (a request
- using one or both of If-Modified-Since and If-None-Match, or
- one or both of If-Unmodified-Since and If-Match) modifies what
- is returned if the GET is otherwise successful and the
- condition is true. It does not affect the 304 (Not Modified)
- response returned if the conditional is false.
-
- In some cases, it might be more appropriate to use the If-Range
- header (see section 14.27) in addition to the Range header.
-
- If a proxy that supports ranges receives a Range request, forwards
- the request to an inbound server, and receives an entire entity in
- reply, it SHOULD only return the requested range to its client. It
- SHOULD store the entire received response in its cache if that is
- consistent with its cache allocation policies.
-
-14.36 Referer
-
- The Referer[sic] request-header field allows the client to specify,
- for the server's benefit, the address (URI) of the resource from
- which the Request-URI was obtained (the "referrer", although the
- header field is misspelled.) The Referer request-header allows a
- server to generate lists of back-links to resources for interest,
- logging, optimized caching, etc. It also allows obsolete or mistyped
- links to be traced for maintenance. The Referer field MUST NOT be
- sent if the Request-URI was obtained from a source that does not have
- its own URI, such as input from the user keyboard.
-
- Referer = "Referer" ":" ( absoluteURI | relativeURI )
-
- Example:
-
- Referer: http://www.w3.org/hypertext/DataSources/Overview.html
-
-
-
-
-Fielding, et al. Standards Track [Page 140]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- If the field value is a relative URI, it SHOULD be interpreted
- relative to the Request-URI. The URI MUST NOT include a fragment. See
- section 15.1.3 for security considerations.
-
-14.37 Retry-After
-
- The Retry-After response-header field can be used with a 503 (Service
- Unavailable) response to indicate how long the service is expected to
- be unavailable to the requesting client. This field MAY also be used
- with any 3xx (Redirection) response to indicate the minimum time the
- user-agent is asked wait before issuing the redirected request. The
- value of this field can be either an HTTP-date or an integer number
- of seconds (in decimal) after the time of the response.
-
- Retry-After = "Retry-After" ":" ( HTTP-date | delta-seconds )
-
- Two examples of its use are
-
- Retry-After: Fri, 31 Dec 1999 23:59:59 GMT
- Retry-After: 120
-
- In the latter example, the delay is 2 minutes.
-
-14.38 Server
-
- The Server response-header field contains information about the
- software used by the origin server to handle the request. The field
- can contain multiple product tokens (section 3.8) and comments
- identifying the server and any significant subproducts. The product
- tokens are listed in order of their significance for identifying the
- application.
-
- Server = "Server" ":" 1*( product | comment )
-
- Example:
-
- Server: CERN/3.0 libwww/2.17
-
- If the response is being forwarded through a proxy, the proxy
- application MUST NOT modify the Server response-header. Instead, it
- SHOULD include a Via field (as described in section 14.45).
-
- Note: Revealing the specific software version of the server might
- allow the server machine to become more vulnerable to attacks
- against software that is known to contain security holes. Server
- implementors are encouraged to make this field a configurable
- option.
-
-
-
-
-Fielding, et al. Standards Track [Page 141]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-14.39 TE
-
- The TE request-header field indicates what extension transfer-codings
- it is willing to accept in the response and whether or not it is
- willing to accept trailer fields in a chunked transfer-coding. Its
- value may consist of the keyword "trailers" and/or a comma-separated
- list of extension transfer-coding names with optional accept
- parameters (as described in section 3.6).
-
- TE = "TE" ":" #( t-codings )
- t-codings = "trailers" | ( transfer-extension [ accept-params ] )
-
- The presence of the keyword "trailers" indicates that the client is
- willing to accept trailer fields in a chunked transfer-coding, as
- defined in section 3.6.1. This keyword is reserved for use with
- transfer-coding values even though it does not itself represent a
- transfer-coding.
-
- Examples of its use are:
-
- TE: deflate
- TE:
- TE: trailers, deflate;q=0.5
-
- The TE header field only applies to the immediate connection.
- Therefore, the keyword MUST be supplied within a Connection header
- field (section 14.10) whenever TE is present in an HTTP/1.1 message.
-
- A server tests whether a transfer-coding is acceptable, according to
- a TE field, using these rules:
-
- 1. The "chunked" transfer-coding is always acceptable. If the
- keyword "trailers" is listed, the client indicates that it is
- willing to accept trailer fields in the chunked response on
- behalf of itself and any downstream clients. The implication is
- that, if given, the client is stating that either all
- downstream clients are willing to accept trailer fields in the
- forwarded response, or that it will attempt to buffer the
- response on behalf of downstream recipients.
-
- Note: HTTP/1.1 does not define any means to limit the size of a
- chunked response such that a client can be assured of buffering
- the entire response.
-
- 2. If the transfer-coding being tested is one of the transfer-
- codings listed in the TE field, then it is acceptable unless it
- is accompanied by a qvalue of 0. (As defined in section 3.9, a
- qvalue of 0 means "not acceptable.")
-
-
-
-Fielding, et al. Standards Track [Page 142]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- 3. If multiple transfer-codings are acceptable, then the
- acceptable transfer-coding with the highest non-zero qvalue is
- preferred. The "chunked" transfer-coding always has a qvalue
- of 1.
-
- If the TE field-value is empty or if no TE field is present, the only
- transfer-coding is "chunked". A message with no transfer-coding is
- always acceptable.
-
-14.40 Trailer
-
- The Trailer general field value indicates that the given set of
- header fields is present in the trailer of a message encoded with
- chunked transfer-coding.
-
- Trailer = "Trailer" ":" 1#field-name
-
- An HTTP/1.1 message SHOULD include a Trailer header field in a
- message using chunked transfer-coding with a non-empty trailer. Doing
- so allows the recipient to know which header fields to expect in the
- trailer.
-
- If no Trailer header field is present, the trailer SHOULD NOT include
- any header fields. See section 3.6.1 for restrictions on the use of
- trailer fields in a "chunked" transfer-coding.
-
- Message header fields listed in the Trailer header field MUST NOT
- include the following header fields:
-
- . Transfer-Encoding
-
- . Content-Length
-
- . Trailer
-
-14.41 Transfer-Encoding
-
- The Transfer-Encoding general-header field indicates what (if any)
- type of transformation has been applied to the message body in order
- to safely transfer it between the sender and the recipient. This
- differs from the content-coding in that the transfer-coding is a
- property of the message, not of the entity.
-
- Transfer-Encoding = "Transfer-Encoding" ":" 1#transfer-coding
-
- Transfer-codings are defined in section 3.6. An example is:
-
- Transfer-Encoding: chunked
-
-
-
-Fielding, et al. Standards Track [Page 143]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- If multiple encodings have been applied to an entity, the transfer-
- codings MUST be listed in the order in which they were applied.
- Additional information about the encoding parameters MAY be provided
- by other entity-header fields not defined by this specification.
-
- Many older HTTP/1.0 applications do not understand the Transfer-
- Encoding header.
-
-14.42 Upgrade
-
- The Upgrade general-header allows the client to specify what
- additional communication protocols it supports and would like to use
- if the server finds it appropriate to switch protocols. The server
- MUST use the Upgrade header field within a 101 (Switching Protocols)
- response to indicate which protocol(s) are being switched.
-
- Upgrade = "Upgrade" ":" 1#product
-
- For example,
-
- Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11
-
- The Upgrade header field is intended to provide a simple mechanism
- for transition from HTTP/1.1 to some other, incompatible protocol. It
- does so by allowing the client to advertise its desire to use another
- protocol, such as a later version of HTTP with a higher major version
- number, even though the current request has been made using HTTP/1.1.
- This eases the difficult transition between incompatible protocols by
- allowing the client to initiate a request in the more commonly
- supported protocol while indicating to the server that it would like
- to use a "better" protocol if available (where "better" is determined
- by the server, possibly according to the nature of the method and/or
- resource being requested).
-
- The Upgrade header field only applies to switching application-layer
- protocols upon the existing transport-layer connection. Upgrade
- cannot be used to insist on a protocol change; its acceptance and use
- by the server is optional. The capabilities and nature of the
- application-layer communication after the protocol change is entirely
- dependent upon the new protocol chosen, although the first action
- after changing the protocol MUST be a response to the initial HTTP
- request containing the Upgrade header field.
-
- The Upgrade header field only applies to the immediate connection.
- Therefore, the upgrade keyword MUST be supplied within a Connection
- header field (section 14.10) whenever Upgrade is present in an
- HTTP/1.1 message.
-
-
-
-
-Fielding, et al. Standards Track [Page 144]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- The Upgrade header field cannot be used to indicate a switch to a
- protocol on a different connection. For that purpose, it is more
- appropriate to use a 301, 302, 303, or 305 redirection response.
-
- This specification only defines the protocol name "HTTP" for use by
- the family of Hypertext Transfer Protocols, as defined by the HTTP
- version rules of section 3.1 and future updates to this
- specification. Any token can be used as a protocol name; however, it
- will only be useful if both the client and server associate the name
- with the same protocol.
-
-14.43 User-Agent
-
- The User-Agent request-header field contains information about the
- user agent originating the request. This is for statistical purposes,
- the tracing of protocol violations, and automated recognition of user
- agents for the sake of tailoring responses to avoid particular user
- agent limitations. User agents SHOULD include this field with
- requests. The field can contain multiple product tokens (section 3.8)
- and comments identifying the agent and any subproducts which form a
- significant part of the user agent. By convention, the product tokens
- are listed in order of their significance for identifying the
- application.
-
- User-Agent = "User-Agent" ":" 1*( product | comment )
-
- Example:
-
- User-Agent: CERN-LineMode/2.15 libwww/2.17b3
-
-14.44 Vary
-
- The Vary field value indicates the set of request-header fields that
- fully determines, while the response is fresh, whether a cache is
- permitted to use the response to reply to a subsequent request
- without revalidation. For uncacheable or stale responses, the Vary
- field value advises the user agent about the criteria that were used
- to select the representation. A Vary field value of "*" implies that
- a cache cannot determine from the request headers of a subsequent
- request whether this response is the appropriate representation. See
- section 13.6 for use of the Vary header field by caches.
-
- Vary = "Vary" ":" ( "*" | 1#field-name )
-
- An HTTP/1.1 server SHOULD include a Vary header field with any
- cacheable response that is subject to server-driven negotiation.
- Doing so allows a cache to properly interpret future requests on that
- resource and informs the user agent about the presence of negotiation
-
-
-
-Fielding, et al. Standards Track [Page 145]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- on that resource. A server MAY include a Vary header field with a
- non-cacheable response that is subject to server-driven negotiation,
- since this might provide the user agent with useful information about
- the dimensions over which the response varies at the time of the
- response.
-
- A Vary field value consisting of a list of field-names signals that
- the representation selected for the response is based on a selection
- algorithm which considers ONLY the listed request-header field values
- in selecting the most appropriate representation. A cache MAY assume
- that the same selection will be made for future requests with the
- same values for the listed field names, for the duration of time for
- which the response is fresh.
-
- The field-names given are not limited to the set of standard
- request-header fields defined by this specification. Field names are
- case-insensitive.
-
- A Vary field value of "*" signals that unspecified parameters not
- limited to the request-headers (e.g., the network address of the
- client), play a role in the selection of the response representation.
- The "*" value MUST NOT be generated by a proxy server; it may only be
- generated by an origin server.
-
-14.45 Via
-
- The Via general-header field MUST be used by gateways and proxies to
- indicate the intermediate protocols and recipients between the user
- agent and the server on requests, and between the origin server and
- the client on responses. It is analogous to the "Received" field of
- RFC 822 [9] and is intended to be used for tracking message forwards,
- avoiding request loops, and identifying the protocol capabilities of
- all senders along the request/response chain.
-
- Via = "Via" ":" 1#( received-protocol received-by [ comment ] )
- received-protocol = [ protocol-name "/" ] protocol-version
- protocol-name = token
- protocol-version = token
- received-by = ( host [ ":" port ] ) | pseudonym
- pseudonym = token
-
- The received-protocol indicates the protocol version of the message
- received by the server or client along each segment of the
- request/response chain. The received-protocol version is appended to
- the Via field value when the message is forwarded so that information
- about the protocol capabilities of upstream applications remains
- visible to all recipients.
-
-
-
-
-Fielding, et al. Standards Track [Page 146]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- The protocol-name is optional if and only if it would be "HTTP". The
- received-by field is normally the host and optional port number of a
- recipient server or client that subsequently forwarded the message.
- However, if the real host is considered to be sensitive information,
- it MAY be replaced by a pseudonym. If the port is not given, it MAY
- be assumed to be the default port of the received-protocol.
-
- Multiple Via field values represents each proxy or gateway that has
- forwarded the message. Each recipient MUST append its information
- such that the end result is ordered according to the sequence of
- forwarding applications.
-
- Comments MAY be used in the Via header field to identify the software
- of the recipient proxy or gateway, analogous to the User-Agent and
- Server header fields. However, all comments in the Via field are
- optional and MAY be removed by any recipient prior to forwarding the
- message.
-
- For example, a request message could be sent from an HTTP/1.0 user
- agent to an internal proxy code-named "fred", which uses HTTP/1.1 to
- forward the request to a public proxy at nowhere.com, which completes
- the request by forwarding it to the origin server at www.ics.uci.edu.
- The request received by www.ics.uci.edu would then have the following
- Via header field:
-
- Via: 1.0 fred, 1.1 nowhere.com (Apache/1.1)
-
- Proxies and gateways used as a portal through a network firewall
- SHOULD NOT, by default, forward the names and ports of hosts within
- the firewall region. This information SHOULD only be propagated if
- explicitly enabled. If not enabled, the received-by host of any host
- behind the firewall SHOULD be replaced by an appropriate pseudonym
- for that host.
-
- For organizations that have strong privacy requirements for hiding
- internal structures, a proxy MAY combine an ordered subsequence of
- Via header field entries with identical received-protocol values into
- a single such entry. For example,
-
- Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy
-
- could be collapsed to
-
- Via: 1.0 ricky, 1.1 mertz, 1.0 lucy
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 147]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Applications SHOULD NOT combine multiple entries unless they are all
- under the same organizational control and the hosts have already been
- replaced by pseudonyms. Applications MUST NOT combine entries which
- have different received-protocol values.
-
-14.46 Warning
-
- The Warning general-header field is used to carry additional
- information about the status or transformation of a message which
- might not be reflected in the message. This information is typically
- used to warn about a possible lack of semantic transparency from
- caching operations or transformations applied to the entity body of
- the message.
-
- Warning headers are sent with responses using:
-
- Warning = "Warning" ":" 1#warning-value
-
- warning-value = warn-code SP warn-agent SP warn-text
- [SP warn-date]
-
- warn-code = 3DIGIT
- warn-agent = ( host [ ":" port ] ) | pseudonym
- ; the name or pseudonym of the server adding
- ; the Warning header, for use in debugging
- warn-text = quoted-string
- warn-date = <"> HTTP-date <">
-
- A response MAY carry more than one Warning header.
-
- The warn-text SHOULD be in a natural language and character set that
- is most likely to be intelligible to the human user receiving the
- response. This decision MAY be based on any available knowledge, such
- as the location of the cache or user, the Accept-Language field in a
- request, the Content-Language field in a response, etc. The default
- language is English and the default character set is ISO-8859-1.
-
- If a character set other than ISO-8859-1 is used, it MUST be encoded
- in the warn-text using the method described in RFC 2047 [14].
-
- Warning headers can in general be applied to any message, however
- some specific warn-codes are specific to caches and can only be
- applied to response messages. New Warning headers SHOULD be added
- after any existing Warning headers. A cache MUST NOT delete any
- Warning header that it received with a message. However, if a cache
- successfully validates a cache entry, it SHOULD remove any Warning
- headers previously attached to that entry except as specified for
-
-
-
-
-Fielding, et al. Standards Track [Page 148]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- specific Warning codes. It MUST then add any Warning headers received
- in the validating response. In other words, Warning headers are those
- that would be attached to the most recent relevant response.
-
- When multiple Warning headers are attached to a response, the user
- agent ought to inform the user of as many of them as possible, in the
- order that they appear in the response. If it is not possible to
- inform the user of all of the warnings, the user agent SHOULD follow
- these heuristics:
-
- - Warnings that appear early in the response take priority over
- those appearing later in the response.
-
- - Warnings in the user's preferred character set take priority
- over warnings in other character sets but with identical warn-
- codes and warn-agents.
-
- Systems that generate multiple Warning headers SHOULD order them with
- this user agent behavior in mind.
-
- Requirements for the behavior of caches with respect to Warnings are
- stated in section 13.1.2.
-
- This is a list of the currently-defined warn-codes, each with a
- recommended warn-text in English, and a description of its meaning.
-
- 110 Response is stale
- MUST be included whenever the returned response is stale.
-
- 111 Revalidation failed
- MUST be included if a cache returns a stale response because an
- attempt to revalidate the response failed, due to an inability to
- reach the server.
-
- 112 Disconnected operation
- SHOULD be included if the cache is intentionally disconnected from
- the rest of the network for a period of time.
-
- 113 Heuristic expiration
- MUST be included if the cache heuristically chose a freshness
- lifetime greater than 24 hours and the response's age is greater
- than 24 hours.
-
- 199 Miscellaneous warning
- The warning text MAY include arbitrary information to be presented
- to a human user, or logged. A system receiving this warning MUST
- NOT take any automated action, besides presenting the warning to
- the user.
-
-
-
-Fielding, et al. Standards Track [Page 149]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- 214 Transformation applied
- MUST be added by an intermediate cache or proxy if it applies any
- transformation changing the content-coding (as specified in the
- Content-Encoding header) or media-type (as specified in the
- Content-Type header) of the response, or the entity-body of the
- response, unless this Warning code already appears in the response.
-
- 299 Miscellaneous persistent warning
- The warning text MAY include arbitrary information to be presented
- to a human user, or logged. A system receiving this warning MUST
- NOT take any automated action.
-
- If an implementation sends a message with one or more Warning headers
- whose version is HTTP/1.0 or lower, then the sender MUST include in
- each warning-value a warn-date that matches the date in the response.
-
- If an implementation receives a message with a warning-value that
- includes a warn-date, and that warn-date is different from the Date
- value in the response, then that warning-value MUST be deleted from
- the message before storing, forwarding, or using it. (This prevents
- bad consequences of naive caching of Warning header fields.) If all
- of the warning-values are deleted for this reason, the Warning header
- MUST be deleted as well.
-
-14.47 WWW-Authenticate
-
- The WWW-Authenticate response-header field MUST be included in 401
- (Unauthorized) response messages. The field value consists of at
- least one challenge that indicates the authentication scheme(s) and
- parameters applicable to the Request-URI.
-
- WWW-Authenticate = "WWW-Authenticate" ":" 1#challenge
-
- The HTTP access authentication process is described in "HTTP
- Authentication: Basic and Digest Access Authentication" [43]. User
- agents are advised to take special care in parsing the WWW-
- Authenticate field value as it might contain more than one challenge,
- or if more than one WWW-Authenticate header field is provided, the
- contents of a challenge itself can contain a comma-separated list of
- authentication parameters.
-
-15 Security Considerations
-
- This section is meant to inform application developers, information
- providers, and users of the security limitations in HTTP/1.1 as
- described by this document. The discussion does not include
- definitive solutions to the problems revealed, though it does make
- some suggestions for reducing security risks.
-
-
-
-Fielding, et al. Standards Track [Page 150]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-15.1 Personal Information
-
- HTTP clients are often privy to large amounts of personal information
- (e.g. the user's name, location, mail address, passwords, encryption
- keys, etc.), and SHOULD be very careful to prevent unintentional
- leakage of this information via the HTTP protocol to other sources.
- We very strongly recommend that a convenient interface be provided
- for the user to control dissemination of such information, and that
- designers and implementors be particularly careful in this area.
- History shows that errors in this area often create serious security
- and/or privacy problems and generate highly adverse publicity for the
- implementor's company.
-
-15.1.1 Abuse of Server Log Information
-
- A server is in the position to save personal data about a user's
- requests which might identify their reading patterns or subjects of
- interest. This information is clearly confidential in nature and its
- handling can be constrained by law in certain countries. People using
- the HTTP protocol to provide data are responsible for ensuring that
- such material is not distributed without the permission of any
- individuals that are identifiable by the published results.
-
-15.1.2 Transfer of Sensitive Information
-
- Like any generic data transfer protocol, HTTP cannot regulate the
- content of the data that is transferred, nor is there any a priori
- method of determining the sensitivity of any particular piece of
- information within the context of any given request. Therefore,
- applications SHOULD supply as much control over this information as
- possible to the provider of that information. Four header fields are
- worth special mention in this context: Server, Via, Referer and From.
-
- Revealing the specific software version of the server might allow the
- server machine to become more vulnerable to attacks against software
- that is known to contain security holes. Implementors SHOULD make the
- Server header field a configurable option.
-
- Proxies which serve as a portal through a network firewall SHOULD
- take special precautions regarding the transfer of header information
- that identifies the hosts behind the firewall. In particular, they
- SHOULD remove, or replace with sanitized versions, any Via fields
- generated behind the firewall.
-
- The Referer header allows reading patterns to be studied and reverse
- links drawn. Although it can be very useful, its power can be abused
- if user details are not separated from the information contained in
-
-
-
-
-Fielding, et al. Standards Track [Page 151]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- the Referer. Even when the personal information has been removed, the
- Referer header might indicate a private document's URI whose
- publication would be inappropriate.
-
- The information sent in the From field might conflict with the user's
- privacy interests or their site's security policy, and hence it
- SHOULD NOT be transmitted without the user being able to disable,
- enable, and modify the contents of the field. The user MUST be able
- to set the contents of this field within a user preference or
- application defaults configuration.
-
- We suggest, though do not require, that a convenient toggle interface
- be provided for the user to enable or disable the sending of From and
- Referer information.
-
- The User-Agent (section 14.43) or Server (section 14.38) header
- fields can sometimes be used to determine that a specific client or
- server have a particular security hole which might be exploited.
- Unfortunately, this same information is often used for other valuable
- purposes for which HTTP currently has no better mechanism.
-
-15.1.3 Encoding Sensitive Information in URI's
-
- Because the source of a link might be private information or might
- reveal an otherwise private information source, it is strongly
- recommended that the user be able to select whether or not the
- Referer field is sent. For example, a browser client could have a
- toggle switch for browsing openly/anonymously, which would
- respectively enable/disable the sending of Referer and From
- information.
-
- Clients SHOULD NOT include a Referer header field in a (non-secure)
- HTTP request if the referring page was transferred with a secure
- protocol.
-
- Authors of services which use the HTTP protocol SHOULD NOT use GET
- based forms for the submission of sensitive data, because this will
- cause this data to be encoded in the Request-URI. Many existing
- servers, proxies, and user agents will log the request URI in some
- place where it might be visible to third parties. Servers can use
- POST-based form submission instead
-
-15.1.4 Privacy Issues Connected to Accept Headers
-
- Accept request-headers can reveal information about the user to all
- servers which are accessed. The Accept-Language header in particular
- can reveal information the user would consider to be of a private
- nature, because the understanding of particular languages is often
-
-
-
-Fielding, et al. Standards Track [Page 152]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- strongly correlated to the membership of a particular ethnic group.
- User agents which offer the option to configure the contents of an
- Accept-Language header to be sent in every request are strongly
- encouraged to let the configuration process include a message which
- makes the user aware of the loss of privacy involved.
-
- An approach that limits the loss of privacy would be for a user agent
- to omit the sending of Accept-Language headers by default, and to ask
- the user whether or not to start sending Accept-Language headers to a
- server if it detects, by looking for any Vary response-header fields
- generated by the server, that such sending could improve the quality
- of service.
-
- Elaborate user-customized accept header fields sent in every request,
- in particular if these include quality values, can be used by servers
- as relatively reliable and long-lived user identifiers. Such user
- identifiers would allow content providers to do click-trail tracking,
- and would allow collaborating content providers to match cross-server
- click-trails or form submissions of individual users. Note that for
- many users not behind a proxy, the network address of the host
- running the user agent will also serve as a long-lived user
- identifier. In environments where proxies are used to enhance
- privacy, user agents ought to be conservative in offering accept
- header configuration options to end users. As an extreme privacy
- measure, proxies could filter the accept headers in relayed requests.
- General purpose user agents which provide a high degree of header
- configurability SHOULD warn users about the loss of privacy which can
- be involved.
-
-15.2 Attacks Based On File and Path Names
-
- Implementations of HTTP origin servers SHOULD be careful to restrict
- the documents returned by HTTP requests to be only those that were
- intended by the server administrators. If an HTTP server translates
- HTTP URIs directly into file system calls, the server MUST take
- special care not to serve files that were not intended to be
- delivered to HTTP clients. For example, UNIX, Microsoft Windows, and
- other operating systems use ".." as a path component to indicate a
- directory level above the current one. On such a system, an HTTP
- server MUST disallow any such construct in the Request-URI if it
- would otherwise allow access to a resource outside those intended to
- be accessible via the HTTP server. Similarly, files intended for
- reference only internally to the server (such as access control
- files, configuration files, and script code) MUST be protected from
- inappropriate retrieval, since they might contain sensitive
- information. Experience has shown that minor bugs in such HTTP server
- implementations have turned into security risks.
-
-
-
-
-Fielding, et al. Standards Track [Page 153]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-15.3 DNS Spoofing
-
- Clients using HTTP rely heavily on the Domain Name Service, and are
- thus generally prone to security attacks based on the deliberate
- mis-association of IP addresses and DNS names. Clients need to be
- cautious in assuming the continuing validity of an IP number/DNS name
- association.
-
- In particular, HTTP clients SHOULD rely on their name resolver for
- confirmation of an IP number/DNS name association, rather than
- caching the result of previous host name lookups. Many platforms
- already can cache host name lookups locally when appropriate, and
- they SHOULD be configured to do so. It is proper for these lookups to
- be cached, however, only when the TTL (Time To Live) information
- reported by the name server makes it likely that the cached
- information will remain useful.
-
- If HTTP clients cache the results of host name lookups in order to
- achieve a performance improvement, they MUST observe the TTL
- information reported by DNS.
-
- If HTTP clients do not observe this rule, they could be spoofed when
- a previously-accessed server's IP address changes. As network
- renumbering is expected to become increasingly common [24], the
- possibility of this form of attack will grow. Observing this
- requirement thus reduces this potential security vulnerability.
-
- This requirement also improves the load-balancing behavior of clients
- for replicated servers using the same DNS name and reduces the
- likelihood of a user's experiencing failure in accessing sites which
- use that strategy.
-
-15.4 Location Headers and Spoofing
-
- If a single server supports multiple organizations that do not trust
- one another, then it MUST check the values of Location and Content-
- Location headers in responses that are generated under control of
- said organizations to make sure that they do not attempt to
- invalidate resources over which they have no authority.
-
-15.5 Content-Disposition Issues
-
- RFC 1806 [35], from which the often implemented Content-Disposition
- (see section 19.5.1) header in HTTP is derived, has a number of very
- serious security considerations. Content-Disposition is not part of
- the HTTP standard, but since it is widely implemented, we are
- documenting its use and risks for implementors. See RFC 2183 [49]
- (which updates RFC 1806) for details.
-
-
-
-Fielding, et al. Standards Track [Page 154]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-15.6 Authentication Credentials and Idle Clients
-
- Existing HTTP clients and user agents typically retain authentication
- information indefinitely. HTTP/1.1. does not provide a method for a
- server to direct clients to discard these cached credentials. This is
- a significant defect that requires further extensions to HTTP.
- Circumstances under which credential caching can interfere with the
- application's security model include but are not limited to:
-
- - Clients which have been idle for an extended period following
- which the server might wish to cause the client to reprompt the
- user for credentials.
-
- - Applications which include a session termination indication
- (such as a `logout' or `commit' button on a page) after which
- the server side of the application `knows' that there is no
- further reason for the client to retain the credentials.
-
- This is currently under separate study. There are a number of work-
- arounds to parts of this problem, and we encourage the use of
- password protection in screen savers, idle time-outs, and other
- methods which mitigate the security problems inherent in this
- problem. In particular, user agents which cache credentials are
- encouraged to provide a readily accessible mechanism for discarding
- cached credentials under user control.
-
-15.7 Proxies and Caching
-
- By their very nature, HTTP proxies are men-in-the-middle, and
- represent an opportunity for man-in-the-middle attacks. Compromise of
- the systems on which the proxies run can result in serious security
- and privacy problems. Proxies have access to security-related
- information, personal information about individual users and
- organizations, and proprietary information belonging to users and
- content providers. A compromised proxy, or a proxy implemented or
- configured without regard to security and privacy considerations,
- might be used in the commission of a wide range of potential attacks.
-
- Proxy operators should protect the systems on which proxies run as
- they would protect any system that contains or transports sensitive
- information. In particular, log information gathered at proxies often
- contains highly sensitive personal information, and/or information
- about organizations. Log information should be carefully guarded, and
- appropriate guidelines for use developed and followed. (Section
- 15.1.1).
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 155]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Caching proxies provide additional potential vulnerabilities, since
- the contents of the cache represent an attractive target for
- malicious exploitation. Because cache contents persist after an HTTP
- request is complete, an attack on the cache can reveal information
- long after a user believes that the information has been removed from
- the network. Therefore, cache contents should be protected as
- sensitive information.
-
- Proxy implementors should consider the privacy and security
- implications of their design and coding decisions, and of the
- configuration options they provide to proxy operators (especially the
- default configuration).
-
- Users of a proxy need to be aware that they are no trustworthier than
- the people who run the proxy; HTTP itself cannot solve this problem.
-
- The judicious use of cryptography, when appropriate, may suffice to
- protect against a broad range of security and privacy attacks. Such
- cryptography is beyond the scope of the HTTP/1.1 specification.
-
-15.7.1 Denial of Service Attacks on Proxies
-
- They exist. They are hard to defend against. Research continues.
- Beware.
-
-16 Acknowledgments
-
- This specification makes heavy use of the augmented BNF and generic
- constructs defined by David H. Crocker for RFC 822 [9]. Similarly, it
- reuses many of the definitions provided by Nathaniel Borenstein and
- Ned Freed for MIME [7]. We hope that their inclusion in this
- specification will help reduce past confusion over the relationship
- between HTTP and Internet mail message formats.
-
- The HTTP protocol has evolved considerably over the years. It has
- benefited from a large and active developer community--the many
- people who have participated on the www-talk mailing list--and it is
- that community which has been most responsible for the success of
- HTTP and of the World-Wide Web in general. Marc Andreessen, Robert
- Cailliau, Daniel W. Connolly, Bob Denny, John Franks, Jean-Francois
- Groff, Phillip M. Hallam-Baker, Hakon W. Lie, Ari Luotonen, Rob
- McCool, Lou Montulli, Dave Raggett, Tony Sanders, and Marc
- VanHeyningen deserve special recognition for their efforts in
- defining early aspects of the protocol.
-
- This document has benefited greatly from the comments of all those
- participating in the HTTP-WG. In addition to those already mentioned,
- the following individuals have contributed to this specification:
-
-
-
-Fielding, et al. Standards Track [Page 156]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Gary Adams Ross Patterson
- Harald Tveit Alvestrand Albert Lunde
- Keith Ball John C. Mallery
- Brian Behlendorf Jean-Philippe Martin-Flatin
- Paul Burchard Mitra
- Maurizio Codogno David Morris
- Mike Cowlishaw Gavin Nicol
- Roman Czyborra Bill Perry
- Michael A. Dolan Jeffrey Perry
- David J. Fiander Scott Powers
- Alan Freier Owen Rees
- Marc Hedlund Luigi Rizzo
- Greg Herlihy David Robinson
- Koen Holtman Marc Salomon
- Alex Hopmann Rich Salz
- Bob Jernigan Allan M. Schiffman
- Shel Kaphan Jim Seidman
- Rohit Khare Chuck Shotton
- John Klensin Eric W. Sink
- Martijn Koster Simon E. Spero
- Alexei Kosut Richard N. Taylor
- David M. Kristol Robert S. Thau
- Daniel LaLiberte Bill (BearHeart) Weinman
- Ben Laurie Francois Yergeau
- Paul J. Leach Mary Ellen Zurko
- Daniel DuBois Josh Cohen
-
-
- Much of the content and presentation of the caching design is due to
- suggestions and comments from individuals including: Shel Kaphan,
- Paul Leach, Koen Holtman, David Morris, and Larry Masinter.
-
- Most of the specification of ranges is based on work originally done
- by Ari Luotonen and John Franks, with additional input from Steve
- Zilles.
-
- Thanks to the "cave men" of Palo Alto. You know who you are.
-
- Jim Gettys (the current editor of this document) wishes particularly
- to thank Roy Fielding, the previous editor of this document, along
- with John Klensin, Jeff Mogul, Paul Leach, Dave Kristol, Koen
- Holtman, John Franks, Josh Cohen, Alex Hopmann, Scott Lawrence, and
- Larry Masinter for their help. And thanks go particularly to Jeff
- Mogul and Scott Lawrence for performing the "MUST/MAY/SHOULD" audit.
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 157]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- The Apache Group, Anselm Baird-Smith, author of Jigsaw, and Henrik
- Frystyk implemented RFC 2068 early, and we wish to thank them for the
- discovery of many of the problems that this document attempts to
- rectify.
-
-17 References
-
- [1] Alvestrand, H., "Tags for the Identification of Languages", RFC
- 1766, March 1995.
-
- [2] Anklesaria, F., McCahill, M., Lindner, P., Johnson, D., Torrey,
- D. and B. Alberti, "The Internet Gopher Protocol (a distributed
- document search and retrieval protocol)", RFC 1436, March 1993.
-
- [3] Berners-Lee, T., "Universal Resource Identifiers in WWW", RFC
- 1630, June 1994.
-
- [4] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource
- Locators (URL)", RFC 1738, December 1994.
-
- [5] Berners-Lee, T. and D. Connolly, "Hypertext Markup Language -
- 2.0", RFC 1866, November 1995.
-
- [6] Berners-Lee, T., Fielding, R. and H. Frystyk, "Hypertext Transfer
- Protocol -- HTTP/1.0", RFC 1945, May 1996.
-
- [7] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part One: Format of Internet Message Bodies",
- RFC 2045, November 1996.
-
- [8] Braden, R., "Requirements for Internet Hosts -- Communication
- Layers", STD 3, RFC 1123, October 1989.
-
- [9] Crocker, D., "Standard for The Format of ARPA Internet Text
- Messages", STD 11, RFC 822, August 1982.
-
- [10] Davis, F., Kahle, B., Morris, H., Salem, J., Shen, T., Wang, R.,
- Sui, J., and M. Grinbaum, "WAIS Interface Protocol Prototype
- Functional Specification," (v1.5), Thinking Machines
- Corporation, April 1990.
-
- [11] Fielding, R., "Relative Uniform Resource Locators", RFC 1808,
- June 1995.
-
- [12] Horton, M. and R. Adams, "Standard for Interchange of USENET
- Messages", RFC 1036, December 1987.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 158]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- [13] Kantor, B. and P. Lapsley, "Network News Transfer Protocol", RFC
- 977, February 1986.
-
- [14] Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part
- Three: Message Header Extensions for Non-ASCII Text", RFC 2047,
- November 1996.
-
- [15] Nebel, E. and L. Masinter, "Form-based File Upload in HTML", RFC
- 1867, November 1995.
-
- [16] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821,
- August 1982.
-
- [17] Postel, J., "Media Type Registration Procedure", RFC 1590,
- November 1996.
-
- [18] Postel, J. and J. Reynolds, "File Transfer Protocol", STD 9, RFC
- 959, October 1985.
-
- [19] Reynolds, J. and J. Postel, "Assigned Numbers", STD 2, RFC 1700,
- October 1994.
-
- [20] Sollins, K. and L. Masinter, "Functional Requirements for
- Uniform Resource Names", RFC 1737, December 1994.
-
- [21] US-ASCII. Coded Character Set - 7-Bit American Standard Code for
- Information Interchange. Standard ANSI X3.4-1986, ANSI, 1986.
-
- [22] ISO-8859. International Standard -- Information Processing --
- 8-bit Single-Byte Coded Graphic Character Sets --
- Part 1: Latin alphabet No. 1, ISO-8859-1:1987.
- Part 2: Latin alphabet No. 2, ISO-8859-2, 1987.
- Part 3: Latin alphabet No. 3, ISO-8859-3, 1988.
- Part 4: Latin alphabet No. 4, ISO-8859-4, 1988.
- Part 5: Latin/Cyrillic alphabet, ISO-8859-5, 1988.
- Part 6: Latin/Arabic alphabet, ISO-8859-6, 1987.
- Part 7: Latin/Greek alphabet, ISO-8859-7, 1987.
- Part 8: Latin/Hebrew alphabet, ISO-8859-8, 1988.
- Part 9: Latin alphabet No. 5, ISO-8859-9, 1990.
-
- [23] Meyers, J. and M. Rose, "The Content-MD5 Header Field", RFC
- 1864, October 1995.
-
- [24] Carpenter, B. and Y. Rekhter, "Renumbering Needs Work", RFC
- 1900, February 1996.
-
- [25] Deutsch, P., "GZIP file format specification version 4.3", RFC
- 1952, May 1996.
-
-
-
-Fielding, et al. Standards Track [Page 159]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- [26] Venkata N. Padmanabhan, and Jeffrey C. Mogul. "Improving HTTP
- Latency", Computer Networks and ISDN Systems, v. 28, pp. 25-35,
- Dec. 1995. Slightly revised version of paper in Proc. 2nd
- International WWW Conference '94: Mosaic and the Web, Oct. 1994,
- which is available at
- http://www.ncsa.uiuc.edu/SDG/IT94/Proceedings/DDay/mogul/HTTPLat
- ency.html.
-
- [27] Joe Touch, John Heidemann, and Katia Obraczka. "Analysis of HTTP
- Performance", <URL: http://www.isi.edu/touch/pubs/http-perf96/>,
- ISI Research Report ISI/RR-98-463, (original report dated Aug.
- 1996), USC/Information Sciences Institute, August 1998.
-
- [28] Mills, D., "Network Time Protocol (Version 3) Specification,
- Implementation and Analysis", RFC 1305, March 1992.
-
- [29] Deutsch, P., "DEFLATE Compressed Data Format Specification
- version 1.3", RFC 1951, May 1996.
-
- [30] S. Spero, "Analysis of HTTP Performance Problems,"
- http://sunsite.unc.edu/mdma-release/http-prob.html.
-
- [31] Deutsch, P. and J. Gailly, "ZLIB Compressed Data Format
- Specification version 3.3", RFC 1950, May 1996.
-
- [32] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P.,
- Luotonen, A., Sink, E. and L. Stewart, "An Extension to HTTP:
- Digest Access Authentication", RFC 2069, January 1997.
-
- [33] Fielding, R., Gettys, J., Mogul, J., Frystyk, H. and T.
- Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC
- 2068, January 1997.
-
- [34] Bradner, S., "Key words for use in RFCs to Indicate Requirement
- Levels", BCP 14, RFC 2119, March 1997.
-
- [35] Troost, R. and Dorner, S., "Communicating Presentation
- Information in Internet Messages: The Content-Disposition
- Header", RFC 1806, June 1995.
-
- [36] Mogul, J., Fielding, R., Gettys, J. and H. Frystyk, "Use and
- Interpretation of HTTP Version Numbers", RFC 2145, May 1997.
- [jg639]
-
- [37] Palme, J., "Common Internet Message Headers", RFC 2076, February
- 1997. [jg640]
-
-
-
-
-
-Fielding, et al. Standards Track [Page 160]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- [38] Yergeau, F., "UTF-8, a transformation format of Unicode and
- ISO-10646", RFC 2279, January 1998. [jg641]
-
- [39] Nielsen, H.F., Gettys, J., Baird-Smith, A., Prud'hommeaux, E.,
- Lie, H., and C. Lilley. "Network Performance Effects of
- HTTP/1.1, CSS1, and PNG," Proceedings of ACM SIGCOMM '97, Cannes
- France, September 1997.[jg642]
-
- [40] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part Two: Media Types", RFC 2046, November
- 1996. [jg643]
-
- [41] Alvestrand, H., "IETF Policy on Character Sets and Languages",
- BCP 18, RFC 2277, January 1998. [jg644]
-
- [42] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource
- Identifiers (URI): Generic Syntax and Semantics", RFC 2396,
- August 1998. [jg645]
-
- [43] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
- Leach, P., Luotonen, A., Sink, E. and L. Stewart, "HTTP
- Authentication: Basic and Digest Access Authentication", RFC
- 2617, June 1999. [jg646]
-
- [44] Luotonen, A., "Tunneling TCP based protocols through Web proxy
- servers," Work in Progress. [jg647]
-
- [45] Palme, J. and A. Hopmann, "MIME E-mail Encapsulation of
- Aggregate Documents, such as HTML (MHTML)", RFC 2110, March
- 1997.
-
- [46] Bradner, S., "The Internet Standards Process -- Revision 3", BCP
- 9, RFC 2026, October 1996.
-
- [47] Masinter, L., "Hyper Text Coffee Pot Control Protocol
- (HTCPCP/1.0)", RFC 2324, 1 April 1998.
-
- [48] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part Five: Conformance Criteria and Examples",
- RFC 2049, November 1996.
-
- [49] Troost, R., Dorner, S. and K. Moore, "Communicating Presentation
- Information in Internet Messages: The Content-Disposition Header
- Field", RFC 2183, August 1997.
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 161]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-18 Authors' Addresses
-
- Roy T. Fielding
- Information and Computer Science
- University of California, Irvine
- Irvine, CA 92697-3425, USA
-
- Fax: +1 (949) 824-1715
- EMail: fielding@ics.uci.edu
-
-
- James Gettys
- World Wide Web Consortium
- MIT Laboratory for Computer Science
- 545 Technology Square
- Cambridge, MA 02139, USA
-
- Fax: +1 (617) 258 8682
- EMail: jg@w3.org
-
-
- Jeffrey C. Mogul
- Western Research Laboratory
- Compaq Computer Corporation
- 250 University Avenue
- Palo Alto, California, 94305, USA
-
- EMail: mogul@wrl.dec.com
-
-
- Henrik Frystyk Nielsen
- World Wide Web Consortium
- MIT Laboratory for Computer Science
- 545 Technology Square
- Cambridge, MA 02139, USA
-
- Fax: +1 (617) 258 8682
- EMail: frystyk@w3.org
-
-
- Larry Masinter
- Xerox Corporation
- 3333 Coyote Hill Road
- Palo Alto, CA 94034, USA
-
- EMail: masinter@parc.xerox.com
-
-
-
-
-
-Fielding, et al. Standards Track [Page 162]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Paul J. Leach
- Microsoft Corporation
- 1 Microsoft Way
- Redmond, WA 98052, USA
-
- EMail: paulle@microsoft.com
-
-
- Tim Berners-Lee
- Director, World Wide Web Consortium
- MIT Laboratory for Computer Science
- 545 Technology Square
- Cambridge, MA 02139, USA
-
- Fax: +1 (617) 258 8682
- EMail: timbl@w3.org
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 163]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-19 Appendices
-
-19.1 Internet Media Type message/http and application/http
-
- In addition to defining the HTTP/1.1 protocol, this document serves
- as the specification for the Internet media type "message/http" and
- "application/http". The message/http type can be used to enclose a
- single HTTP request or response message, provided that it obeys the
- MIME restrictions for all "message" types regarding line length and
- encodings. The application/http type can be used to enclose a
- pipeline of one or more HTTP request or response messages (not
- intermixed). The following is to be registered with IANA [17].
-
- Media Type name: message
- Media subtype name: http
- Required parameters: none
- Optional parameters: version, msgtype
- version: The HTTP-Version number of the enclosed message
- (e.g., "1.1"). If not present, the version can be
- determined from the first line of the body.
- msgtype: The message type -- "request" or "response". If not
- present, the type can be determined from the first
- line of the body.
- Encoding considerations: only "7bit", "8bit", or "binary" are
- permitted
- Security considerations: none
-
- Media Type name: application
- Media subtype name: http
- Required parameters: none
- Optional parameters: version, msgtype
- version: The HTTP-Version number of the enclosed messages
- (e.g., "1.1"). If not present, the version can be
- determined from the first line of the body.
- msgtype: The message type -- "request" or "response". If not
- present, the type can be determined from the first
- line of the body.
- Encoding considerations: HTTP messages enclosed by this type
- are in "binary" format; use of an appropriate
- Content-Transfer-Encoding is required when
- transmitted via E-mail.
- Security considerations: none
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 164]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-19.2 Internet Media Type multipart/byteranges
-
- When an HTTP 206 (Partial Content) response message includes the
- content of multiple ranges (a response to a request for multiple
- non-overlapping ranges), these are transmitted as a multipart
- message-body. The media type for this purpose is called
- "multipart/byteranges".
-
- The multipart/byteranges media type includes two or more parts, each
- with its own Content-Type and Content-Range fields. The required
- boundary parameter specifies the boundary string used to separate
- each body-part.
-
- Media Type name: multipart
- Media subtype name: byteranges
- Required parameters: boundary
- Optional parameters: none
- Encoding considerations: only "7bit", "8bit", or "binary" are
- permitted
- Security considerations: none
-
-
- For example:
-
- HTTP/1.1 206 Partial Content
- Date: Wed, 15 Nov 1995 06:25:24 GMT
- Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
- Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES
-
- --THIS_STRING_SEPARATES
- Content-type: application/pdf
- Content-range: bytes 500-999/8000
-
- ...the first range...
- --THIS_STRING_SEPARATES
- Content-type: application/pdf
- Content-range: bytes 7000-7999/8000
-
- ...the second range
- --THIS_STRING_SEPARATES--
-
- Notes:
-
- 1) Additional CRLFs may precede the first boundary string in the
- entity.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 165]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- 2) Although RFC 2046 [40] permits the boundary string to be
- quoted, some existing implementations handle a quoted boundary
- string incorrectly.
-
- 3) A number of browsers and servers were coded to an early draft
- of the byteranges specification to use a media type of
- multipart/x-byteranges, which is almost, but not quite
- compatible with the version documented in HTTP/1.1.
-
-19.3 Tolerant Applications
-
- Although this document specifies the requirements for the generation
- of HTTP/1.1 messages, not all applications will be correct in their
- implementation. We therefore recommend that operational applications
- be tolerant of deviations whenever those deviations can be
- interpreted unambiguously.
-
- Clients SHOULD be tolerant in parsing the Status-Line and servers
- tolerant when parsing the Request-Line. In particular, they SHOULD
- accept any amount of SP or HT characters between fields, even though
- only a single SP is required.
-
- The line terminator for message-header fields is the sequence CRLF.
- However, we recommend that applications, when parsing such headers,
- recognize a single LF as a line terminator and ignore the leading CR.
-
- The character set of an entity-body SHOULD be labeled as the lowest
- common denominator of the character codes used within that body, with
- the exception that not labeling the entity is preferred over labeling
- the entity with the labels US-ASCII or ISO-8859-1. See section 3.7.1
- and 3.4.1.
-
- Additional rules for requirements on parsing and encoding of dates
- and other potential problems with date encodings include:
-
- - HTTP/1.1 clients and caches SHOULD assume that an RFC-850 date
- which appears to be more than 50 years in the future is in fact
- in the past (this helps solve the "year 2000" problem).
-
- - An HTTP/1.1 implementation MAY internally represent a parsed
- Expires date as earlier than the proper value, but MUST NOT
- internally represent a parsed Expires date as later than the
- proper value.
-
- - All expiration-related calculations MUST be done in GMT. The
- local time zone MUST NOT influence the calculation or comparison
- of an age or expiration time.
-
-
-
-
-Fielding, et al. Standards Track [Page 166]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- - If an HTTP header incorrectly carries a date value with a time
- zone other than GMT, it MUST be converted into GMT using the
- most conservative possible conversion.
-
-19.4 Differences Between HTTP Entities and RFC 2045 Entities
-
- HTTP/1.1 uses many of the constructs defined for Internet Mail (RFC
- 822 [9]) and the Multipurpose Internet Mail Extensions (MIME [7]) to
- allow entities to be transmitted in an open variety of
- representations and with extensible mechanisms. However, RFC 2045
- discusses mail, and HTTP has a few features that are different from
- those described in RFC 2045. These differences were carefully chosen
- to optimize performance over binary connections, to allow greater
- freedom in the use of new media types, to make date comparisons
- easier, and to acknowledge the practice of some early HTTP servers
- and clients.
-
- This appendix describes specific areas where HTTP differs from RFC
- 2045. Proxies and gateways to strict MIME environments SHOULD be
- aware of these differences and provide the appropriate conversions
- where necessary. Proxies and gateways from MIME environments to HTTP
- also need to be aware of the differences because some conversions
- might be required.
-
-19.4.1 MIME-Version
-
- HTTP is not a MIME-compliant protocol. However, HTTP/1.1 messages MAY
- include a single MIME-Version general-header field to indicate what
- version of the MIME protocol was used to construct the message. Use
- of the MIME-Version header field indicates that the message is in
- full compliance with the MIME protocol (as defined in RFC 2045[7]).
- Proxies/gateways are responsible for ensuring full compliance (where
- possible) when exporting HTTP messages to strict MIME environments.
-
- MIME-Version = "MIME-Version" ":" 1*DIGIT "." 1*DIGIT
-
- MIME version "1.0" is the default for use in HTTP/1.1. However,
- HTTP/1.1 message parsing and semantics are defined by this document
- and not the MIME specification.
-
-19.4.2 Conversion to Canonical Form
-
- RFC 2045 [7] requires that an Internet mail entity be converted to
- canonical form prior to being transferred, as described in section 4
- of RFC 2049 [48]. Section 3.7.1 of this document describes the forms
- allowed for subtypes of the "text" media type when transmitted over
- HTTP. RFC 2046 requires that content with a type of "text" represent
- line breaks as CRLF and forbids the use of CR or LF outside of line
-
-
-
-Fielding, et al. Standards Track [Page 167]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- break sequences. HTTP allows CRLF, bare CR, and bare LF to indicate a
- line break within text content when a message is transmitted over
- HTTP.
-
- Where it is possible, a proxy or gateway from HTTP to a strict MIME
- environment SHOULD translate all line breaks within the text media
- types described in section 3.7.1 of this document to the RFC 2049
- canonical form of CRLF. Note, however, that this might be complicated
- by the presence of a Content-Encoding and by the fact that HTTP
- allows the use of some character sets which do not use octets 13 and
- 10 to represent CR and LF, as is the case for some multi-byte
- character sets.
-
- Implementors should note that conversion will break any cryptographic
- checksums applied to the original content unless the original content
- is already in canonical form. Therefore, the canonical form is
- recommended for any content that uses such checksums in HTTP.
-
-19.4.3 Conversion of Date Formats
-
- HTTP/1.1 uses a restricted set of date formats (section 3.3.1) to
- simplify the process of date comparison. Proxies and gateways from
- other protocols SHOULD ensure that any Date header field present in a
- message conforms to one of the HTTP/1.1 formats and rewrite the date
- if necessary.
-
-19.4.4 Introduction of Content-Encoding
-
- RFC 2045 does not include any concept equivalent to HTTP/1.1's
- Content-Encoding header field. Since this acts as a modifier on the
- media type, proxies and gateways from HTTP to MIME-compliant
- protocols MUST either change the value of the Content-Type header
- field or decode the entity-body before forwarding the message. (Some
- experimental applications of Content-Type for Internet mail have used
- a media-type parameter of ";conversions=<content-coding>" to perform
- a function equivalent to Content-Encoding. However, this parameter is
- not part of RFC 2045.)
-
-19.4.5 No Content-Transfer-Encoding
-
- HTTP does not use the Content-Transfer-Encoding (CTE) field of RFC
- 2045. Proxies and gateways from MIME-compliant protocols to HTTP MUST
- remove any non-identity CTE ("quoted-printable" or "base64") encoding
- prior to delivering the response message to an HTTP client.
-
- Proxies and gateways from HTTP to MIME-compliant protocols are
- responsible for ensuring that the message is in the correct format
- and encoding for safe transport on that protocol, where "safe
-
-
-
-Fielding, et al. Standards Track [Page 168]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- transport" is defined by the limitations of the protocol being used.
- Such a proxy or gateway SHOULD label the data with an appropriate
- Content-Transfer-Encoding if doing so will improve the likelihood of
- safe transport over the destination protocol.
-
-19.4.6 Introduction of Transfer-Encoding
-
- HTTP/1.1 introduces the Transfer-Encoding header field (section
- 14.41). Proxies/gateways MUST remove any transfer-coding prior to
- forwarding a message via a MIME-compliant protocol.
-
- A process for decoding the "chunked" transfer-coding (section 3.6)
- can be represented in pseudo-code as:
-
- length := 0
- read chunk-size, chunk-extension (if any) and CRLF
- while (chunk-size > 0) {
- read chunk-data and CRLF
- append chunk-data to entity-body
- length := length + chunk-size
- read chunk-size and CRLF
- }
- read entity-header
- while (entity-header not empty) {
- append entity-header to existing header fields
- read entity-header
- }
- Content-Length := length
- Remove "chunked" from Transfer-Encoding
-
-19.4.7 MHTML and Line Length Limitations
-
- HTTP implementations which share code with MHTML [45] implementations
- need to be aware of MIME line length limitations. Since HTTP does not
- have this limitation, HTTP does not fold long lines. MHTML messages
- being transported by HTTP follow all conventions of MHTML, including
- line length limitations and folding, canonicalization, etc., since
- HTTP transports all message-bodies as payload (see section 3.7.2) and
- does not interpret the content or any MIME header lines that might be
- contained therein.
-
-19.5 Additional Features
-
- RFC 1945 and RFC 2068 document protocol elements used by some
- existing HTTP implementations, but not consistently and correctly
- across most HTTP/1.1 applications. Implementors are advised to be
- aware of these features, but cannot rely upon their presence in, or
- interoperability with, other HTTP/1.1 applications. Some of these
-
-
-
-Fielding, et al. Standards Track [Page 169]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- describe proposed experimental features, and some describe features
- that experimental deployment found lacking that are now addressed in
- the base HTTP/1.1 specification.
-
- A number of other headers, such as Content-Disposition and Title,
- from SMTP and MIME are also often implemented (see RFC 2076 [37]).
-
-19.5.1 Content-Disposition
-
- The Content-Disposition response-header field has been proposed as a
- means for the origin server to suggest a default filename if the user
- requests that the content is saved to a file. This usage is derived
- from the definition of Content-Disposition in RFC 1806 [35].
-
- content-disposition = "Content-Disposition" ":"
- disposition-type *( ";" disposition-parm )
- disposition-type = "attachment" | disp-extension-token
- disposition-parm = filename-parm | disp-extension-parm
- filename-parm = "filename" "=" quoted-string
- disp-extension-token = token
- disp-extension-parm = token "=" ( token | quoted-string )
-
- An example is
-
- Content-Disposition: attachment; filename="fname.ext"
-
- The receiving user agent SHOULD NOT respect any directory path
- information present in the filename-parm parameter, which is the only
- parameter believed to apply to HTTP implementations at this time. The
- filename SHOULD be treated as a terminal component only.
-
- If this header is used in a response with the application/octet-
- stream content-type, the implied suggestion is that the user agent
- should not display the response, but directly enter a `save response
- as...' dialog.
-
- See section 15.5 for Content-Disposition security issues.
-
-19.6 Compatibility with Previous Versions
-
- It is beyond the scope of a protocol specification to mandate
- compliance with previous versions. HTTP/1.1 was deliberately
- designed, however, to make supporting previous versions easy. It is
- worth noting that, at the time of composing this specification
- (1996), we would expect commercial HTTP/1.1 servers to:
-
- - recognize the format of the Request-Line for HTTP/0.9, 1.0, and
- 1.1 requests;
-
-
-
-Fielding, et al. Standards Track [Page 170]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- - understand any valid request in the format of HTTP/0.9, 1.0, or
- 1.1;
-
- - respond appropriately with a message in the same major version
- used by the client.
-
- And we would expect HTTP/1.1 clients to:
-
- - recognize the format of the Status-Line for HTTP/1.0 and 1.1
- responses;
-
- - understand any valid response in the format of HTTP/0.9, 1.0, or
- 1.1.
-
- For most implementations of HTTP/1.0, each connection is established
- by the client prior to the request and closed by the server after
- sending the response. Some implementations implement the Keep-Alive
- version of persistent connections described in section 19.7.1 of RFC
- 2068 [33].
-
-19.6.1 Changes from HTTP/1.0
-
- This section summarizes major differences between versions HTTP/1.0
- and HTTP/1.1.
-
-19.6.1.1 Changes to Simplify Multi-homed Web Servers and Conserve IP
- Addresses
-
- The requirements that clients and servers support the Host request-
- header, report an error if the Host request-header (section 14.23) is
- missing from an HTTP/1.1 request, and accept absolute URIs (section
- 5.1.2) are among the most important changes defined by this
- specification.
-
- Older HTTP/1.0 clients assumed a one-to-one relationship of IP
- addresses and servers; there was no other established mechanism for
- distinguishing the intended server of a request than the IP address
- to which that request was directed. The changes outlined above will
- allow the Internet, once older HTTP clients are no longer common, to
- support multiple Web sites from a single IP address, greatly
- simplifying large operational Web servers, where allocation of many
- IP addresses to a single host has created serious problems. The
- Internet will also be able to recover the IP addresses that have been
- allocated for the sole purpose of allowing special-purpose domain
- names to be used in root-level HTTP URLs. Given the rate of growth of
- the Web, and the number of servers already deployed, it is extremely
-
-
-
-
-
-Fielding, et al. Standards Track [Page 171]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- important that all implementations of HTTP (including updates to
- existing HTTP/1.0 applications) correctly implement these
- requirements:
-
- - Both clients and servers MUST support the Host request-header.
-
- - A client that sends an HTTP/1.1 request MUST send a Host header.
-
- - Servers MUST report a 400 (Bad Request) error if an HTTP/1.1
- request does not include a Host request-header.
-
- - Servers MUST accept absolute URIs.
-
-19.6.2 Compatibility with HTTP/1.0 Persistent Connections
-
- Some clients and servers might wish to be compatible with some
- previous implementations of persistent connections in HTTP/1.0
- clients and servers. Persistent connections in HTTP/1.0 are
- explicitly negotiated as they are not the default behavior. HTTP/1.0
- experimental implementations of persistent connections are faulty,
- and the new facilities in HTTP/1.1 are designed to rectify these
- problems. The problem was that some existing 1.0 clients may be
- sending Keep-Alive to a proxy server that doesn't understand
- Connection, which would then erroneously forward it to the next
- inbound server, which would establish the Keep-Alive connection and
- result in a hung HTTP/1.0 proxy waiting for the close on the
- response. The result is that HTTP/1.0 clients must be prevented from
- using Keep-Alive when talking to proxies.
-
- However, talking to proxies is the most important use of persistent
- connections, so that prohibition is clearly unacceptable. Therefore,
- we need some other mechanism for indicating a persistent connection
- is desired, which is safe to use even when talking to an old proxy
- that ignores Connection. Persistent connections are the default for
- HTTP/1.1 messages; we introduce a new keyword (Connection: close) for
- declaring non-persistence. See section 14.10.
-
- The original HTTP/1.0 form of persistent connections (the Connection:
- Keep-Alive and Keep-Alive header) is documented in RFC 2068. [33]
-
-19.6.3 Changes from RFC 2068
-
- This specification has been carefully audited to correct and
- disambiguate key word usage; RFC 2068 had many problems in respect to
- the conventions laid out in RFC 2119 [34].
-
- Clarified which error code should be used for inbound server failures
- (e.g. DNS failures). (Section 10.5.5).
-
-
-
-Fielding, et al. Standards Track [Page 172]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- CREATE had a race that required an Etag be sent when a resource is
- first created. (Section 10.2.2).
-
- Content-Base was deleted from the specification: it was not
- implemented widely, and there is no simple, safe way to introduce it
- without a robust extension mechanism. In addition, it is used in a
- similar, but not identical fashion in MHTML [45].
-
- Transfer-coding and message lengths all interact in ways that
- required fixing exactly when chunked encoding is used (to allow for
- transfer encoding that may not be self delimiting); it was important
- to straighten out exactly how message lengths are computed. (Sections
- 3.6, 4.4, 7.2.2, 13.5.2, 14.13, 14.16)
-
- A content-coding of "identity" was introduced, to solve problems
- discovered in caching. (section 3.5)
-
- Quality Values of zero should indicate that "I don't want something"
- to allow clients to refuse a representation. (Section 3.9)
-
- The use and interpretation of HTTP version numbers has been clarified
- by RFC 2145. Require proxies to upgrade requests to highest protocol
- version they support to deal with problems discovered in HTTP/1.0
- implementations (Section 3.1)
-
- Charset wildcarding is introduced to avoid explosion of character set
- names in accept headers. (Section 14.2)
-
- A case was missed in the Cache-Control model of HTTP/1.1; s-maxage
- was introduced to add this missing case. (Sections 13.4, 14.8, 14.9,
- 14.9.3)
-
- The Cache-Control: max-age directive was not properly defined for
- responses. (Section 14.9.3)
-
- There are situations where a server (especially a proxy) does not
- know the full length of a response but is capable of serving a
- byterange request. We therefore need a mechanism to allow byteranges
- with a content-range not indicating the full length of the message.
- (Section 14.16)
-
- Range request responses would become very verbose if all meta-data
- were always returned; by allowing the server to only send needed
- headers in a 206 response, this problem can be avoided. (Section
- 10.2.7, 13.5.3, and 14.27)
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 173]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Fix problem with unsatisfiable range requests; there are two cases:
- syntactic problems, and range doesn't exist in the document. The 416
- status code was needed to resolve this ambiguity needed to indicate
- an error for a byte range request that falls outside of the actual
- contents of a document. (Section 10.4.17, 14.16)
-
- Rewrite of message transmission requirements to make it much harder
- for implementors to get it wrong, as the consequences of errors here
- can have significant impact on the Internet, and to deal with the
- following problems:
-
- 1. Changing "HTTP/1.1 or later" to "HTTP/1.1", in contexts where
- this was incorrectly placing a requirement on the behavior of
- an implementation of a future version of HTTP/1.x
-
- 2. Made it clear that user-agents should retry requests, not
- "clients" in general.
-
- 3. Converted requirements for clients to ignore unexpected 100
- (Continue) responses, and for proxies to forward 100 responses,
- into a general requirement for 1xx responses.
-
- 4. Modified some TCP-specific language, to make it clearer that
- non-TCP transports are possible for HTTP.
-
- 5. Require that the origin server MUST NOT wait for the request
- body before it sends a required 100 (Continue) response.
-
- 6. Allow, rather than require, a server to omit 100 (Continue) if
- it has already seen some of the request body.
-
- 7. Allow servers to defend against denial-of-service attacks and
- broken clients.
-
- This change adds the Expect header and 417 status code. The message
- transmission requirements fixes are in sections 8.2, 10.4.18,
- 8.1.2.2, 13.11, and 14.20.
-
- Proxies should be able to add Content-Length when appropriate.
- (Section 13.5.2)
-
- Clean up confusion between 403 and 404 responses. (Section 10.4.4,
- 10.4.5, and 10.4.11)
-
- Warnings could be cached incorrectly, or not updated appropriately.
- (Section 13.1.2, 13.2.4, 13.5.2, 13.5.3, 14.9.3, and 14.46) Warning
- also needed to be a general header, as PUT or other methods may have
- need for it in requests.
-
-
-
-Fielding, et al. Standards Track [Page 174]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
- Transfer-coding had significant problems, particularly with
- interactions with chunked encoding. The solution is that transfer-
- codings become as full fledged as content-codings. This involves
- adding an IANA registry for transfer-codings (separate from content
- codings), a new header field (TE) and enabling trailer headers in the
- future. Transfer encoding is a major performance benefit, so it was
- worth fixing [39]. TE also solves another, obscure, downward
- interoperability problem that could have occurred due to interactions
- between authentication trailers, chunked encoding and HTTP/1.0
- clients.(Section 3.6, 3.6.1, and 14.39)
-
- The PATCH, LINK, UNLINK methods were defined but not commonly
- implemented in previous versions of this specification. See RFC 2068
- [33].
-
- The Alternates, Content-Version, Derived-From, Link, URI, Public and
- Content-Base header fields were defined in previous versions of this
- specification, but not commonly implemented. See RFC 2068 [33].
-
-20 Index
-
- Please see the PostScript version of this RFC for the INDEX.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 175]
-\f
-RFC 2616 HTTP/1.1 June 1999
-
-
-21. Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 176]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group J. Franks
-Request for Comments: 2617 Northwestern University
-Obsoletes: 2069 P. Hallam-Baker
-Category: Standards Track Verisign, Inc.
- J. Hostetler
- AbiSource, Inc.
- S. Lawrence
- Agranat Systems, Inc.
- P. Leach
- Microsoft Corporation
- A. Luotonen
- Netscape Communications Corporation
- L. Stewart
- Open Market, Inc.
- June 1999
-
-
- HTTP Authentication: Basic and Digest Access Authentication
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-Abstract
-
- "HTTP/1.0", includes the specification for a Basic Access
- Authentication scheme. This scheme is not considered to be a secure
- method of user authentication (unless used in conjunction with some
- external secure system such as SSL [5]), as the user name and
- password are passed over the network as cleartext.
-
- This document also provides the specification for HTTP's
- authentication framework, the original Basic authentication scheme
- and a scheme based on cryptographic hashes, referred to as "Digest
- Access Authentication". It is therefore also intended to serve as a
- replacement for RFC 2069 [6]. Some optional elements specified by
- RFC 2069 have been removed from this specification due to problems
- found since its publication; other new elements have been added for
- compatibility, those new elements have been made optional, but are
- strongly recommended.
-
-
-
-Franks, et al. Standards Track [Page 1]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- Like Basic, Digest access authentication verifies that both parties
- to a communication know a shared secret (a password); unlike Basic,
- this verification can be done without sending the password in the
- clear, which is Basic's biggest weakness. As with most other
- authentication protocols, the greatest sources of risks are usually
- found not in the core protocol itself but in policies and procedures
- surrounding its use.
-
-Table of Contents
-
- 1 Access Authentication................................ 3
- 1.1 Reliance on the HTTP/1.1 Specification............ 3
- 1.2 Access Authentication Framework................... 3
- 2 Basic Authentication Scheme.......................... 5
- 3 Digest Access Authentication Scheme.................. 6
- 3.1 Introduction...................................... 6
- 3.1.1 Purpose......................................... 6
- 3.1.2 Overall Operation............................... 6
- 3.1.3 Representation of digest values................. 7
- 3.1.4 Limitations..................................... 7
- 3.2 Specification of Digest Headers................... 7
- 3.2.1 The WWW-Authenticate Response Header............ 8
- 3.2.2 The Authorization Request Header................ 11
- 3.2.3 The Authentication-Info Header.................. 15
- 3.3 Digest Operation.................................. 17
- 3.4 Security Protocol Negotiation..................... 18
- 3.5 Example........................................... 18
- 3.6 Proxy-Authentication and Proxy-Authorization...... 19
- 4 Security Considerations.............................. 19
- 4.1 Authentication of Clients using Basic
- Authentication.................................... 19
- 4.2 Authentication of Clients using Digest
- Authentication.................................... 20
- 4.3 Limited Use Nonce Values.......................... 21
- 4.4 Comparison of Digest with Basic Authentication.... 22
- 4.5 Replay Attacks.................................... 22
- 4.6 Weakness Created by Multiple Authentication
- Schemes........................................... 23
- 4.7 Online dictionary attacks......................... 23
- 4.8 Man in the Middle................................. 24
- 4.9 Chosen plaintext attacks.......................... 24
- 4.10 Precomputed dictionary attacks.................... 25
- 4.11 Batch brute force attacks......................... 25
- 4.12 Spoofing by Counterfeit Servers................... 25
- 4.13 Storing passwords................................. 26
- 4.14 Summary........................................... 26
- 5 Sample implementation................................ 27
- 6 Acknowledgments...................................... 31
-
-
-
-Franks, et al. Standards Track [Page 2]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- 7 References........................................... 31
- 8 Authors' Addresses................................... 32
- 9 Full Copyright Statement............................. 34
-
-1 Access Authentication
-
-1.1 Reliance on the HTTP/1.1 Specification
-
- This specification is a companion to the HTTP/1.1 specification [2].
- It uses the augmented BNF section 2.1 of that document, and relies on
- both the non-terminals defined in that document and other aspects of
- the HTTP/1.1 specification.
-
-1.2 Access Authentication Framework
-
- HTTP provides a simple challenge-response authentication mechanism
- that MAY be used by a server to challenge a client request and by a
- client to provide authentication information. It uses an extensible,
- case-insensitive token to identify the authentication scheme,
- followed by a comma-separated list of attribute-value pairs which
- carry the parameters necessary for achieving authentication via that
- scheme.
-
- auth-scheme = token
- auth-param = token "=" ( token | quoted-string )
-
- The 401 (Unauthorized) response message is used by an origin server
- to challenge the authorization of a user agent. This response MUST
- include a WWW-Authenticate header field containing at least one
- challenge applicable to the requested resource. The 407 (Proxy
- Authentication Required) response message is used by a proxy to
- challenge the authorization of a client and MUST include a Proxy-
- Authenticate header field containing at least one challenge
- applicable to the proxy for the requested resource.
-
- challenge = auth-scheme 1*SP 1#auth-param
-
- Note: User agents will need to take special care in parsing the WWW-
- Authenticate or Proxy-Authenticate header field value if it contains
- more than one challenge, or if more than one WWW-Authenticate header
- field is provided, since the contents of a challenge may itself
- contain a comma-separated list of authentication parameters.
-
- The authentication parameter realm is defined for all authentication
- schemes:
-
- realm = "realm" "=" realm-value
- realm-value = quoted-string
-
-
-
-Franks, et al. Standards Track [Page 3]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- The realm directive (case-insensitive) is required for all
- authentication schemes that issue a challenge. The realm value
- (case-sensitive), in combination with the canonical root URL (the
- absoluteURI for the server whose abs_path is empty; see section 5.1.2
- of [2]) of the server being accessed, defines the protection space.
- These realms allow the protected resources on a server to be
- partitioned into a set of protection spaces, each with its own
- authentication scheme and/or authorization database. The realm value
- is a string, generally assigned by the origin server, which may have
- additional semantics specific to the authentication scheme. Note that
- there may be multiple challenges with the same auth-scheme but
- different realms.
-
- A user agent that wishes to authenticate itself with an origin
- server--usually, but not necessarily, after receiving a 401
- (Unauthorized)--MAY do so by including an Authorization header field
- with the request. A client that wishes to authenticate itself with a
- proxy--usually, but not necessarily, after receiving a 407 (Proxy
- Authentication Required)--MAY do so by including a Proxy-
- Authorization header field with the request. Both the Authorization
- field value and the Proxy-Authorization field value consist of
- credentials containing the authentication information of the client
- for the realm of the resource being requested. The user agent MUST
- choose to use one of the challenges with the strongest auth-scheme it
- understands and request credentials from the user based upon that
- challenge.
-
- credentials = auth-scheme #auth-param
-
- Note that many browsers will only recognize Basic and will require
- that it be the first auth-scheme presented. Servers should only
- include Basic if it is minimally acceptable.
-
- The protection space determines the domain over which credentials can
- be automatically applied. If a prior request has been authorized, the
- same credentials MAY be reused for all other requests within that
- protection space for a period of time determined by the
- authentication scheme, parameters, and/or user preference. Unless
- otherwise defined by the authentication scheme, a single protection
- space cannot extend outside the scope of its server.
-
- If the origin server does not wish to accept the credentials sent
- with a request, it SHOULD return a 401 (Unauthorized) response. The
- response MUST include a WWW-Authenticate header field containing at
- least one (possibly new) challenge applicable to the requested
- resource. If a proxy does not accept the credentials sent with a
- request, it SHOULD return a 407 (Proxy Authentication Required). The
- response MUST include a Proxy-Authenticate header field containing a
-
-
-
-Franks, et al. Standards Track [Page 4]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- (possibly new) challenge applicable to the proxy for the requested
- resource.
-
- The HTTP protocol does not restrict applications to this simple
- challenge-response mechanism for access authentication. Additional
- mechanisms MAY be used, such as encryption at the transport level or
- via message encapsulation, and with additional header fields
- specifying authentication information. However, these additional
- mechanisms are not defined by this specification.
-
- Proxies MUST be completely transparent regarding user agent
- authentication by origin servers. That is, they must forward the
- WWW-Authenticate and Authorization headers untouched, and follow the
- rules found in section 14.8 of [2]. Both the Proxy-Authenticate and
- the Proxy-Authorization header fields are hop-by-hop headers (see
- section 13.5.1 of [2]).
-
-2 Basic Authentication Scheme
-
- The "basic" authentication scheme is based on the model that the
- client must authenticate itself with a user-ID and a password for
- each realm. The realm value should be considered an opaque string
- which can only be compared for equality with other realms on that
- server. The server will service the request only if it can validate
- the user-ID and password for the protection space of the Request-URI.
- There are no optional authentication parameters.
-
- For Basic, the framework above is utilized as follows:
-
- challenge = "Basic" realm
- credentials = "Basic" basic-credentials
-
- Upon receipt of an unauthorized request for a URI within the
- protection space, the origin server MAY respond with a challenge like
- the following:
-
- WWW-Authenticate: Basic realm="WallyWorld"
-
- where "WallyWorld" is the string assigned by the server to identify
- the protection space of the Request-URI. A proxy may respond with the
- same challenge using the Proxy-Authenticate header field.
-
- To receive authorization, the client sends the userid and password,
- separated by a single colon (":") character, within a base64 [7]
- encoded string in the credentials.
-
- basic-credentials = base64-user-pass
- base64-user-pass = <base64 [4] encoding of user-pass,
-
-
-
-Franks, et al. Standards Track [Page 5]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- except not limited to 76 char/line>
- user-pass = userid ":" password
- userid = *<TEXT excluding ":">
- password = *TEXT
-
- Userids might be case sensitive.
-
- If the user agent wishes to send the userid "Aladdin" and password
- "open sesame", it would use the following header field:
-
- Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
-
- A client SHOULD assume that all paths at or deeper than the depth of
- the last symbolic element in the path field of the Request-URI also
- are within the protection space specified by the Basic realm value of
- the current challenge. A client MAY preemptively send the
- corresponding Authorization header with requests for resources in
- that space without receipt of another challenge from the server.
- Similarly, when a client sends a request to a proxy, it may reuse a
- userid and password in the Proxy-Authorization header field without
- receiving another challenge from the proxy server. See section 4 for
- security considerations associated with Basic authentication.
-
-3 Digest Access Authentication Scheme
-
-3.1 Introduction
-
-3.1.1 Purpose
-
- The protocol referred to as "HTTP/1.0" includes the specification for
- a Basic Access Authentication scheme[1]. That scheme is not
- considered to be a secure method of user authentication, as the user
- name and password are passed over the network in an unencrypted form.
- This section provides the specification for a scheme that does not
- send the password in cleartext, referred to as "Digest Access
- Authentication".
-
- The Digest Access Authentication scheme is not intended to be a
- complete answer to the need for security in the World Wide Web. This
- scheme provides no encryption of message content. The intent is
- simply to create an access authentication method that avoids the most
- serious flaws of Basic authentication.
-
-3.1.2 Overall Operation
-
- Like Basic Access Authentication, the Digest scheme is based on a
- simple challenge-response paradigm. The Digest scheme challenges
- using a nonce value. A valid response contains a checksum (by
-
-
-
-Franks, et al. Standards Track [Page 6]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- default, the MD5 checksum) of the username, the password, the given
- nonce value, the HTTP method, and the requested URI. In this way, the
- password is never sent in the clear. Just as with the Basic scheme,
- the username and password must be prearranged in some fashion not
- addressed by this document.
-
-3.1.3 Representation of digest values
-
- An optional header allows the server to specify the algorithm used to
- create the checksum or digest. By default the MD5 algorithm is used
- and that is the only algorithm described in this document.
-
- For the purposes of this document, an MD5 digest of 128 bits is
- represented as 32 ASCII printable characters. The bits in the 128 bit
- digest are converted from most significant to least significant bit,
- four bits at a time to their ASCII presentation as follows. Each four
- bits is represented by its familiar hexadecimal notation from the
- characters 0123456789abcdef. That is, binary 0000 gets represented by
- the character '0', 0001, by '1', and so on up to the representation
- of 1111 as 'f'.
-
-3.1.4 Limitations
-
- The Digest authentication scheme described in this document suffers
- from many known limitations. It is intended as a replacement for
- Basic authentication and nothing more. It is a password-based system
- and (on the server side) suffers from all the same problems of any
- password system. In particular, no provision is made in this protocol
- for the initial secure arrangement between user and server to
- establish the user's password.
-
- Users and implementors should be aware that this protocol is not as
- secure as Kerberos, and not as secure as any client-side private-key
- scheme. Nevertheless it is better than nothing, better than what is
- commonly used with telnet and ftp, and better than Basic
- authentication.
-
-3.2 Specification of Digest Headers
-
- The Digest Access Authentication scheme is conceptually similar to
- the Basic scheme. The formats of the modified WWW-Authenticate header
- line and the Authorization header line are specified below. In
- addition, a new header, Authentication-Info, is specified.
-
-
-
-
-
-
-
-
-Franks, et al. Standards Track [Page 7]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
-3.2.1 The WWW-Authenticate Response Header
-
- If a server receives a request for an access-protected object, and an
- acceptable Authorization header is not sent, the server responds with
- a "401 Unauthorized" status code, and a WWW-Authenticate header as
- per the framework defined above, which for the digest scheme is
- utilized as follows:
-
- challenge = "Digest" digest-challenge
-
- digest-challenge = 1#( realm | [ domain ] | nonce |
- [ opaque ] |[ stale ] | [ algorithm ] |
- [ qop-options ] | [auth-param] )
-
-
- domain = "domain" "=" <"> URI ( 1*SP URI ) <">
- URI = absoluteURI | abs_path
- nonce = "nonce" "=" nonce-value
- nonce-value = quoted-string
- opaque = "opaque" "=" quoted-string
- stale = "stale" "=" ( "true" | "false" )
- algorithm = "algorithm" "=" ( "MD5" | "MD5-sess" |
- token )
- qop-options = "qop" "=" <"> 1#qop-value <">
- qop-value = "auth" | "auth-int" | token
-
- The meanings of the values of the directives used above are as
- follows:
-
- realm
- A string to be displayed to users so they know which username and
- password to use. This string should contain at least the name of
- the host performing the authentication and might additionally
- indicate the collection of users who might have access. An example
- might be "registered_users@gotham.news.com".
-
- domain
- A quoted, space-separated list of URIs, as specified in RFC XURI
- [7], that define the protection space. If a URI is an abs_path, it
- is relative to the canonical root URL (see section 1.2 above) of
- the server being accessed. An absoluteURI in this list may refer to
- a different server than the one being accessed. The client can use
- this list to determine the set of URIs for which the same
- authentication information may be sent: any URI that has a URI in
- this list as a prefix (after both have been made absolute) may be
- assumed to be in the same protection space. If this directive is
- omitted or its value is empty, the client should assume that the
- protection space consists of all URIs on the responding server.
-
-
-
-Franks, et al. Standards Track [Page 8]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- This directive is not meaningful in Proxy-Authenticate headers, for
- which the protection space is always the entire proxy; if present
- it should be ignored.
-
- nonce
- A server-specified data string which should be uniquely generated
- each time a 401 response is made. It is recommended that this
- string be base64 or hexadecimal data. Specifically, since the
- string is passed in the header lines as a quoted string, the
- double-quote character is not allowed.
-
- The contents of the nonce are implementation dependent. The quality
- of the implementation depends on a good choice. A nonce might, for
- example, be constructed as the base 64 encoding of
-
- time-stamp H(time-stamp ":" ETag ":" private-key)
-
- where time-stamp is a server-generated time or other non-repeating
- value, ETag is the value of the HTTP ETag header associated with
- the requested entity, and private-key is data known only to the
- server. With a nonce of this form a server would recalculate the
- hash portion after receiving the client authentication header and
- reject the request if it did not match the nonce from that header
- or if the time-stamp value is not recent enough. In this way the
- server can limit the time of the nonce's validity. The inclusion of
- the ETag prevents a replay request for an updated version of the
- resource. (Note: including the IP address of the client in the
- nonce would appear to offer the server the ability to limit the
- reuse of the nonce to the same client that originally got it.
- However, that would break proxy farms, where requests from a single
- user often go through different proxies in the farm. Also, IP
- address spoofing is not that hard.)
-
- An implementation might choose not to accept a previously used
- nonce or a previously used digest, in order to protect against a
- replay attack. Or, an implementation might choose to use one-time
- nonces or digests for POST or PUT requests and a time-stamp for GET
- requests. For more details on the issues involved see section 4.
- of this document.
-
- The nonce is opaque to the client.
-
- opaque
- A string of data, specified by the server, which should be returned
- by the client unchanged in the Authorization header of subsequent
- requests with URIs in the same protection space. It is recommended
- that this string be base64 or hexadecimal data.
-
-
-
-
-Franks, et al. Standards Track [Page 9]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- stale
- A flag, indicating that the previous request from the client was
- rejected because the nonce value was stale. If stale is TRUE
- (case-insensitive), the client may wish to simply retry the request
- with a new encrypted response, without reprompting the user for a
- new username and password. The server should only set stale to TRUE
- if it receives a request for which the nonce is invalid but with a
- valid digest for that nonce (indicating that the client knows the
- correct username/password). If stale is FALSE, or anything other
- than TRUE, or the stale directive is not present, the username
- and/or password are invalid, and new values must be obtained.
-
- algorithm
- A string indicating a pair of algorithms used to produce the digest
- and a checksum. If this is not present it is assumed to be "MD5".
- If the algorithm is not understood, the challenge should be ignored
- (and a different one used, if there is more than one).
-
- In this document the string obtained by applying the digest
- algorithm to the data "data" with secret "secret" will be denoted
- by KD(secret, data), and the string obtained by applying the
- checksum algorithm to the data "data" will be denoted H(data). The
- notation unq(X) means the value of the quoted-string X without the
- surrounding quotes.
-
- For the "MD5" and "MD5-sess" algorithms
-
- H(data) = MD5(data)
-
- and
-
- KD(secret, data) = H(concat(secret, ":", data))
-
- i.e., the digest is the MD5 of the secret concatenated with a colon
- concatenated with the data. The "MD5-sess" algorithm is intended to
- allow efficient 3rd party authentication servers; for the
- difference in usage, see the description in section 3.2.2.2.
-
- qop-options
- This directive is optional, but is made so only for backward
- compatibility with RFC 2069 [6]; it SHOULD be used by all
- implementations compliant with this version of the Digest scheme.
- If present, it is a quoted string of one or more tokens indicating
- the "quality of protection" values supported by the server. The
- value "auth" indicates authentication; the value "auth-int"
- indicates authentication with integrity protection; see the
-
-
-
-
-
-Franks, et al. Standards Track [Page 10]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- descriptions below for calculating the response directive value for
- the application of this choice. Unrecognized options MUST be
- ignored.
-
- auth-param
- This directive allows for future extensions. Any unrecognized
- directive MUST be ignored.
-
-3.2.2 The Authorization Request Header
-
- The client is expected to retry the request, passing an Authorization
- header line, which is defined according to the framework above,
- utilized as follows.
-
- credentials = "Digest" digest-response
- digest-response = 1#( username | realm | nonce | digest-uri
- | response | [ algorithm ] | [cnonce] |
- [opaque] | [message-qop] |
- [nonce-count] | [auth-param] )
-
- username = "username" "=" username-value
- username-value = quoted-string
- digest-uri = "uri" "=" digest-uri-value
- digest-uri-value = request-uri ; As specified by HTTP/1.1
- message-qop = "qop" "=" qop-value
- cnonce = "cnonce" "=" cnonce-value
- cnonce-value = nonce-value
- nonce-count = "nc" "=" nc-value
- nc-value = 8LHEX
- response = "response" "=" request-digest
- request-digest = <"> 32LHEX <">
- LHEX = "0" | "1" | "2" | "3" |
- "4" | "5" | "6" | "7" |
- "8" | "9" | "a" | "b" |
- "c" | "d" | "e" | "f"
-
- The values of the opaque and algorithm fields must be those supplied
- in the WWW-Authenticate response header for the entity being
- requested.
-
- response
- A string of 32 hex digits computed as defined below, which proves
- that the user knows a password
-
- username
- The user's name in the specified realm.
-
-
-
-
-
-Franks, et al. Standards Track [Page 11]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- digest-uri
- The URI from Request-URI of the Request-Line; duplicated here
- because proxies are allowed to change the Request-Line in transit.
-
- qop
- Indicates what "quality of protection" the client has applied to
- the message. If present, its value MUST be one of the alternatives
- the server indicated it supports in the WWW-Authenticate header.
- These values affect the computation of the request-digest. Note
- that this is a single token, not a quoted list of alternatives as
- in WWW- Authenticate. This directive is optional in order to
- preserve backward compatibility with a minimal implementation of
- RFC 2069 [6], but SHOULD be used if the server indicated that qop
- is supported by providing a qop directive in the WWW-Authenticate
- header field.
-
- cnonce
- This MUST be specified if a qop directive is sent (see above), and
- MUST NOT be specified if the server did not send a qop directive in
- the WWW-Authenticate header field. The cnonce-value is an opaque
- quoted string value provided by the client and used by both client
- and server to avoid chosen plaintext attacks, to provide mutual
- authentication, and to provide some message integrity protection.
- See the descriptions below of the calculation of the response-
- digest and request-digest values.
-
- nonce-count
- This MUST be specified if a qop directive is sent (see above), and
- MUST NOT be specified if the server did not send a qop directive in
- the WWW-Authenticate header field. The nc-value is the hexadecimal
- count of the number of requests (including the current request)
- that the client has sent with the nonce value in this request. For
- example, in the first request sent in response to a given nonce
- value, the client sends "nc=00000001". The purpose of this
- directive is to allow the server to detect request replays by
- maintaining its own copy of this count - if the same nc-value is
- seen twice, then the request is a replay. See the description
- below of the construction of the request-digest value.
-
- auth-param
- This directive allows for future extensions. Any unrecognized
- directive MUST be ignored.
-
- If a directive or its value is improper, or required directives are
- missing, the proper response is 400 Bad Request. If the request-
- digest is invalid, then a login failure should be logged, since
- repeated login failures from a single client may indicate an attacker
- attempting to guess passwords.
-
-
-
-Franks, et al. Standards Track [Page 12]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- The definition of request-digest above indicates the encoding for its
- value. The following definitions show how the value is computed.
-
-3.2.2.1 Request-Digest
-
- If the "qop" value is "auth" or "auth-int":
-
- request-digest = <"> < KD ( H(A1), unq(nonce-value)
- ":" nc-value
- ":" unq(cnonce-value)
- ":" unq(qop-value)
- ":" H(A2)
- ) <">
-
- If the "qop" directive is not present (this construction is for
- compatibility with RFC 2069):
-
- request-digest =
- <"> < KD ( H(A1), unq(nonce-value) ":" H(A2) ) >
- <">
-
- See below for the definitions for A1 and A2.
-
-3.2.2.2 A1
-
- If the "algorithm" directive's value is "MD5" or is unspecified, then
- A1 is:
-
- A1 = unq(username-value) ":" unq(realm-value) ":" passwd
-
- where
-
- passwd = < user's password >
-
- If the "algorithm" directive's value is "MD5-sess", then A1 is
- calculated only once - on the first request by the client following
- receipt of a WWW-Authenticate challenge from the server. It uses the
- server nonce from that challenge, and the first client nonce value to
- construct A1 as follows:
-
- A1 = H( unq(username-value) ":" unq(realm-value)
- ":" passwd )
- ":" unq(nonce-value) ":" unq(cnonce-value)
-
- This creates a 'session key' for the authentication of subsequent
- requests and responses which is different for each "authentication
- session", thus limiting the amount of material hashed with any one
- key. (Note: see further discussion of the authentication session in
-
-
-
-Franks, et al. Standards Track [Page 13]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- section 3.3.) Because the server need only use the hash of the user
- credentials in order to create the A1 value, this construction could
- be used in conjunction with a third party authentication service so
- that the web server would not need the actual password value. The
- specification of such a protocol is beyond the scope of this
- specification.
-
-3.2.2.3 A2
-
- If the "qop" directive's value is "auth" or is unspecified, then A2
- is:
-
- A2 = Method ":" digest-uri-value
-
- If the "qop" value is "auth-int", then A2 is:
-
- A2 = Method ":" digest-uri-value ":" H(entity-body)
-
-3.2.2.4 Directive values and quoted-string
-
- Note that the value of many of the directives, such as "username-
- value", are defined as a "quoted-string". However, the "unq" notation
- indicates that surrounding quotation marks are removed in forming the
- string A1. Thus if the Authorization header includes the fields
-
- username="Mufasa", realm=myhost@testrealm.com
-
- and the user Mufasa has password "Circle Of Life" then H(A1) would be
- H(Mufasa:myhost@testrealm.com:Circle Of Life) with no quotation marks
- in the digested string.
-
- No white space is allowed in any of the strings to which the digest
- function H() is applied unless that white space exists in the quoted
- strings or entity body whose contents make up the string to be
- digested. For example, the string A1 illustrated above must be
-
- Mufasa:myhost@testrealm.com:Circle Of Life
-
- with no white space on either side of the colons, but with the white
- space between the words used in the password value. Likewise, the
- other strings digested by H() must not have white space on either
- side of the colons which delimit their fields unless that white space
- was in the quoted strings or entity body being digested.
-
- Also note that if integrity protection is applied (qop=auth-int), the
- H(entity-body) is the hash of the entity body, not the message body -
- it is computed before any transfer encoding is applied by the sender
-
-
-
-
-Franks, et al. Standards Track [Page 14]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- and after it has been removed by the recipient. Note that this
- includes multipart boundaries and embedded headers in each part of
- any multipart content-type.
-
-3.2.2.5 Various considerations
-
- The "Method" value is the HTTP request method as specified in section
- 5.1.1 of [2]. The "request-uri" value is the Request-URI from the
- request line as specified in section 5.1.2 of [2]. This may be "*",
- an "absoluteURL" or an "abs_path" as specified in section 5.1.2 of
- [2], but it MUST agree with the Request-URI. In particular, it MUST
- be an "absoluteURL" if the Request-URI is an "absoluteURL". The
- "cnonce-value" is an optional client-chosen value whose purpose is
- to foil chosen plaintext attacks.
-
- The authenticating server must assure that the resource designated by
- the "uri" directive is the same as the resource specified in the
- Request-Line; if they are not, the server SHOULD return a 400 Bad
- Request error. (Since this may be a symptom of an attack, server
- implementers may want to consider logging such errors.) The purpose
- of duplicating information from the request URL in this field is to
- deal with the possibility that an intermediate proxy may alter the
- client's Request-Line. This altered (but presumably semantically
- equivalent) request would not result in the same digest as that
- calculated by the client.
-
- Implementers should be aware of how authenticated transactions
- interact with shared caches. The HTTP/1.1 protocol specifies that
- when a shared cache (see section 13.7 of [2]) has received a request
- containing an Authorization header and a response from relaying that
- request, it MUST NOT return that response as a reply to any other
- request, unless one of two Cache-Control (see section 14.9 of [2])
- directives was present in the response. If the original response
- included the "must-revalidate" Cache-Control directive, the cache MAY
- use the entity of that response in replying to a subsequent request,
- but MUST first revalidate it with the origin server, using the
- request headers from the new request to allow the origin server to
- authenticate the new request. Alternatively, if the original response
- included the "public" Cache-Control directive, the response entity
- MAY be returned in reply to any subsequent request.
-
-3.2.3 The Authentication-Info Header
-
- The Authentication-Info header is used by the server to communicate
- some information regarding the successful authentication in the
- response.
-
-
-
-
-
-Franks, et al. Standards Track [Page 15]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- AuthenticationInfo = "Authentication-Info" ":" auth-info
- auth-info = 1#(nextnonce | [ message-qop ]
- | [ response-auth ] | [ cnonce ]
- | [nonce-count] )
- nextnonce = "nextnonce" "=" nonce-value
- response-auth = "rspauth" "=" response-digest
- response-digest = <"> *LHEX <">
-
- The value of the nextnonce directive is the nonce the server wishes
- the client to use for a future authentication response. The server
- may send the Authentication-Info header with a nextnonce field as a
- means of implementing one-time or otherwise changing nonces. If the
- nextnonce field is present the client SHOULD use it when constructing
- the Authorization header for its next request. Failure of the client
- to do so may result in a request to re-authenticate from the server
- with the "stale=TRUE".
-
- Server implementations should carefully consider the performance
- implications of the use of this mechanism; pipelined requests will
- not be possible if every response includes a nextnonce directive
- that must be used on the next request received by the server.
- Consideration should be given to the performance vs. security
- tradeoffs of allowing an old nonce value to be used for a limited
- time to permit request pipelining. Use of the nonce-count can
- retain most of the security advantages of a new server nonce
- without the deleterious affects on pipelining.
-
- message-qop
- Indicates the "quality of protection" options applied to the
- response by the server. The value "auth" indicates authentication;
- the value "auth-int" indicates authentication with integrity
- protection. The server SHOULD use the same value for the message-
- qop directive in the response as was sent by the client in the
- corresponding request.
-
- The optional response digest in the "response-auth" directive
- supports mutual authentication -- the server proves that it knows the
- user's secret, and with qop=auth-int also provides limited integrity
- protection of the response. The "response-digest" value is calculated
- as for the "request-digest" in the Authorization header, except that
- if "qop=auth" or is not specified in the Authorization header for the
- request, A2 is
-
- A2 = ":" digest-uri-value
-
- and if "qop=auth-int", then A2 is
-
- A2 = ":" digest-uri-value ":" H(entity-body)
-
-
-
-Franks, et al. Standards Track [Page 16]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- where "digest-uri-value" is the value of the "uri" directive on the
- Authorization header in the request. The "cnonce-value" and "nc-
- value" MUST be the ones for the client request to which this message
- is the response. The "response-auth", "cnonce", and "nonce-count"
- directives MUST BE present if "qop=auth" or "qop=auth-int" is
- specified.
-
- The Authentication-Info header is allowed in the trailer of an HTTP
- message transferred via chunked transfer-coding.
-
-3.3 Digest Operation
-
- Upon receiving the Authorization header, the server may check its
- validity by looking up the password that corresponds to the submitted
- username. Then, the server must perform the same digest operation
- (e.g., MD5) performed by the client, and compare the result to the
- given request-digest value.
-
- Note that the HTTP server does not actually need to know the user's
- cleartext password. As long as H(A1) is available to the server, the
- validity of an Authorization header may be verified.
-
- The client response to a WWW-Authenticate challenge for a protection
- space starts an authentication session with that protection space.
- The authentication session lasts until the client receives another
- WWW-Authenticate challenge from any server in the protection space. A
- client should remember the username, password, nonce, nonce count and
- opaque values associated with an authentication session to use to
- construct the Authorization header in future requests within that
- protection space. The Authorization header may be included
- preemptively; doing so improves server efficiency and avoids extra
- round trips for authentication challenges. The server may choose to
- accept the old Authorization header information, even though the
- nonce value included might not be fresh. Alternatively, the server
- may return a 401 response with a new nonce value, causing the client
- to retry the request; by specifying stale=TRUE with this response,
- the server tells the client to retry with the new nonce, but without
- prompting for a new username and password.
-
- Because the client is required to return the value of the opaque
- directive given to it by the server for the duration of a session,
- the opaque data may be used to transport authentication session state
- information. (Note that any such use can also be accomplished more
- easily and safely by including the state in the nonce.) For example,
- a server could be responsible for authenticating content that
- actually sits on another server. It would achieve this by having the
- first 401 response include a domain directive whose value includes a
- URI on the second server, and an opaque directive whose value
-
-
-
-Franks, et al. Standards Track [Page 17]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- contains the state information. The client will retry the request, at
- which time the server might respond with a 301/302 redirection,
- pointing to the URI on the second server. The client will follow the
- redirection, and pass an Authorization header , including the
- <opaque> data.
-
- As with the basic scheme, proxies must be completely transparent in
- the Digest access authentication scheme. That is, they must forward
- the WWW-Authenticate, Authentication-Info and Authorization headers
- untouched. If a proxy wants to authenticate a client before a request
- is forwarded to the server, it can be done using the Proxy-
- Authenticate and Proxy-Authorization headers described in section 3.6
- below.
-
-3.4 Security Protocol Negotiation
-
- It is useful for a server to be able to know which security schemes a
- client is capable of handling.
-
- It is possible that a server may want to require Digest as its
- authentication method, even if the server does not know that the
- client supports it. A client is encouraged to fail gracefully if the
- server specifies only authentication schemes it cannot handle.
-
-3.5 Example
-
- The following example assumes that an access-protected document is
- being requested from the server via a GET request. The URI of the
- document is "http://www.nowhere.org/dir/index.html". Both client and
- server know that the username for this document is "Mufasa", and the
- password is "Circle Of Life" (with one space between each of the
- three words).
-
- The first time the client requests the document, no Authorization
- header is sent, so the server responds with:
-
- HTTP/1.1 401 Unauthorized
- WWW-Authenticate: Digest
- realm="testrealm@host.com",
- qop="auth,auth-int",
- nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
- opaque="5ccc069c403ebaf9f0171e9517f40e41"
-
- The client may prompt the user for the username and password, after
- which it will respond with a new request, including the following
- Authorization header:
-
-
-
-
-
-Franks, et al. Standards Track [Page 18]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- Authorization: Digest username="Mufasa",
- realm="testrealm@host.com",
- nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
- uri="/dir/index.html",
- qop=auth,
- nc=00000001,
- cnonce="0a4f113b",
- response="6629fae49393a05397450978507c4ef1",
- opaque="5ccc069c403ebaf9f0171e9517f40e41"
-
-3.6 Proxy-Authentication and Proxy-Authorization
-
- The digest authentication scheme may also be used for authenticating
- users to proxies, proxies to proxies, or proxies to origin servers by
- use of the Proxy-Authenticate and Proxy-Authorization headers. These
- headers are instances of the Proxy-Authenticate and Proxy-
- Authorization headers specified in sections 10.33 and 10.34 of the
- HTTP/1.1 specification [2] and their behavior is subject to
- restrictions described there. The transactions for proxy
- authentication are very similar to those already described. Upon
- receiving a request which requires authentication, the proxy/server
- must issue the "407 Proxy Authentication Required" response with a
- "Proxy-Authenticate" header. The digest-challenge used in the
- Proxy-Authenticate header is the same as that for the WWW-
- Authenticate header as defined above in section 3.2.1.
-
- The client/proxy must then re-issue the request with a Proxy-
- Authorization header, with directives as specified for the
- Authorization header in section 3.2.2 above.
-
- On subsequent responses, the server sends Proxy-Authentication-Info
- with directives the same as those for the Authentication-Info header
- field.
-
- Note that in principle a client could be asked to authenticate itself
- to both a proxy and an end-server, but never in the same response.
-
-4 Security Considerations
-
-4.1 Authentication of Clients using Basic Authentication
-
- The Basic authentication scheme is not a secure method of user
- authentication, nor does it in any way protect the entity, which is
- transmitted in cleartext across the physical network used as the
- carrier. HTTP does not prevent additional authentication schemes and
- encryption mechanisms from being employed to increase security or the
- addition of enhancements (such as schemes to use one-time passwords)
- to Basic authentication.
-
-
-
-Franks, et al. Standards Track [Page 19]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- The most serious flaw in Basic authentication is that it results in
- the essentially cleartext transmission of the user's password over
- the physical network. It is this problem which Digest Authentication
- attempts to address.
-
- Because Basic authentication involves the cleartext transmission of
- passwords it SHOULD NOT be used (without enhancements) to protect
- sensitive or valuable information.
-
- A common use of Basic authentication is for identification purposes
- -- requiring the user to provide a user name and password as a means
- of identification, for example, for purposes of gathering accurate
- usage statistics on a server. When used in this way it is tempting to
- think that there is no danger in its use if illicit access to the
- protected documents is not a major concern. This is only correct if
- the server issues both user name and password to the users and in
- particular does not allow the user to choose his or her own password.
- The danger arises because naive users frequently reuse a single
- password to avoid the task of maintaining multiple passwords.
-
- If a server permits users to select their own passwords, then the
- threat is not only unauthorized access to documents on the server but
- also unauthorized access to any other resources on other systems that
- the user protects with the same password. Furthermore, in the
- server's password database, many of the passwords may also be users'
- passwords for other sites. The owner or administrator of such a
- system could therefore expose all users of the system to the risk of
- unauthorized access to all those sites if this information is not
- maintained in a secure fashion.
-
- Basic Authentication is also vulnerable to spoofing by counterfeit
- servers. If a user can be led to believe that he is connecting to a
- host containing information protected by Basic authentication when,
- in fact, he is connecting to a hostile server or gateway, then the
- attacker can request a password, store it for later use, and feign an
- error. This type of attack is not possible with Digest
- Authentication. Server implementers SHOULD guard against the
- possibility of this sort of counterfeiting by gateways or CGI
- scripts. In particular it is very dangerous for a server to simply
- turn over a connection to a gateway. That gateway can then use the
- persistent connection mechanism to engage in multiple transactions
- with the client while impersonating the original server in a way that
- is not detectable by the client.
-
-4.2 Authentication of Clients using Digest Authentication
-
- Digest Authentication does not provide a strong authentication
- mechanism, when compared to public key based mechanisms, for example.
-
-
-
-Franks, et al. Standards Track [Page 20]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- However, it is significantly stronger than (e.g.) CRAM-MD5, which has
- been proposed for use with LDAP [10], POP and IMAP (see RFC 2195
- [9]). It is intended to replace the much weaker and even more
- dangerous Basic mechanism.
-
- Digest Authentication offers no confidentiality protection beyond
- protecting the actual password. All of the rest of the request and
- response are available to an eavesdropper.
-
- Digest Authentication offers only limited integrity protection for
- the messages in either direction. If qop=auth-int mechanism is used,
- those parts of the message used in the calculation of the WWW-
- Authenticate and Authorization header field response directive values
- (see section 3.2 above) are protected. Most header fields and their
- values could be modified as a part of a man-in-the-middle attack.
-
- Many needs for secure HTTP transactions cannot be met by Digest
- Authentication. For those needs TLS or SHTTP are more appropriate
- protocols. In particular Digest authentication cannot be used for any
- transaction requiring confidentiality protection. Nevertheless many
- functions remain for which Digest authentication is both useful and
- appropriate. Any service in present use that uses Basic should be
- switched to Digest as soon as practical.
-
-4.3 Limited Use Nonce Values
-
- The Digest scheme uses a server-specified nonce to seed the
- generation of the request-digest value (as specified in section
- 3.2.2.1 above). As shown in the example nonce in section 3.2.1, the
- server is free to construct the nonce such that it may only be used
- from a particular client, for a particular resource, for a limited
- period of time or number of uses, or any other restrictions. Doing
- so strengthens the protection provided against, for example, replay
- attacks (see 4.5). However, it should be noted that the method
- chosen for generating and checking the nonce also has performance and
- resource implications. For example, a server may choose to allow
- each nonce value to be used only once by maintaining a record of
- whether or not each recently issued nonce has been returned and
- sending a next-nonce directive in the Authentication-Info header
- field of every response. This protects against even an immediate
- replay attack, but has a high cost checking nonce values, and perhaps
- more important will cause authentication failures for any pipelined
- requests (presumably returning a stale nonce indication). Similarly,
- incorporating a request-specific element such as the Etag value for a
- resource limits the use of the nonce to that version of the resource
- and also defeats pipelining. Thus it may be useful to do so for
- methods with side effects but have unacceptable performance for those
- that do not.
-
-
-
-Franks, et al. Standards Track [Page 21]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
-4.4 Comparison of Digest with Basic Authentication
-
- Both Digest and Basic Authentication are very much on the weak end of
- the security strength spectrum. But a comparison between the two
- points out the utility, even necessity, of replacing Basic by Digest.
-
- The greatest threat to the type of transactions for which these
- protocols are used is network snooping. This kind of transaction
- might involve, for example, online access to a database whose use is
- restricted to paying subscribers. With Basic authentication an
- eavesdropper can obtain the password of the user. This not only
- permits him to access anything in the database, but, often worse,
- will permit access to anything else the user protects with the same
- password.
-
- By contrast, with Digest Authentication the eavesdropper only gets
- access to the transaction in question and not to the user's password.
- The information gained by the eavesdropper would permit a replay
- attack, but only with a request for the same document, and even that
- may be limited by the server's choice of nonce.
-
-4.5 Replay Attacks
-
- A replay attack against Digest authentication would usually be
- pointless for a simple GET request since an eavesdropper would
- already have seen the only document he could obtain with a replay.
- This is because the URI of the requested document is digested in the
- client request and the server will only deliver that document. By
- contrast under Basic Authentication once the eavesdropper has the
- user's password, any document protected by that password is open to
- him.
-
- Thus, for some purposes, it is necessary to protect against replay
- attacks. A good Digest implementation can do this in various ways.
- The server created "nonce" value is implementation dependent, but if
- it contains a digest of the client IP, a time-stamp, the resource
- ETag, and a private server key (as recommended above) then a replay
- attack is not simple. An attacker must convince the server that the
- request is coming from a false IP address and must cause the server
- to deliver the document to an IP address different from the address
- to which it believes it is sending the document. An attack can only
- succeed in the period before the time-stamp expires. Digesting the
- client IP and time-stamp in the nonce permits an implementation which
- does not maintain state between transactions.
-
- For applications where no possibility of replay attack can be
- tolerated the server can use one-time nonce values which will not be
- honored for a second use. This requires the overhead of the server
-
-
-
-Franks, et al. Standards Track [Page 22]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- remembering which nonce values have been used until the nonce time-
- stamp (and hence the digest built with it) has expired, but it
- effectively protects against replay attacks.
-
- An implementation must give special attention to the possibility of
- replay attacks with POST and PUT requests. Unless the server employs
- one-time or otherwise limited-use nonces and/or insists on the use of
- the integrity protection of qop=auth-int, an attacker could replay
- valid credentials from a successful request with counterfeit form
- data or other message body. Even with the use of integrity protection
- most metadata in header fields is not protected. Proper nonce
- generation and checking provides some protection against replay of
- previously used valid credentials, but see 4.8.
-
-4.6 Weakness Created by Multiple Authentication Schemes
-
- An HTTP/1.1 server may return multiple challenges with a 401
- (Authenticate) response, and each challenge may use a different
- auth-scheme. A user agent MUST choose to use the strongest auth-
- scheme it understands and request credentials from the user based
- upon that challenge.
-
- Note that many browsers will only recognize Basic and will require
- that it be the first auth-scheme presented. Servers should only
- include Basic if it is minimally acceptable.
-
- When the server offers choices of authentication schemes using the
- WWW-Authenticate header, the strength of the resulting authentication
- is only as good as that of the of the weakest of the authentication
- schemes. See section 4.8 below for discussion of particular attack
- scenarios that exploit multiple authentication schemes.
-
-4.7 Online dictionary attacks
-
- If the attacker can eavesdrop, then it can test any overheard
- nonce/response pairs against a list of common words. Such a list is
- usually much smaller than the total number of possible passwords. The
- cost of computing the response for each password on the list is paid
- once for each challenge.
-
- The server can mitigate this attack by not allowing users to select
- passwords that are in a dictionary.
-
-
-
-
-
-
-
-
-
-Franks, et al. Standards Track [Page 23]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
-4.8 Man in the Middle
-
- Both Basic and Digest authentication are vulnerable to "man in the
- middle" (MITM) attacks, for example, from a hostile or compromised
- proxy. Clearly, this would present all the problems of eavesdropping.
- But it also offers some additional opportunities to the attacker.
-
- A possible man-in-the-middle attack would be to add a weak
- authentication scheme to the set of choices, hoping that the client
- will use one that exposes the user's credentials (e.g. password). For
- this reason, the client should always use the strongest scheme that
- it understands from the choices offered.
-
- An even better MITM attack would be to remove all offered choices,
- replacing them with a challenge that requests only Basic
- authentication, then uses the cleartext credentials from the Basic
- authentication to authenticate to the origin server using the
- stronger scheme it requested. A particularly insidious way to mount
- such a MITM attack would be to offer a "free" proxy caching service
- to gullible users.
-
- User agents should consider measures such as presenting a visual
- indication at the time of the credentials request of what
- authentication scheme is to be used, or remembering the strongest
- authentication scheme ever requested by a server and produce a
- warning message before using a weaker one. It might also be a good
- idea for the user agent to be configured to demand Digest
- authentication in general, or from specific sites.
-
- Or, a hostile proxy might spoof the client into making a request the
- attacker wanted rather than one the client wanted. Of course, this is
- still much harder than a comparable attack against Basic
- Authentication.
-
-4.9 Chosen plaintext attacks
-
- With Digest authentication, a MITM or a malicious server can
- arbitrarily choose the nonce that the client will use to compute the
- response. This is called a "chosen plaintext" attack. The ability to
- choose the nonce is known to make cryptanalysis much easier [8].
-
- However, no way to analyze the MD5 one-way function used by Digest
- using chosen plaintext is currently known.
-
- The countermeasure against this attack is for clients to be
- configured to require the use of the optional "cnonce" directive;
- this allows the client to vary the input to the hash in a way not
- chosen by the attacker.
-
-
-
-Franks, et al. Standards Track [Page 24]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
-4.10 Precomputed dictionary attacks
-
- With Digest authentication, if the attacker can execute a chosen
- plaintext attack, the attacker can precompute the response for many
- common words to a nonce of its choice, and store a dictionary of
- (response, password) pairs. Such precomputation can often be done in
- parallel on many machines. It can then use the chosen plaintext
- attack to acquire a response corresponding to that challenge, and
- just look up the password in the dictionary. Even if most passwords
- are not in the dictionary, some might be. Since the attacker gets to
- pick the challenge, the cost of computing the response for each
- password on the list can be amortized over finding many passwords. A
- dictionary with 100 million password/response pairs would take about
- 3.2 gigabytes of disk storage.
-
- The countermeasure against this attack is to for clients to be
- configured to require the use of the optional "cnonce" directive.
-
-4.11 Batch brute force attacks
-
- With Digest authentication, a MITM can execute a chosen plaintext
- attack, and can gather responses from many users to the same nonce.
- It can then find all the passwords within any subset of password
- space that would generate one of the nonce/response pairs in a single
- pass over that space. It also reduces the time to find the first
- password by a factor equal to the number of nonce/response pairs
- gathered. This search of the password space can often be done in
- parallel on many machines, and even a single machine can search large
- subsets of the password space very quickly -- reports exist of
- searching all passwords with six or fewer letters in a few hours.
-
- The countermeasure against this attack is to for clients to be
- configured to require the use of the optional "cnonce" directive.
-
-4.12 Spoofing by Counterfeit Servers
-
- Basic Authentication is vulnerable to spoofing by counterfeit
- servers. If a user can be led to believe that she is connecting to a
- host containing information protected by a password she knows, when
- in fact she is connecting to a hostile server, then the hostile
- server can request a password, store it away for later use, and feign
- an error. This type of attack is more difficult with Digest
- Authentication -- but the client must know to demand that Digest
- authentication be used, perhaps using some of the techniques
- described above to counter "man-in-the-middle" attacks. Again, the
- user can be helped in detecting this attack by a visual indication of
- the authentication mechanism in use with appropriate guidance in
- interpreting the implications of each scheme.
-
-
-
-Franks, et al. Standards Track [Page 25]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
-4.13 Storing passwords
-
- Digest authentication requires that the authenticating agent (usually
- the server) store some data derived from the user's name and password
- in a "password file" associated with a given realm. Normally this
- might contain pairs consisting of username and H(A1), where H(A1) is
- the digested value of the username, realm, and password as described
- above.
-
- The security implications of this are that if this password file is
- compromised, then an attacker gains immediate access to documents on
- the server using this realm. Unlike, say a standard UNIX password
- file, this information need not be decrypted in order to access
- documents in the server realm associated with this file. On the other
- hand, decryption, or more likely a brute force attack, would be
- necessary to obtain the user's password. This is the reason that the
- realm is part of the digested data stored in the password file. It
- means that if one Digest authentication password file is compromised,
- it does not automatically compromise others with the same username
- and password (though it does expose them to brute force attack).
-
- There are two important security consequences of this. First the
- password file must be protected as if it contained unencrypted
- passwords, because for the purpose of accessing documents in its
- realm, it effectively does.
-
- A second consequence of this is that the realm string should be
- unique among all realms which any single user is likely to use. In
- particular a realm string should include the name of the host doing
- the authentication. The inability of the client to authenticate the
- server is a weakness of Digest Authentication.
-
-4.14 Summary
-
- By modern cryptographic standards Digest Authentication is weak. But
- for a large range of purposes it is valuable as a replacement for
- Basic Authentication. It remedies some, but not all, weaknesses of
- Basic Authentication. Its strength may vary depending on the
- implementation. In particular the structure of the nonce (which is
- dependent on the server implementation) may affect the ease of
- mounting a replay attack. A range of server options is appropriate
- since, for example, some implementations may be willing to accept the
- server overhead of one-time nonces or digests to eliminate the
- possibility of replay. Others may satisfied with a nonce like the one
- recommended above restricted to a single IP address and a single ETag
- or with a limited lifetime.
-
-
-
-
-
-Franks, et al. Standards Track [Page 26]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- The bottom line is that *any* compliant implementation will be
- relatively weak by cryptographic standards, but *any* compliant
- implementation will be far superior to Basic Authentication.
-
-5 Sample implementation
-
- The following code implements the calculations of H(A1), H(A2),
- request-digest and response-digest, and a test program which computes
- the values used in the example of section 3.5. It uses the MD5
- implementation from RFC 1321.
-
- File "digcalc.h":
-
-#define HASHLEN 16
-typedef char HASH[HASHLEN];
-#define HASHHEXLEN 32
-typedef char HASHHEX[HASHHEXLEN+1];
-#define IN
-#define OUT
-
-/* calculate H(A1) as per HTTP Digest spec */
-void DigestCalcHA1(
- IN char * pszAlg,
- IN char * pszUserName,
- IN char * pszRealm,
- IN char * pszPassword,
- IN char * pszNonce,
- IN char * pszCNonce,
- OUT HASHHEX SessionKey
- );
-
-/* calculate request-digest/response-digest as per HTTP Digest spec */
-void DigestCalcResponse(
- IN HASHHEX HA1, /* H(A1) */
- IN char * pszNonce, /* nonce from server */
- IN char * pszNonceCount, /* 8 hex digits */
- IN char * pszCNonce, /* client nonce */
- IN char * pszQop, /* qop-value: "", "auth", "auth-int" */
- IN char * pszMethod, /* method from the request */
- IN char * pszDigestUri, /* requested URL */
- IN HASHHEX HEntity, /* H(entity body) if qop="auth-int" */
- OUT HASHHEX Response /* request-digest or response-digest */
- );
-
-File "digcalc.c":
-
-#include <global.h>
-#include <md5.h>
-
-
-
-Franks, et al. Standards Track [Page 27]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
-#include <string.h>
-#include "digcalc.h"
-
-void CvtHex(
- IN HASH Bin,
- OUT HASHHEX Hex
- )
-{
- unsigned short i;
- unsigned char j;
-
- for (i = 0; i < HASHLEN; i++) {
- j = (Bin[i] >> 4) & 0xf;
- if (j <= 9)
- Hex[i*2] = (j + '0');
- else
- Hex[i*2] = (j + 'a' - 10);
- j = Bin[i] & 0xf;
- if (j <= 9)
- Hex[i*2+1] = (j + '0');
- else
- Hex[i*2+1] = (j + 'a' - 10);
- };
- Hex[HASHHEXLEN] = '\0';
-};
-
-/* calculate H(A1) as per spec */
-void DigestCalcHA1(
- IN char * pszAlg,
- IN char * pszUserName,
- IN char * pszRealm,
- IN char * pszPassword,
- IN char * pszNonce,
- IN char * pszCNonce,
- OUT HASHHEX SessionKey
- )
-{
- MD5_CTX Md5Ctx;
- HASH HA1;
-
- MD5Init(&Md5Ctx);
- MD5Update(&Md5Ctx, pszUserName, strlen(pszUserName));
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, pszRealm, strlen(pszRealm));
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, pszPassword, strlen(pszPassword));
- MD5Final(HA1, &Md5Ctx);
- if (stricmp(pszAlg, "md5-sess") == 0) {
-
-
-
-Franks, et al. Standards Track [Page 28]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- MD5Init(&Md5Ctx);
- MD5Update(&Md5Ctx, HA1, HASHLEN);
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, pszNonce, strlen(pszNonce));
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, pszCNonce, strlen(pszCNonce));
- MD5Final(HA1, &Md5Ctx);
- };
- CvtHex(HA1, SessionKey);
-};
-
-/* calculate request-digest/response-digest as per HTTP Digest spec */
-void DigestCalcResponse(
- IN HASHHEX HA1, /* H(A1) */
- IN char * pszNonce, /* nonce from server */
- IN char * pszNonceCount, /* 8 hex digits */
- IN char * pszCNonce, /* client nonce */
- IN char * pszQop, /* qop-value: "", "auth", "auth-int" */
- IN char * pszMethod, /* method from the request */
- IN char * pszDigestUri, /* requested URL */
- IN HASHHEX HEntity, /* H(entity body) if qop="auth-int" */
- OUT HASHHEX Response /* request-digest or response-digest */
- )
-{
- MD5_CTX Md5Ctx;
- HASH HA2;
- HASH RespHash;
- HASHHEX HA2Hex;
-
- // calculate H(A2)
- MD5Init(&Md5Ctx);
- MD5Update(&Md5Ctx, pszMethod, strlen(pszMethod));
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, pszDigestUri, strlen(pszDigestUri));
- if (stricmp(pszQop, "auth-int") == 0) {
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, HEntity, HASHHEXLEN);
- };
- MD5Final(HA2, &Md5Ctx);
- CvtHex(HA2, HA2Hex);
-
- // calculate response
- MD5Init(&Md5Ctx);
- MD5Update(&Md5Ctx, HA1, HASHHEXLEN);
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, pszNonce, strlen(pszNonce));
- MD5Update(&Md5Ctx, ":", 1);
- if (*pszQop) {
-
-
-
-Franks, et al. Standards Track [Page 29]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- MD5Update(&Md5Ctx, pszNonceCount, strlen(pszNonceCount));
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, pszCNonce, strlen(pszCNonce));
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, pszQop, strlen(pszQop));
- MD5Update(&Md5Ctx, ":", 1);
- };
- MD5Update(&Md5Ctx, HA2Hex, HASHHEXLEN);
- MD5Final(RespHash, &Md5Ctx);
- CvtHex(RespHash, Response);
-};
-
-File "digtest.c":
-
-
-#include <stdio.h>
-#include "digcalc.h"
-
-void main(int argc, char ** argv) {
-
- char * pszNonce = "dcd98b7102dd2f0e8b11d0f600bfb0c093";
- char * pszCNonce = "0a4f113b";
- char * pszUser = "Mufasa";
- char * pszRealm = "testrealm@host.com";
- char * pszPass = "Circle Of Life";
- char * pszAlg = "md5";
- char szNonceCount[9] = "00000001";
- char * pszMethod = "GET";
- char * pszQop = "auth";
- char * pszURI = "/dir/index.html";
- HASHHEX HA1;
- HASHHEX HA2 = "";
- HASHHEX Response;
-
- DigestCalcHA1(pszAlg, pszUser, pszRealm, pszPass, pszNonce,
-pszCNonce, HA1);
- DigestCalcResponse(HA1, pszNonce, szNonceCount, pszCNonce, pszQop,
- pszMethod, pszURI, HA2, Response);
- printf("Response = %s\n", Response);
-};
-
-
-
-
-
-
-
-
-
-
-
-Franks, et al. Standards Track [Page 30]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
-6 Acknowledgments
-
- Eric W. Sink, of AbiSource, Inc., was one of the original authors
- before the specification underwent substantial revision.
-
- In addition to the authors, valuable discussion instrumental in
- creating this document has come from Peter J. Churchyard, Ned Freed,
- and David M. Kristol.
-
- Jim Gettys and Larry Masinter edited this document for update.
-
-7 References
-
- [1] Berners-Lee, T., Fielding, R. and H. Frystyk, "Hypertext
- Transfer Protocol -- HTTP/1.0", RFC 1945, May 1996.
-
- [2] Fielding, R., Gettys, J., Mogul, J., Frysyk, H., Masinter, L.,
- Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
- HTTP/1.1", RFC 2616, June 1999.
-
- [3] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April
- 1992.
-
- [4] Freed, N. and N. Borenstein. "Multipurpose Internet Mail
- Extensions (MIME) Part One: Format of Internet Message Bodies",
- RFC 2045, November 1996.
-
- [5] Dierks, T. and C. Allen "The TLS Protocol, Version 1.0", RFC
- 2246, January 1999.
-
- [6] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P.,
- Luotonen, A., Sink, E. and L. Stewart, "An Extension to HTTP :
- Digest Access Authentication", RFC 2069, January 1997.
-
- [7] Berners Lee, T, Fielding, R. and L. Masinter, "Uniform Resource
- Identifiers (URI): Generic Syntax", RFC 2396, August 1998.
-
- [8] Kaliski, B.,Robshaw, M., "Message Authentication with MD5",
- CryptoBytes, Sping 1995, RSA Inc,
- (http://www.rsa.com/rsalabs/pubs/cryptobytes/spring95/md5.htm)
-
- [9] Klensin, J., Catoe, R. and P. Krumviede, "IMAP/POP AUTHorize
- Extension for Simple Challenge/Response", RFC 2195, September
- 1997.
-
- [10] Morgan, B., Alvestrand, H., Hodges, J., Wahl, M.,
- "Authentication Methods for LDAP", Work in Progress.
-
-
-
-
-Franks, et al. Standards Track [Page 31]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
-8 Authors' Addresses
-
- John Franks
- Professor of Mathematics
- Department of Mathematics
- Northwestern University
- Evanston, IL 60208-2730, USA
-
- EMail: john@math.nwu.edu
-
-
- Phillip M. Hallam-Baker
- Principal Consultant
- Verisign Inc.
- 301 Edgewater Place
- Suite 210
- Wakefield MA 01880, USA
-
- EMail: pbaker@verisign.com
-
-
- Jeffery L. Hostetler
- Software Craftsman
- AbiSource, Inc.
- 6 Dunlap Court
- Savoy, IL 61874
-
- EMail: jeff@AbiSource.com
-
-
- Scott D. Lawrence
- Agranat Systems, Inc.
- 5 Clocktower Place, Suite 400
- Maynard, MA 01754, USA
-
- EMail: lawrence@agranat.com
-
-
- Paul J. Leach
- Microsoft Corporation
- 1 Microsoft Way
- Redmond, WA 98052, USA
-
- EMail: paulle@microsoft.com
-
-
-
-
-
-
-
-Franks, et al. Standards Track [Page 32]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
- Ari Luotonen
- Member of Technical Staff
- Netscape Communications Corporation
- 501 East Middlefield Road
- Mountain View, CA 94043, USA
-
-
- Lawrence C. Stewart
- Open Market, Inc.
- 215 First Street
- Cambridge, MA 02142, USA
-
- EMail: stewart@OpenMarket.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Franks, et al. Standards Track [Page 33]
-\f
-RFC 2617 HTTP Authentication June 1999
-
-
-9. Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Franks, et al. Standards Track [Page 34]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group A. Medvinsky
-Request for Comments: 2712 Excite
-Category: Standards Track M. Hur
- CyberSafe Corporation
- October 1999
-
-
- Addition of Kerberos Cipher Suites to Transport Layer Security (TLS)
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-IESG Note:
-
- The 40-bit ciphersuites defined in this memo are included only for
- the purpose of documenting the fact that those ciphersuite codes have
- already been assigned. 40-bit ciphersuites were designed to comply
- with US-centric, and now obsolete, export restrictions. They were
- never secure, and nowadays are inadequate even for casual
- applications. Implementation and use of the 40-bit ciphersuites
- defined in this document, and elsewhere, is strongly discouraged.
-
-1. Abstract
-
- This document proposes the addition of new cipher suites to the TLS
- protocol [1] to support Kerberos-based authentication. Kerberos
- credentials are used to achieve mutual authentication and to
- establish a master secret which is subsequently used to secure
- client-server communication.
-
-2. Introduction
-
- Flexibility is one of the main strengths of the TLS protocol.
- Clients and servers can negotiate cipher suites to meet specific
- security and administrative policies. However, to date,
- authentication in TLS is limited only to public key solutions. As a
- result, TLS does not fully support organizations with heterogeneous
- security deployments that include authentication systems based on
- symmetric cryptography. Kerberos, originally developed at MIT, is
-
-
-
-Medvinsky & Hur Standards Track [Page 1]
-\f
-RFC 2712 Addition of Kerberos Cipher Suites to TLS October 1999
-
-
- based on an open standard [2] and is the most widely deployed
- symmetric key authentication system. This document proposes a new
- option for negotiating Kerberos authentication within the TLS
- framework. This achieves mutual authentication and the establishment
- of a master secret using Kerberos credentials. The proposed changes
- are minimal and, in fact, no different from adding a new public key
- algorithm to the TLS framework.
-
-3. Kerberos Authentication Option In TLS
-
- This section describes the addition of the Kerberos authentication
- option to the TLS protocol. Throughout this document, we refer to
- the basic SSL handshake shown in Figure 1. For a review of the TLS
- handshake see [1].
-
- CLIENT SERVER
- ------ ------
- ClientHello
- -------------------------------->
- ServerHello
- Certificate *
- ServerKeyExchange*
- CertificateRequest*
- ServerHelloDone
- <-------------------------------
- Certificate*
- ClientKeyExchange
- CertificateVerify*
- change cipher spec
- Finished
- | -------------------------------->
- | change cipher spec
- | Finished
- | |
- | |
- Application Data <------------------------------->Application Data
-
- FIGURE 1: The TLS protocol. All messages followed by a star are
- optional. Note: This figure was taken from an IETF document
- [1].
-
- The TLS security context is negotiated in the client and server hello
- messages. For example: TLS_RSA_WITH_RC4_MD5 means the initial
- authentication will be done using the RSA public key algorithm, RC4
- will be used for the session key, and MACs will be based on the MD5
- algorithm. Thus, to facilitate the Kerberos authentication option,
- we must start by defining new cipher suites including (but not
- limited to):
-
-
-
-Medvinsky & Hur Standards Track [Page 2]
-\f
-RFC 2712 Addition of Kerberos Cipher Suites to TLS October 1999
-
-
- CipherSuite TLS_KRB5_WITH_DES_CBC_SHA = { 0x00,0x1E };
- CipherSuite TLS_KRB5_WITH_3DES_EDE_CBC_SHA = { 0x00,0x1F };
- CipherSuite TLS_KRB5_WITH_RC4_128_SHA = { 0x00,0x20 };
- CipherSuite TLS_KRB5_WITH_IDEA_CBC_SHA = { 0x00,0x21 };
- CipherSuite TLS_KRB5_WITH_DES_CBC_MD5 = { 0x00,0x22 };
- CipherSuite TLS_KRB5_WITH_3DES_EDE_CBC_MD5 = { 0x00,0x23 };
- CipherSuite TLS_KRB5_WITH_RC4_128_MD5 = { 0x00,0x24 };
- CipherSuite TLS_KRB5_WITH_IDEA_CBC_MD5 = { 0x00,0x25 };
-
- CipherSuite TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA = { 0x00,0x26 };
- CipherSuite TLS_KRB5_EXPORT_WITH_RC2_CBC_40_SHA = { 0x00,0x27 };
- CipherSuite TLS_KRB5_EXPORT_WITH_RC4_40_SHA = { 0x00,0x28 };
- CipherSuite TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5 = { 0x00,0x29 };
- CipherSuite TLS_KRB5_EXPORT_WITH_RC2_CBC_40_MD5 = { 0x00,0x2A };
- CipherSuite TLS_KRB5_EXPORT_WITH_RC4_40_MD5 = { 0x00,0x2B };
-
- To establish a Kerberos-based security context, one or more of the
- above cipher suites must be specified in the client hello message.
- If the TLS server supports the Kerberos authentication option, the
- server hello message, sent to the client, will confirm the Kerberos
- cipher suite selected by the server. The server's certificate, the
- client
-
- CertificateRequest, and the ServerKeyExchange shown in Figure 1 will
- be omitted since authentication and the establishment of a master
- secret will be done using the client's Kerberos credentials for the
- TLS server. The client's certificate will be omitted for the same
- reason. Note that these messages are specified as optional in the
- TLS protocol; therefore, omitting them is permissible.
-
- The Kerberos option must be added to the ClientKeyExchange message as
- shown in Figure 2.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Medvinsky & Hur Standards Track [Page 3]
-\f
-RFC 2712 Addition of Kerberos Cipher Suites to TLS October 1999
-
-
- struct
- {
- select (KeyExchangeAlgorithm)
- {
- case krb5: KerberosWrapper; /* new addition */
- case rsa: EncryptedPreMasterSecret;
- case diffie_hellman: ClientDiffieHellmanPublic;
- } Exchange_keys;
-
- } ClientKeyExchange;
-
- struct
- {
- opaque Ticket;
- opaque authenticator; /* optional */
- opaque EncryptedPreMasterSecret; /* encrypted with the session key
- which is sealed in the ticket */
- } KerberosWrapper; /* new addition */
-
- FIGURE 2: The Kerberos option in the ClientKeyExchange.
-
- To use the Kerberos authentication option, the TLS client must obtain
- a service ticket for the TLS server. In TLS, the ClientKeyExchange
- message is used to pass a random 48-byte pre-master secret to the
- server.
-
- The client and server then use the pre-master secret to independently
- derive the master secret, which in turn is used for generating
- session keys and for MAC computations. Thus, if the Kerberos option
- is selected, the pre-master secret structure is the same as that used
- in the RSA case; it is encrypted under the Kerberos session key and
- sent to the TLS server along with the Kerberos credentials (see
- Figure 2). The ticket and authenticator are encoded per RFC 1510
- (ASN.1 encoding). Once the ClientKeyExchange message is received,
- the server's secret key is used to unwrap the credentials and extract
- the pre-master secret.
-
- Note that a Kerberos authenticator is not required, since the master
- secret derived by the client and server is seeded with a random value
- passed in the server hello message, thus foiling replay attacks.
- However, the authenticator may still prove useful for passing
- authorization information and is thus allotted an optional field (see
- Figure 2).
-
- Lastly, the client and server exchange the finished messages to
- complete the handshake. At this point we have achieved the
- following:
-
-
-
-
-Medvinsky & Hur Standards Track [Page 4]
-\f
-RFC 2712 Addition of Kerberos Cipher Suites to TLS October 1999
-
-
- 1) A master secret, used to protect all subsequent communication, is
- securely established.
-
- 2) Mutual client-server authentication is achieved, since the TLS
- server proves knowledge of the master secret in the finished
- message.
-
- Note that the Kerberos option fits in seamlessly, without adding any
- new messages.
-
-4. Naming Conventions:
-
- To obtain an appropriate service ticket, the TLS client must
- determine the principal name of the TLS server. The Kerberos service
- naming convention is used for this purpose, as follows:
-
- host/MachineName@Realm
- where:
- - The literal, "host", follows the Kerberos convention when not
- concerned about the protection domain on a particular machine.
- - "MachineName" is the particular instance of the service.
- - The Kerberos "Realm" is the domain name of the machine.
-
-5. Summary
-
- The proposed Kerberos authentication option is added in exactly the
- same manner as a new public key algorithm would be added to TLS.
- Furthermore, it establishes the master secret in exactly the same
- manner.
-
-6. Security Considerations
-
- Kerberos ciphersuites are subject to the same security considerations
- as the TLS protocol. In addition, just as a public key
- implementation must take care to protect the private key (for example
- the PIN for a smartcard), a Kerberos implementation must take care to
- protect the long lived secret that is shared between the principal
- and the KDC. In particular, a weak password may be subject to a
- dictionary attack. In order to strengthen the initial authentication
- to a KDC, an implementor may choose to utilize secondary
- authentication via a token card, or one may utilize initial
- authentication to the KDC based on public key cryptography (commonly
- known as PKINIT - a product of the Common Authentication Technology
- working group of the IETF).
-
-
-
-
-
-
-
-Medvinsky & Hur Standards Track [Page 5]
-\f
-RFC 2712 Addition of Kerberos Cipher Suites to TLS October 1999
-
-
-7. Acknowledgements
-
- We would like to thank Clifford Neuman for his invaluable comments on
- earlier versions of this document.
-
-8. References
-
- [1] Dierks, T. and C. Allen, "The TLS Protocol, Version 1.0", RFC
- 2246, January 1999.
-
- [2] Kohl J. and C. Neuman, "The Kerberos Network Authentication
- Service (V5)", RFC 1510, September 1993.
-
-9. Authors' Addresses
-
- Ari Medvinsky
- Excite
- 555 Broadway
- Redwood City, CA 94063
-
- Phone: +1 650 569 2119
- EMail: amedvins@excitecorp.com
- http://www.excite.com
-
-
- Matthew Hur
- CyberSafe Corporation
- 1605 NW Sammamish Road
- Issaquah WA 98027-5378
-
- Phone: +1 425 391 6000
- EMail: matt.hur@cybersafe.com
- http://www.cybersafe.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Medvinsky & Hur Standards Track [Page 6]
-\f
-RFC 2712 Addition of Kerberos Cipher Suites to TLS October 1999
-
-
-10. Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Medvinsky & Hur Standards Track [Page 7]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group S. Waldbusser
-Request for Comments: 2790 Lucent Technologies Inc.
-Obsoletes: 1514 P. Grillo
-Category: Standards Track WeSync.com
- March 2000
-
-
- Host Resources MIB
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2000). All Rights Reserved.
-
-Abstract
-
- This memo defines a portion of the Management Information Base (MIB)
- for use with network management protocols in the Internet community.
- This memo obsoletes RFC 1514, the "Host Resources MIB". This memo
- extends that specification by clarifying changes based on
- implementation and deployment experience and documenting the Host
- Resources MIB in SMIv2 format while remaining semantically identical
- to the existing SMIv1-based MIB.
-
- This memo defines a MIB for use with managing host systems. The term
- "host" is construed to mean any computer that communicates with other
- similar computers attached to the internet and that is directly used
- by one or more human beings. Although this MIB does not necessarily
- apply to devices whose primary function is communications services
- (e.g., terminal servers, routers, bridges, monitoring equipment),
- such relevance is not explicitly precluded. This MIB instruments
- attributes common to all internet hosts including, for example, both
- personal computers and systems that run variants of Unix.
-
-
-
-
-
-
-
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 1]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
-Table of Contents
-
- 1 The SNMP Management Framework ............................ 2
- 2 Host Resources MIB ....................................... 3
- 3 IANA Considerations ...................................... 4
- 4 Definitions .............................................. 4
- 4.1 Textual Conventions .................................... 6
- 4.2 The Host Resources System Group ........................ 7
- 4.3 The Host Resources Storage Group ....................... 9
- 4.4 The Host Resources Device Group ........................ 12
- 4.5 The Host Resources Running Software Group .............. 26
- 4.6 The Host Resources Running Software Performance
- Group ................................................. 29
- 4.7 The Host Resources Installed Software Group ............ 30
- 4.8 Conformance Definitions ................................ 33
- 5 Type Definitions ......................................... 36
- 6 Internationalization Considerations ...................... 44
- 7 Security Considerations .................................. 45
- 8 References ............................................... 46
- 9 Acknowledgments .......................................... 48
- 10 Authors' Addresses ...................................... 49
- 11 Intellectual Property ................................... 49
- 12 Full Copyright Statement ................................ 50
-
-1. The SNMP Management Framework
-
- The SNMP Management Framework presently consists of five major
- components:
-
- o An overall architecture, described in RFC 2571 [RFC2571].
-
- o Mechanisms for describing and naming objects and events for the
- purpose of management. The first version of this Structure of
- Management Information (SMI) is called SMIv1 and described in STD
- 16, RFC 1155 [RFC1155], STD 16, RFC 1212 [RFC1212] and RFC 1215
- [RFC1215]. The second version, called SMIv2, is described in STD
- 58, RFC 2578 [RFC2578], RFC 2579 [RFC2579] and RFC 2580
- [RFC2580].
-
- o Message protocols for transferring management information. The
- first version of the SNMP message protocol is called SNMPv1 and
- described in STD 15, RFC 1157 [RFC1157]. A second version of the
- SNMP message protocol, which is not an Internet standards track
- protocol, is called SNMPv2c and described in RFC 1901 [RFC1901]
- and RFC 1906 [RFC1906]. The third version of the message protocol
- is called SNMPv3 and described in RFC 1906 [RFC1906], RFC 2572
- [RFC2572] and RFC 2574 [RFC2574].
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 2]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- o Protocol operations for accessing management information. The
- first set of protocol operations and associated PDU formats is
- described in STD 15, RFC 1157 [RFC1157]. A second set of protocol
- operations and associated PDU formats is described in RFC 1905
- [RFC1905].
-
- o A set of fundamental applications described in RFC 2573 [RFC2573]
- and the view-based access control mechanism described in RFC 2575
- [RFC2575].
-
- A more detailed introduction to the current SNMP Management Framework
- can be found in RFC 2570 [RFC2570].
-
- Managed objects are accessed via a virtual information store, termed
- the Management Information Base or MIB. Objects in the MIB are
- defined using the mechanisms defined in the SMI.
-
- This memo specifies a MIB module that is compliant to the SMIv2. A
- MIB conforming to the SMIv1 can be produced through the appropriate
- translations. The resulting translated MIB must be semantically
- equivalent, except where objects or events are omitted because no
- translation is possible (use of Counter64). Some machine readable
- information in SMIv2 will be converted into textual descriptions in
- SMIv1 during the translation process. However, this loss of machine
- readable information is not considered to change the semantics of the
- MIB.
-
-2. Host Resources MIB
-
- The Host Resources MIB defines a uniform set of objects useful for
- the management of host computers. Host computers are independent of
- the operating system, network services, or any software application.
-
- The Host Resources MIB defines objects which are common across many
- computer system architectures.
-
- In addition, there are objects in the SNMPv2-MIB [RFC1907] and IF-MIB
- [RFC2233] which also provide host management functionality.
- Implementation of the System and Interfaces groups is mandatory for
- implementors of the Host Resources MIB.
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED","MAY", and "OPTIONAL" in this
- document are to be interpreted as described in [RFC2119].
-
-
-
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 3]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
-3. IANA Considerations
-
- This MIB contains type definitions for storage types, device types,
- and file system types for use as values for the hrStorageType,
- hrDeviceType, and hrFSType objects, respectively. As new computing
- technologies are developed, new types need to be registered for these
- technologies. The IANA (Internet Assigned Numbers Authority) is
- designated as the registration authority for new registrations beyond
- those published in this document. The IANA will maintain the HOST-
- RESOURCES-TYPES module as new registrations are added and publish new
- versions of this module.
-
- Given the large number of such technologies and potential confusion
- in naming of these technologies (such as a technology known by two
- names or a name and an acronym), there is a real danger that more
- than one registration might be created for what is essentially the
- same technology. In order to ensure that future type registrations
- are performed correctly, applications for new types will be reviewed
- by a Designated Expert appointed by the IESG.
-
-4. Definitions
-
- HOST-RESOURCES-MIB DEFINITIONS ::= BEGIN
-
- IMPORTS
- MODULE-IDENTITY, OBJECT-TYPE, mib-2,
- Integer32, Counter32, Gauge32, TimeTicks FROM SNMPv2-SMI
-
- TEXTUAL-CONVENTION, DisplayString,
- TruthValue, DateAndTime, AutonomousType FROM SNMPv2-TC
-
- MODULE-COMPLIANCE, OBJECT-GROUP FROM SNMPv2-CONF
-
- InterfaceIndexOrZero FROM IF-MIB;
-
- hostResourcesMibModule MODULE-IDENTITY
- LAST-UPDATED "200003060000Z" -- 6 March 2000
- ORGANIZATION "IETF Host Resources MIB Working Group"
- CONTACT-INFO
- "Steve Waldbusser
- Postal: Lucent Technologies, Inc.
- 1213 Innsbruck Dr.
- Sunnyvale, CA 94089
- USA
- Phone: 650-318-1251
- Fax: 650-318-1633
- Email: waldbusser@lucent.com
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 4]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- In addition, the Host Resources MIB mailing list is
- dedicated to discussion of this MIB. To join the
- mailing list, send a request message to
- hostmib-request@andrew.cmu.edu. The mailing list
- address is hostmib@andrew.cmu.edu."
-
- DESCRIPTION
- "This MIB is for use in managing host systems. The term
- `host' is construed to mean any computer that communicates
- with other similar computers attached to the internet and
- that is directly used by one or more human beings. Although
- this MIB does not necessarily apply to devices whose primary
- function is communications services (e.g., terminal servers,
- routers, bridges, monitoring equipment), such relevance is
- not explicitly precluded. This MIB instruments attributes
- common to all internet hosts including, for example, both
- personal computers and systems that run variants of Unix."
-
- REVISION "200003060000Z" -- 6 March 2000
- DESCRIPTION
- "Clarifications and bug fixes based on implementation
- experience. This revision was also reformatted in the SMIv2
- format. The revisions made were:
-
- New RFC document standards:
- Added Copyright notice, updated introduction to SNMP
- Framework, updated references section, added reference to
- RFC 2119, and added a meaningful Security Considerations
- section.
-
- New IANA considerations section for registration of new types
-
- Conversion to new SMIv2 syntax for the following types and
- macros:
- Counter32, Integer32, Gauge32, MODULE-IDENTITY,
- OBJECT-TYPE, TEXTUAL-CONVENTION, OBJECT-IDENTITY,
- MODULE-COMPLIANCE, OBJECT-GROUP
-
- Used new Textual Conventions:
- TruthValue, DateAndTime, AutonomousType,
- InterfaceIndexOrZero
-
- Fixed typo in hrPrinterStatus.
-
- Added missing error bits to hrPrinterDetectedErrorState and
- clarified confusion resulting from suggested mappings to
- hrPrinterStatus.
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 5]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- Clarified that size of objects of type
- InternationalDisplayString is number of octets, not number
- of encoded symbols.
-
- Clarified the use of the following objects based on
- implementation experience:
- hrSystemInitialLoadDevice, hrSystemInitialLoadParameters,
- hrMemorySize, hrStorageSize, hrStorageAllocationFailures,
- hrDeviceErrors, hrProcessorLoad, hrNetworkIfIndex,
- hrDiskStorageCapacity, hrSWRunStatus, hrSWRunPerfCPU,
- and hrSWInstalledDate.
-
- Clarified implementation technique for hrSWInstalledTable.
-
- Used new AUGMENTS clause for hrSWRunPerfTable.
-
- Added Internationalization Considerations section.
-
- This revision published as RFC2790."
-
- REVISION "9910202200Z" -- 20 October, 1999
- DESCRIPTION
- "The original version of this MIB, published as
- RFC1514."
- ::= { hrMIBAdminInfo 1 }
-
- host OBJECT IDENTIFIER ::= { mib-2 25 }
-
- hrSystem OBJECT IDENTIFIER ::= { host 1 }
- hrStorage OBJECT IDENTIFIER ::= { host 2 }
- hrDevice OBJECT IDENTIFIER ::= { host 3 }
- hrSWRun OBJECT IDENTIFIER ::= { host 4 }
- hrSWRunPerf OBJECT IDENTIFIER ::= { host 5 }
- hrSWInstalled OBJECT IDENTIFIER ::= { host 6 }
- hrMIBAdminInfo OBJECT IDENTIFIER ::= { host 7 }
-
- -- textual conventions
-
- KBytes ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "Storage size, expressed in units of 1024 bytes."
- SYNTAX Integer32 (0..2147483647)
-
- ProductID ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "This textual convention is intended to identify the
-
-
-
-Waldbusser & Grillo Standards Track [Page 6]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- manufacturer, model, and version of a specific
- hardware or software product. It is suggested that
- these OBJECT IDENTIFIERs are allocated such that all
- products from a particular manufacturer are registered
- under a subtree distinct to that manufacturer. In
- addition, all versions of a product should be
- registered under a subtree distinct to that product.
- With this strategy, a management station may uniquely
- determine the manufacturer and/or model of a product
- whose productID is unknown to the management station.
- Objects of this type may be useful for inventory
- purposes or for automatically detecting
- incompatibilities or version mismatches between
- various hardware and software components on a system.
-
- For example, the product ID for the ACME 4860 66MHz
- clock doubled processor might be:
- enterprises.acme.acmeProcessors.a4860DX2.MHz66
-
- A software product might be registered as:
- enterprises.acme.acmeOperatingSystems.acmeDOS.six(6).one(1)
- "
- SYNTAX OBJECT IDENTIFIER
-
- -- unknownProduct will be used for any unknown ProductID
- -- unknownProduct OBJECT IDENTIFIER ::= { 0 0 }
-
- InternationalDisplayString ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "This data type is used to model textual information
- in some character set. A network management station
- should use a local algorithm to determine which
- character set is in use and how it should be
- displayed. Note that this character set may be
- encoded with more than one octet per symbol, but will
- most often be NVT ASCII. When a size clause is
- specified for an object of this type, the size refers
- to the length in octets, not the number of symbols."
- SYNTAX OCTET STRING
-
- -- The Host Resources System Group
-
- hrSystemUptime OBJECT-TYPE
- SYNTAX TimeTicks
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
-
-
-
-Waldbusser & Grillo Standards Track [Page 7]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- "The amount of time since this host was last
- initialized. Note that this is different from
- sysUpTime in the SNMPv2-MIB [RFC1907] because
- sysUpTime is the uptime of the network management
- portion of the system."
- ::= { hrSystem 1 }
-
- hrSystemDate OBJECT-TYPE
- SYNTAX DateAndTime
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The host's notion of the local date and time of day."
- ::= { hrSystem 2 }
-
- hrSystemInitialLoadDevice OBJECT-TYPE
- SYNTAX Integer32 (1..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The index of the hrDeviceEntry for the device from
- which this host is configured to load its initial
- operating system configuration (i.e., which operating
- system code and/or boot parameters).
-
- Note that writing to this object just changes the
- configuration that will be used the next time the
- operating system is loaded and does not actually cause
- the reload to occur."
- ::= { hrSystem 3 }
-
- hrSystemInitialLoadParameters OBJECT-TYPE
- SYNTAX InternationalDisplayString (SIZE (0..128))
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "This object contains the parameters (e.g. a pathname
- and parameter) supplied to the load device when
- requesting the initial operating system configuration
- from that device.
-
- Note that writing to this object just changes the
- configuration that will be used the next time the
- operating system is loaded and does not actually cause
- the reload to occur."
- ::= { hrSystem 4 }
-
- hrSystemNumUsers OBJECT-TYPE
-
-
-
-Waldbusser & Grillo Standards Track [Page 8]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- SYNTAX Gauge32
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The number of user sessions for which this host is
- storing state information. A session is a collection
- of processes requiring a single act of user
- authentication and possibly subject to collective job
- control."
- ::= { hrSystem 5 }
-
- hrSystemProcesses OBJECT-TYPE
- SYNTAX Gauge32
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The number of process contexts currently loaded or
- running on this system."
- ::= { hrSystem 6 }
-
- hrSystemMaxProcesses OBJECT-TYPE
- SYNTAX Integer32 (0..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The maximum number of process contexts this system
- can support. If there is no fixed maximum, the value
- should be zero. On systems that have a fixed maximum,
- this object can help diagnose failures that occur when
- this maximum is reached."
- ::= { hrSystem 7 }
-
- -- The Host Resources Storage Group
-
- -- Registration point for storage types, for use with hrStorageType.
- -- These are defined in the HOST-RESOURCES-TYPES module.
- hrStorageTypes OBJECT IDENTIFIER ::= { hrStorage 1 }
-
- hrMemorySize OBJECT-TYPE
- SYNTAX KBytes
- UNITS "KBytes"
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The amount of physical read-write main memory,
- typically RAM, contained by the host."
- ::= { hrStorage 2 }
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 9]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- hrStorageTable OBJECT-TYPE
- SYNTAX SEQUENCE OF HrStorageEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The (conceptual) table of logical storage areas on
- the host.
-
- An entry shall be placed in the storage table for each
- logical area of storage that is allocated and has
- fixed resource limits. The amount of storage
- represented in an entity is the amount actually usable
- by the requesting entity, and excludes loss due to
- formatting or file system reference information.
-
- These entries are associated with logical storage
- areas, as might be seen by an application, rather than
- physical storage entities which are typically seen by
- an operating system. Storage such as tapes and
- floppies without file systems on them are typically
- not allocated in chunks by the operating system to
- requesting applications, and therefore shouldn't
- appear in this table. Examples of valid storage for
- this table include disk partitions, file systems, ram
- (for some architectures this is further segmented into
- regular memory, extended memory, and so on), backing
- store for virtual memory (`swap space').
-
- This table is intended to be a useful diagnostic for
- `out of memory' and `out of buffers' types of
- failures. In addition, it can be a useful performance
- monitoring tool for tracking memory, disk, or buffer
- usage."
- ::= { hrStorage 3 }
-
- hrStorageEntry OBJECT-TYPE
- SYNTAX HrStorageEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A (conceptual) entry for one logical storage area on
- the host. As an example, an instance of the
- hrStorageType object might be named hrStorageType.3"
- INDEX { hrStorageIndex }
- ::= { hrStorageTable 1 }
-
- HrStorageEntry ::= SEQUENCE {
- hrStorageIndex Integer32,
-
-
-
-Waldbusser & Grillo Standards Track [Page 10]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- hrStorageType AutonomousType,
- hrStorageDescr DisplayString,
- hrStorageAllocationUnits Integer32,
- hrStorageSize Integer32,
- hrStorageUsed Integer32,
- hrStorageAllocationFailures Counter32
- }
-
- hrStorageIndex OBJECT-TYPE
- SYNTAX Integer32 (1..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A unique value for each logical storage area
- contained by the host."
- ::= { hrStorageEntry 1 }
-
- hrStorageType OBJECT-TYPE
- SYNTAX AutonomousType
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The type of storage represented by this entry."
- ::= { hrStorageEntry 2 }
-
- hrStorageDescr OBJECT-TYPE
- SYNTAX DisplayString
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A description of the type and instance of the storage
- described by this entry."
- ::= { hrStorageEntry 3 }
-
- hrStorageAllocationUnits OBJECT-TYPE
- SYNTAX Integer32 (1..2147483647)
- UNITS "Bytes"
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The size, in bytes, of the data objects allocated
- from this pool. If this entry is monitoring sectors,
- blocks, buffers, or packets, for example, this number
- will commonly be greater than one. Otherwise this
- number will typically be one."
- ::= { hrStorageEntry 4 }
-
- hrStorageSize OBJECT-TYPE
-
-
-
-Waldbusser & Grillo Standards Track [Page 11]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- SYNTAX Integer32 (0..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The size of the storage represented by this entry, in
- units of hrStorageAllocationUnits. This object is
- writable to allow remote configuration of the size of
- the storage area in those cases where such an
- operation makes sense and is possible on the
- underlying system. For example, the amount of main
- memory allocated to a buffer pool might be modified or
- the amount of disk space allocated to virtual memory
- might be modified."
- ::= { hrStorageEntry 5 }
-
- hrStorageUsed OBJECT-TYPE
- SYNTAX Integer32 (0..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The amount of the storage represented by this entry
- that is allocated, in units of
- hrStorageAllocationUnits."
- ::= { hrStorageEntry 6 }
-
- hrStorageAllocationFailures OBJECT-TYPE
- SYNTAX Counter32
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The number of requests for storage represented by
- this entry that could not be honored due to not enough
- storage. It should be noted that as this object has a
- SYNTAX of Counter32, that it does not have a defined
- initial value. However, it is recommended that this
- object be initialized to zero, even though management
- stations must not depend on such an initialization."
- ::= { hrStorageEntry 7 }
-
- -- The Host Resources Device Group
- --
- -- The device group is useful for identifying and diagnosing the
- -- devices on a system. The hrDeviceTable contains common
- -- information for any type of device. In addition, some devices
- -- have device-specific tables for more detailed information. More
- -- such tables may be defined in the future for other device types.
-
- -- Registration point for device types, for use with hrDeviceType.
-
-
-
-Waldbusser & Grillo Standards Track [Page 12]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- -- These are defined in the HOST-RESOURCES-TYPES module.
- hrDeviceTypes OBJECT IDENTIFIER ::= { hrDevice 1 }
-
- hrDeviceTable OBJECT-TYPE
- SYNTAX SEQUENCE OF HrDeviceEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The (conceptual) table of devices contained by the
- host."
- ::= { hrDevice 2 }
-
- hrDeviceEntry OBJECT-TYPE
- SYNTAX HrDeviceEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A (conceptual) entry for one device contained by the
- host. As an example, an instance of the hrDeviceType
- object might be named hrDeviceType.3"
- INDEX { hrDeviceIndex }
- ::= { hrDeviceTable 1 }
-
- HrDeviceEntry ::= SEQUENCE {
- hrDeviceIndex Integer32,
- hrDeviceType AutonomousType,
- hrDeviceDescr DisplayString,
- hrDeviceID ProductID,
- hrDeviceStatus INTEGER,
- hrDeviceErrors Counter32
- }
-
- hrDeviceIndex OBJECT-TYPE
- SYNTAX Integer32 (1..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A unique value for each device contained by the host.
- The value for each device must remain constant at
- least from one re-initialization of the agent to the
- next re-initialization."
- ::= { hrDeviceEntry 1 }
-
- hrDeviceType OBJECT-TYPE
- SYNTAX AutonomousType
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
-
-
-
-Waldbusser & Grillo Standards Track [Page 13]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- "An indication of the type of device.
-
- If this value is
- `hrDeviceProcessor { hrDeviceTypes 3 }' then an entry
- exists in the hrProcessorTable which corresponds to
- this device.
-
- If this value is
- `hrDeviceNetwork { hrDeviceTypes 4 }', then an entry
- exists in the hrNetworkTable which corresponds to this
- device.
-
- If this value is
- `hrDevicePrinter { hrDeviceTypes 5 }', then an entry
- exists in the hrPrinterTable which corresponds to this
- device.
-
- If this value is
- `hrDeviceDiskStorage { hrDeviceTypes 6 }', then an
- entry exists in the hrDiskStorageTable which
- corresponds to this device."
- ::= { hrDeviceEntry 2 }
-
- hrDeviceDescr OBJECT-TYPE
- SYNTAX DisplayString (SIZE (0..64))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A textual description of this device, including the
- device's manufacturer and revision, and optionally,
- its serial number."
- ::= { hrDeviceEntry 3 }
-
- hrDeviceID OBJECT-TYPE
- SYNTAX ProductID
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The product ID for this device."
- ::= { hrDeviceEntry 4 }
-
- hrDeviceStatus OBJECT-TYPE
- SYNTAX INTEGER {
- unknown(1),
- running(2),
- warning(3),
- testing(4),
- down(5)
-
-
-
-Waldbusser & Grillo Standards Track [Page 14]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- }
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The current operational state of the device described
- by this row of the table. A value unknown(1)
- indicates that the current state of the device is
- unknown. running(2) indicates that the device is up
- and running and that no unusual error conditions are
- known. The warning(3) state indicates that agent has
- been informed of an unusual error condition by the
- operational software (e.g., a disk device driver) but
- that the device is still 'operational'. An example
- would be a high number of soft errors on a disk. A
- value of testing(4), indicates that the device is not
- available for use because it is in the testing state.
- The state of down(5) is used only when the agent has
- been informed that the device is not available for any
- use."
- ::= { hrDeviceEntry 5 }
-
- hrDeviceErrors OBJECT-TYPE
- SYNTAX Counter32
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The number of errors detected on this device. It
- should be noted that as this object has a SYNTAX of
- Counter32, that it does not have a defined initial
- value. However, it is recommended that this object be
- initialized to zero, even though management stations
- must not depend on such an initialization."
- ::= { hrDeviceEntry 6 }
-
- hrProcessorTable OBJECT-TYPE
- SYNTAX SEQUENCE OF HrProcessorEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The (conceptual) table of processors contained by the
- host.
-
- Note that this table is potentially sparse: a
- (conceptual) entry exists only if the correspondent
- value of the hrDeviceType object is
- `hrDeviceProcessor'."
- ::= { hrDevice 3 }
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 15]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- hrProcessorEntry OBJECT-TYPE
- SYNTAX HrProcessorEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A (conceptual) entry for one processor contained by
- the host. The hrDeviceIndex in the index represents
- the entry in the hrDeviceTable that corresponds to the
- hrProcessorEntry.
-
- As an example of how objects in this table are named,
- an instance of the hrProcessorFrwID object might be
- named hrProcessorFrwID.3"
- INDEX { hrDeviceIndex }
- ::= { hrProcessorTable 1 }
-
- HrProcessorEntry ::= SEQUENCE {
- hrProcessorFrwID ProductID,
- hrProcessorLoad Integer32
- }
-
- hrProcessorFrwID OBJECT-TYPE
- SYNTAX ProductID
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The product ID of the firmware associated with the
- processor."
- ::= { hrProcessorEntry 1 }
-
- hrProcessorLoad OBJECT-TYPE
- SYNTAX Integer32 (0..100)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The average, over the last minute, of the percentage
- of time that this processor was not idle.
- Implementations may approximate this one minute
- smoothing period if necessary."
- ::= { hrProcessorEntry 2 }
-
- hrNetworkTable OBJECT-TYPE
- SYNTAX SEQUENCE OF HrNetworkEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The (conceptual) table of network devices contained
- by the host.
-
-
-
-Waldbusser & Grillo Standards Track [Page 16]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- Note that this table is potentially sparse: a
- (conceptual) entry exists only if the correspondent
- value of the hrDeviceType object is
- `hrDeviceNetwork'."
- ::= { hrDevice 4 }
-
- hrNetworkEntry OBJECT-TYPE
- SYNTAX HrNetworkEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A (conceptual) entry for one network device contained
- by the host. The hrDeviceIndex in the index
- represents the entry in the hrDeviceTable that
- corresponds to the hrNetworkEntry.
-
- As an example of how objects in this table are named,
- an instance of the hrNetworkIfIndex object might be
- named hrNetworkIfIndex.3"
- INDEX { hrDeviceIndex }
- ::= { hrNetworkTable 1 }
-
- HrNetworkEntry ::= SEQUENCE {
- hrNetworkIfIndex InterfaceIndexOrZero
- }
-
- hrNetworkIfIndex OBJECT-TYPE
- SYNTAX InterfaceIndexOrZero
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The value of ifIndex which corresponds to this
- network device. If this device is not represented in
- the ifTable, then this value shall be zero."
- ::= { hrNetworkEntry 1 }
-
- hrPrinterTable OBJECT-TYPE
- SYNTAX SEQUENCE OF HrPrinterEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The (conceptual) table of printers local to the host.
-
- Note that this table is potentially sparse: a
- (conceptual) entry exists only if the correspondent
- value of the hrDeviceType object is
- `hrDevicePrinter'."
- ::= { hrDevice 5 }
-
-
-
-Waldbusser & Grillo Standards Track [Page 17]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- hrPrinterEntry OBJECT-TYPE
- SYNTAX HrPrinterEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A (conceptual) entry for one printer local to the
- host. The hrDeviceIndex in the index represents the
- entry in the hrDeviceTable that corresponds to the
- hrPrinterEntry.
-
- As an example of how objects in this table are named,
- an instance of the hrPrinterStatus object might be
- named hrPrinterStatus.3"
- INDEX { hrDeviceIndex }
- ::= { hrPrinterTable 1 }
-
- HrPrinterEntry ::= SEQUENCE {
- hrPrinterStatus INTEGER,
- hrPrinterDetectedErrorState OCTET STRING
- }
-
- hrPrinterStatus OBJECT-TYPE
- SYNTAX INTEGER {
- other(1),
- unknown(2),
- idle(3),
- printing(4),
- warmup(5)
- }
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The current status of this printer device."
- ::= { hrPrinterEntry 1 }
-
- hrPrinterDetectedErrorState OBJECT-TYPE
- SYNTAX OCTET STRING
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "This object represents any error conditions detected
- by the printer. The error conditions are encoded as
- bits in an octet string, with the following
- definitions:
-
- Condition Bit #
-
- lowPaper 0
-
-
-
-Waldbusser & Grillo Standards Track [Page 18]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- noPaper 1
- lowToner 2
- noToner 3
- doorOpen 4
- jammed 5
- offline 6
- serviceRequested 7
- inputTrayMissing 8
- outputTrayMissing 9
- markerSupplyMissing 10
- outputNearFull 11
- outputFull 12
- inputTrayEmpty 13
- overduePreventMaint 14
-
- Bits are numbered starting with the most significant
- bit of the first byte being bit 0, the least
- significant bit of the first byte being bit 7, the
- most significant bit of the second byte being bit 8,
- and so on. A one bit encodes that the condition was
- detected, while a zero bit encodes that the condition
- was not detected.
-
- This object is useful for alerting an operator to
- specific warning or error conditions that may occur,
- especially those requiring human intervention."
- ::= { hrPrinterEntry 2 }
-
- hrDiskStorageTable OBJECT-TYPE
- SYNTAX SEQUENCE OF HrDiskStorageEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The (conceptual) table of long-term storage devices
- contained by the host. In particular, disk devices
- accessed remotely over a network are not included
- here.
-
- Note that this table is potentially sparse: a
- (conceptual) entry exists only if the correspondent
- value of the hrDeviceType object is
- `hrDeviceDiskStorage'."
- ::= { hrDevice 6 }
-
- hrDiskStorageEntry OBJECT-TYPE
- SYNTAX HrDiskStorageEntry
- MAX-ACCESS not-accessible
- STATUS current
-
-
-
-Waldbusser & Grillo Standards Track [Page 19]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- DESCRIPTION
- "A (conceptual) entry for one long-term storage device
- contained by the host. The hrDeviceIndex in the index
- represents the entry in the hrDeviceTable that
- corresponds to the hrDiskStorageEntry. As an example,
- an instance of the hrDiskStorageCapacity object might
- be named hrDiskStorageCapacity.3"
- INDEX { hrDeviceIndex }
- ::= { hrDiskStorageTable 1 }
-
- HrDiskStorageEntry ::= SEQUENCE {
- hrDiskStorageAccess INTEGER,
- hrDiskStorageMedia INTEGER,
- hrDiskStorageRemoveble TruthValue,
- hrDiskStorageCapacity KBytes
- }
-
- hrDiskStorageAccess OBJECT-TYPE
- SYNTAX INTEGER {
- readWrite(1),
- readOnly(2)
- }
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "An indication if this long-term storage device is
- readable and writable or only readable. This should
- reflect the media type, any write-protect mechanism,
- and any device configuration that affects the entire
- device."
- ::= { hrDiskStorageEntry 1 }
-
- hrDiskStorageMedia OBJECT-TYPE
- SYNTAX INTEGER {
- other(1),
- unknown(2),
- hardDisk(3),
- floppyDisk(4),
- opticalDiskROM(5),
- opticalDiskWORM(6), -- Write Once Read Many
- opticalDiskRW(7),
- ramDisk(8)
- }
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "An indication of the type of media used in this long-
- term storage device."
-
-
-
-Waldbusser & Grillo Standards Track [Page 20]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- ::= { hrDiskStorageEntry 2 }
-
- hrDiskStorageRemoveble OBJECT-TYPE
- SYNTAX TruthValue
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "Denotes whether or not the disk media may be removed
- from the drive."
- ::= { hrDiskStorageEntry 3 }
-
- hrDiskStorageCapacity OBJECT-TYPE
- SYNTAX KBytes
- UNITS "KBytes"
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The total size for this long-term storage device. If
- the media is removable and is currently removed, this
- value should be zero."
- ::= { hrDiskStorageEntry 4 }
-
- hrPartitionTable OBJECT-TYPE
- SYNTAX SEQUENCE OF HrPartitionEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The (conceptual) table of partitions for long-term
- storage devices contained by the host. In particular,
- partitions accessed remotely over a network are not
- included here."
- ::= { hrDevice 7 }
-
- hrPartitionEntry OBJECT-TYPE
- SYNTAX HrPartitionEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A (conceptual) entry for one partition. The
- hrDeviceIndex in the index represents the entry in the
- hrDeviceTable that corresponds to the
- hrPartitionEntry.
-
- As an example of how objects in this table are named,
- an instance of the hrPartitionSize object might be
- named hrPartitionSize.3.1"
- INDEX { hrDeviceIndex, hrPartitionIndex }
- ::= { hrPartitionTable 1 }
-
-
-
-Waldbusser & Grillo Standards Track [Page 21]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- HrPartitionEntry ::= SEQUENCE {
- hrPartitionIndex Integer32,
- hrPartitionLabel InternationalDisplayString,
- hrPartitionID OCTET STRING,
- hrPartitionSize KBytes,
- hrPartitionFSIndex Integer32
- }
-
- hrPartitionIndex OBJECT-TYPE
- SYNTAX Integer32 (1..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A unique value for each partition on this long-term
- storage device. The value for each long-term storage
- device must remain constant at least from one re-
- initialization of the agent to the next re-
- initialization."
- ::= { hrPartitionEntry 1 }
-
- hrPartitionLabel OBJECT-TYPE
- SYNTAX InternationalDisplayString (SIZE (0..128))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A textual description of this partition."
- ::= { hrPartitionEntry 2 }
-
- hrPartitionID OBJECT-TYPE
- SYNTAX OCTET STRING
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A descriptor which uniquely represents this partition
- to the responsible operating system. On some systems,
- this might take on a binary representation."
- ::= { hrPartitionEntry 3 }
-
- hrPartitionSize OBJECT-TYPE
- SYNTAX KBytes
- UNITS "KBytes"
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The size of this partition."
- ::= { hrPartitionEntry 4 }
-
- hrPartitionFSIndex OBJECT-TYPE
-
-
-
-Waldbusser & Grillo Standards Track [Page 22]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- SYNTAX Integer32 (0..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The index of the file system mounted on this
- partition. If no file system is mounted on this
- partition, then this value shall be zero. Note that
- multiple partitions may point to one file system,
- denoting that that file system resides on those
- partitions. Multiple file systems may not reside on
- one partition."
- ::= { hrPartitionEntry 5 }
-
- -- The File System Table
-
- -- Registration point for popular File System types,
- -- for use with hrFSType. These are defined in the
- -- HOST-RESOURCES-TYPES module.
- hrFSTypes OBJECT IDENTIFIER ::= { hrDevice 9 }
-
- hrFSTable OBJECT-TYPE
- SYNTAX SEQUENCE OF HrFSEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The (conceptual) table of file systems local to this
- host or remotely mounted from a file server. File
- systems that are in only one user's environment on a
- multi-user system will not be included in this table."
- ::= { hrDevice 8 }
-
- hrFSEntry OBJECT-TYPE
- SYNTAX HrFSEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A (conceptual) entry for one file system local to
- this host or remotely mounted from a file server.
- File systems that are in only one user's environment
- on a multi-user system will not be included in this
- table.
-
- As an example of how objects in this table are named,
- an instance of the hrFSMountPoint object might be
- named hrFSMountPoint.3"
- INDEX { hrFSIndex }
- ::= { hrFSTable 1 }
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 23]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- HrFSEntry ::= SEQUENCE {
- hrFSIndex Integer32,
- hrFSMountPoint InternationalDisplayString,
- hrFSRemoteMountPoint InternationalDisplayString,
- hrFSType AutonomousType,
- hrFSAccess INTEGER,
- hrFSBootable TruthValue,
- hrFSStorageIndex Integer32,
- hrFSLastFullBackupDate DateAndTime,
- hrFSLastPartialBackupDate DateAndTime
- }
-
- hrFSIndex OBJECT-TYPE
- SYNTAX Integer32 (1..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A unique value for each file system local to this
- host. The value for each file system must remain
- constant at least from one re-initialization of the
- agent to the next re-initialization."
- ::= { hrFSEntry 1 }
-
- hrFSMountPoint OBJECT-TYPE
- SYNTAX InternationalDisplayString (SIZE(0..128))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The path name of the root of this file system."
- ::= { hrFSEntry 2 }
-
- hrFSRemoteMountPoint OBJECT-TYPE
- SYNTAX InternationalDisplayString (SIZE(0..128))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A description of the name and/or address of the
- server that this file system is mounted from. This
- may also include parameters such as the mount point on
- the remote file system. If this is not a remote file
- system, this string should have a length of zero."
- ::= { hrFSEntry 3 }
-
- hrFSType OBJECT-TYPE
- SYNTAX AutonomousType
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
-
-
-
-Waldbusser & Grillo Standards Track [Page 24]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- "The value of this object identifies the type of this
- file system."
- ::= { hrFSEntry 4 }
-
- hrFSAccess OBJECT-TYPE
- SYNTAX INTEGER {
- readWrite(1),
- readOnly(2)
- }
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "An indication if this file system is logically
- configured by the operating system to be readable and
- writable or only readable. This does not represent
- any local access-control policy, except one that is
- applied to the file system as a whole."
- ::= { hrFSEntry 5 }
-
- hrFSBootable OBJECT-TYPE
- SYNTAX TruthValue
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A flag indicating whether this file system is
- bootable."
- ::= { hrFSEntry 6 }
-
- hrFSStorageIndex OBJECT-TYPE
- SYNTAX Integer32 (0..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The index of the hrStorageEntry that represents
- information about this file system. If there is no
- such information available, then this value shall be
- zero. The relevant storage entry will be useful in
- tracking the percent usage of this file system and
- diagnosing errors that may occur when it runs out of
- space."
- ::= { hrFSEntry 7 }
-
- hrFSLastFullBackupDate OBJECT-TYPE
- SYNTAX DateAndTime
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The last date at which this complete file system was
-
-
-
-Waldbusser & Grillo Standards Track [Page 25]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- copied to another storage device for backup. This
- information is useful for ensuring that backups are
- being performed regularly.
-
- If this information is not known, then this variable
- shall have the value corresponding to January 1, year
- 0000, 00:00:00.0, which is encoded as
- (hex)'00 00 01 01 00 00 00 00'."
- ::= { hrFSEntry 8 }
-
- hrFSLastPartialBackupDate OBJECT-TYPE
- SYNTAX DateAndTime
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The last date at which a portion of this file system
- was copied to another storage device for backup. This
- information is useful for ensuring that backups are
- being performed regularly.
-
- If this information is not known, then this variable
- shall have the value corresponding to January 1, year
- 0000, 00:00:00.0, which is encoded as
- (hex)'00 00 01 01 00 00 00 00'."
- ::= { hrFSEntry 9 }
-
- -- The Host Resources Running Software Group
- --
- -- The hrSWRunTable contains an entry for each distinct piece of
- -- software that is running or loaded into physical or virtual
- -- memory in preparation for running. This includes the host's
- -- operating system, device drivers, and applications.
-
- hrSWOSIndex OBJECT-TYPE
- SYNTAX Integer32 (1..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The value of the hrSWRunIndex for the hrSWRunEntry
- that represents the primary operating system running
- on this host. This object is useful for quickly and
- uniquely identifying that primary operating system."
- ::= { hrSWRun 1 }
-
- hrSWRunTable OBJECT-TYPE
- SYNTAX SEQUENCE OF HrSWRunEntry
- MAX-ACCESS not-accessible
- STATUS current
-
-
-
-Waldbusser & Grillo Standards Track [Page 26]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- DESCRIPTION
- "The (conceptual) table of software running on the
- host."
- ::= { hrSWRun 2 }
-
- hrSWRunEntry OBJECT-TYPE
- SYNTAX HrSWRunEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A (conceptual) entry for one piece of software
- running on the host Note that because the installed
- software table only contains information for software
- stored locally on this host, not every piece of
- running software will be found in the installed
- software table. This is true of software that was
- loaded and run from a non-local source, such as a
- network-mounted file system.
-
- As an example of how objects in this table are named,
- an instance of the hrSWRunName object might be named
- hrSWRunName.1287"
- INDEX { hrSWRunIndex }
- ::= { hrSWRunTable 1 }
-
- HrSWRunEntry ::= SEQUENCE {
- hrSWRunIndex Integer32,
- hrSWRunName InternationalDisplayString,
- hrSWRunID ProductID,
- hrSWRunPath InternationalDisplayString,
- hrSWRunParameters InternationalDisplayString,
- hrSWRunType INTEGER,
- hrSWRunStatus INTEGER
- }
-
- hrSWRunIndex OBJECT-TYPE
- SYNTAX Integer32 (1..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A unique value for each piece of software running on
- the host. Wherever possible, this should be the
- system's native, unique identification number."
- ::= { hrSWRunEntry 1 }
-
- hrSWRunName OBJECT-TYPE
- SYNTAX InternationalDisplayString (SIZE (0..64))
- MAX-ACCESS read-only
-
-
-
-Waldbusser & Grillo Standards Track [Page 27]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- STATUS current
- DESCRIPTION
- "A textual description of this running piece of
- software, including the manufacturer, revision, and
- the name by which it is commonly known. If this
- software was installed locally, this should be the
- same string as used in the corresponding
- hrSWInstalledName."
- ::= { hrSWRunEntry 2 }
-
- hrSWRunID OBJECT-TYPE
- SYNTAX ProductID
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The product ID of this running piece of software."
- ::= { hrSWRunEntry 3 }
-
- hrSWRunPath OBJECT-TYPE
- SYNTAX InternationalDisplayString (SIZE(0..128))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A description of the location on long-term storage
- (e.g. a disk drive) from which this software was
- loaded."
- ::= { hrSWRunEntry 4 }
-
- hrSWRunParameters OBJECT-TYPE
- SYNTAX InternationalDisplayString (SIZE(0..128))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A description of the parameters supplied to this
- software when it was initially loaded."
- ::= { hrSWRunEntry 5 }
-
- hrSWRunType OBJECT-TYPE
- SYNTAX INTEGER {
- unknown(1),
- operatingSystem(2),
- deviceDriver(3),
- application(4)
- }
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The type of this software."
-
-
-
-Waldbusser & Grillo Standards Track [Page 28]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- ::= { hrSWRunEntry 6 }
-
- hrSWRunStatus OBJECT-TYPE
- SYNTAX INTEGER {
- running(1),
- runnable(2), -- waiting for resource
- -- (i.e., CPU, memory, IO)
- notRunnable(3), -- loaded but waiting for event
- invalid(4) -- not loaded
- }
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The status of this running piece of software.
- Setting this value to invalid(4) shall cause this
- software to stop running and to be unloaded. Sets to
- other values are not valid."
- ::= { hrSWRunEntry 7 }
-
- -- The Host Resources Running Software Performance Group
- --
- -- The hrSWRunPerfTable contains an entry corresponding to
- -- each entry in the hrSWRunTable.
-
- hrSWRunPerfTable OBJECT-TYPE
- SYNTAX SEQUENCE OF HrSWRunPerfEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The (conceptual) table of running software
- performance metrics."
- ::= { hrSWRunPerf 1 }
-
- hrSWRunPerfEntry OBJECT-TYPE
- SYNTAX HrSWRunPerfEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A (conceptual) entry containing software performance
- metrics. As an example, an instance of the
- hrSWRunPerfCPU object might be named
- hrSWRunPerfCPU.1287"
- AUGMENTS { hrSWRunEntry } -- This table augments information in
- -- the hrSWRunTable.
- ::= { hrSWRunPerfTable 1 }
-
- HrSWRunPerfEntry ::= SEQUENCE {
- hrSWRunPerfCPU Integer32,
-
-
-
-Waldbusser & Grillo Standards Track [Page 29]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- hrSWRunPerfMem KBytes
- }
-
- hrSWRunPerfCPU OBJECT-TYPE
- SYNTAX Integer32 (0..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The number of centi-seconds of the total system's CPU
- resources consumed by this process. Note that on a
- multi-processor system, this value may increment by
- more than one centi-second in one centi-second of real
- (wall clock) time."
- ::= { hrSWRunPerfEntry 1 }
-
- hrSWRunPerfMem OBJECT-TYPE
- SYNTAX KBytes
- UNITS "KBytes"
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The total amount of real system memory allocated to
- this process."
- ::= { hrSWRunPerfEntry 2 }
-
- -- The Host Resources Installed Software Group
- --
- -- The hrSWInstalledTable contains an entry for each piece
- -- of software installed in long-term storage (e.g. a disk
- -- drive) locally on this host. Note that this does not
- -- include software loadable remotely from a network
- -- server.
- --
- -- Different implementations may track software in varying
- -- ways. For example, while some implementations may track
- -- executable files as distinct pieces of software, other
- -- implementations may use other strategies such as keeping
- -- track of software "packages" (e.g., related groups of files)
- -- or keeping track of system or application "patches".
- --
- -- This table is useful for identifying and inventorying
- -- software on a host and for diagnosing incompatibility
- -- and version mismatch problems between various pieces
- -- of hardware and software.
-
- hrSWInstalledLastChange OBJECT-TYPE
- SYNTAX TimeTicks
- MAX-ACCESS read-only
-
-
-
-Waldbusser & Grillo Standards Track [Page 30]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- STATUS current
- DESCRIPTION
- "The value of sysUpTime when an entry in the
- hrSWInstalledTable was last added, renamed, or
- deleted. Because this table is likely to contain many
- entries, polling of this object allows a management
- station to determine when re-downloading of the table
- might be useful."
- ::= { hrSWInstalled 1 }
-
- hrSWInstalledLastUpdateTime OBJECT-TYPE
- SYNTAX TimeTicks
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The value of sysUpTime when the hrSWInstalledTable
- was last completely updated. Because caching of this
- data will be a popular implementation strategy,
- retrieval of this object allows a management station
- to obtain a guarantee that no data in this table is
- older than the indicated time."
- ::= { hrSWInstalled 2 }
-
- hrSWInstalledTable OBJECT-TYPE
- SYNTAX SEQUENCE OF HrSWInstalledEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The (conceptual) table of software installed on this
- host."
- ::= { hrSWInstalled 3 }
-
- hrSWInstalledEntry OBJECT-TYPE
- SYNTAX HrSWInstalledEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A (conceptual) entry for a piece of software
- installed on this host.
-
- As an example of how objects in this table are named,
- an instance of the hrSWInstalledName object might be
- named hrSWInstalledName.96"
- INDEX { hrSWInstalledIndex }
- ::= { hrSWInstalledTable 1 }
-
- HrSWInstalledEntry ::= SEQUENCE {
- hrSWInstalledIndex Integer32,
-
-
-
-Waldbusser & Grillo Standards Track [Page 31]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- hrSWInstalledName InternationalDisplayString,
- hrSWInstalledID ProductID,
- hrSWInstalledType INTEGER,
- hrSWInstalledDate DateAndTime
- }
-
- hrSWInstalledIndex OBJECT-TYPE
- SYNTAX Integer32 (1..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A unique value for each piece of software installed
- on the host. This value shall be in the range from 1
- to the number of pieces of software installed on the
- host."
- ::= { hrSWInstalledEntry 1 }
-
- hrSWInstalledName OBJECT-TYPE
- SYNTAX InternationalDisplayString (SIZE (0..64))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A textual description of this installed piece of
- software, including the manufacturer, revision, the
- name by which it is commonly known, and optionally,
- its serial number."
- ::= { hrSWInstalledEntry 2 }
-
- hrSWInstalledID OBJECT-TYPE
- SYNTAX ProductID
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The product ID of this installed piece of software."
- ::= { hrSWInstalledEntry 3 }
-
- hrSWInstalledType OBJECT-TYPE
- SYNTAX INTEGER {
- unknown(1),
- operatingSystem(2),
- deviceDriver(3),
- application(4)
- }
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The type of this software."
- ::= { hrSWInstalledEntry 4 }
-
-
-
-Waldbusser & Grillo Standards Track [Page 32]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- hrSWInstalledDate OBJECT-TYPE
- SYNTAX DateAndTime
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The last-modification date of this application as it
- would appear in a directory listing.
-
- If this information is not known, then this variable
- shall have the value corresponding to January 1, year
- 0000, 00:00:00.0, which is encoded as
- (hex)'00 00 01 01 00 00 00 00'."
- ::= { hrSWInstalledEntry 5 }
-
- -- Conformance information
-
- hrMIBCompliances OBJECT IDENTIFIER ::= { hrMIBAdminInfo 2 }
- hrMIBGroups OBJECT IDENTIFIER ::= { hrMIBAdminInfo 3 }
-
- -- Compliance Statements
- hrMIBCompliance MODULE-COMPLIANCE
- STATUS current
- DESCRIPTION
- "The requirements for conformance to the Host Resources MIB."
- MODULE -- this module
- MANDATORY-GROUPS { hrSystemGroup, hrStorageGroup,
- hrDeviceGroup }
-
- OBJECT hrSystemDate
- MIN-ACCESS read-only
- DESCRIPTION
- "Write access is not required."
-
- OBJECT hrSystemInitialLoadDevice
- MIN-ACCESS read-only
- DESCRIPTION
- "Write access is not required."
-
- OBJECT hrSystemInitialLoadParameters
- MIN-ACCESS read-only
- DESCRIPTION
- "Write access is not required."
-
- OBJECT hrStorageSize
- MIN-ACCESS read-only
- DESCRIPTION
- "Write access is not required."
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 33]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- OBJECT hrFSLastFullBackupDate
- MIN-ACCESS read-only
- DESCRIPTION
- "Write access is not required."
-
- OBJECT hrFSLastPartialBackupDate
- MIN-ACCESS read-only
- DESCRIPTION
- "Write access is not required."
-
- GROUP hrSWRunGroup
- DESCRIPTION
- "The Running Software Group. Implementation
- of this group is mandatory only when the
- hrSWRunPerfGroup is implemented."
-
- OBJECT hrSWRunStatus
- MIN-ACCESS read-only
- DESCRIPTION
- "Write access is not required."
-
- GROUP hrSWRunPerfGroup
- DESCRIPTION
- "The Running Software Performance Group.
- Implementation of this group is at the discretion
- of the implementor."
-
- GROUP hrSWInstalledGroup
- DESCRIPTION
- "The Installed Software Group.
- Implementation of this group is at the discretion
- of the implementor."
-
- ::= { hrMIBCompliances 1 }
-
- hrSystemGroup OBJECT-GROUP
- OBJECTS {
- hrSystemUptime, hrSystemDate,
- hrSystemInitialLoadDevice,
- hrSystemInitialLoadParameters,
- hrSystemNumUsers, hrSystemProcesses,
- hrSystemMaxProcesses
- }
- STATUS current
- DESCRIPTION
- "The Host Resources System Group."
- ::= { hrMIBGroups 1 }
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 34]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- hrStorageGroup OBJECT-GROUP
- OBJECTS {
- hrMemorySize, hrStorageIndex, hrStorageType,
- hrStorageDescr, hrStorageAllocationUnits,
- hrStorageSize, hrStorageUsed,
- hrStorageAllocationFailures
- }
- STATUS current
- DESCRIPTION
- "The Host Resources Storage Group."
- ::= { hrMIBGroups 2 }
-
- hrDeviceGroup OBJECT-GROUP
- OBJECTS {
- hrDeviceIndex, hrDeviceType, hrDeviceDescr,
- hrDeviceID, hrDeviceStatus, hrDeviceErrors,
- hrProcessorFrwID, hrProcessorLoad,
- hrNetworkIfIndex, hrPrinterStatus,
- hrPrinterDetectedErrorState,
- hrDiskStorageAccess, hrDiskStorageMedia,
- hrDiskStorageRemoveble, hrDiskStorageCapacity,
- hrPartitionIndex, hrPartitionLabel,
- hrPartitionID, hrPartitionSize,
- hrPartitionFSIndex, hrFSIndex, hrFSMountPoint,
- hrFSRemoteMountPoint, hrFSType, hrFSAccess,
- hrFSBootable, hrFSStorageIndex,
- hrFSLastFullBackupDate,
- hrFSLastPartialBackupDate
- }
- STATUS current
- DESCRIPTION
- "The Host Resources Device Group."
- ::= { hrMIBGroups 3 }
-
- hrSWRunGroup OBJECT-GROUP
- OBJECTS {
- hrSWOSIndex, hrSWRunIndex, hrSWRunName,
- hrSWRunID, hrSWRunPath, hrSWRunParameters,
- hrSWRunType, hrSWRunStatus
- }
- STATUS current
- DESCRIPTION
- "The Host Resources Running Software Group."
- ::= { hrMIBGroups 4 }
-
- hrSWRunPerfGroup OBJECT-GROUP
- OBJECTS { hrSWRunPerfCPU, hrSWRunPerfMem }
- STATUS current
-
-
-
-Waldbusser & Grillo Standards Track [Page 35]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- DESCRIPTION
- "The Host Resources Running Software
- Performance Group."
- ::= { hrMIBGroups 5 }
-
- hrSWInstalledGroup OBJECT-GROUP
- OBJECTS {
- hrSWInstalledLastChange,
- hrSWInstalledLastUpdateTime,
- hrSWInstalledIndex, hrSWInstalledName,
- hrSWInstalledID, hrSWInstalledType,
- hrSWInstalledDate
- }
- STATUS current
- DESCRIPTION
- "The Host Resources Installed Software Group."
- ::= { hrMIBGroups 6 }
-
- END
-
-5. Type Definitions
-
- HOST-RESOURCES-TYPES DEFINITIONS ::= BEGIN
-
- IMPORTS
- MODULE-IDENTITY, OBJECT-IDENTITY FROM SNMPv2-SMI
- hrMIBAdminInfo, hrStorage, hrDevice FROM HOST-RESOURCES-MIB;
-
- hostResourcesTypesModule MODULE-IDENTITY
- LAST-UPDATED "200003060000Z" -- 6 March, 2000
- ORGANIZATION "IETF Host Resources MIB Working Group"
- CONTACT-INFO
- "Steve Waldbusser
- Postal: Lucent Technologies, Inc.
- 1213 Innsbruck Dr.
- Sunnyvale, CA 94089
- USA
- Phone: 650-318-1251
- Fax: 650-318-1633
- Email: waldbusser@ins.com
-
- In addition, the Host Resources MIB mailing list is dedicated
- to discussion of this MIB. To join the mailing list, send a
- request message to hostmib-request@andrew.cmu.edu. The mailing
- list address is hostmib@andrew.cmu.edu."
- DESCRIPTION
- "This MIB module registers type definitions for
- storage types, device types, and file system types.
-
-
-
-Waldbusser & Grillo Standards Track [Page 36]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- After the initial revision, this module will be
- maintained by IANA."
- REVISION "200003060000Z" -- 6 March 2000
- DESCRIPTION
- "The original version of this module, published as RFC
- 2790."
- ::= { hrMIBAdminInfo 4 }
-
- -- Registrations for some storage types, for use with hrStorageType
- hrStorageTypes OBJECT IDENTIFIER ::= { hrStorage 1 }
-
- hrStorageOther OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The storage type identifier used when no other defined
- type is appropriate."
- ::= { hrStorageTypes 1 }
-
- hrStorageRam OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The storage type identifier used for RAM."
- ::= { hrStorageTypes 2 }
-
- hrStorageVirtualMemory OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The storage type identifier used for virtual memory,
- temporary storage of swapped or paged memory."
- ::= { hrStorageTypes 3 }
-
- hrStorageFixedDisk OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The storage type identifier used for non-removable
- rigid rotating magnetic storage devices."
- ::= { hrStorageTypes 4 }
-
- hrStorageRemovableDisk OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The storage type identifier used for removable rigid
- rotating magnetic storage devices."
- ::= { hrStorageTypes 5 }
-
- hrStorageFloppyDisk OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
-
-
-
-Waldbusser & Grillo Standards Track [Page 37]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- "The storage type identifier used for non-rigid rotating
- magnetic storage devices."
- ::= { hrStorageTypes 6 }
-
- hrStorageCompactDisc OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The storage type identifier used for read-only rotating
- optical storage devices."
- ::= { hrStorageTypes 7 }
-
- hrStorageRamDisk OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The storage type identifier used for a file system that
- is stored in RAM."
- ::= { hrStorageTypes 8 }
-
- hrStorageFlashMemory OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The storage type identifier used for flash memory."
- ::= { hrStorageTypes 9 }
-
- hrStorageNetworkDisk OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The storage type identifier used for a
- networked file system."
- ::= { hrStorageTypes 10 }
-
- -- Registrations for some device types, for use with hrDeviceType
- hrDeviceTypes OBJECT IDENTIFIER ::= { hrDevice 1 }
-
- hrDeviceOther OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used when no other defined
- type is appropriate."
- ::= { hrDeviceTypes 1 }
-
- hrDeviceUnknown OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used when the device type is
- unknown."
- ::= { hrDeviceTypes 2 }
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 38]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- hrDeviceProcessor OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used for a CPU."
- ::= { hrDeviceTypes 3 }
-
- hrDeviceNetwork OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used for a network interface."
- ::= { hrDeviceTypes 4 }
-
- hrDevicePrinter OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used for a printer."
- ::= { hrDeviceTypes 5 }
-
- hrDeviceDiskStorage OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used for a disk drive."
- ::= { hrDeviceTypes 6 }
-
- hrDeviceVideo OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used for a video device."
- ::= { hrDeviceTypes 10 }
-
- hrDeviceAudio OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used for an audio device."
- ::= { hrDeviceTypes 11 }
-
- hrDeviceCoprocessor OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used for a co-processor."
- ::= { hrDeviceTypes 12 }
-
- hrDeviceKeyboard OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used for a keyboard device."
- ::= { hrDeviceTypes 13 }
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 39]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- hrDeviceModem OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used for a modem."
- ::= { hrDeviceTypes 14 }
-
- hrDeviceParallelPort OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used for a parallel port."
- ::= { hrDeviceTypes 15 }
-
- hrDevicePointing OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used for a pointing device
- (e.g., a mouse)."
- ::= { hrDeviceTypes 16 }
-
- hrDeviceSerialPort OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used for a serial port."
- ::= { hrDeviceTypes 17 }
-
- hrDeviceTape OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used for a tape storage device."
- ::= { hrDeviceTypes 18 }
-
- hrDeviceClock OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used for a clock device."
- ::= { hrDeviceTypes 19 }
-
- hrDeviceVolatileMemory OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used for a volatile memory
- storage device."
- ::= { hrDeviceTypes 20 }
-
- hrDeviceNonVolatileMemory OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The device type identifier used for a non-volatile memory
-
-
-
-Waldbusser & Grillo Standards Track [Page 40]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- storage device."
- ::= { hrDeviceTypes 21 }
-
- -- Registrations for some popular File System types,
- -- for use with hrFSType.
- hrFSTypes OBJECT IDENTIFIER ::= { hrDevice 9 }
-
- hrFSOther OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used when no other
- defined type is appropriate."
- ::= { hrFSTypes 1 }
-
- hrFSUnknown OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used when the type of
- file system is unknown."
- ::= { hrFSTypes 2 }
-
- hrFSBerkeleyFFS OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- Berkeley Fast File System."
- ::= { hrFSTypes 3 }
-
- hrFSSys5FS OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- System V File System."
- ::= { hrFSTypes 4 }
-
- hrFSFat OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for
- DOS's FAT file system."
- ::= { hrFSTypes 5 }
-
- hrFSHPFS OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for OS/2's
- High Performance File System."
- ::= { hrFSTypes 6 }
-
-
-
-Waldbusser & Grillo Standards Track [Page 41]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- hrFSHFS OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- Macintosh Hierarchical File System."
- ::= { hrFSTypes 7 }
-
- hrFSMFS OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- Macintosh File System."
- ::= { hrFSTypes 8 }
-
- hrFSNTFS OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- Windows NT File System."
- ::= { hrFSTypes 9 }
-
- hrFSVNode OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- VNode File System."
- ::= { hrFSTypes 10 }
-
- hrFSJournaled OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- Journaled File System."
- ::= { hrFSTypes 11 }
-
- hrFSiso9660 OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- ISO 9660 File System for CD's."
- ::= { hrFSTypes 12 }
-
- hrFSRockRidge OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- RockRidge File System for CD's."
- ::= { hrFSTypes 13 }
-
-
-
-Waldbusser & Grillo Standards Track [Page 42]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- hrFSNFS OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- NFS File System."
- ::= { hrFSTypes 14 }
-
- hrFSNetware OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- Netware File System."
- ::= { hrFSTypes 15 }
-
- hrFSAFS OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- Andrew File System."
- ::= { hrFSTypes 16 }
-
- hrFSDFS OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- OSF DCE Distributed File System."
- ::= { hrFSTypes 17 }
-
- hrFSAppleshare OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- AppleShare File System."
- ::= { hrFSTypes 18 }
-
- hrFSRFS OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- RFS File System."
- ::= { hrFSTypes 19 }
-
- hrFSDGCFS OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- Data General DGCFS."
- ::= { hrFSTypes 20 }
-
-
-
-Waldbusser & Grillo Standards Track [Page 43]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- hrFSBFS OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- SVR4 Boot File System."
- ::= { hrFSTypes 21 }
-
- hrFSFAT32 OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- Windows FAT32 File System."
- ::= { hrFSTypes 22 }
-
- hrFSLinuxExt2 OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The file system type identifier used for the
- Linux EXT2 File System."
- ::= { hrFSTypes 23 }
-
- END
-
-6. Internationalization Considerations
-
- This MIB has many objects that identify file-system pathnames on the
- managed host. Many file systems allow pathnames to be encoded in a
- variety of character sets (other than ASCII), but do not support the
- encoding of the actual character set used with the pathname. The
- implementation strategy is that user interfaces (i.e. character-based
- shells or graphical applications) will have configuration options
- that control with which character set they will interpret and display
- all pathnames. This is often a per-user configuration (e.g. an
- environment variable), so that users using different languages and
- character sets on a multi-user system may each work effectively with
- their preferred character set. A human usually controls this
- configuration. If an application is not configured or is configured
- incorrectly, it will often have trouble displaying pathnames in the
- intended character set.
-
- This situation made it important for this MIB to handle two issues:
-
- 1) Pathname objects must be able to transfer a variety of character
- sets with potentially multi-byte encodings; and,
-
-
-
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 44]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- 2) HostMIB agents will generally not be correctly configured for the
- appropriate character set to be used for all files on the system,
- particularly on a system with multiple users using different
- character sets. It was thus impossible to mandate that the agent
- tag pathnames with the character set in use.
-
- These issues were solved with the introduction of the
- InternationalDisplayString textual convention, which supports multi-
- byte encodings. Network management stations should use a local
- algorithm to determine which character set is in use and how it
- should be displayed. It is expected that network management station
- applications will rely on human configuration to choose which
- character set in which to interpret InternationalDisplayString
- objects, much like an application running locally on that host.
-
-7. Security Considerations
-
- There are a number of management objects defined in this MIB that
- have a MAX-ACCESS clause of read-write. Such objects may be
- considered sensitive or vulnerable in some network environments. The
- support for SET operations in a non-secure environment without proper
- protection can have a negative effect on system operations.
-
- There are a number of managed objects in this MIB that may contain
- sensitive information. The objects in the Running Software Group list
- information about running software on the system (including the
- operating system software and version). Some may wish not to
- disclose to others what software they are running. Further, an
- inventory of the running software and versions may be helpful to an
- attacker who hopes to exploit software bugs in certain applications.
- The same issues exist for the objects in the Installed Software
- Group.
-
- It is thus important to control even GET access to these objects and
- possibly to even encrypt the values of these object when sending them
- over the network via SNMP. Not all versions of SNMP provide features
- for such a secure environment.
-
- SNMPv1 by itself is not a secure environment. Even if the network
- itself is secure (for example by using IPSec), even then, there is no
- control as to who on the secure network is allowed to access and
- GET/SET (read/change/create/delete) the objects in this MIB.
-
- It is recommended that the implementers consider the security
- features as provided by the SNMPv3 framework. Specifically, the use
- of the User-based Security Model RFC 2574 [RFC2574] and the View-
- based Access Control Model RFC 2575 [RFC2575] is recommended.
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 45]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- It is then a customer/user responsibility to ensure that the SNMP
- entity giving access to an instance of this MIB, is properly
- configured to give access to the objects only to those principals
- (users) that have legitimate rights to indeed GET or SET
- (change/create/delete) them.
-
-8. References
-
- [RFC2571] Harrington, D., Presuhn, R. and B. Wijnen, "An
- Architecture for Describing SNMP Management Frameworks",
- RFC 2571, April 1999.
-
- [RFC1155] Rose, M. and K. McCloghrie, "Structure and Identification
- of Management Information for TCP/IP-based Internets",
- STD 16, RFC 1155, May 1990.
-
- [RFC1212] Rose, M. and K. McCloghrie, "Concise MIB Definitions",
- STD 16, RFC 1212, March 1991.
-
- [RFC1215] Rose, M., "A Convention for Defining Traps for use with
- the SNMP", RFC 1215, March 1991.
-
- [RFC2578] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J.,
- Rose, M. and S. Waldbusser, "Structure of Management
- Information Version 2 (SMIv2)", STD 58, RFC 2578, April
- 1999.
-
- [RFC2579] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J.,
- Rose, M. and S. Waldbusser, "Textual Conventions for
- SMIv2", STD 58, RFC 2579, April 1999.
-
- [RFC2580] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J.,
- Rose, M. and S. Waldbusser, "Conformance Statements for
- SMIv2", STD 58, RFC 2580, April 1999.
-
- [RFC1157] Case, J., Fedor, M., Schoffstall, M. and J. Davin,
- "Simple Network Management Protocol", STD 15, RFC 1157,
- May 1990.
-
- [RFC1901] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser,
- "Introduction to Community-based SNMPv2", RFC 1901,
- January 1996.
-
- [RFC1906] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser,
- "Transport Mappings for Version 2 of the Simple Network
- Management Protocol (SNMPv2)", RFC 1906, January 1996.
-
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 46]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
- [RFC2572] Case, J., Harrington D., Presuhn R. and B. Wijnen,
- "Message Processing and Dispatching for the Simple
- Network Management Protocol (SNMP)", RFC 2572, April 1999
-
- [RFC2574] Blumenthal, U. and B. Wijnen, "User-based Security Model
- (USM) for version 3 of the Simple Network Management
- Protocol (SNMPv3)", RFC 2574, April 1999.
-
- [RFC1905] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser,
- "Protocol Operations for Version 2 of the Simple Network
- Management Protocol (SNMPv2)", RFC 1905, January 1996.
-
- [RFC2573] Levi, D., Meyer, P. and B. Stewart, "SNMPv3
- Applications", RFC 2573, April 1999.
-
- [RFC2575] Wijnen, B., Presuhn, R. and K. McCloghrie, "View-based
- Access Control Model (VACM) for the Simple Network
- Management Protocol (SNMP)", RFC 2575, April 1999.
-
- [RFC2570] Case, J., Mundy, R., Partain, D. and B. Stewart,
- "Introduction to Version 3 of the Internet- standard
- Network Management Framework", RFC 2570, April 1999.
-
- [RFC1907] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser,
- "Management Information Base for Version 2 of the Simple
- Network Management Protocol (SNMPv2)", RFC 1907, January
- 1996.
-
- [RFC2233] McCloghrie, K. and F. Kastenholz, "The Interfaces Group
- MIB", RFC 2233, November 1997.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 47]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
-9. Acknowledgments
-
- This document was produced by the Host Resources MIB working group.
-
- Bobby Krupczak's efforts were particularly helpful in the creation of
- the draft standard version of this document.
-
- In addition, the authors gratefully acknowledge the comments of the
- following individuals:
-
- Amatzia Ben-Artzi NetManage
- Ron Bergman Hitachi, Inc.
- Steve Bostock Novell
- Stephen Bush GE Information Systems
- Jeff Case SNMP Research
- Chuck Davin Bellcore
- Ray Edgarton Bell Atlantic
- Mike Erlinger Aerospace Corporation
- Tim Farley Magee Enterprises
- Mark Kepke Hewlett Packard
- Bobby Krupczak Empire Technologies, Inc.
- Cheryl Krupczak Empire Technologies, Inc.
- Harry Lewis IBM Corp.
- Keith McCloghrie Cisco Systems
- Greg Minshall Novell
- Steve Moulton SNMP Research
- Dave Perkins Synoptics
- Ed Reeder Objective Systems Integrators
- Mike Ritter Apple Computer
- Marshall Rose Dover Beach Consulting
- Jon Saperia DEC
- Rodney Thayer Sable Technology
- Kaj Tesink Bellcore
- Dean Throop Data General
- Bert Wijnen Lucent
- Lloyd Young Lexmark International
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 48]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
-10. Authors' Addresses
-
- Pete Grillo
- WeSync.com
- 1001 SW Fifth Ave, Fifth Floor
- Portland, OR 97204
-
- Phone: 503-425-5051
- Fax: 503-827-6718
- email: pete@wesync.com
- Phone: +1 503 827 6717
-
-
- Steven Waldbusser
- Lucent Technologies, Inc.
- 1213 Innsbruck Dr.
- Sunnyvale CA 94089
-
- Phone: +1 650 318 1251
- Fax: +1 650 318 1633
- EMail: waldbusser@ins.com
-
-11. Intellectual Property
-
- The IETF takes no position regarding the validity or scope of
- any intellectual property or other rights that might be
- claimed to pertain to the implementation or use of the
- technology described in this document or the extent to which
- any license under such rights might or might not be available;
- neither does it represent that it has made any effort to
- identify any such rights. Information on the IETF's
- procedures with respect to rights in standards-track and
- standards-related documentation can be found in BCP-11.
- Copies of claims of rights made available for publication and
- any assurances of licenses to be made available, or the result
- of an attempt made to obtain a general license or permission
- for the use of such proprietary rights by implementors or
- users of this specification can be obtained from the IETF
- Secretariat.
-
- The IETF invites any interested party to bring to its
- attention any copyrights, patents or patent applications, or
- other proprietary rights which may cover technology that may
- be required to practice this standard. Please address the
- information to the IETF Executive Director.
-
-
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 49]
-\f
-RFC 2790 Host Resources MIB March 2000
-
-
-12. Full Copyright Statement
-
- Copyright (C) The Internet Society (2000). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Waldbusser & Grillo Standards Track [Page 50]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group R. Khare
-Request for Comments: 2817 4K Associates / UC Irvine
-Updates: 2616 S. Lawrence
-Category: Standards Track Agranat Systems, Inc.
- May 2000
-
-
- Upgrading to TLS Within HTTP/1.1
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2000). All Rights Reserved.
-
-Abstract
-
- This memo explains how to use the Upgrade mechanism in HTTP/1.1 to
- initiate Transport Layer Security (TLS) over an existing TCP
- connection. This allows unsecured and secured HTTP traffic to share
- the same well known port (in this case, http: at 80 rather than
- https: at 443). It also enables "virtual hosting", so a single HTTP +
- TLS server can disambiguate traffic intended for several hostnames at
- a single IP address.
-
- Since HTTP/1.1 [1] defines Upgrade as a hop-by-hop mechanism, this
- memo also documents the HTTP CONNECT method for establishing end-to-
- end tunnels across HTTP proxies. Finally, this memo establishes new
- IANA registries for public HTTP status codes, as well as public or
- private Upgrade product tokens.
-
- This memo does NOT affect the current definition of the 'https' URI
- scheme, which already defines a separate namespace
- (http://example.org/ and https://example.org/ are not equivalent).
-
-
-
-
-
-
-
-
-
-
-
-Khare & Lawrence Standards Track [Page 1]
-\f
-RFC 2817 HTTP Upgrade to TLS May 2000
-
-
-Table of Contents
-
- 1. Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . 2
- 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 2.1 Requirements Terminology . . . . . . . . . . . . . . . . . . . 4
- 3. Client Requested Upgrade to HTTP over TLS . . . . . . . . . . 4
- 3.1 Optional Upgrade . . . . . . . . . . . . . . . . . . . . . . . 4
- 3.2 Mandatory Upgrade . . . . . . . . . . . . . . . . . . . . . . 4
- 3.3 Server Acceptance of Upgrade Request . . . . . . . . . . . . . 4
- 4. Server Requested Upgrade to HTTP over TLS . . . . . . . . . . 5
- 4.1 Optional Advertisement . . . . . . . . . . . . . . . . . . . . 5
- 4.2 Mandatory Advertisement . . . . . . . . . . . . . . . . . . . 5
- 5. Upgrade across Proxies . . . . . . . . . . . . . . . . . . . . 6
- 5.1 Implications of Hop By Hop Upgrade . . . . . . . . . . . . . . 6
- 5.2 Requesting a Tunnel with CONNECT . . . . . . . . . . . . . . . 6
- 5.3 Establishing a Tunnel with CONNECT . . . . . . . . . . . . . . 7
- 6. Rationale for the use of a 4xx (client error) Status Code . . 7
- 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
- 7.1 HTTP Status Code Registry . . . . . . . . . . . . . . . . . . 8
- 7.2 HTTP Upgrade Token Registry . . . . . . . . . . . . . . . . . 8
- 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9
- 8.1 Implications for the https: URI Scheme . . . . . . . . . . . . 10
- 8.2 Security Considerations for CONNECT . . . . . . . . . . . . . 10
- References . . . . . . . . . . . . . . . . . . . . . . . . . . 10
- Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 11
- A. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12
- Full Copyright Statement . . . . . . . . . . . . . . . . . . . 13
-
-1. Motivation
-
- The historical practice of deploying HTTP over SSL3 [3] has
- distinguished the combination from HTTP alone by a unique URI scheme
- and the TCP port number. The scheme 'http' meant the HTTP protocol
- alone on port 80, while 'https' meant the HTTP protocol over SSL on
- port 443. Parallel well-known port numbers have similarly been
- requested -- and in some cases, granted -- to distinguish between
- secured and unsecured use of other application protocols (e.g.
- snews, ftps). This approach effectively halves the number of
- available well known ports.
-
- At the Washington DC IETF meeting in December 1997, the Applications
- Area Directors and the IESG reaffirmed that the practice of issuing
- parallel "secure" port numbers should be deprecated. The HTTP/1.1
- Upgrade mechanism can apply Transport Layer Security [6] to an open
- HTTP connection.
-
-
-
-
-
-
-Khare & Lawrence Standards Track [Page 2]
-\f
-RFC 2817 HTTP Upgrade to TLS May 2000
-
-
- In the nearly two years since, there has been broad acceptance of the
- concept behind this proposal, but little interest in implementing
- alternatives to port 443 for generic Web browsing. In fact, nothing
- in this memo affects the current interpretation of https: URIs.
- However, new application protocols built atop HTTP, such as the
- Internet Printing Protocol [7], call for just such a mechanism in
- order to move ahead in the IETF standards process.
-
- The Upgrade mechanism also solves the "virtual hosting" problem.
- Rather than allocating multiple IP addresses to a single host, an
- HTTP/1.1 server will use the Host: header to disambiguate the
- intended web service. As HTTP/1.1 usage has grown more prevalent,
- more ISPs are offering name-based virtual hosting, thus delaying IP
- address space exhaustion.
-
- TLS (and SSL) have been hobbled by the same limitation as earlier
- versions of HTTP: the initial handshake does not specify the intended
- hostname, relying exclusively on the IP address. Using a cleartext
- HTTP/1.1 Upgrade: preamble to the TLS handshake -- choosing the
- certificates based on the initial Host: header -- will allow ISPs to
- provide secure name-based virtual hosting as well.
-
-2. Introduction
-
- TLS, a.k.a., SSL (Secure Sockets Layer), establishes a private end-
- to-end connection, optionally including strong mutual authentication,
- using a variety of cryptosystems. Initially, a handshake phase uses
- three subprotocols to set up a record layer, authenticate endpoints,
- set parameters, as well as report errors. Then, there is an ongoing
- layered record protocol that handles encryption, compression, and
- reassembly for the remainder of the connection. The latter is
- intended to be completely transparent. For example, there is no
- dependency between TLS's record markers and or certificates and
- HTTP/1.1's chunked encoding or authentication.
-
- Either the client or server can use the HTTP/1.1 [1] Upgrade
- mechanism (Section 14.42) to indicate that a TLS-secured connection
- is desired or necessary. This memo defines the "TLS/1.0" Upgrade
- token, and a new HTTP Status Code, "426 Upgrade Required".
-
- Section 3 and Section 4 describe the operation of a directly
- connected client and server. Intermediate proxies must establish an
- end-to-end tunnel before applying those operations, as explained in
- Section 5.
-
-
-
-
-
-
-
-Khare & Lawrence Standards Track [Page 3]
-\f
-RFC 2817 HTTP Upgrade to TLS May 2000
-
-
-2.1 Requirements Terminology
-
- Keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT" and
- "MAY" that appear in this document are to be interpreted as described
- in RFC 2119 [11].
-
-3. Client Requested Upgrade to HTTP over TLS
-
- When the client sends an HTTP/1.1 request with an Upgrade header
- field containing the token "TLS/1.0", it is requesting the server to
- complete the current HTTP/1.1 request after switching to TLS/1.0.
-
-3.1 Optional Upgrade
-
- A client MAY offer to switch to secured operation during any clear
- HTTP request when an unsecured response would be acceptable:
-
- GET http://example.bank.com/acct_stat.html?749394889300 HTTP/1.1
- Host: example.bank.com
- Upgrade: TLS/1.0
- Connection: Upgrade
-
- In this case, the server MAY respond to the clear HTTP operation
- normally, OR switch to secured operation (as detailed in the next
- section).
-
- Note that HTTP/1.1 [1] specifies "the upgrade keyword MUST be
- supplied within a Connection header field (section 14.10) whenever
- Upgrade is present in an HTTP/1.1 message".
-
-3.2 Mandatory Upgrade
-
- If an unsecured response would be unacceptable, a client MUST send an
- OPTIONS request first to complete the switch to TLS/1.0 (if
- possible).
-
- OPTIONS * HTTP/1.1
- Host: example.bank.com
- Upgrade: TLS/1.0
- Connection: Upgrade
-
-3.3 Server Acceptance of Upgrade Request
-
- As specified in HTTP/1.1 [1], if the server is prepared to initiate
- the TLS handshake, it MUST send the intermediate "101 Switching
- Protocol" and MUST include an Upgrade response header specifying the
- tokens of the protocol stack it is switching to:
-
-
-
-
-Khare & Lawrence Standards Track [Page 4]
-\f
-RFC 2817 HTTP Upgrade to TLS May 2000
-
-
- HTTP/1.1 101 Switching Protocols
- Upgrade: TLS/1.0, HTTP/1.1
- Connection: Upgrade
-
- Note that the protocol tokens listed in the Upgrade header of a 101
- Switching Protocols response specify an ordered 'bottom-up' stack.
-
- As specified in HTTP/1.1 [1], Section 10.1.2: "The server will
- switch protocols to those defined by the response's Upgrade header
- field immediately after the empty line which terminates the 101
- response".
-
- Once the TLS handshake completes successfully, the server MUST
- continue with the response to the original request. Any TLS handshake
- failure MUST lead to disconnection, per the TLS error alert
- specification.
-
-4. Server Requested Upgrade to HTTP over TLS
-
- The Upgrade response header field advertises possible protocol
- upgrades a server MAY accept. In conjunction with the "426 Upgrade
- Required" status code, a server can advertise the exact protocol
- upgrade(s) that a client MUST accept to complete the request.
-
-4.1 Optional Advertisement
-
- As specified in HTTP/1.1 [1], the server MAY include an Upgrade
- header in any response other than 101 or 426 to indicate a
- willingness to switch to any (combination) of the protocols listed.
-
-4.2 Mandatory Advertisement
-
- A server MAY indicate that a client request can not be completed
- without TLS using the "426 Upgrade Required" status code, which MUST
- include an an Upgrade header field specifying the token of the
- required TLS version.
-
- HTTP/1.1 426 Upgrade Required
- Upgrade: TLS/1.0, HTTP/1.1
- Connection: Upgrade
-
- The server SHOULD include a message body in the 426 response which
- indicates in human readable form the reason for the error and
- describes any alternative courses which may be available to the user.
-
- Note that even if a client is willing to use TLS, it must use the
- operations in Section 3 to proceed; the TLS handshake cannot begin
- immediately after the 426 response.
-
-
-
-Khare & Lawrence Standards Track [Page 5]
-\f
-RFC 2817 HTTP Upgrade to TLS May 2000
-
-
-5. Upgrade across Proxies
-
- As a hop-by-hop header, Upgrade is negotiated between each pair of
- HTTP counterparties. If a User Agent sends a request with an Upgrade
- header to a proxy, it is requesting a change to the protocol between
- itself and the proxy, not an end-to-end change.
-
- Since TLS, in particular, requires end-to-end connectivity to provide
- authentication and prevent man-in-the-middle attacks, this memo
- specifies the CONNECT method to establish a tunnel across proxies.
-
- Once a tunnel is established, any of the operations in Section 3 can
- be used to establish a TLS connection.
-
-5.1 Implications of Hop By Hop Upgrade
-
- If an origin server receives an Upgrade header from a proxy and
- responds with a 101 Switching Protocols response, it is changing the
- protocol only on the connection between the proxy and itself.
- Similarly, a proxy might return a 101 response to its client to
- change the protocol on that connection independently of the protocols
- it is using to communicate toward the origin server.
-
- These scenarios also complicate diagnosis of a 426 response. Since
- Upgrade is a hop-by-hop header, a proxy that does not recognize 426
- might remove the accompanying Upgrade header and prevent the client
- from determining the required protocol switch. If a client receives
- a 426 status without an accompanying Upgrade header, it will need to
- request an end to end tunnel connection as described in Section 5.2
- and repeat the request in order to obtain the required upgrade
- information.
-
- This hop-by-hop definition of Upgrade was a deliberate choice. It
- allows for incremental deployment on either side of proxies, and for
- optimized protocols between cascaded proxies without the knowledge of
- the parties that are not a part of the change.
-
-5.2 Requesting a Tunnel with CONNECT
-
- A CONNECT method requests that a proxy establish a tunnel connection
- on its behalf. The Request-URI portion of the Request-Line is always
- an 'authority' as defined by URI Generic Syntax [2], which is to say
- the host name and port number destination of the requested connection
- separated by a colon:
-
- CONNECT server.example.com:80 HTTP/1.1
- Host: server.example.com:80
-
-
-
-
-Khare & Lawrence Standards Track [Page 6]
-\f
-RFC 2817 HTTP Upgrade to TLS May 2000
-
-
- Other HTTP mechanisms can be used normally with the CONNECT method --
- except end-to-end protocol Upgrade requests, of course, since the
- tunnel must be established first.
-
- For example, proxy authentication might be used to establish the
- authority to create a tunnel:
-
- CONNECT server.example.com:80 HTTP/1.1
- Host: server.example.com:80
- Proxy-Authorization: basic aGVsbG86d29ybGQ=
-
- Like any other pipelined HTTP/1.1 request, data to be tunneled may be
- sent immediately after the blank line. The usual caveats also apply:
- data may be discarded if the eventual response is negative, and the
- connection may be reset with no response if more than one TCP segment
- is outstanding.
-
-5.3 Establishing a Tunnel with CONNECT
-
- Any successful (2xx) response to a CONNECT request indicates that the
- proxy has established a connection to the requested host and port,
- and has switched to tunneling the current connection to that server
- connection.
-
- It may be the case that the proxy itself can only reach the requested
- origin server through another proxy. In this case, the first proxy
- SHOULD make a CONNECT request of that next proxy, requesting a tunnel
- to the authority. A proxy MUST NOT respond with any 2xx status code
- unless it has either a direct or tunnel connection established to the
- authority.
-
- An origin server which receives a CONNECT request for itself MAY
- respond with a 2xx status code to indicate that a connection is
- established.
-
- If at any point either one of the peers gets disconnected, any
- outstanding data that came from that peer will be passed to the other
- one, and after that also the other connection will be terminated by
- the proxy. If there is outstanding data to that peer undelivered,
- that data will be discarded.
-
-6. Rationale for the use of a 4xx (client error) Status Code
-
- Reliable, interoperable negotiation of Upgrade features requires an
- unambiguous failure signal. The 426 Upgrade Required status code
- allows a server to definitively state the precise protocol extensions
- a given resource must be served with.
-
-
-
-
-Khare & Lawrence Standards Track [Page 7]
-\f
-RFC 2817 HTTP Upgrade to TLS May 2000
-
-
- It might at first appear that the response should have been some form
- of redirection (a 3xx code), by analogy to an old-style redirection
- to an https: URI. User agents that do not understand Upgrade:
- preclude this.
-
- Suppose that a 3xx code had been assigned for "Upgrade Required"; a
- user agent that did not recognize it would treat it as 300. It would
- then properly look for a "Location" header in the response and
- attempt to repeat the request at the URL in that header field. Since
- it did not know to Upgrade to incorporate the TLS layer, it would at
- best fail again at the new URL.
-
-7. IANA Considerations
-
- IANA shall create registries for two name spaces, as described in BCP
- 26 [10]:
-
- o HTTP Status Codes
- o HTTP Upgrade Tokens
-
-7.1 HTTP Status Code Registry
-
- The HTTP Status Code Registry defines the name space for the Status-
- Code token in the Status line of an HTTP response. The initial
- values for this name space are those specified by:
-
- 1. Draft Standard for HTTP/1.1 [1]
- 2. Web Distributed Authoring and Versioning [4] [defines 420-424]
- 3. WebDAV Advanced Collections [5] (Work in Progress) [defines 425]
- 4. Section 6 [defines 426]
-
- Values to be added to this name space SHOULD be subject to review in
- the form of a standards track document within the IETF Applications
- Area. Any such document SHOULD be traceable through statuses of
- either 'Obsoletes' or 'Updates' to the Draft Standard for
- HTTP/1.1 [1].
-
-7.2 HTTP Upgrade Token Registry
-
- The HTTP Upgrade Token Registry defines the name space for product
- tokens used to identify protocols in the Upgrade HTTP header field.
- Each registered token should be associated with one or a set of
- specifications, and with contact information.
-
- The Draft Standard for HTTP/1.1 [1] specifies that these tokens obey
- the production for 'product':
-
-
-
-
-
-Khare & Lawrence Standards Track [Page 8]
-\f
-RFC 2817 HTTP Upgrade to TLS May 2000
-
-
- product = token ["/" product-version]
- product-version = token
-
- Registrations should be allowed on a First Come First Served basis as
- described in BCP 26 [10]. These specifications need not be IETF
- documents or be subject to IESG review, but should obey the following
- rules:
-
- 1. A token, once registered, stays registered forever.
- 2. The registration MUST name a responsible party for the
- registration.
- 3. The registration MUST name a point of contact.
- 4. The registration MAY name the documentation required for the
- token.
- 5. The responsible party MAY change the registration at any time.
- The IANA will keep a record of all such changes, and make them
- available upon request.
- 6. The responsible party for the first registration of a "product"
- token MUST approve later registrations of a "version" token
- together with that "product" token before they can be registered.
- 7. If absolutely required, the IESG MAY reassign the responsibility
- for a token. This will normally only be used in the case when a
- responsible party cannot be contacted.
-
- This specification defines the protocol token "TLS/1.0" as the
- identifier for the protocol specified by The TLS Protocol [6].
-
- It is NOT required that specifications for upgrade tokens be made
- publicly available, but the contact information for the registration
- SHOULD be.
-
-8. Security Considerations
-
- The potential for a man-in-the-middle attack (deleting the Upgrade
- header) remains the same as current, mixed http/https practice:
-
- o Removing the Upgrade header is similar to rewriting web pages to
- change https:// links to http:// links.
- o The risk is only present if the server is willing to vend such
- information over both a secure and an insecure channel in the
- first place.
- o If the client knows for a fact that a server is TLS-compliant, it
- can insist on it by only sending an Upgrade request with a no-op
- method like OPTIONS.
- o Finally, as the https: specification warns, "users should
- carefully examine the certificate presented by the server to
- determine if it meets their expectations".
-
-
-
-
-Khare & Lawrence Standards Track [Page 9]
-\f
-RFC 2817 HTTP Upgrade to TLS May 2000
-
-
- Furthermore, for clients that do not explicitly try to invoke TLS,
- servers can use the Upgrade header in any response other than 101 or
- 426 to advertise TLS compliance. Since TLS compliance should be
- considered a feature of the server and not the resource at hand, it
- should be sufficient to send it once, and let clients cache that
- fact.
-
-8.1 Implications for the https: URI Scheme
-
- While nothing in this memo affects the definition of the 'https' URI
- scheme, widespread adoption of this mechanism for HyperText content
- could use 'http' to identify both secure and non-secure resources.
-
- The choice of what security characteristics are required on the
- connection is left to the client and server. This allows either
- party to use any information available in making this determination.
- For example, user agents may rely on user preference settings or
- information about the security of the network such as 'TLS required
- on all POST operations not on my local net', or servers may apply
- resource access rules such as 'the FORM on this page must be served
- and submitted using TLS'.
-
-8.2 Security Considerations for CONNECT
-
- A generic TCP tunnel is fraught with security risks. First, such
- authorization should be limited to a small number of known ports.
- The Upgrade: mechanism defined here only requires onward tunneling at
- port 80. Second, since tunneled data is opaque to the proxy, there
- are additional risks to tunneling to other well-known or reserved
- ports. A putative HTTP client CONNECTing to port 25 could relay spam
- via SMTP, for example.
-
-References
-
- [1] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L.,
- Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
- HTTP/1.1", RFC 2616, June 1999.
-
- [2] Berners-Lee, T., Fielding, R. and L. Masinter, "URI Generic
- Syntax", RFC 2396, August 1998.
-
- [3] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
-
- [4] Goland, Y., Whitehead, E., Faizi, A., Carter, S. and D. Jensen,
- "Web Distributed Authoring and Versioning", RFC 2518, February
- 1999.
-
-
-
-
-
-Khare & Lawrence Standards Track [Page 10]
-\f
-RFC 2817 HTTP Upgrade to TLS May 2000
-
-
- [5] Slein, J., Whitehead, E.J., et al., "WebDAV Advanced Collections
- Protocol", Work In Progress.
-
- [6] Dierks, T. and C. Allen, "The TLS Protocol", RFC 2246, January
- 1999.
-
- [7] Herriot, R., Butler, S., Moore, P. and R. Turner, "Internet
- Printing Protocol/1.0: Encoding and Transport", RFC 2565, April
- 1999.
-
- [8] Luotonen, A., "Tunneling TCP based protocols through Web proxy
- servers", Work In Progress. (Also available in: Luotonen, Ari.
- Web Proxy Servers, Prentice-Hall, 1997 ISBN:0136806120.)
-
- [9] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June
- 1999.
-
- [10] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA
- Considerations Section in RFCs", BCP 26, RFC 2434, October 1998.
-
- [11] Bradner, S., "Key words for use in RFCs to Indicate Requirement
- Levels", BCP 14, RFC 2119, March 1997.
-
-Authors' Addresses
-
- Rohit Khare
- 4K Associates / UC Irvine
- 3207 Palo Verde
- Irvine, CA 92612
- US
-
- Phone: +1 626 806 7574
- EMail: rohit@4K-associates.com
- URI: http://www.4K-associates.com/
-
-
- Scott Lawrence
- Agranat Systems, Inc.
- 5 Clocktower Place
- Suite 400
- Maynard, MA 01754
- US
-
- Phone: +1 978 461 0888
- EMail: lawrence@agranat.com
- URI: http://www.agranat.com/
-
-
-
-
-
-Khare & Lawrence Standards Track [Page 11]
-\f
-RFC 2817 HTTP Upgrade to TLS May 2000
-
-
-Appendix A. Acknowledgments
-
- The CONNECT method was originally described in a Work in Progress
- titled, "Tunneling TCP based protocols through Web proxy servers",
- [8] by Ari Luotonen of Netscape Communications Corporation. It was
- widely implemented by HTTP proxies, but was never made a part of any
- IETF Standards Track document. The method name CONNECT was reserved,
- but not defined in [1].
-
- The definition provided here is derived directly from that earlier
- memo, with some editorial changes and conformance to the stylistic
- conventions since established in other HTTP specifications.
-
- Additional Thanks to:
-
- o Paul Hoffman for his work on the STARTTLS command extension for
- ESMTP.
- o Roy Fielding for assistance with the rationale behind Upgrade:
- and its interaction with OPTIONS.
- o Eric Rescorla for his work on standardizing the existing https:
- practice to compare with.
- o Marshall Rose, for the xml2rfc document type description and tools
- [9].
- o Jim Whitehead, for sorting out the current range of available HTTP
- status codes.
- o Henrik Frystyk Nielsen, whose work on the Mandatory extension
- mechanism pointed out a hop-by-hop Upgrade still requires
- tunneling.
- o Harald Alvestrand for improvements to the token registration
- rules.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Khare & Lawrence Standards Track [Page 12]
-\f
-RFC 2817 HTTP Upgrade to TLS May 2000
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2000). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Khare & Lawrence Standards Track [Page 13]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group E. Rescorla
-Request for Comments: 2818 RTFM, Inc.
-Category: Informational May 2000
-
-
- HTTP Over TLS
-
-Status of this Memo
-
- This memo provides information for the Internet community. It does
- not specify an Internet standard of any kind. Distribution of this
- memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2000). All Rights Reserved.
-
-Abstract
-
- This memo describes how to use TLS to secure HTTP connections over
- the Internet. Current practice is to layer HTTP over SSL (the
- predecessor to TLS), distinguishing secured traffic from insecure
- traffic by the use of a different server port. This document
- documents that practice using TLS. A companion document describes a
- method for using HTTP/TLS over the same port as normal HTTP
- [RFC2817].
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . 2
- 1.1. Requirements Terminology . . . . . . . . . . . . . . . 2
- 2. HTTP Over TLS . . . . . . . . . . . . . . . . . . . . . . 2
- 2.1. Connection Initiation . . . . . . . . . . . . . . . . . 2
- 2.2. Connection Closure . . . . . . . . . . . . . . . . . . 2
- 2.2.1. Client Behavior . . . . . . . . . . . . . . . . . . . 3
- 2.2.2. Server Behavior . . . . . . . . . . . . . . . . . . . 3
- 2.3. Port Number . . . . . . . . . . . . . . . . . . . . . . 4
- 2.4. URI Format . . . . . . . . . . . . . . . . . . . . . . 4
- 3. Endpoint Identification . . . . . . . . . . . . . . . . . 4
- 3.1. Server Identity . . . . . . . . . . . . . . . . . . . . 4
- 3.2. Client Identity . . . . . . . . . . . . . . . . . . . . 5
- References . . . . . . . . . . . . . . . . . . . . . . . . . 6
- Security Considerations . . . . . . . . . . . . . . . . . . 6
- Author's Address . . . . . . . . . . . . . . . . . . . . . . 6
- Full Copyright Statement . . . . . . . . . . . . . . . . . . 7
-
-
-
-
-
-
-Rescorla Informational [Page 1]
-\f
-RFC 2818 HTTP Over TLS May 2000
-
-
-1. Introduction
-
- HTTP [RFC2616] was originally used in the clear on the Internet.
- However, increased use of HTTP for sensitive applications has
- required security measures. SSL, and its successor TLS [RFC2246] were
- designed to provide channel-oriented security. This document
- describes how to use HTTP over TLS.
-
-1.1. Requirements Terminology
-
- Keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT" and
- "MAY" that appear in this document are to be interpreted as described
- in [RFC2119].
-
-2. HTTP Over TLS
-
- Conceptually, HTTP/TLS is very simple. Simply use HTTP over TLS
- precisely as you would use HTTP over TCP.
-
-2.1. Connection Initiation
-
- The agent acting as the HTTP client should also act as the TLS
- client. It should initiate a connection to the server on the
- appropriate port and then send the TLS ClientHello to begin the TLS
- handshake. When the TLS handshake has finished. The client may then
- initiate the first HTTP request. All HTTP data MUST be sent as TLS
- "application data". Normal HTTP behavior, including retained
- connections should be followed.
-
-2.2. Connection Closure
-
- TLS provides a facility for secure connection closure. When a valid
- closure alert is received, an implementation can be assured that no
- further data will be received on that connection. TLS
- implementations MUST initiate an exchange of closure alerts before
- closing a connection. A TLS implementation MAY, after sending a
- closure alert, close the connection without waiting for the peer to
- send its closure alert, generating an "incomplete close". Note that
- an implementation which does this MAY choose to reuse the session.
- This SHOULD only be done when the application knows (typically
- through detecting HTTP message boundaries) that it has received all
- the message data that it cares about.
-
- As specified in [RFC2246], any implementation which receives a
- connection close without first receiving a valid closure alert (a
- "premature close") MUST NOT reuse that session. Note that a
- premature close does not call into question the security of the data
- already received, but simply indicates that subsequent data might
-
-
-
-Rescorla Informational [Page 2]
-\f
-RFC 2818 HTTP Over TLS May 2000
-
-
- have been truncated. Because TLS is oblivious to HTTP
- request/response boundaries, it is necessary to examine the HTTP data
- itself (specifically the Content-Length header) to determine whether
- the truncation occurred inside a message or between messages.
-
-2.2.1. Client Behavior
-
- Because HTTP uses connection closure to signal end of server data,
- client implementations MUST treat any premature closes as errors and
- the data received as potentially truncated. While in some cases the
- HTTP protocol allows the client to find out whether truncation took
- place so that, if it received the complete reply, it may tolerate
- such errors following the principle to "[be] strict when sending and
- tolerant when receiving" [RFC1958], often truncation does not show in
- the HTTP protocol data; two cases in particular deserve special note:
-
- A HTTP response without a Content-Length header. Since data length
- in this situation is signalled by connection close a premature
- close generated by the server cannot be distinguished from a
- spurious close generated by an attacker.
-
- A HTTP response with a valid Content-Length header closed before
- all data has been read. Because TLS does not provide document
- oriented protection, it is impossible to determine whether the
- server has miscomputed the Content-Length or an attacker has
- truncated the connection.
-
- There is one exception to the above rule. When encountering a
- premature close, a client SHOULD treat as completed all requests for
- which it has received as much data as specified in the Content-Length
- header.
-
- A client detecting an incomplete close SHOULD recover gracefully. It
- MAY resume a TLS session closed in this fashion.
-
- Clients MUST send a closure alert before closing the connection.
- Clients which are unprepared to receive any more data MAY choose not
- to wait for the server's closure alert and simply close the
- connection, thus generating an incomplete close on the server side.
-
-2.2.2. Server Behavior
-
- RFC 2616 permits an HTTP client to close the connection at any time,
- and requires servers to recover gracefully. In particular, servers
- SHOULD be prepared to receive an incomplete close from the client,
- since the client can often determine when the end of server data is.
- Servers SHOULD be willing to resume TLS sessions closed in this
- fashion.
-
-
-
-Rescorla Informational [Page 3]
-\f
-RFC 2818 HTTP Over TLS May 2000
-
-
- Implementation note: In HTTP implementations which do not use
- persistent connections, the server ordinarily expects to be able to
- signal end of data by closing the connection. When Content-Length is
- used, however, the client may have already sent the closure alert and
- dropped the connection.
-
- Servers MUST attempt to initiate an exchange of closure alerts with
- the client before closing the connection. Servers MAY close the
- connection after sending the closure alert, thus generating an
- incomplete close on the client side.
-
-2.3. Port Number
-
- The first data that an HTTP server expects to receive from the client
- is the Request-Line production. The first data that a TLS server (and
- hence an HTTP/TLS server) expects to receive is the ClientHello.
- Consequently, common practice has been to run HTTP/TLS over a
- separate port in order to distinguish which protocol is being used.
- When HTTP/TLS is being run over a TCP/IP connection, the default port
- is 443. This does not preclude HTTP/TLS from being run over another
- transport. TLS only presumes a reliable connection-oriented data
- stream.
-
-2.4. URI Format
-
- HTTP/TLS is differentiated from HTTP URIs by using the 'https'
- protocol identifier in place of the 'http' protocol identifier. An
- example URI specifying HTTP/TLS is:
-
- https://www.example.com/~smith/home.html
-
-3. Endpoint Identification
-
-3.1. Server Identity
-
- In general, HTTP/TLS requests are generated by dereferencing a URI.
- As a consequence, the hostname for the server is known to the client.
- If the hostname is available, the client MUST check it against the
- server's identity as presented in the server's Certificate message,
- in order to prevent man-in-the-middle attacks.
-
- If the client has external information as to the expected identity of
- the server, the hostname check MAY be omitted. (For instance, a
- client may be connecting to a machine whose address and hostname are
- dynamic but the client knows the certificate that the server will
- present.) In such cases, it is important to narrow the scope of
- acceptable certificates as much as possible in order to prevent man
-
-
-
-
-Rescorla Informational [Page 4]
-\f
-RFC 2818 HTTP Over TLS May 2000
-
-
- in the middle attacks. In special cases, it may be appropriate for
- the client to simply ignore the server's identity, but it must be
- understood that this leaves the connection open to active attack.
-
- If a subjectAltName extension of type dNSName is present, that MUST
- be used as the identity. Otherwise, the (most specific) Common Name
- field in the Subject field of the certificate MUST be used. Although
- the use of the Common Name is existing practice, it is deprecated and
- Certification Authorities are encouraged to use the dNSName instead.
-
- Matching is performed using the matching rules specified by
- [RFC2459]. If more than one identity of a given type is present in
- the certificate (e.g., more than one dNSName name, a match in any one
- of the set is considered acceptable.) Names may contain the wildcard
- character * which is considered to match any single domain name
- component or component fragment. E.g., *.a.com matches foo.a.com but
- not bar.foo.a.com. f*.com matches foo.com but not bar.com.
-
- In some cases, the URI is specified as an IP address rather than a
- hostname. In this case, the iPAddress subjectAltName must be present
- in the certificate and must exactly match the IP in the URI.
-
- If the hostname does not match the identity in the certificate, user
- oriented clients MUST either notify the user (clients MAY give the
- user the opportunity to continue with the connection in any case) or
- terminate the connection with a bad certificate error. Automated
- clients MUST log the error to an appropriate audit log (if available)
- and SHOULD terminate the connection (with a bad certificate error).
- Automated clients MAY provide a configuration setting that disables
- this check, but MUST provide a setting which enables it.
-
- Note that in many cases the URI itself comes from an untrusted
- source. The above-described check provides no protection against
- attacks where this source is compromised. For example, if the URI was
- obtained by clicking on an HTML page which was itself obtained
- without using HTTP/TLS, a man in the middle could have replaced the
- URI. In order to prevent this form of attack, users should carefully
- examine the certificate presented by the server to determine if it
- meets their expectations.
-
-3.2. Client Identity
-
- Typically, the server has no external knowledge of what the client's
- identity ought to be and so checks (other than that the client has a
- certificate chain rooted in an appropriate CA) are not possible. If a
- server has such knowledge (typically from some source external to
- HTTP or TLS) it SHOULD check the identity as described above.
-
-
-
-
-Rescorla Informational [Page 5]
-\f
-RFC 2818 HTTP Over TLS May 2000
-
-
-References
-
- [RFC2459] Housley, R., Ford, W., Polk, W. and D. Solo, "Internet
- Public Key Infrastructure: Part I: X.509 Certificate and
- CRL Profile", RFC 2459, January 1999.
-
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter,
- L., Leach, P. and T. Berners-Lee, "Hypertext Transfer
- Protocol, HTTP/1.1", RFC 2616, June 1999.
-
- [RFC2119] Bradner, S., "Key Words for use in RFCs to indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol", RFC 2246,
- January 1999.
-
- [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within
- HTTP/1.1", RFC 2817, May 2000.
-
-Security Considerations
-
- This entire document is about security.
-
-Author's Address
-
- Eric Rescorla
- RTFM, Inc.
- 30 Newell Road, #16
- East Palo Alto, CA 94303
-
- Phone: (650) 328-8631
- EMail: ekr@rtfm.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Rescorla Informational [Page 6]
-\f
-RFC 2818 HTTP Over TLS May 2000
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2000). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Rescorla Informational [Page 7]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group J. Klensin, Editor
-Request for Comments: 2821 AT&T Laboratories
-Obsoletes: 821, 974, 1869 April 2001
-Updates: 1123
-Category: Standards Track
-
-
- Simple Mail Transfer Protocol
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2001). All Rights Reserved.
-
-Abstract
-
- This document is a self-contained specification of the basic protocol
- for the Internet electronic mail transport. It consolidates, updates
- and clarifies, but doesn't add new or change existing functionality
- of the following:
-
- - the original SMTP (Simple Mail Transfer Protocol) specification of
- RFC 821 [30],
-
- - domain name system requirements and implications for mail
- transport from RFC 1035 [22] and RFC 974 [27],
-
- - the clarifications and applicability statements in RFC 1123 [2],
- and
-
- - material drawn from the SMTP Extension mechanisms [19].
-
- It obsoletes RFC 821, RFC 974, and updates RFC 1123 (replaces the
- mail transport materials of RFC 1123). However, RFC 821 specifies
- some features that were not in significant use in the Internet by the
- mid-1990s and (in appendices) some additional transport models.
- Those sections are omitted here in the interest of clarity and
- brevity; readers needing them should refer to RFC 821.
-
-
-
-
-
-
-Klensin Standards Track [Page 1]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- It also includes some additional material from RFC 1123 that required
- amplification. This material has been identified in multiple ways,
- mostly by tracking flaming on various lists and newsgroups and
- problems of unusual readings or interpretations that have appeared as
- the SMTP extensions have been deployed. Where this specification
- moves beyond consolidation and actually differs from earlier
- documents, it supersedes them technically as well as textually.
-
- Although SMTP was designed as a mail transport and delivery protocol,
- this specification also contains information that is important to its
- use as a 'mail submission' protocol, as recommended for POP [3, 26]
- and IMAP [6]. Additional submission issues are discussed in RFC 2476
- [15].
-
- Section 2.3 provides definitions of terms specific to this document.
- Except when the historical terminology is necessary for clarity, this
- document uses the current 'client' and 'server' terminology to
- identify the sending and receiving SMTP processes, respectively.
-
- A companion document [32] discusses message headers, message bodies
- and formats and structures for them, and their relationship.
-
-Table of Contents
-
- 1. Introduction .................................................. 4
- 2. The SMTP Model ................................................ 5
- 2.1 Basic Structure .............................................. 5
- 2.2 The Extension Model .......................................... 7
- 2.2.1 Background ................................................. 7
- 2.2.2 Definition and Registration of Extensions .................. 8
- 2.3 Terminology .................................................. 9
- 2.3.1 Mail Objects ............................................... 10
- 2.3.2 Senders and Receivers ...................................... 10
- 2.3.3 Mail Agents and Message Stores ............................. 10
- 2.3.4 Host ....................................................... 11
- 2.3.5 Domain ..................................................... 11
- 2.3.6 Buffer and State Table ..................................... 11
- 2.3.7 Lines ...................................................... 12
- 2.3.8 Originator, Delivery, Relay, and Gateway Systems ........... 12
- 2.3.9 Message Content and Mail Data .............................. 13
- 2.3.10 Mailbox and Address ....................................... 13
- 2.3.11 Reply ..................................................... 13
- 2.4 General Syntax Principles and Transaction Model .............. 13
- 3. The SMTP Procedures: An Overview .............................. 15
- 3.1 Session Initiation ........................................... 15
- 3.2 Client Initiation ............................................ 16
- 3.3 Mail Transactions ............................................ 16
- 3.4 Forwarding for Address Correction or Updating ................ 19
-
-
-
-Klensin Standards Track [Page 2]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- 3.5 Commands for Debugging Addresses ............................. 20
- 3.5.1 Overview ................................................... 20
- 3.5.2 VRFY Normal Response ....................................... 22
- 3.5.3 Meaning of VRFY or EXPN Success Response ................... 22
- 3.5.4 Semantics and Applications of EXPN ......................... 23
- 3.6 Domains ...................................................... 23
- 3.7 Relaying ..................................................... 24
- 3.8 Mail Gatewaying .............................................. 25
- 3.8.1 Header Fields in Gatewaying ................................ 26
- 3.8.2 Received Lines in Gatewaying ............................... 26
- 3.8.3 Addresses in Gatewaying .................................... 26
- 3.8.4 Other Header Fields in Gatewaying .......................... 27
- 3.8.5 Envelopes in Gatewaying .................................... 27
- 3.9 Terminating Sessions and Connections ......................... 27
- 3.10 Mailing Lists and Aliases ................................... 28
- 3.10.1 Alias ..................................................... 28
- 3.10.2 List ...................................................... 28
- 4. The SMTP Specifications ....................................... 29
- 4.1 SMTP Commands ................................................ 29
- 4.1.1 Command Semantics and Syntax ............................... 29
- 4.1.1.1 Extended HELLO (EHLO) or HELLO (HELO) ................... 29
- 4.1.1.2 MAIL (MAIL) .............................................. 31
- 4.1.1.3 RECIPIENT (RCPT) ......................................... 31
- 4.1.1.4 DATA (DATA) .............................................. 33
- 4.1.1.5 RESET (RSET) ............................................. 34
- 4.1.1.6 VERIFY (VRFY) ............................................ 35
- 4.1.1.7 EXPAND (EXPN) ............................................ 35
- 4.1.1.8 HELP (HELP) .............................................. 35
- 4.1.1.9 NOOP (NOOP) .............................................. 35
- 4.1.1.10 QUIT (QUIT) ............................................. 36
- 4.1.2 Command Argument Syntax .................................... 36
- 4.1.3 Address Literals ........................................... 38
- 4.1.4 Order of Commands .......................................... 39
- 4.1.5 Private-use Commands ....................................... 40
- 4.2 SMTP Replies ................................................ 40
- 4.2.1 Reply Code Severities and Theory ........................... 42
- 4.2.2 Reply Codes by Function Groups ............................. 44
- 4.2.3 Reply Codes in Numeric Order .............................. 45
- 4.2.4 Reply Code 502 ............................................. 46
- 4.2.5 Reply Codes After DATA and the Subsequent <CRLF>.<CRLF> .... 46
- 4.3 Sequencing of Commands and Replies ........................... 47
- 4.3.1 Sequencing Overview ........................................ 47
- 4.3.2 Command-Reply Sequences .................................... 48
- 4.4 Trace Information ............................................ 49
- 4.5 Additional Implementation Issues ............................. 53
- 4.5.1 Minimum Implementation ..................................... 53
- 4.5.2 Transparency ............................................... 53
- 4.5.3 Sizes and Timeouts ......................................... 54
-
-
-
-Klensin Standards Track [Page 3]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- 4.5.3.1 Size limits and minimums ................................. 54
- 4.5.3.2 Timeouts ................................................. 56
- 4.5.4 Retry Strategies ........................................... 57
- 4.5.4.1 Sending Strategy ......................................... 58
- 4.5.4.2 Receiving Strategy ....................................... 59
- 4.5.5 Messages with a null reverse-path .......................... 59
- 5. Address Resolution and Mail Handling .......................... 60
- 6. Problem Detection and Handling ................................ 62
- 6.1 Reliable Delivery and Replies by Email ....................... 62
- 6.2 Loop Detection ............................................... 63
- 6.3 Compensating for Irregularities .............................. 63
- 7. Security Considerations ....................................... 64
- 7.1 Mail Security and Spoofing ................................... 64
- 7.2 "Blind" Copies ............................................... 65
- 7.3 VRFY, EXPN, and Security ..................................... 65
- 7.4 Information Disclosure in Announcements ...................... 66
- 7.5 Information Disclosure in Trace Fields ....................... 66
- 7.6 Information Disclosure in Message Forwarding ................. 67
- 7.7 Scope of Operation of SMTP Servers ........................... 67
- 8. IANA Considerations ........................................... 67
- 9. References .................................................... 68
- 10. Editor's Address ............................................. 70
- 11. Acknowledgments .............................................. 70
- Appendices ....................................................... 71
- A. TCP Transport Service ......................................... 71
- B. Generating SMTP Commands from RFC 822 Headers ................. 71
- C. Source Routes ................................................. 72
- D. Scenarios ..................................................... 73
- E. Other Gateway Issues .......................................... 76
- F. Deprecated Features of RFC 821 ................................ 76
- Full Copyright Statement ......................................... 79
-
-1. Introduction
-
- The objective of the Simple Mail Transfer Protocol (SMTP) is to
- transfer mail reliably and efficiently.
-
- SMTP is independent of the particular transmission subsystem and
- requires only a reliable ordered data stream channel. While this
- document specifically discusses transport over TCP, other transports
- are possible. Appendices to RFC 821 describe some of them.
-
- An important feature of SMTP is its capability to transport mail
- across networks, usually referred to as "SMTP mail relaying" (see
- section 3.8). A network consists of the mutually-TCP-accessible
- hosts on the public Internet, the mutually-TCP-accessible hosts on a
- firewall-isolated TCP/IP Intranet, or hosts in some other LAN or WAN
- environment utilizing a non-TCP transport-level protocol. Using
-
-
-
-Klensin Standards Track [Page 4]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- SMTP, a process can transfer mail to another process on the same
- network or to some other network via a relay or gateway process
- accessible to both networks.
-
- In this way, a mail message may pass through a number of intermediate
- relay or gateway hosts on its path from sender to ultimate recipient.
- The Mail eXchanger mechanisms of the domain name system [22, 27] (and
- section 5 of this document) are used to identify the appropriate
- next-hop destination for a message being transported.
-
-2. The SMTP Model
-
-2.1 Basic Structure
-
- The SMTP design can be pictured as:
-
- +----------+ +----------+
- +------+ | | | |
- | User |<-->| | SMTP | |
- +------+ | Client- |Commands/Replies| Server- |
- +------+ | SMTP |<-------------->| SMTP | +------+
- | File |<-->| | and Mail | |<-->| File |
- |System| | | | | |System|
- +------+ +----------+ +----------+ +------+
- SMTP client SMTP server
-
- When an SMTP client has a message to transmit, it establishes a two-
- way transmission channel to an SMTP server. The responsibility of an
- SMTP client is to transfer mail messages to one or more SMTP servers,
- or report its failure to do so.
-
- The means by which a mail message is presented to an SMTP client, and
- how that client determines the domain name(s) to which mail messages
- are to be transferred is a local matter, and is not addressed by this
- document. In some cases, the domain name(s) transferred to, or
- determined by, an SMTP client will identify the final destination(s)
- of the mail message. In other cases, common with SMTP clients
- associated with implementations of the POP [3, 26] or IMAP [6]
- protocols, or when the SMTP client is inside an isolated transport
- service environment, the domain name determined will identify an
- intermediate destination through which all mail messages are to be
- relayed. SMTP clients that transfer all traffic, regardless of the
- target domain names associated with the individual messages, or that
- do not maintain queues for retrying message transmissions that
- initially cannot be completed, may otherwise conform to this
- specification but are not considered fully-capable. Fully-capable
- SMTP implementations, including the relays used by these less capable
-
-
-
-
-Klensin Standards Track [Page 5]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- ones, and their destinations, are expected to support all of the
- queuing, retrying, and alternate address functions discussed in this
- specification.
-
- The means by which an SMTP client, once it has determined a target
- domain name, determines the identity of an SMTP server to which a
- copy of a message is to be transferred, and then performs that
- transfer, is covered by this document. To effect a mail transfer to
- an SMTP server, an SMTP client establishes a two-way transmission
- channel to that SMTP server. An SMTP client determines the address
- of an appropriate host running an SMTP server by resolving a
- destination domain name to either an intermediate Mail eXchanger host
- or a final target host.
-
- An SMTP server may be either the ultimate destination or an
- intermediate "relay" (that is, it may assume the role of an SMTP
- client after receiving the message) or "gateway" (that is, it may
- transport the message further using some protocol other than SMTP).
- SMTP commands are generated by the SMTP client and sent to the SMTP
- server. SMTP replies are sent from the SMTP server to the SMTP
- client in response to the commands.
-
- In other words, message transfer can occur in a single connection
- between the original SMTP-sender and the final SMTP-recipient, or can
- occur in a series of hops through intermediary systems. In either
- case, a formal handoff of responsibility for the message occurs: the
- protocol requires that a server accept responsibility for either
- delivering a message or properly reporting the failure to do so.
-
- Once the transmission channel is established and initial handshaking
- completed, the SMTP client normally initiates a mail transaction.
- Such a transaction consists of a series of commands to specify the
- originator and destination of the mail and transmission of the
- message content (including any headers or other structure) itself.
- When the same message is sent to multiple recipients, this protocol
- encourages the transmission of only one copy of the data for all
- recipients at the same destination (or intermediate relay) host.
-
- The server responds to each command with a reply; replies may
- indicate that the command was accepted, that additional commands are
- expected, or that a temporary or permanent error condition exists.
- Commands specifying the sender or recipients may include server-
- permitted SMTP service extension requests as discussed in section
- 2.2. The dialog is purposely lock-step, one-at-a-time, although this
- can be modified by mutually-agreed extension requests such as command
- pipelining [13].
-
-
-
-
-
-Klensin Standards Track [Page 6]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- Once a given mail message has been transmitted, the client may either
- request that the connection be shut down or may initiate other mail
- transactions. In addition, an SMTP client may use a connection to an
- SMTP server for ancillary services such as verification of email
- addresses or retrieval of mailing list subscriber addresses.
-
- As suggested above, this protocol provides mechanisms for the
- transmission of mail. This transmission normally occurs directly
- from the sending user's host to the receiving user's host when the
- two hosts are connected to the same transport service. When they are
- not connected to the same transport service, transmission occurs via
- one or more relay SMTP servers. An intermediate host that acts as
- either an SMTP relay or as a gateway into some other transmission
- environment is usually selected through the use of the domain name
- service (DNS) Mail eXchanger mechanism.
-
- Usually, intermediate hosts are determined via the DNS MX record, not
- by explicit "source" routing (see section 5 and appendices C and
- F.2).
-
-2.2 The Extension Model
-
-2.2.1 Background
-
- In an effort that started in 1990, approximately a decade after RFC
- 821 was completed, the protocol was modified with a "service
- extensions" model that permits the client and server to agree to
- utilize shared functionality beyond the original SMTP requirements.
- The SMTP extension mechanism defines a means whereby an extended SMTP
- client and server may recognize each other, and the server can inform
- the client as to the service extensions that it supports.
-
- Contemporary SMTP implementations MUST support the basic extension
- mechanisms. For instance, servers MUST support the EHLO command even
- if they do not implement any specific extensions and clients SHOULD
- preferentially utilize EHLO rather than HELO. (However, for
- compatibility with older conforming implementations, SMTP clients and
- servers MUST support the original HELO mechanisms as a fallback.)
- Unless the different characteristics of HELO must be identified for
- interoperability purposes, this document discusses only EHLO.
-
- SMTP is widely deployed and high-quality implementations have proven
- to be very robust. However, the Internet community now considers
- some services to be important that were not anticipated when the
- protocol was first designed. If support for those services is to be
- added, it must be done in a way that permits older implementations to
- continue working acceptably. The extension framework consists of:
-
-
-
-
-Klensin Standards Track [Page 7]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- - The SMTP command EHLO, superseding the earlier HELO,
-
- - a registry of SMTP service extensions,
-
- - additional parameters to the SMTP MAIL and RCPT commands, and
-
- - optional replacements for commands defined in this protocol, such
- as for DATA in non-ASCII transmissions [33].
-
- SMTP's strength comes primarily from its simplicity. Experience with
- many protocols has shown that protocols with few options tend towards
- ubiquity, whereas protocols with many options tend towards obscurity.
-
- Each and every extension, regardless of its benefits, must be
- carefully scrutinized with respect to its implementation, deployment,
- and interoperability costs. In many cases, the cost of extending the
- SMTP service will likely outweigh the benefit.
-
-2.2.2 Definition and Registration of Extensions
-
- The IANA maintains a registry of SMTP service extensions. A
- corresponding EHLO keyword value is associated with each extension.
- Each service extension registered with the IANA must be defined in a
- formal standards-track or IESG-approved experimental protocol
- document. The definition must include:
-
- - the textual name of the SMTP service extension;
-
- - the EHLO keyword value associated with the extension;
-
- - the syntax and possible values of parameters associated with the
- EHLO keyword value;
-
- - any additional SMTP verbs associated with the extension
- (additional verbs will usually be, but are not required to be, the
- same as the EHLO keyword value);
-
- - any new parameters the extension associates with the MAIL or RCPT
- verbs;
-
- - a description of how support for the extension affects the
- behavior of a server and client SMTP; and,
-
- - the increment by which the extension is increasing the maximum
- length of the commands MAIL and/or RCPT, over that specified in
- this standard.
-
-
-
-
-
-Klensin Standards Track [Page 8]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- In addition, any EHLO keyword value starting with an upper or lower
- case "X" refers to a local SMTP service extension used exclusively
- through bilateral agreement. Keywords beginning with "X" MUST NOT be
- used in a registered service extension. Conversely, keyword values
- presented in the EHLO response that do not begin with "X" MUST
- correspond to a standard, standards-track, or IESG-approved
- experimental SMTP service extension registered with IANA. A
- conforming server MUST NOT offer non-"X"-prefixed keyword values that
- are not described in a registered extension.
-
- Additional verbs and parameter names are bound by the same rules as
- EHLO keywords; specifically, verbs beginning with "X" are local
- extensions that may not be registered or standardized. Conversely,
- verbs not beginning with "X" must always be registered.
-
-2.3 Terminology
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described below.
-
- 1. MUST This word, or the terms "REQUIRED" or "SHALL", mean that
- the definition is an absolute requirement of the specification.
-
- 2. MUST NOT This phrase, or the phrase "SHALL NOT", mean that the
- definition is an absolute prohibition of the specification.
-
- 3. SHOULD This word, or the adjective "RECOMMENDED", mean that
- there may exist valid reasons in particular circumstances to
- ignore a particular item, but the full implications must be
- understood and carefully weighed before choosing a different
- course.
-
- 4. SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" mean
- that there may exist valid reasons in particular circumstances
- when the particular behavior is acceptable or even useful, but the
- full implications should be understood and the case carefully
- weighed before implementing any behavior described with this
- label.
-
- 5. MAY This word, or the adjective "OPTIONAL", mean that an item is
- truly optional. One vendor may choose to include the item because
- a particular marketplace requires it or because the vendor feels
- that it enhances the product while another vendor may omit the
- same item. An implementation which does not include a particular
- option MUST be prepared to interoperate with another
- implementation which does include the option, though perhaps with
- reduced functionality. In the same vein an implementation which
-
-
-
-Klensin Standards Track [Page 9]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- does include a particular option MUST be prepared to interoperate
- with another implementation which does not include the option
- (except, of course, for the feature the option provides.)
-
-2.3.1 Mail Objects
-
- SMTP transports a mail object. A mail object contains an envelope
- and content.
-
- The SMTP envelope is sent as a series of SMTP protocol units
- (described in section 3). It consists of an originator address (to
- which error reports should be directed); one or more recipient
- addresses; and optional protocol extension material. Historically,
- variations on the recipient address specification command (RCPT TO)
- could be used to specify alternate delivery modes, such as immediate
- display; those variations have now been deprecated (see appendix F,
- section F.6).
-
- The SMTP content is sent in the SMTP DATA protocol unit and has two
- parts: the headers and the body. If the content conforms to other
- contemporary standards, the headers form a collection of field/value
- pairs structured as in the message format specification [32]; the
- body, if structured, is defined according to MIME [12]. The content
- is textual in nature, expressed using the US-ASCII repertoire [1].
- Although SMTP extensions (such as "8BITMIME" [20]) may relax this
- restriction for the content body, the content headers are always
- encoded using the US-ASCII repertoire. A MIME extension [23] defines
- an algorithm for representing header values outside the US-ASCII
- repertoire, while still encoding them using the US-ASCII repertoire.
-
-2.3.2 Senders and Receivers
-
- In RFC 821, the two hosts participating in an SMTP transaction were
- described as the "SMTP-sender" and "SMTP-receiver". This document
- has been changed to reflect current industry terminology and hence
- refers to them as the "SMTP client" (or sometimes just "the client")
- and "SMTP server" (or just "the server"), respectively. Since a
- given host may act both as server and client in a relay situation,
- "receiver" and "sender" terminology is still used where needed for
- clarity.
-
-2.3.3 Mail Agents and Message Stores
-
- Additional mail system terminology became common after RFC 821 was
- published and, where convenient, is used in this specification. In
- particular, SMTP servers and clients provide a mail transport service
- and therefore act as "Mail Transfer Agents" (MTAs). "Mail User
- Agents" (MUAs or UAs) are normally thought of as the sources and
-
-
-
-Klensin Standards Track [Page 10]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- targets of mail. At the source, an MUA might collect mail to be
- transmitted from a user and hand it off to an MTA; the final
- ("delivery") MTA would be thought of as handing the mail off to an
- MUA (or at least transferring responsibility to it, e.g., by
- depositing the message in a "message store"). However, while these
- terms are used with at least the appearance of great precision in
- other environments, the implied boundaries between MUAs and MTAs
- often do not accurately match common, and conforming, practices with
- Internet mail. Hence, the reader should be cautious about inferring
- the strong relationships and responsibilities that might be implied
- if these terms were used elsewhere.
-
-2.3.4 Host
-
- For the purposes of this specification, a host is a computer system
- attached to the Internet (or, in some cases, to a private TCP/IP
- network) and supporting the SMTP protocol. Hosts are known by names
- (see "domain"); identifying them by numerical address is discouraged.
-
-2.3.5 Domain
-
- A domain (or domain name) consists of one or more dot-separated
- components. These components ("labels" in DNS terminology [22]) are
- restricted for SMTP purposes to consist of a sequence of letters,
- digits, and hyphens drawn from the ASCII character set [1]. Domain
- names are used as names of hosts and of other entities in the domain
- name hierarchy. For example, a domain may refer to an alias (label
- of a CNAME RR) or the label of Mail eXchanger records to be used to
- deliver mail instead of representing a host name. See [22] and
- section 5 of this specification.
-
- The domain name, as described in this document and in [22], is the
- entire, fully-qualified name (often referred to as an "FQDN"). A
- domain name that is not in FQDN form is no more than a local alias.
- Local aliases MUST NOT appear in any SMTP transaction.
-
-2.3.6 Buffer and State Table
-
- SMTP sessions are stateful, with both parties carefully maintaining a
- common view of the current state. In this document we model this
- state by a virtual "buffer" and a "state table" on the server which
- may be used by the client to, for example, "clear the buffer" or
- "reset the state table," causing the information in the buffer to be
- discarded and the state to be returned to some previous state.
-
-
-
-
-
-
-
-Klensin Standards Track [Page 11]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
-2.3.7 Lines
-
- SMTP commands and, unless altered by a service extension, message
- data, are transmitted in "lines". Lines consist of zero or more data
- characters terminated by the sequence ASCII character "CR" (hex value
- 0D) followed immediately by ASCII character "LF" (hex value 0A).
- This termination sequence is denoted as <CRLF> in this document.
- Conforming implementations MUST NOT recognize or generate any other
- character or character sequence as a line terminator. Limits MAY be
- imposed on line lengths by servers (see section 4.5.3).
-
- In addition, the appearance of "bare" "CR" or "LF" characters in text
- (i.e., either without the other) has a long history of causing
- problems in mail implementations and applications that use the mail
- system as a tool. SMTP client implementations MUST NOT transmit
- these characters except when they are intended as line terminators
- and then MUST, as indicated above, transmit them only as a <CRLF>
- sequence.
-
-2.3.8 Originator, Delivery, Relay, and Gateway Systems
-
- This specification makes a distinction among four types of SMTP
- systems, based on the role those systems play in transmitting
- electronic mail. An "originating" system (sometimes called an SMTP
- originator) introduces mail into the Internet or, more generally,
- into a transport service environment. A "delivery" SMTP system is
- one that receives mail from a transport service environment and
- passes it to a mail user agent or deposits it in a message store
- which a mail user agent is expected to subsequently access. A
- "relay" SMTP system (usually referred to just as a "relay") receives
- mail from an SMTP client and transmits it, without modification to
- the message data other than adding trace information, to another SMTP
- server for further relaying or for delivery.
-
- A "gateway" SMTP system (usually referred to just as a "gateway")
- receives mail from a client system in one transport environment and
- transmits it to a server system in another transport environment.
- Differences in protocols or message semantics between the transport
- environments on either side of a gateway may require that the gateway
- system perform transformations to the message that are not permitted
- to SMTP relay systems. For the purposes of this specification,
- firewalls that rewrite addresses should be considered as gateways,
- even if SMTP is used on both sides of them (see [11]).
-
-
-
-
-
-
-
-
-Klensin Standards Track [Page 12]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
-2.3.9 Message Content and Mail Data
-
- The terms "message content" and "mail data" are used interchangeably
- in this document to describe the material transmitted after the DATA
- command is accepted and before the end of data indication is
- transmitted. Message content includes message headers and the
- possibly-structured message body. The MIME specification [12]
- provides the standard mechanisms for structured message bodies.
-
-2.3.10 Mailbox and Address
-
- As used in this specification, an "address" is a character string
- that identifies a user to whom mail will be sent or a location into
- which mail will be deposited. The term "mailbox" refers to that
- depository. The two terms are typically used interchangeably unless
- the distinction between the location in which mail is placed (the
- mailbox) and a reference to it (the address) is important. An
- address normally consists of user and domain specifications. The
- standard mailbox naming convention is defined to be "local-
- part@domain": contemporary usage permits a much broader set of
- applications than simple "user names". Consequently, and due to a
- long history of problems when intermediate hosts have attempted to
- optimize transport by modifying them, the local-part MUST be
- interpreted and assigned semantics only by the host specified in the
- domain part of the address.
-
-2.3.11 Reply
-
- An SMTP reply is an acknowledgment (positive or negative) sent from
- receiver to sender via the transmission channel in response to a
- command. The general form of a reply is a numeric completion code
- (indicating failure or success) usually followed by a text string.
- The codes are for use by programs and the text is usually intended
- for human users. Recent work [34] has specified further structuring
- of the reply strings, including the use of supplemental and more
- specific completion codes.
-
-2.4 General Syntax Principles and Transaction Model
-
- SMTP commands and replies have a rigid syntax. All commands begin
- with a command verb. All Replies begin with a three digit numeric
- code. In some commands and replies, arguments MUST follow the verb
- or reply code. Some commands do not accept arguments (after the
- verb), and some reply codes are followed, sometimes optionally, by
- free form text. In both cases, where text appears, it is separated
- from the verb or reply code by a space character. Complete
- definitions of commands and replies appear in section 4.
-
-
-
-
-Klensin Standards Track [Page 13]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- Verbs and argument values (e.g., "TO:" or "to:" in the RCPT command
- and extension name keywords) are not case sensitive, with the sole
- exception in this specification of a mailbox local-part (SMTP
- Extensions may explicitly specify case-sensitive elements). That is,
- a command verb, an argument value other than a mailbox local-part,
- and free form text MAY be encoded in upper case, lower case, or any
- mixture of upper and lower case with no impact on its meaning. This
- is NOT true of a mailbox local-part. The local-part of a mailbox
- MUST BE treated as case sensitive. Therefore, SMTP implementations
- MUST take care to preserve the case of mailbox local-parts. Mailbox
- domains are not case sensitive. In particular, for some hosts the
- user "smith" is different from the user "Smith". However, exploiting
- the case sensitivity of mailbox local-parts impedes interoperability
- and is discouraged.
-
- A few SMTP servers, in violation of this specification (and RFC 821)
- require that command verbs be encoded by clients in upper case.
- Implementations MAY wish to employ this encoding to accommodate those
- servers.
-
- The argument field consists of a variable length character string
- ending with the end of the line, i.e., with the character sequence
- <CRLF>. The receiver will take no action until this sequence is
- received.
-
- The syntax for each command is shown with the discussion of that
- command. Common elements and parameters are shown in section 4.1.2.
-
- Commands and replies are composed of characters from the ASCII
- character set [1]. When the transport service provides an 8-bit byte
- (octet) transmission channel, each 7-bit character is transmitted
- right justified in an octet with the high order bit cleared to zero.
- More specifically, the unextended SMTP service provides seven bit
- transport only. An originating SMTP client which has not
- successfully negotiated an appropriate extension with a particular
- server MUST NOT transmit messages with information in the high-order
- bit of octets. If such messages are transmitted in violation of this
- rule, receiving SMTP servers MAY clear the high-order bit or reject
- the message as invalid. In general, a relay SMTP SHOULD assume that
- the message content it has received is valid and, assuming that the
- envelope permits doing so, relay it without inspecting that content.
- Of course, if the content is mislabeled and the data path cannot
- accept the actual content, this may result in ultimate delivery of a
- severely garbled message to the recipient. Delivery SMTP systems MAY
- reject ("bounce") such messages rather than deliver them. No sending
- SMTP system is permitted to send envelope commands in any character
-
-
-
-
-
-Klensin Standards Track [Page 14]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- set other than US-ASCII; receiving systems SHOULD reject such
- commands, normally using "500 syntax error - invalid character"
- replies.
-
- Eight-bit message content transmission MAY be requested of the server
- by a client using extended SMTP facilities, notably the "8BITMIME"
- extension [20]. 8BITMIME SHOULD be supported by SMTP servers.
- However, it MUST not be construed as authorization to transmit
- unrestricted eight bit material. 8BITMIME MUST NOT be requested by
- senders for material with the high bit on that is not in MIME format
- with an appropriate content-transfer encoding; servers MAY reject
- such messages.
-
- The metalinguistic notation used in this document corresponds to the
- "Augmented BNF" used in other Internet mail system documents. The
- reader who is not familiar with that syntax should consult the ABNF
- specification [8]. Metalanguage terms used in running text are
- surrounded by pointed brackets (e.g., <CRLF>) for clarity.
-
-3. The SMTP Procedures: An Overview
-
- This section contains descriptions of the procedures used in SMTP:
- session initiation, the mail transaction, forwarding mail, verifying
- mailbox names and expanding mailing lists, and the opening and
- closing exchanges. Comments on relaying, a note on mail domains, and
- a discussion of changing roles are included at the end of this
- section. Several complete scenarios are presented in appendix D.
-
-3.1 Session Initiation
-
- An SMTP session is initiated when a client opens a connection to a
- server and the server responds with an opening message.
-
- SMTP server implementations MAY include identification of their
- software and version information in the connection greeting reply
- after the 220 code, a practice that permits more efficient isolation
- and repair of any problems. Implementations MAY make provision for
- SMTP servers to disable the software and version announcement where
- it causes security concerns. While some systems also identify their
- contact point for mail problems, this is not a substitute for
- maintaining the required "postmaster" address (see section 4.5.1).
-
- The SMTP protocol allows a server to formally reject a transaction
- while still allowing the initial connection as follows: a 554
- response MAY be given in the initial connection opening message
- instead of the 220. A server taking this approach MUST still wait
- for the client to send a QUIT (see section 4.1.1.10) before closing
- the connection and SHOULD respond to any intervening commands with
-
-
-
-Klensin Standards Track [Page 15]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- "503 bad sequence of commands". Since an attempt to make an SMTP
- connection to such a system is probably in error, a server returning
- a 554 response on connection opening SHOULD provide enough
- information in the reply text to facilitate debugging of the sending
- system.
-
-3.2 Client Initiation
-
- Once the server has sent the welcoming message and the client has
- received it, the client normally sends the EHLO command to the
- server, indicating the client's identity. In addition to opening the
- session, use of EHLO indicates that the client is able to process
- service extensions and requests that the server provide a list of the
- extensions it supports. Older SMTP systems which are unable to
- support service extensions and contemporary clients which do not
- require service extensions in the mail session being initiated, MAY
- use HELO instead of EHLO. Servers MUST NOT return the extended
- EHLO-style response to a HELO command. For a particular connection
- attempt, if the server returns a "command not recognized" response to
- EHLO, the client SHOULD be able to fall back and send HELO.
-
- In the EHLO command the host sending the command identifies itself;
- the command may be interpreted as saying "Hello, I am <domain>" (and,
- in the case of EHLO, "and I support service extension requests").
-
-3.3 Mail Transactions
-
- There are three steps to SMTP mail transactions. The transaction
- starts with a MAIL command which gives the sender identification.
- (In general, the MAIL command may be sent only when no mail
- transaction is in progress; see section 4.1.4.) A series of one or
- more RCPT commands follows giving the receiver information. Then a
- DATA command initiates transfer of the mail data and is terminated by
- the "end of mail" data indicator, which also confirms the
- transaction.
-
- The first step in the procedure is the MAIL command.
-
- MAIL FROM:<reverse-path> [SP <mail-parameters> ] <CRLF>
-
- This command tells the SMTP-receiver that a new mail transaction is
- starting and to reset all its state tables and buffers, including any
- recipients or mail data. The <reverse-path> portion of the first or
- only argument contains the source mailbox (between "<" and ">"
- brackets), which can be used to report errors (see section 4.2 for a
- discussion of error reporting). If accepted, the SMTP server returns
- a 250 OK reply. If the mailbox specification is not acceptable for
- some reason, the server MUST return a reply indicating whether the
-
-
-
-Klensin Standards Track [Page 16]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- failure is permanent (i.e., will occur again if the client tries to
- send the same address again) or temporary (i.e., the address might be
- accepted if the client tries again later). Despite the apparent
- scope of this requirement, there are circumstances in which the
- acceptability of the reverse-path may not be determined until one or
- more forward-paths (in RCPT commands) can be examined. In those
- cases, the server MAY reasonably accept the reverse-path (with a 250
- reply) and then report problems after the forward-paths are received
- and examined. Normally, failures produce 550 or 553 replies.
-
- Historically, the <reverse-path> can contain more than just a
- mailbox, however, contemporary systems SHOULD NOT use source routing
- (see appendix C).
-
- The optional <mail-parameters> are associated with negotiated SMTP
- service extensions (see section 2.2).
-
- The second step in the procedure is the RCPT command.
-
- RCPT TO:<forward-path> [ SP <rcpt-parameters> ] <CRLF>
-
- The first or only argument to this command includes a forward-path
- (normally a mailbox and domain, always surrounded by "<" and ">"
- brackets) identifying one recipient. If accepted, the SMTP server
- returns a 250 OK reply and stores the forward-path. If the recipient
- is known not to be a deliverable address, the SMTP server returns a
- 550 reply, typically with a string such as "no such user - " and the
- mailbox name (other circumstances and reply codes are possible).
- This step of the procedure can be repeated any number of times.
-
- The <forward-path> can contain more than just a mailbox.
- Historically, the <forward-path> can be a source routing list of
- hosts and the destination mailbox, however, contemporary SMTP clients
- SHOULD NOT utilize source routes (see appendix C). Servers MUST be
- prepared to encounter a list of source routes in the forward path,
- but SHOULD ignore the routes or MAY decline to support the relaying
- they imply. Similarly, servers MAY decline to accept mail that is
- destined for other hosts or systems. These restrictions make a
- server useless as a relay for clients that do not support full SMTP
- functionality. Consequently, restricted-capability clients MUST NOT
- assume that any SMTP server on the Internet can be used as their mail
- processing (relaying) site. If a RCPT command appears without a
- previous MAIL command, the server MUST return a 503 "Bad sequence of
- commands" response. The optional <rcpt-parameters> are associated
- with negotiated SMTP service extensions (see section 2.2).
-
- The third step in the procedure is the DATA command (or some
- alternative specified in a service extension).
-
-
-
-Klensin Standards Track [Page 17]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- DATA <CRLF>
-
- If accepted, the SMTP server returns a 354 Intermediate reply and
- considers all succeeding lines up to but not including the end of
- mail data indicator to be the message text. When the end of text is
- successfully received and stored the SMTP-receiver sends a 250 OK
- reply.
-
- Since the mail data is sent on the transmission channel, the end of
- mail data must be indicated so that the command and reply dialog can
- be resumed. SMTP indicates the end of the mail data by sending a
- line containing only a "." (period or full stop). A transparency
- procedure is used to prevent this from interfering with the user's
- text (see section 4.5.2).
-
- The end of mail data indicator also confirms the mail transaction and
- tells the SMTP server to now process the stored recipients and mail
- data. If accepted, the SMTP server returns a 250 OK reply. The DATA
- command can fail at only two points in the protocol exchange:
-
- - If there was no MAIL, or no RCPT, command, or all such commands
- were rejected, the server MAY return a "command out of sequence"
- (503) or "no valid recipients" (554) reply in response to the DATA
- command. If one of those replies (or any other 5yz reply) is
- received, the client MUST NOT send the message data; more
- generally, message data MUST NOT be sent unless a 354 reply is
- received.
-
- - If the verb is initially accepted and the 354 reply issued, the
- DATA command should fail only if the mail transaction was
- incomplete (for example, no recipients), or if resources were
- unavailable (including, of course, the server unexpectedly
- becoming unavailable), or if the server determines that the
- message should be rejected for policy or other reasons.
-
- However, in practice, some servers do not perform recipient
- verification until after the message text is received. These servers
- SHOULD treat a failure for one or more recipients as a "subsequent
- failure" and return a mail message as discussed in section 6. Using
- a "550 mailbox not found" (or equivalent) reply code after the data
- are accepted makes it difficult or impossible for the client to
- determine which recipients failed.
-
- When RFC 822 format [7, 32] is being used, the mail data include the
- memo header items such as Date, Subject, To, Cc, From. Server SMTP
- systems SHOULD NOT reject messages based on perceived defects in the
- RFC 822 or MIME [12] message header or message body. In particular,
-
-
-
-
-Klensin Standards Track [Page 18]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- they MUST NOT reject messages in which the numbers of Resent-fields
- do not match or Resent-to appears without Resent-from and/or Resent-
- date.
-
- Mail transaction commands MUST be used in the order discussed above.
-
-3.4 Forwarding for Address Correction or Updating
-
- Forwarding support is most often required to consolidate and simplify
- addresses within, or relative to, some enterprise and less frequently
- to establish addresses to link a person's prior address with current
- one. Silent forwarding of messages (without server notification to
- the sender), for security or non-disclosure purposes, is common in
- the contemporary Internet.
-
- In both the enterprise and the "new address" cases, information
- hiding (and sometimes security) considerations argue against exposure
- of the "final" address through the SMTP protocol as a side-effect of
- the forwarding activity. This may be especially important when the
- final address may not even be reachable by the sender. Consequently,
- the "forwarding" mechanisms described in section 3.2 of RFC 821, and
- especially the 251 (corrected destination) and 551 reply codes from
- RCPT must be evaluated carefully by implementers and, when they are
- available, by those configuring systems.
-
- In particular:
-
- * Servers MAY forward messages when they are aware of an address
- change. When they do so, they MAY either provide address-updating
- information with a 251 code, or may forward "silently" and return
- a 250 code. But, if a 251 code is used, they MUST NOT assume that
- the client will actually update address information or even return
- that information to the user.
-
- Alternately,
-
- * Servers MAY reject or bounce messages when they are not
- deliverable when addressed. When they do so, they MAY either
- provide address-updating information with a 551 code, or may
- reject the message as undeliverable with a 550 code and no
- address-specific information. But, if a 551 code is used, they
- MUST NOT assume that the client will actually update address
- information or even return that information to the user.
-
- SMTP server implementations that support the 251 and/or 551 reply
- codes are strongly encouraged to provide configuration mechanisms so
- that sites which conclude that they would undesirably disclose
- information can disable or restrict their use.
-
-
-
-Klensin Standards Track [Page 19]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
-3.5 Commands for Debugging Addresses
-
-3.5.1 Overview
-
- SMTP provides commands to verify a user name or obtain the content of
- a mailing list. This is done with the VRFY and EXPN commands, which
- have character string arguments. Implementations SHOULD support VRFY
- and EXPN (however, see section 3.5.2 and 7.3).
-
- For the VRFY command, the string is a user name or a user name and
- domain (see below). If a normal (i.e., 250) response is returned,
- the response MAY include the full name of the user and MUST include
- the mailbox of the user. It MUST be in either of the following
- forms:
-
- User Name <local-part@domain>
- local-part@domain
-
- When a name that is the argument to VRFY could identify more than one
- mailbox, the server MAY either note the ambiguity or identify the
- alternatives. In other words, any of the following are legitimate
- response to VRFY:
-
- 553 User ambiguous
-
- or
-
- 553- Ambiguous; Possibilities are
- 553-Joe Smith <jsmith@foo.com>
- 553-Harry Smith <hsmith@foo.com>
- 553 Melvin Smith <dweep@foo.com>
-
- or
-
- 553-Ambiguous; Possibilities
- 553- <jsmith@foo.com>
- 553- <hsmith@foo.com>
- 553 <dweep@foo.com>
-
- Under normal circumstances, a client receiving a 553 reply would be
- expected to expose the result to the user. Use of exactly the forms
- given, and the "user ambiguous" or "ambiguous" keywords, possibly
- supplemented by extended reply codes such as those described in [34],
- will facilitate automated translation into other languages as needed.
- Of course, a client that was highly automated or that was operating
- in another language than English, might choose to try to translate
- the response, to return some other indication to the user than the
-
-
-
-
-Klensin Standards Track [Page 20]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- literal text of the reply, or to take some automated action such as
- consulting a directory service for additional information before
- reporting to the user.
-
- For the EXPN command, the string identifies a mailing list, and the
- successful (i.e., 250) multiline response MAY include the full name
- of the users and MUST give the mailboxes on the mailing list.
-
- In some hosts the distinction between a mailing list and an alias for
- a single mailbox is a bit fuzzy, since a common data structure may
- hold both types of entries, and it is possible to have mailing lists
- containing only one mailbox. If a request is made to apply VRFY to a
- mailing list, a positive response MAY be given if a message so
- addressed would be delivered to everyone on the list, otherwise an
- error SHOULD be reported (e.g., "550 That is a mailing list, not a
- user" or "252 Unable to verify members of mailing list"). If a
- request is made to expand a user name, the server MAY return a
- positive response consisting of a list containing one name, or an
- error MAY be reported (e.g., "550 That is a user name, not a mailing
- list").
-
- In the case of a successful multiline reply (normal for EXPN) exactly
- one mailbox is to be specified on each line of the reply. The case
- of an ambiguous request is discussed above.
-
- "User name" is a fuzzy term and has been used deliberately. An
- implementation of the VRFY or EXPN commands MUST include at least
- recognition of local mailboxes as "user names". However, since
- current Internet practice often results in a single host handling
- mail for multiple domains, hosts, especially hosts that provide this
- functionality, SHOULD accept the "local-part@domain" form as a "user
- name"; hosts MAY also choose to recognize other strings as "user
- names".
-
- The case of expanding a mailbox list requires a multiline reply, such
- as:
-
- C: EXPN Example-People
- S: 250-Jon Postel <Postel@isi.edu>
- S: 250-Fred Fonebone <Fonebone@physics.foo-u.edu>
- S: 250 Sam Q. Smith <SQSmith@specific.generic.com>
-
- or
-
- C: EXPN Executive-Washroom-List
- S: 550 Access Denied to You.
-
-
-
-
-
-Klensin Standards Track [Page 21]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- The character string arguments of the VRFY and EXPN commands cannot
- be further restricted due to the variety of implementations of the
- user name and mailbox list concepts. On some systems it may be
- appropriate for the argument of the EXPN command to be a file name
- for a file containing a mailing list, but again there are a variety
- of file naming conventions in the Internet. Similarly, historical
- variations in what is returned by these commands are such that the
- response SHOULD be interpreted very carefully, if at all, and SHOULD
- generally only be used for diagnostic purposes.
-
-3.5.2 VRFY Normal Response
-
- When normal (2yz or 551) responses are returned from a VRFY or EXPN
- request, the reply normally includes the mailbox name, i.e.,
- "<local-part@domain>", where "domain" is a fully qualified domain
- name, MUST appear in the syntax. In circumstances exceptional enough
- to justify violating the intent of this specification, free-form text
- MAY be returned. In order to facilitate parsing by both computers
- and people, addresses SHOULD appear in pointed brackets. When
- addresses, rather than free-form debugging information, are returned,
- EXPN and VRFY MUST return only valid domain addresses that are usable
- in SMTP RCPT commands. Consequently, if an address implies delivery
- to a program or other system, the mailbox name used to reach that
- target MUST be given. Paths (explicit source routes) MUST NOT be
- returned by VRFY or EXPN.
-
- Server implementations SHOULD support both VRFY and EXPN. For
- security reasons, implementations MAY provide local installations a
- way to disable either or both of these commands through configuration
- options or the equivalent. When these commands are supported, they
- are not required to work across relays when relaying is supported.
- Since they were both optional in RFC 821, they MUST be listed as
- service extensions in an EHLO response, if they are supported.
-
-3.5.3 Meaning of VRFY or EXPN Success Response
-
- A server MUST NOT return a 250 code in response to a VRFY or EXPN
- command unless it has actually verified the address. In particular,
- a server MUST NOT return 250 if all it has done is to verify that the
- syntax given is valid. In that case, 502 (Command not implemented)
- or 500 (Syntax error, command unrecognized) SHOULD be returned. As
- stated elsewhere, implementation (in the sense of actually validating
- addresses and returning information) of VRFY and EXPN are strongly
- recommended. Hence, implementations that return 500 or 502 for VRFY
- are not in full compliance with this specification.
-
-
-
-
-
-
-Klensin Standards Track [Page 22]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- There may be circumstances where an address appears to be valid but
- cannot reasonably be verified in real time, particularly when a
- server is acting as a mail exchanger for another server or domain.
- "Apparent validity" in this case would normally involve at least
- syntax checking and might involve verification that any domains
- specified were ones to which the host expected to be able to relay
- mail. In these situations, reply code 252 SHOULD be returned. These
- cases parallel the discussion of RCPT verification discussed in
- section 2.1. Similarly, the discussion in section 3.4 applies to the
- use of reply codes 251 and 551 with VRFY (and EXPN) to indicate
- addresses that are recognized but that would be forwarded or bounced
- were mail received for them. Implementations generally SHOULD be
- more aggressive about address verification in the case of VRFY than
- in the case of RCPT, even if it takes a little longer to do so.
-
-3.5.4 Semantics and Applications of EXPN
-
- EXPN is often very useful in debugging and understanding problems
- with mailing lists and multiple-target-address aliases. Some systems
- have attempted to use source expansion of mailing lists as a means of
- eliminating duplicates. The propagation of aliasing systems with
- mail on the Internet, for hosts (typically with MX and CNAME DNS
- records), for mailboxes (various types of local host aliases), and in
- various proxying arrangements, has made it nearly impossible for
- these strategies to work consistently, and mail systems SHOULD NOT
- attempt them.
-
-3.6 Domains
-
- Only resolvable, fully-qualified, domain names (FQDNs) are permitted
- when domain names are used in SMTP. In other words, names that can
- be resolved to MX RRs or A RRs (as discussed in section 5) are
- permitted, as are CNAME RRs whose targets can be resolved, in turn,
- to MX or A RRs. Local nicknames or unqualified names MUST NOT be
- used. There are two exceptions to the rule requiring FQDNs:
-
- - The domain name given in the EHLO command MUST BE either a primary
- host name (a domain name that resolves to an A RR) or, if the host
- has no name, an address literal as described in section 4.1.1.1.
-
- - The reserved mailbox name "postmaster" may be used in a RCPT
- command without domain qualification (see section 4.1.1.3) and
- MUST be accepted if so used.
-
-
-
-
-
-
-
-
-Klensin Standards Track [Page 23]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
-3.7 Relaying
-
- In general, the availability of Mail eXchanger records in the domain
- name system [22, 27] makes the use of explicit source routes in the
- Internet mail system unnecessary. Many historical problems with
- their interpretation have made their use undesirable. SMTP clients
- SHOULD NOT generate explicit source routes except under unusual
- circumstances. SMTP servers MAY decline to act as mail relays or to
- accept addresses that specify source routes. When route information
- is encountered, SMTP servers are also permitted to ignore the route
- information and simply send to the final destination specified as the
- last element in the route and SHOULD do so. There has been an
- invalid practice of using names that do not appear in the DNS as
- destination names, with the senders counting on the intermediate
- hosts specified in source routing to resolve any problems. If source
- routes are stripped, this practice will cause failures. This is one
- of several reasons why SMTP clients MUST NOT generate invalid source
- routes or depend on serial resolution of names.
-
- When source routes are not used, the process described in RFC 821 for
- constructing a reverse-path from the forward-path is not applicable
- and the reverse-path at the time of delivery will simply be the
- address that appeared in the MAIL command.
-
- A relay SMTP server is usually the target of a DNS MX record that
- designates it, rather than the final delivery system. The relay
- server may accept or reject the task of relaying the mail in the same
- way it accepts or rejects mail for a local user. If it accepts the
- task, it then becomes an SMTP client, establishes a transmission
- channel to the next SMTP server specified in the DNS (according to
- the rules in section 5), and sends it the mail. If it declines to
- relay mail to a particular address for policy reasons, a 550 response
- SHOULD be returned.
-
- Many mail-sending clients exist, especially in conjunction with
- facilities that receive mail via POP3 or IMAP, that have limited
- capability to support some of the requirements of this specification,
- such as the ability to queue messages for subsequent delivery
- attempts. For these clients, it is common practice to make private
- arrangements to send all messages to a single server for processing
- and subsequent distribution. SMTP, as specified here, is not ideally
- suited for this role, and work is underway on standardized mail
- submission protocols that might eventually supercede the current
- practices. In any event, because these arrangements are private and
- fall outside the scope of this specification, they are not described
- here.
-
-
-
-
-
-Klensin Standards Track [Page 24]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- It is important to note that MX records can point to SMTP servers
- which act as gateways into other environments, not just SMTP relays
- and final delivery systems; see sections 3.8 and 5.
-
- If an SMTP server has accepted the task of relaying the mail and
- later finds that the destination is incorrect or that the mail cannot
- be delivered for some other reason, then it MUST construct an
- "undeliverable mail" notification message and send it to the
- originator of the undeliverable mail (as indicated by the reverse-
- path). Formats specified for non-delivery reports by other standards
- (see, for example, [24, 25]) SHOULD be used if possible.
-
- This notification message must be from the SMTP server at the relay
- host or the host that first determines that delivery cannot be
- accomplished. Of course, SMTP servers MUST NOT send notification
- messages about problems transporting notification messages. One way
- to prevent loops in error reporting is to specify a null reverse-path
- in the MAIL command of a notification message. When such a message
- is transmitted the reverse-path MUST be set to null (see section
- 4.5.5 for additional discussion). A MAIL command with a null
- reverse-path appears as follows:
-
- MAIL FROM:<>
-
- As discussed in section 2.4.1, a relay SMTP has no need to inspect or
- act upon the headers or body of the message data and MUST NOT do so
- except to add its own "Received:" header (section 4.4) and,
- optionally, to attempt to detect looping in the mail system (see
- section 6.2).
-
-3.8 Mail Gatewaying
-
- While the relay function discussed above operates within the Internet
- SMTP transport service environment, MX records or various forms of
- explicit routing may require that an intermediate SMTP server perform
- a translation function between one transport service and another. As
- discussed in section 2.3.8, when such a system is at the boundary
- between two transport service environments, we refer to it as a
- "gateway" or "gateway SMTP".
-
- Gatewaying mail between different mail environments, such as
- different mail formats and protocols, is complex and does not easily
- yield to standardization. However, some general requirements may be
- given for a gateway between the Internet and another mail
- environment.
-
-
-
-
-
-
-Klensin Standards Track [Page 25]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
-3.8.1 Header Fields in Gatewaying
-
- Header fields MAY be rewritten when necessary as messages are
- gatewayed across mail environment boundaries. This may involve
- inspecting the message body or interpreting the local-part of the
- destination address in spite of the prohibitions in section 2.4.1.
-
- Other mail systems gatewayed to the Internet often use a subset of
- RFC 822 headers or provide similar functionality with a different
- syntax, but some of these mail systems do not have an equivalent to
- the SMTP envelope. Therefore, when a message leaves the Internet
- environment, it may be necessary to fold the SMTP envelope
- information into the message header. A possible solution would be to
- create new header fields to carry the envelope information (e.g.,
- "X-SMTP-MAIL:" and "X-SMTP-RCPT:"); however, this would require
- changes in mail programs in foreign environments and might risk
- disclosure of private information (see section 7.2).
-
-3.8.2 Received Lines in Gatewaying
-
- When forwarding a message into or out of the Internet environment, a
- gateway MUST prepend a Received: line, but it MUST NOT alter in any
- way a Received: line that is already in the header.
-
- "Received:" fields of messages originating from other environments
- may not conform exactly to this specification. However, the most
- important use of Received: lines is for debugging mail faults, and
- this debugging can be severely hampered by well-meaning gateways that
- try to "fix" a Received: line. As another consequence of trace
- fields arising in non-SMTP environments, receiving systems MUST NOT
- reject mail based on the format of a trace field and SHOULD be
- extremely robust in the light of unexpected information or formats in
- those fields.
-
- The gateway SHOULD indicate the environment and protocol in the "via"
- clauses of Received field(s) that it supplies.
-
-3.8.3 Addresses in Gatewaying
-
- From the Internet side, the gateway SHOULD accept all valid address
- formats in SMTP commands and in RFC 822 headers, and all valid RFC
- 822 messages. Addresses and headers generated by gateways MUST
- conform to applicable Internet standards (including this one and RFC
- 822). Gateways are, of course, subject to the same rules for
- handling source routes as those described for other SMTP systems in
- section 3.3.
-
-
-
-
-
-Klensin Standards Track [Page 26]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
-3.8.4 Other Header Fields in Gatewaying
-
- The gateway MUST ensure that all header fields of a message that it
- forwards into the Internet mail environment meet the requirements for
- Internet mail. In particular, all addresses in "From:", "To:",
- "Cc:", etc., fields MUST be transformed (if necessary) to satisfy RFC
- 822 syntax, MUST reference only fully-qualified domain names, and
- MUST be effective and useful for sending replies. The translation
- algorithm used to convert mail from the Internet protocols to another
- environment's protocol SHOULD ensure that error messages from the
- foreign mail environment are delivered to the return path from the
- SMTP envelope, not to the sender listed in the "From:" field (or
- other fields) of the RFC 822 message.
-
-3.8.5 Envelopes in Gatewaying
-
- Similarly, when forwarding a message from another environment into
- the Internet, the gateway SHOULD set the envelope return path in
- accordance with an error message return address, if supplied by the
- foreign environment. If the foreign environment has no equivalent
- concept, the gateway must select and use a best approximation, with
- the message originator's address as the default of last resort.
-
-3.9 Terminating Sessions and Connections
-
- An SMTP connection is terminated when the client sends a QUIT
- command. The server responds with a positive reply code, after which
- it closes the connection.
-
- An SMTP server MUST NOT intentionally close the connection except:
-
- - After receiving a QUIT command and responding with a 221 reply.
-
- - After detecting the need to shut down the SMTP service and
- returning a 421 response code. This response code can be issued
- after the server receives any command or, if necessary,
- asynchronously from command receipt (on the assumption that the
- client will receive it after the next command is issued).
-
- In particular, a server that closes connections in response to
- commands that are not understood is in violation of this
- specification. Servers are expected to be tolerant of unknown
- commands, issuing a 500 reply and awaiting further instructions from
- the client.
-
-
-
-
-
-
-
-Klensin Standards Track [Page 27]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- An SMTP server which is forcibly shut down via external means SHOULD
- attempt to send a line containing a 421 response code to the SMTP
- client before exiting. The SMTP client will normally read the 421
- response code after sending its next command.
-
- SMTP clients that experience a connection close, reset, or other
- communications failure due to circumstances not under their control
- (in violation of the intent of this specification but sometimes
- unavoidable) SHOULD, to maintain the robustness of the mail system,
- treat the mail transaction as if a 451 response had been received and
- act accordingly.
-
-3.10 Mailing Lists and Aliases
-
- An SMTP-capable host SHOULD support both the alias and the list
- models of address expansion for multiple delivery. When a message is
- delivered or forwarded to each address of an expanded list form, the
- return address in the envelope ("MAIL FROM:") MUST be changed to be
- the address of a person or other entity who administers the list.
- However, in this case, the message header [32] MUST be left
- unchanged; in particular, the "From" field of the message header is
- unaffected.
-
- An important mail facility is a mechanism for multi-destination
- delivery of a single message, by transforming (or "expanding" or
- "exploding") a pseudo-mailbox address into a list of destination
- mailbox addresses. When a message is sent to such a pseudo-mailbox
- (sometimes called an "exploder"), copies are forwarded or
- redistributed to each mailbox in the expanded list. Servers SHOULD
- simply utilize the addresses on the list; application of heuristics
- or other matching rules to eliminate some addresses, such as that of
- the originator, is strongly discouraged. We classify such a pseudo-
- mailbox as an "alias" or a "list", depending upon the expansion
- rules.
-
-3.10.1 Alias
-
- To expand an alias, the recipient mailer simply replaces the pseudo-
- mailbox address in the envelope with each of the expanded addresses
- in turn; the rest of the envelope and the message body are left
- unchanged. The message is then delivered or forwarded to each
- expanded address.
-
-3.10.2 List
-
- A mailing list may be said to operate by "redistribution" rather than
- by "forwarding". To expand a list, the recipient mailer replaces the
- pseudo-mailbox address in the envelope with all of the expanded
-
-
-
-Klensin Standards Track [Page 28]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- addresses. The return address in the envelope is changed so that all
- error messages generated by the final deliveries will be returned to
- a list administrator, not to the message originator, who generally
- has no control over the contents of the list and will typically find
- error messages annoying.
-
-4. The SMTP Specifications
-
-4.1 SMTP Commands
-
-4.1.1 Command Semantics and Syntax
-
- The SMTP commands define the mail transfer or the mail system
- function requested by the user. SMTP commands are character strings
- terminated by <CRLF>. The commands themselves are alphabetic
- characters terminated by <SP> if parameters follow and <CRLF>
- otherwise. (In the interest of improved interoperability, SMTP
- receivers are encouraged to tolerate trailing white space before the
- terminating <CRLF>.) The syntax of the local part of a mailbox must
- conform to receiver site conventions and the syntax specified in
- section 4.1.2. The SMTP commands are discussed below. The SMTP
- replies are discussed in section 4.2.
-
- A mail transaction involves several data objects which are
- communicated as arguments to different commands. The reverse-path is
- the argument of the MAIL command, the forward-path is the argument of
- the RCPT command, and the mail data is the argument of the DATA
- command. These arguments or data objects must be transmitted and
- held pending the confirmation communicated by the end of mail data
- indication which finalizes the transaction. The model for this is
- that distinct buffers are provided to hold the types of data objects,
- that is, there is a reverse-path buffer, a forward-path buffer, and a
- mail data buffer. Specific commands cause information to be appended
- to a specific buffer, or cause one or more buffers to be cleared.
-
- Several commands (RSET, DATA, QUIT) are specified as not permitting
- parameters. In the absence of specific extensions offered by the
- server and accepted by the client, clients MUST NOT send such
- parameters and servers SHOULD reject commands containing them as
- having invalid syntax.
-
-4.1.1.1 Extended HELLO (EHLO) or HELLO (HELO)
-
- These commands are used to identify the SMTP client to the SMTP
- server. The argument field contains the fully-qualified domain name
- of the SMTP client if one is available. In situations in which the
- SMTP client system does not have a meaningful domain name (e.g., when
- its address is dynamically allocated and no reverse mapping record is
-
-
-
-Klensin Standards Track [Page 29]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- available), the client SHOULD send an address literal (see section
- 4.1.3), optionally followed by information that will help to identify
- the client system. y The SMTP server identifies itself to the SMTP
- client in the connection greeting reply and in the response to this
- command.
-
- A client SMTP SHOULD start an SMTP session by issuing the EHLO
- command. If the SMTP server supports the SMTP service extensions it
- will give a successful response, a failure response, or an error
- response. If the SMTP server, in violation of this specification,
- does not support any SMTP service extensions it will generate an
- error response. Older client SMTP systems MAY, as discussed above,
- use HELO (as specified in RFC 821) instead of EHLO, and servers MUST
- support the HELO command and reply properly to it. In any event, a
- client MUST issue HELO or EHLO before starting a mail transaction.
-
- These commands, and a "250 OK" reply to one of them, confirm that
- both the SMTP client and the SMTP server are in the initial state,
- that is, there is no transaction in progress and all state tables and
- buffers are cleared.
-
- Syntax:
-
- ehlo = "EHLO" SP Domain CRLF
- helo = "HELO" SP Domain CRLF
-
- Normally, the response to EHLO will be a multiline reply. Each line
- of the response contains a keyword and, optionally, one or more
- parameters. Following the normal syntax for multiline replies, these
- keyworks follow the code (250) and a hyphen for all but the last
- line, and the code and a space for the last line. The syntax for a
- positive response, using the ABNF notation and terminal symbols of
- [8], is:
-
- ehlo-ok-rsp = ( "250" domain [ SP ehlo-greet ] CRLF )
- / ( "250-" domain [ SP ehlo-greet ] CRLF
- *( "250-" ehlo-line CRLF )
- "250" SP ehlo-line CRLF )
-
- ehlo-greet = 1*(%d0-9 / %d11-12 / %d14-127)
- ; string of any characters other than CR or LF
-
- ehlo-line = ehlo-keyword *( SP ehlo-param )
-
- ehlo-keyword = (ALPHA / DIGIT) *(ALPHA / DIGIT / "-")
- ; additional syntax of ehlo-params depends on
- ; ehlo-keyword
-
-
-
-
-Klensin Standards Track [Page 30]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- ehlo-param = 1*(%d33-127)
- ; any CHAR excluding <SP> and all
- ; control characters (US-ASCII 0-31 inclusive)
-
- Although EHLO keywords may be specified in upper, lower, or mixed
- case, they MUST always be recognized and processed in a case-
- insensitive manner. This is simply an extension of practices
- specified in RFC 821 and section 2.4.1.
-
-4.1.1.2 MAIL (MAIL)
-
- This command is used to initiate a mail transaction in which the mail
- data is delivered to an SMTP server which may, in turn, deliver it to
- one or more mailboxes or pass it on to another system (possibly using
- SMTP). The argument field contains a reverse-path and may contain
- optional parameters. In general, the MAIL command may be sent only
- when no mail transaction is in progress, see section 4.1.4.
-
- The reverse-path consists of the sender mailbox. Historically, that
- mailbox might optionally have been preceded by a list of hosts, but
- that behavior is now deprecated (see appendix C). In some types of
- reporting messages for which a reply is likely to cause a mail loop
- (for example, mail delivery and nondelivery notifications), the
- reverse-path may be null (see section 3.7).
-
- This command clears the reverse-path buffer, the forward-path buffer,
- and the mail data buffer; and inserts the reverse-path information
- from this command into the reverse-path buffer.
-
- If service extensions were negotiated, the MAIL command may also
- carry parameters associated with a particular service extension.
-
- Syntax:
-
- "MAIL FROM:" ("<>" / Reverse-Path)
- [SP Mail-parameters] CRLF
-
-4.1.1.3 RECIPIENT (RCPT)
-
- This command is used to identify an individual recipient of the mail
- data; multiple recipients are specified by multiple use of this
- command. The argument field contains a forward-path and may contain
- optional parameters.
-
- The forward-path normally consists of the required destination
- mailbox. Sending systems SHOULD not generate the optional list of
- hosts known as a source route. Receiving systems MUST recognize
-
-
-
-
-Klensin Standards Track [Page 31]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- source route syntax but SHOULD strip off the source route
- specification and utilize the domain name associated with the mailbox
- as if the source route had not been provided.
-
- Similarly, relay hosts SHOULD strip or ignore source routes, and
- names MUST NOT be copied into the reverse-path. When mail reaches
- its ultimate destination (the forward-path contains only a
- destination mailbox), the SMTP server inserts it into the destination
- mailbox in accordance with its host mail conventions.
-
- For example, mail received at relay host xyz.com with envelope
- commands
-
- MAIL FROM:<userx@y.foo.org>
- RCPT TO:<@hosta.int,@jkl.org:userc@d.bar.org>
-
- will normally be sent directly on to host d.bar.org with envelope
- commands
-
- MAIL FROM:<userx@y.foo.org>
- RCPT TO:<userc@d.bar.org>
-
- As provided in appendix C, xyz.com MAY also choose to relay the
- message to hosta.int, using the envelope commands
-
- MAIL FROM:<userx@y.foo.org>
- RCPT TO:<@hosta.int,@jkl.org:userc@d.bar.org>
-
- or to jkl.org, using the envelope commands
-
- MAIL FROM:<userx@y.foo.org>
- RCPT TO:<@jkl.org:userc@d.bar.org>
-
- Of course, since hosts are not required to relay mail at all, xyz.com
- may also reject the message entirely when the RCPT command is
- received, using a 550 code (since this is a "policy reason").
-
- If service extensions were negotiated, the RCPT command may also
- carry parameters associated with a particular service extension
- offered by the server. The client MUST NOT transmit parameters other
- than those associated with a service extension offered by the server
- in its EHLO response.
-
-Syntax:
- "RCPT TO:" ("<Postmaster@" domain ">" / "<Postmaster>" / Forward-Path)
- [SP Rcpt-parameters] CRLF
-
-
-
-
-
-Klensin Standards Track [Page 32]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
-4.1.1.4 DATA (DATA)
-
- The receiver normally sends a 354 response to DATA, and then treats
- the lines (strings ending in <CRLF> sequences, as described in
- section 2.3.7) following the command as mail data from the sender.
- This command causes the mail data to be appended to the mail data
- buffer. The mail data may contain any of the 128 ASCII character
- codes, although experience has indicated that use of control
- characters other than SP, HT, CR, and LF may cause problems and
- SHOULD be avoided when possible.
-
- The mail data is terminated by a line containing only a period, that
- is, the character sequence "<CRLF>.<CRLF>" (see section 4.5.2). This
- is the end of mail data indication. Note that the first <CRLF> of
- this terminating sequence is also the <CRLF> that ends the final line
- of the data (message text) or, if there was no data, ends the DATA
- command itself. An extra <CRLF> MUST NOT be added, as that would
- cause an empty line to be added to the message. The only exception
- to this rule would arise if the message body were passed to the
- originating SMTP-sender with a final "line" that did not end in
- <CRLF>; in that case, the originating SMTP system MUST either reject
- the message as invalid or add <CRLF> in order to have the receiving
- SMTP server recognize the "end of data" condition.
-
- The custom of accepting lines ending only in <LF>, as a concession to
- non-conforming behavior on the part of some UNIX systems, has proven
- to cause more interoperability problems than it solves, and SMTP
- server systems MUST NOT do this, even in the name of improved
- robustness. In particular, the sequence "<LF>.<LF>" (bare line
- feeds, without carriage returns) MUST NOT be treated as equivalent to
- <CRLF>.<CRLF> as the end of mail data indication.
-
- Receipt of the end of mail data indication requires the server to
- process the stored mail transaction information. This processing
- consumes the information in the reverse-path buffer, the forward-path
- buffer, and the mail data buffer, and on the completion of this
- command these buffers are cleared. If the processing is successful,
- the receiver MUST send an OK reply. If the processing fails the
- receiver MUST send a failure reply. The SMTP model does not allow
- for partial failures at this point: either the message is accepted by
- the server for delivery and a positive response is returned or it is
- not accepted and a failure reply is returned. In sending a positive
- completion reply to the end of data indication, the receiver takes
- full responsibility for the message (see section 6.1). Errors that
- are diagnosed subsequently MUST be reported in a mail message, as
- discussed in section 4.4.
-
-
-
-
-
-Klensin Standards Track [Page 33]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- When the SMTP server accepts a message either for relaying or for
- final delivery, it inserts a trace record (also referred to
- interchangeably as a "time stamp line" or "Received" line) at the top
- of the mail data. This trace record indicates the identity of the
- host that sent the message, the identity of the host that received
- the message (and is inserting this time stamp), and the date and time
- the message was received. Relayed messages will have multiple time
- stamp lines. Details for formation of these lines, including their
- syntax, is specified in section 4.4.
-
- Additional discussion about the operation of the DATA command appears
- in section 3.3.
-
- Syntax:
- "DATA" CRLF
-
-4.1.1.5 RESET (RSET)
-
- This command specifies that the current mail transaction will be
- aborted. Any stored sender, recipients, and mail data MUST be
- discarded, and all buffers and state tables cleared. The receiver
- MUST send a "250 OK" reply to a RSET command with no arguments. A
- reset command may be issued by the client at any time. It is
- effectively equivalent to a NOOP (i.e., if has no effect) if issued
- immediately after EHLO, before EHLO is issued in the session, after
- an end-of-data indicator has been sent and acknowledged, or
- immediately before a QUIT. An SMTP server MUST NOT close the
- connection as the result of receiving a RSET; that action is reserved
- for QUIT (see section 4.1.1.10).
-
- Since EHLO implies some additional processing and response by the
- server, RSET will normally be more efficient than reissuing that
- command, even though the formal semantics are the same.
-
- There are circumstances, contrary to the intent of this
- specification, in which an SMTP server may receive an indication that
- the underlying TCP connection has been closed or reset. To preserve
- the robustness of the mail system, SMTP servers SHOULD be prepared
- for this condition and SHOULD treat it as if a QUIT had been received
- before the connection disappeared.
-
- Syntax:
- "RSET" CRLF
-
-
-
-
-
-
-
-
-Klensin Standards Track [Page 34]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
-4.1.1.6 VERIFY (VRFY)
-
- This command asks the receiver to confirm that the argument
- identifies a user or mailbox. If it is a user name, information is
- returned as specified in section 3.5.
-
- This command has no effect on the reverse-path buffer, the forward-
- path buffer, or the mail data buffer.
-
- Syntax:
- "VRFY" SP String CRLF
-
-4.1.1.7 EXPAND (EXPN)
-
- This command asks the receiver to confirm that the argument
- identifies a mailing list, and if so, to return the membership of
- that list. If the command is successful, a reply is returned
- containing information as described in section 3.5. This reply will
- have multiple lines except in the trivial case of a one-member list.
-
- This command has no effect on the reverse-path buffer, the forward-
- path buffer, or the mail data buffer and may be issued at any time.
-
- Syntax:
- "EXPN" SP String CRLF
-
-4.1.1.8 HELP (HELP)
-
- This command causes the server to send helpful information to the
- client. The command MAY take an argument (e.g., any command name)
- and return more specific information as a response.
-
- This command has no effect on the reverse-path buffer, the forward-
- path buffer, or the mail data buffer and may be issued at any time.
-
- SMTP servers SHOULD support HELP without arguments and MAY support it
- with arguments.
-
- Syntax:
- "HELP" [ SP String ] CRLF
-
-4.1.1.9 NOOP (NOOP)
-
- This command does not affect any parameters or previously entered
- commands. It specifies no action other than that the receiver send
- an OK reply.
-
-
-
-
-
-Klensin Standards Track [Page 35]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- This command has no effect on the reverse-path buffer, the forward-
- path buffer, or the mail data buffer and may be issued at any time.
- If a parameter string is specified, servers SHOULD ignore it.
-
- Syntax:
- "NOOP" [ SP String ] CRLF
-
-4.1.1.10 QUIT (QUIT)
-
- This command specifies that the receiver MUST send an OK reply, and
- then close the transmission channel.
-
- The receiver MUST NOT intentionally close the transmission channel
- until it receives and replies to a QUIT command (even if there was an
- error). The sender MUST NOT intentionally close the transmission
- channel until it sends a QUIT command and SHOULD wait until it
- receives the reply (even if there was an error response to a previous
- command). If the connection is closed prematurely due to violations
- of the above or system or network failure, the server MUST cancel any
- pending transaction, but not undo any previously completed
- transaction, and generally MUST act as if the command or transaction
- in progress had received a temporary error (i.e., a 4yz response).
-
- The QUIT command may be issued at any time.
-
- Syntax:
- "QUIT" CRLF
-
-4.1.2 Command Argument Syntax
-
- The syntax of the argument fields of the above commands (using the
- syntax specified in [8] where applicable) is given below. Some of
- the productions given below are used only in conjunction with source
- routes as described in appendix C. Terminals not defined in this
- document, such as ALPHA, DIGIT, SP, CR, LF, CRLF, are as defined in
- the "core" syntax [8 (section 6)] or in the message format syntax
- [32].
-
- Reverse-path = Path
- Forward-path = Path
- Path = "<" [ A-d-l ":" ] Mailbox ">"
- A-d-l = At-domain *( "," A-d-l )
- ; Note that this form, the so-called "source route",
- ; MUST BE accepted, SHOULD NOT be generated, and SHOULD be
- ; ignored.
- At-domain = "@" domain
- Mail-parameters = esmtp-param *(SP esmtp-param)
- Rcpt-parameters = esmtp-param *(SP esmtp-param)
-
-
-
-Klensin Standards Track [Page 36]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- esmtp-param = esmtp-keyword ["=" esmtp-value]
- esmtp-keyword = (ALPHA / DIGIT) *(ALPHA / DIGIT / "-")
- esmtp-value = 1*(%d33-60 / %d62-127)
- ; any CHAR excluding "=", SP, and control characters
- Keyword = Ldh-str
- Argument = Atom
- Domain = (sub-domain 1*("." sub-domain)) / address-literal
- sub-domain = Let-dig [Ldh-str]
-
- address-literal = "[" IPv4-address-literal /
- IPv6-address-literal /
- General-address-literal "]"
- ; See section 4.1.3
-
- Mailbox = Local-part "@" Domain
-
- Local-part = Dot-string / Quoted-string
- ; MAY be case-sensitive
-
- Dot-string = Atom *("." Atom)
-
- Atom = 1*atext
-
- Quoted-string = DQUOTE *qcontent DQUOTE
-
- String = Atom / Quoted-string
-
- While the above definition for Local-part is relatively permissive,
- for maximum interoperability, a host that expects to receive mail
- SHOULD avoid defining mailboxes where the Local-part requires (or
- uses) the Quoted-string form or where the Local-part is case-
- sensitive. For any purposes that require generating or comparing
- Local-parts (e.g., to specific mailbox names), all quoted forms MUST
- be treated as equivalent and the sending system SHOULD transmit the
- form that uses the minimum quoting possible.
-
- Systems MUST NOT define mailboxes in such a way as to require the use
- in SMTP of non-ASCII characters (octets with the high order bit set
- to one) or ASCII "control characters" (decimal value 0-31 and 127).
- These characters MUST NOT be used in MAIL or RCPT commands or other
- commands that require mailbox names.
-
- Note that the backslash, "\", is a quote character, which is used to
- indicate that the next character is to be used literally (instead of
- its normal interpretation). For example, "Joe\,Smith" indicates a
- single nine character user field with the comma being the fourth
- character of the field.
-
-
-
-
-Klensin Standards Track [Page 37]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- To promote interoperability and consistent with long-standing
- guidance about conservative use of the DNS in naming and applications
- (e.g., see section 2.3.1 of the base DNS document, RFC1035 [22]),
- characters outside the set of alphas, digits, and hyphen MUST NOT
- appear in domain name labels for SMTP clients or servers. In
- particular, the underscore character is not permitted. SMTP servers
- that receive a command in which invalid character codes have been
- employed, and for which there are no other reasons for rejection,
- MUST reject that command with a 501 response.
-
-4.1.3 Address Literals
-
- Sometimes a host is not known to the domain name system and
- communication (and, in particular, communication to report and repair
- the error) is blocked. To bypass this barrier a special literal form
- of the address is allowed as an alternative to a domain name. For
- IPv4 addresses, this form uses four small decimal integers separated
- by dots and enclosed by brackets such as [123.255.37.2], which
- indicates an (IPv4) Internet Address in sequence-of-octets form. For
- IPv6 and other forms of addressing that might eventually be
- standardized, the form consists of a standardized "tag" that
- identifies the address syntax, a colon, and the address itself, in a
- format specified as part of the IPv6 standards [17].
-
- Specifically:
-
- IPv4-address-literal = Snum 3("." Snum)
- IPv6-address-literal = "IPv6:" IPv6-addr
- General-address-literal = Standardized-tag ":" 1*dcontent
- Standardized-tag = Ldh-str
- ; MUST be specified in a standards-track RFC
- ; and registered with IANA
-
- Snum = 1*3DIGIT ; representing a decimal integer
- ; value in the range 0 through 255
- Let-dig = ALPHA / DIGIT
- Ldh-str = *( ALPHA / DIGIT / "-" ) Let-dig
-
- IPv6-addr = IPv6-full / IPv6-comp / IPv6v4-full / IPv6v4-comp
- IPv6-hex = 1*4HEXDIG
- IPv6-full = IPv6-hex 7(":" IPv6-hex)
- IPv6-comp = [IPv6-hex *5(":" IPv6-hex)] "::" [IPv6-hex *5(":"
- IPv6-hex)]
- ; The "::" represents at least 2 16-bit groups of zeros
- ; No more than 6 groups in addition to the "::" may be
- ; present
- IPv6v4-full = IPv6-hex 5(":" IPv6-hex) ":" IPv4-address-literal
- IPv6v4-comp = [IPv6-hex *3(":" IPv6-hex)] "::"
-
-
-
-Klensin Standards Track [Page 38]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- [IPv6-hex *3(":" IPv6-hex) ":"] IPv4-address-literal
- ; The "::" represents at least 2 16-bit groups of zeros
- ; No more than 4 groups in addition to the "::" and
- ; IPv4-address-literal may be present
-
-4.1.4 Order of Commands
-
- There are restrictions on the order in which these commands may be
- used.
-
- A session that will contain mail transactions MUST first be
- initialized by the use of the EHLO command. An SMTP server SHOULD
- accept commands for non-mail transactions (e.g., VRFY or EXPN)
- without this initialization.
-
- An EHLO command MAY be issued by a client later in the session. If
- it is issued after the session begins, the SMTP server MUST clear all
- buffers and reset the state exactly as if a RSET command had been
- issued. In other words, the sequence of RSET followed immediately by
- EHLO is redundant, but not harmful other than in the performance cost
- of executing unnecessary commands.
-
- If the EHLO command is not acceptable to the SMTP server, 501, 500,
- or 502 failure replies MUST be returned as appropriate. The SMTP
- server MUST stay in the same state after transmitting these replies
- that it was in before the EHLO was received.
-
- The SMTP client MUST, if possible, ensure that the domain parameter
- to the EHLO command is a valid principal host name (not a CNAME or MX
- name) for its host. If this is not possible (e.g., when the client's
- address is dynamically assigned and the client does not have an
- obvious name), an address literal SHOULD be substituted for the
- domain name and supplemental information provided that will assist in
- identifying the client.
-
- An SMTP server MAY verify that the domain name parameter in the EHLO
- command actually corresponds to the IP address of the client.
- However, the server MUST NOT refuse to accept a message for this
- reason if the verification fails: the information about verification
- failure is for logging and tracing only.
-
- The NOOP, HELP, EXPN, VRFY, and RSET commands can be used at any time
- during a session, or without previously initializing a session. SMTP
- servers SHOULD process these normally (that is, not return a 503
- code) even if no EHLO command has yet been received; clients SHOULD
- open a session with EHLO before sending these commands.
-
-
-
-
-
-Klensin Standards Track [Page 39]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- If these rules are followed, the example in RFC 821 that shows "550
- access denied to you" in response to an EXPN command is incorrect
- unless an EHLO command precedes the EXPN or the denial of access is
- based on the client's IP address or other authentication or
- authorization-determining mechanisms.
-
- The MAIL command (or the obsolete SEND, SOML, or SAML commands)
- begins a mail transaction. Once started, a mail transaction consists
- of a transaction beginning command, one or more RCPT commands, and a
- DATA command, in that order. A mail transaction may be aborted by
- the RSET (or a new EHLO) command. There may be zero or more
- transactions in a session. MAIL (or SEND, SOML, or SAML) MUST NOT be
- sent if a mail transaction is already open, i.e., it should be sent
- only if no mail transaction had been started in the session, or it
- the previous one successfully concluded with a successful DATA
- command, or if the previous one was aborted with a RSET.
-
- If the transaction beginning command argument is not acceptable, a
- 501 failure reply MUST be returned and the SMTP server MUST stay in
- the same state. If the commands in a transaction are out of order to
- the degree that they cannot be processed by the server, a 503 failure
- reply MUST be returned and the SMTP server MUST stay in the same
- state.
-
- The last command in a session MUST be the QUIT command. The QUIT
- command cannot be used at any other time in a session, but SHOULD be
- used by the client SMTP to request connection closure, even when no
- session opening command was sent and accepted.
-
-4.1.5 Private-use Commands
-
- As specified in section 2.2.2, commands starting in "X" may be used
- by bilateral agreement between the client (sending) and server
- (receiving) SMTP agents. An SMTP server that does not recognize such
- a command is expected to reply with "500 Command not recognized". An
- extended SMTP server MAY list the feature names associated with these
- private commands in the response to the EHLO command.
-
- Commands sent or accepted by SMTP systems that do not start with "X"
- MUST conform to the requirements of section 2.2.2.
-
-4.2 SMTP Replies
-
- Replies to SMTP commands serve to ensure the synchronization of
- requests and actions in the process of mail transfer and to guarantee
- that the SMTP client always knows the state of the SMTP server.
- Every command MUST generate exactly one reply.
-
-
-
-
-Klensin Standards Track [Page 40]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- The details of the command-reply sequence are described in section
- 4.3.
-
- An SMTP reply consists of a three digit number (transmitted as three
- numeric characters) followed by some text unless specified otherwise
- in this document. The number is for use by automata to determine
- what state to enter next; the text is for the human user. The three
- digits contain enough encoded information that the SMTP client need
- not examine the text and may either discard it or pass it on to the
- user, as appropriate. Exceptions are as noted elsewhere in this
- document. In particular, the 220, 221, 251, 421, and 551 reply codes
- are associated with message text that must be parsed and interpreted
- by machines. In the general case, the text may be receiver dependent
- and context dependent, so there are likely to be varying texts for
- each reply code. A discussion of the theory of reply codes is given
- in section 4.2.1. Formally, a reply is defined to be the sequence: a
- three-digit code, <SP>, one line of text, and <CRLF>, or a multiline
- reply (as defined in section 4.2.1). Since, in violation of this
- specification, the text is sometimes not sent, clients which do not
- receive it SHOULD be prepared to process the code alone (with or
- without a trailing space character). Only the EHLO, EXPN, and HELP
- commands are expected to result in multiline replies in normal
- circumstances, however, multiline replies are allowed for any
- command.
-
- In ABNF, server responses are:
-
- Greeting = "220 " Domain [ SP text ] CRLF
- Reply-line = Reply-code [ SP text ] CRLF
-
- where "Greeting" appears only in the 220 response that announces that
- the server is opening its part of the connection.
-
- An SMTP server SHOULD send only the reply codes listed in this
- document. An SMTP server SHOULD use the text shown in the examples
- whenever appropriate.
-
- An SMTP client MUST determine its actions only by the reply code, not
- by the text (except for the "change of address" 251 and 551 and, if
- necessary, 220, 221, and 421 replies); in the general case, any text,
- including no text at all (although senders SHOULD NOT send bare
- codes), MUST be acceptable. The space (blank) following the reply
- code is considered part of the text. Whenever possible, a receiver-
- SMTP SHOULD test the first digit (severity indication) of the reply
- code.
-
-
-
-
-
-
-Klensin Standards Track [Page 41]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- The list of codes that appears below MUST NOT be construed as
- permanent. While the addition of new codes should be a rare and
- significant activity, with supplemental information in the textual
- part of the response being preferred, new codes may be added as the
- result of new Standards or Standards-track specifications.
- Consequently, a sender-SMTP MUST be prepared to handle codes not
- specified in this document and MUST do so by interpreting the first
- digit only.
-
-4.2.1 Reply Code Severities and Theory
-
- The three digits of the reply each have a special significance. The
- first digit denotes whether the response is good, bad or incomplete.
- An unsophisticated SMTP client, or one that receives an unexpected
- code, will be able to determine its next action (proceed as planned,
- redo, retrench, etc.) by examining this first digit. An SMTP client
- that wants to know approximately what kind of error occurred (e.g.,
- mail system error, command syntax error) may examine the second
- digit. The third digit and any supplemental information that may be
- present is reserved for the finest gradation of information.
-
- There are five values for the first digit of the reply code:
-
- 1yz Positive Preliminary reply
- The command has been accepted, but the requested action is being
- held in abeyance, pending confirmation of the information in this
- reply. The SMTP client should send another command specifying
- whether to continue or abort the action. Note: unextended SMTP
- does not have any commands that allow this type of reply, and so
- does not have continue or abort commands.
-
- 2yz Positive Completion reply
- The requested action has been successfully completed. A new
- request may be initiated.
-
- 3yz Positive Intermediate reply
- The command has been accepted, but the requested action is being
- held in abeyance, pending receipt of further information. The
- SMTP client should send another command specifying this
- information. This reply is used in command sequence groups (i.e.,
- in DATA).
-
- 4yz Transient Negative Completion reply
- The command was not accepted, and the requested action did not
- occur. However, the error condition is temporary and the action
- may be requested again. The sender should return to the beginning
- of the command sequence (if any). It is difficult to assign a
- meaning to "transient" when two different sites (receiver- and
-
-
-
-Klensin Standards Track [Page 42]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- sender-SMTP agents) must agree on the interpretation. Each reply
- in this category might have a different time value, but the SMTP
- client is encouraged to try again. A rule of thumb to determine
- whether a reply fits into the 4yz or the 5yz category (see below)
- is that replies are 4yz if they can be successful if repeated
- without any change in command form or in properties of the sender
- or receiver (that is, the command is repeated identically and the
- receiver does not put up a new implementation.)
-
- 5yz Permanent Negative Completion reply
- The command was not accepted and the requested action did not
- occur. The SMTP client is discouraged from repeating the exact
- request (in the same sequence). Even some "permanent" error
- conditions can be corrected, so the human user may want to direct
- the SMTP client to reinitiate the command sequence by direct
- action at some point in the future (e.g., after the spelling has
- been changed, or the user has altered the account status).
-
- The second digit encodes responses in specific categories:
-
- x0z Syntax: These replies refer to syntax errors, syntactically
- correct commands that do not fit any functional category, and
- unimplemented or superfluous commands.
-
- x1z Information: These are replies to requests for information,
- such as status or help.
-
- x2z Connections: These are replies referring to the transmission
- channel.
-
- x3z Unspecified.
-
- x4z Unspecified.
-
- x5z Mail system: These replies indicate the status of the receiver
- mail system vis-a-vis the requested transfer or other mail system
- action.
-
- The third digit gives a finer gradation of meaning in each category
- specified by the second digit. The list of replies illustrates this.
- Each reply text is recommended rather than mandatory, and may even
- change according to the command with which it is associated. On the
- other hand, the reply codes must strictly follow the specifications
- in this section. Receiver implementations should not invent new
- codes for slightly different situations from the ones described here,
- but rather adapt codes already defined.
-
-
-
-
-
-Klensin Standards Track [Page 43]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- For example, a command such as NOOP, whose successful execution does
- not offer the SMTP client any new information, will return a 250
- reply. The reply is 502 when the command requests an unimplemented
- non-site-specific action. A refinement of that is the 504 reply for
- a command that is implemented, but that requests an unimplemented
- parameter.
-
- The reply text may be longer than a single line; in these cases the
- complete text must be marked so the SMTP client knows when it can
- stop reading the reply. This requires a special format to indicate a
- multiple line reply.
-
- The format for multiline replies requires that every line, except the
- last, begin with the reply code, followed immediately by a hyphen,
- "-" (also known as minus), followed by text. The last line will
- begin with the reply code, followed immediately by <SP>, optionally
- some text, and <CRLF>. As noted above, servers SHOULD send the <SP>
- if subsequent text is not sent, but clients MUST be prepared for it
- to be omitted.
-
- For example:
-
- 123-First line
- 123-Second line
- 123-234 text beginning with numbers
- 123 The last line
-
- In many cases the SMTP client then simply needs to search for a line
- beginning with the reply code followed by <SP> or <CRLF> and ignore
- all preceding lines. In a few cases, there is important data for the
- client in the reply "text". The client will be able to identify
- these cases from the current context.
-
-4.2.2 Reply Codes by Function Groups
-
- 500 Syntax error, command unrecognized
- (This may include errors such as command line too long)
- 501 Syntax error in parameters or arguments
- 502 Command not implemented (see section 4.2.4)
- 503 Bad sequence of commands
- 504 Command parameter not implemented
-
- 211 System status, or system help reply
- 214 Help message
- (Information on how to use the receiver or the meaning of a
- particular non-standard command; this reply is useful only
- to the human user)
-
-
-
-
-Klensin Standards Track [Page 44]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- 220 <domain> Service ready
- 221 <domain> Service closing transmission channel
- 421 <domain> Service not available, closing transmission channel
- (This may be a reply to any command if the service knows it
- must shut down)
-
- 250 Requested mail action okay, completed
- 251 User not local; will forward to <forward-path>
- (See section 3.4)
- 252 Cannot VRFY user, but will accept message and attempt
- delivery
- (See section 3.5.3)
- 450 Requested mail action not taken: mailbox unavailable
- (e.g., mailbox busy)
- 550 Requested action not taken: mailbox unavailable
- (e.g., mailbox not found, no access, or command rejected
- for policy reasons)
- 451 Requested action aborted: error in processing
- 551 User not local; please try <forward-path>
- (See section 3.4)
- 452 Requested action not taken: insufficient system storage
- 552 Requested mail action aborted: exceeded storage allocation
- 553 Requested action not taken: mailbox name not allowed
- (e.g., mailbox syntax incorrect)
- 354 Start mail input; end with <CRLF>.<CRLF>
- 554 Transaction failed (Or, in the case of a connection-opening
- response, "No SMTP service here")
-
-4.2.3 Reply Codes in Numeric Order
-
- 211 System status, or system help reply
- 214 Help message
- (Information on how to use the receiver or the meaning of a
- particular non-standard command; this reply is useful only
- to the human user)
- 220 <domain> Service ready
- 221 <domain> Service closing transmission channel
- 250 Requested mail action okay, completed
- 251 User not local; will forward to <forward-path>
- (See section 3.4)
- 252 Cannot VRFY user, but will accept message and attempt
- delivery
- (See section 3.5.3)
-
- 354 Start mail input; end with <CRLF>.<CRLF>
-
-
-
-
-
-
-Klensin Standards Track [Page 45]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- 421 <domain> Service not available, closing transmission channel
- (This may be a reply to any command if the service knows it
- must shut down)
- 450 Requested mail action not taken: mailbox unavailable
- (e.g., mailbox busy)
- 451 Requested action aborted: local error in processing
- 452 Requested action not taken: insufficient system storage
- 500 Syntax error, command unrecognized
- (This may include errors such as command line too long)
- 501 Syntax error in parameters or arguments
- 502 Command not implemented (see section 4.2.4)
- 503 Bad sequence of commands
- 504 Command parameter not implemented
- 550 Requested action not taken: mailbox unavailable
- (e.g., mailbox not found, no access, or command rejected
- for policy reasons)
- 551 User not local; please try <forward-path>
- (See section 3.4)
- 552 Requested mail action aborted: exceeded storage allocation
- 553 Requested action not taken: mailbox name not allowed
- (e.g., mailbox syntax incorrect)
- 554 Transaction failed (Or, in the case of a connection-opening
- response, "No SMTP service here")
-
-4.2.4 Reply Code 502
-
- Questions have been raised as to when reply code 502 (Command not
- implemented) SHOULD be returned in preference to other codes. 502
- SHOULD be used when the command is actually recognized by the SMTP
- server, but not implemented. If the command is not recognized, code
- 500 SHOULD be returned. Extended SMTP systems MUST NOT list
- capabilities in response to EHLO for which they will return 502 (or
- 500) replies.
-
-4.2.5 Reply Codes After DATA and the Subsequent <CRLF>.<CRLF>
-
- When an SMTP server returns a positive completion status (2yz code)
- after the DATA command is completed with <CRLF>.<CRLF>, it accepts
- responsibility for:
-
- - delivering the message (if the recipient mailbox exists), or
-
- - if attempts to deliver the message fail due to transient
- conditions, retrying delivery some reasonable number of times at
- intervals as specified in section 4.5.4.
-
-
-
-
-
-
-Klensin Standards Track [Page 46]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- - if attempts to deliver the message fail due to permanent
- conditions, or if repeated attempts to deliver the message fail
- due to transient conditions, returning appropriate notification to
- the sender of the original message (using the address in the SMTP
- MAIL command).
-
- When an SMTP server returns a permanent error status (5yz) code after
- the DATA command is completed with <CRLF>.<CRLF>, it MUST NOT make
- any subsequent attempt to deliver that message. The SMTP client
- retains responsibility for delivery of that message and may either
- return it to the user or requeue it for a subsequent attempt (see
- section 4.5.4.1).
-
- The user who originated the message SHOULD be able to interpret the
- return of a transient failure status (by mail message or otherwise)
- as a non-delivery indication, just as a permanent failure would be
- interpreted. I.e., if the client SMTP successfully handles these
- conditions, the user will not receive such a reply.
-
- When an SMTP server returns a permanent error status (5yz) code after
- the DATA command is completely with <CRLF>.<CRLF>, it MUST NOT make
- any subsequent attempt to deliver the message. As with temporary
- error status codes, the SMTP client retains responsibility for the
- message, but SHOULD not again attempt delivery to the same server
- without user review and intervention of the message.
-
-4.3 Sequencing of Commands and Replies
-
-4.3.1 Sequencing Overview
-
- The communication between the sender and receiver is an alternating
- dialogue, controlled by the sender. As such, the sender issues a
- command and the receiver responds with a reply. Unless other
- arrangements are negotiated through service extensions, the sender
- MUST wait for this response before sending further commands.
-
- One important reply is the connection greeting. Normally, a receiver
- will send a 220 "Service ready" reply when the connection is
- completed. The sender SHOULD wait for this greeting message before
- sending any commands.
-
- Note: all the greeting-type replies have the official name (the
- fully-qualified primary domain name) of the server host as the first
- word following the reply code. Sometimes the host will have no
- meaningful name. See 4.1.3 for a discussion of alternatives in these
- situations.
-
-
-
-
-
-Klensin Standards Track [Page 47]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- For example,
-
- 220 ISIF.USC.EDU Service ready
- or
- 220 mail.foo.com SuperSMTP v 6.1.2 Service ready
- or
- 220 [10.0.0.1] Clueless host service ready
-
- The table below lists alternative success and failure replies for
- each command. These SHOULD be strictly adhered to: a receiver may
- substitute text in the replies, but the meaning and action implied by
- the code numbers and by the specific command reply sequence cannot be
- altered.
-
-4.3.2 Command-Reply Sequences
-
- Each command is listed with its usual possible replies. The prefixes
- used before the possible replies are "I" for intermediate, "S" for
- success, and "E" for error. Since some servers may generate other
- replies under special circumstances, and to allow for future
- extension, SMTP clients SHOULD, when possible, interpret only the
- first digit of the reply and MUST be prepared to deal with
- unrecognized reply codes by interpreting the first digit only.
- Unless extended using the mechanisms described in section 2.2, SMTP
- servers MUST NOT transmit reply codes to an SMTP client that are
- other than three digits or that do not start in a digit between 2 and
- 5 inclusive.
-
- These sequencing rules and, in principle, the codes themselves, can
- be extended or modified by SMTP extensions offered by the server and
- accepted (requested) by the client.
-
- In addition to the codes listed below, any SMTP command can return
- any of the following codes if the corresponding unusual circumstances
- are encountered:
-
- 500 For the "command line too long" case or if the command name was
- not recognized. Note that producing a "command not recognized"
- error in response to the required subset of these commands is a
- violation of this specification.
-
- 501 Syntax error in command or arguments. In order to provide for
- future extensions, commands that are specified in this document as
- not accepting arguments (DATA, RSET, QUIT) SHOULD return a 501
- message if arguments are supplied in the absence of EHLO-
- advertised extensions.
-
- 421 Service shutting down and closing transmission channel
-
-
-
-Klensin Standards Track [Page 48]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- Specific sequences are:
-
- CONNECTION ESTABLISHMENT
- S: 220
- E: 554
- EHLO or HELO
- S: 250
- E: 504, 550
- MAIL
- S: 250
- E: 552, 451, 452, 550, 553, 503
- RCPT
- S: 250, 251 (but see section 3.4 for discussion of 251 and 551)
- E: 550, 551, 552, 553, 450, 451, 452, 503, 550
- DATA
- I: 354 -> data -> S: 250
- E: 552, 554, 451, 452
- E: 451, 554, 503
- RSET
- S: 250
- VRFY
- S: 250, 251, 252
- E: 550, 551, 553, 502, 504
- EXPN
- S: 250, 252
- E: 550, 500, 502, 504
- HELP
- S: 211, 214
- E: 502, 504
- NOOP
- S: 250
- QUIT
- S: 221
-
-4.4 Trace Information
-
- When an SMTP server receives a message for delivery or further
- processing, it MUST insert trace ("time stamp" or "Received")
- information at the beginning of the message content, as discussed in
- section 4.1.1.4.
-
- This line MUST be structured as follows:
-
- - The FROM field, which MUST be supplied in an SMTP environment,
- SHOULD contain both (1) the name of the source host as presented
- in the EHLO command and (2) an address literal containing the IP
- address of the source, determined from the TCP connection.
-
-
-
-
-Klensin Standards Track [Page 49]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- - The ID field MAY contain an "@" as suggested in RFC 822, but this
- is not required.
-
- - The FOR field MAY contain a list of <path> entries when multiple
- RCPT commands have been given. This may raise some security
- issues and is usually not desirable; see section 7.2.
-
- An Internet mail program MUST NOT change a Received: line that was
- previously added to the message header. SMTP servers MUST prepend
- Received lines to messages; they MUST NOT change the order of
- existing lines or insert Received lines in any other location.
-
- As the Internet grows, comparability of Received fields is important
- for detecting problems, especially slow relays. SMTP servers that
- create Received fields SHOULD use explicit offsets in the dates
- (e.g., -0800), rather than time zone names of any type. Local time
- (with an offset) is preferred to UT when feasible. This formulation
- allows slightly more information about local circumstances to be
- specified. If UT is needed, the receiver need merely do some simple
- arithmetic to convert the values. Use of UT loses information about
- the time zone-location of the server. If it is desired to supply a
- time zone name, it SHOULD be included in a comment.
-
- When the delivery SMTP server makes the "final delivery" of a
- message, it inserts a return-path line at the beginning of the mail
- data. This use of return-path is required; mail systems MUST support
- it. The return-path line preserves the information in the <reverse-
- path> from the MAIL command. Here, final delivery means the message
- has left the SMTP environment. Normally, this would mean it had been
- delivered to the destination user or an associated mail drop, but in
- some cases it may be further processed and transmitted by another
- mail system.
-
- It is possible for the mailbox in the return path to be different
- from the actual sender's mailbox, for example, if error responses are
- to be delivered to a special error handling mailbox rather than to
- the message sender. When mailing lists are involved, this
- arrangement is common and useful as a means of directing errors to
- the list maintainer rather than the message originator.
-
- The text above implies that the final mail data will begin with a
- return path line, followed by one or more time stamp lines. These
- lines will be followed by the mail data headers and body [32].
-
- It is sometimes difficult for an SMTP server to determine whether or
- not it is making final delivery since forwarding or other operations
- may occur after the message is accepted for delivery. Consequently,
-
-
-
-
-Klensin Standards Track [Page 50]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- any further (forwarding, gateway, or relay) systems MAY remove the
- return path and rebuild the MAIL command as needed to ensure that
- exactly one such line appears in a delivered message.
-
- A message-originating SMTP system SHOULD NOT send a message that
- already contains a Return-path header. SMTP servers performing a
- relay function MUST NOT inspect the message data, and especially not
- to the extent needed to determine if Return-path headers are present.
- SMTP servers making final delivery MAY remove Return-path headers
- before adding their own.
-
- The primary purpose of the Return-path is to designate the address to
- which messages indicating non-delivery or other mail system failures
- are to be sent. For this to be unambiguous, exactly one return path
- SHOULD be present when the message is delivered. Systems using RFC
- 822 syntax with non-SMTP transports SHOULD designate an unambiguous
- address, associated with the transport envelope, to which error
- reports (e.g., non-delivery messages) should be sent.
-
- Historical note: Text in RFC 822 that appears to contradict the use
- of the Return-path header (or the envelope reverse path address from
- the MAIL command) as the destination for error messages is not
- applicable on the Internet. The reverse path address (as copied into
- the Return-path) MUST be used as the target of any mail containing
- delivery error messages.
-
- In particular:
-
- - a gateway from SMTP->elsewhere SHOULD insert a return-path header,
- unless it is known that the "elsewhere" transport also uses
- Internet domain addresses and maintains the envelope sender
- address separately.
-
- - a gateway from elsewhere->SMTP SHOULD delete any return-path
- header present in the message, and either copy that information to
- the SMTP envelope or combine it with information present in the
- envelope of the other transport system to construct the reverse
- path argument to the MAIL command in the SMTP envelope.
-
- The server must give special treatment to cases in which the
- processing following the end of mail data indication is only
- partially successful. This could happen if, after accepting several
- recipients and the mail data, the SMTP server finds that the mail
- data could be successfully delivered to some, but not all, of the
- recipients. In such cases, the response to the DATA command MUST be
- an OK reply. However, the SMTP server MUST compose and send an
- "undeliverable mail" notification message to the originator of the
- message.
-
-
-
-Klensin Standards Track [Page 51]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- A single notification listing all of the failed recipients or
- separate notification messages MUST be sent for each failed
- recipient. For economy of processing by the sender, the former is
- preferred when possible. All undeliverable mail notification
- messages are sent using the MAIL command (even if they result from
- processing the obsolete SEND, SOML, or SAML commands) and use a null
- return path as discussed in section 3.7.
-
- The time stamp line and the return path line are formally defined as
- follows:
-
-Return-path-line = "Return-Path:" FWS Reverse-path <CRLF>
-
-Time-stamp-line = "Received:" FWS Stamp <CRLF>
-
-Stamp = From-domain By-domain Opt-info ";" FWS date-time
-
- ; where "date-time" is as defined in [32]
- ; but the "obs-" forms, especially two-digit
- ; years, are prohibited in SMTP and MUST NOT be used.
-
-From-domain = "FROM" FWS Extended-Domain CFWS
-
-By-domain = "BY" FWS Extended-Domain CFWS
-
-Extended-Domain = Domain /
- ( Domain FWS "(" TCP-info ")" ) /
- ( Address-literal FWS "(" TCP-info ")" )
-
-TCP-info = Address-literal / ( Domain FWS Address-literal )
- ; Information derived by server from TCP connection
- ; not client EHLO.
-
-Opt-info = [Via] [With] [ID] [For]
-
-Via = "VIA" FWS Link CFWS
-
-With = "WITH" FWS Protocol CFWS
-
-ID = "ID" FWS String / msg-id CFWS
-
-For = "FOR" FWS 1*( Path / Mailbox ) CFWS
-
-Link = "TCP" / Addtl-Link
-Addtl-Link = Atom
- ; Additional standard names for links are registered with the
- ; Internet Assigned Numbers Authority (IANA). "Via" is
- ; primarily of value with non-Internet transports. SMTP
-
-
-
-Klensin Standards Track [Page 52]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- ; servers SHOULD NOT use unregistered names.
-Protocol = "ESMTP" / "SMTP" / Attdl-Protocol
-Attdl-Protocol = Atom
- ; Additional standard names for protocols are registered with the
- ; Internet Assigned Numbers Authority (IANA). SMTP servers
- ; SHOULD NOT use unregistered names.
-
-4.5 Additional Implementation Issues
-
-4.5.1 Minimum Implementation
-
- In order to make SMTP workable, the following minimum implementation
- is required for all receivers. The following commands MUST be
- supported to conform to this specification:
-
- EHLO
- HELO
- MAIL
- RCPT
- DATA
- RSET
- NOOP
- QUIT
- VRFY
-
- Any system that includes an SMTP server supporting mail relaying or
- delivery MUST support the reserved mailbox "postmaster" as a case-
- insensitive local name. This postmaster address is not strictly
- necessary if the server always returns 554 on connection opening (as
- described in section 3.1). The requirement to accept mail for
- postmaster implies that RCPT commands which specify a mailbox for
- postmaster at any of the domains for which the SMTP server provides
- mail service, as well as the special case of "RCPT TO:<Postmaster>"
- (with no domain specification), MUST be supported.
-
- SMTP systems are expected to make every reasonable effort to accept
- mail directed to Postmaster from any other system on the Internet.
- In extreme cases --such as to contain a denial of service attack or
- other breach of security-- an SMTP server may block mail directed to
- Postmaster. However, such arrangements SHOULD be narrowly tailored
- so as to avoid blocking messages which are not part of such attacks.
-
-4.5.2 Transparency
-
- Without some provision for data transparency, the character sequence
- "<CRLF>.<CRLF>" ends the mail text and cannot be sent by the user.
- In general, users are not aware of such "forbidden" sequences. To
-
-
-
-
-Klensin Standards Track [Page 53]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- allow all user composed text to be transmitted transparently, the
- following procedures are used:
-
- - Before sending a line of mail text, the SMTP client checks the
- first character of the line. If it is a period, one additional
- period is inserted at the beginning of the line.
-
- - When a line of mail text is received by the SMTP server, it checks
- the line. If the line is composed of a single period, it is
- treated as the end of mail indicator. If the first character is a
- period and there are other characters on the line, the first
- character is deleted.
-
- The mail data may contain any of the 128 ASCII characters. All
- characters are to be delivered to the recipient's mailbox, including
- spaces, vertical and horizontal tabs, and other control characters.
- If the transmission channel provides an 8-bit byte (octet) data
- stream, the 7-bit ASCII codes are transmitted right justified in the
- octets, with the high order bits cleared to zero. See 3.7 for
- special treatment of these conditions in SMTP systems serving a relay
- function.
-
- In some systems it may be necessary to transform the data as it is
- received and stored. This may be necessary for hosts that use a
- different character set than ASCII as their local character set, that
- store data in records rather than strings, or which use special
- character sequences as delimiters inside mailboxes. If such
- transformations are necessary, they MUST be reversible, especially if
- they are applied to mail being relayed.
-
-4.5.3 Sizes and Timeouts
-
-4.5.3.1 Size limits and minimums
-
- There are several objects that have required minimum/maximum sizes.
- Every implementation MUST be able to receive objects of at least
- these sizes. Objects larger than these sizes SHOULD be avoided when
- possible. However, some Internet mail constructs such as encoded
- X.400 addresses [16] will often require larger objects: clients MAY
- attempt to transmit these, but MUST be prepared for a server to
- reject them if they cannot be handled by it. To the maximum extent
- possible, implementation techniques which impose no limits on the
- length of these objects should be used.
-
- local-part
- The maximum total length of a user name or other local-part is 64
- characters.
-
-
-
-
-Klensin Standards Track [Page 54]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- domain
- The maximum total length of a domain name or number is 255
- characters.
-
- path
- The maximum total length of a reverse-path or forward-path is 256
- characters (including the punctuation and element separators).
-
- command line
- The maximum total length of a command line including the command
- word and the <CRLF> is 512 characters. SMTP extensions may be
- used to increase this limit.
-
- reply line
- The maximum total length of a reply line including the reply code
- and the <CRLF> is 512 characters. More information may be
- conveyed through multiple-line replies.
-
- text line
- The maximum total length of a text line including the <CRLF> is
- 1000 characters (not counting the leading dot duplicated for
- transparency). This number may be increased by the use of SMTP
- Service Extensions.
-
- message content
- The maximum total length of a message content (including any
- message headers as well as the message body) MUST BE at least 64K
- octets. Since the introduction of Internet standards for
- multimedia mail [12], message lengths on the Internet have grown
- dramatically, and message size restrictions should be avoided if
- at all possible. SMTP server systems that must impose
- restrictions SHOULD implement the "SIZE" service extension [18],
- and SMTP client systems that will send large messages SHOULD
- utilize it when possible.
-
- recipients buffer
- The minimum total number of recipients that must be buffered is
- 100 recipients. Rejection of messages (for excessive recipients)
- with fewer than 100 RCPT commands is a violation of this
- specification. The general principle that relaying SMTP servers
- MUST NOT, and delivery SMTP servers SHOULD NOT, perform validation
- tests on message headers suggests that rejecting a message based
- on the total number of recipients shown in header fields is to be
- discouraged. A server which imposes a limit on the number of
- recipients MUST behave in an orderly fashion, such as to reject
- additional addresses over its limit rather than silently
- discarding addresses previously accepted. A client that needs to
-
-
-
-
-Klensin Standards Track [Page 55]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- deliver a message containing over 100 RCPT commands SHOULD be
- prepared to transmit in 100-recipient "chunks" if the server
- declines to accept more than 100 recipients in a single message.
-
- Errors due to exceeding these limits may be reported by using the
- reply codes. Some examples of reply codes are:
-
- 500 Line too long.
- or
- 501 Path too long
- or
- 452 Too many recipients (see below)
- or
- 552 Too much mail data.
-
- RFC 821 [30] incorrectly listed the error where an SMTP server
- exhausts its implementation limit on the number of RCPT commands
- ("too many recipients") as having reply code 552. The correct reply
- code for this condition is 452. Clients SHOULD treat a 552 code in
- this case as a temporary, rather than permanent, failure so the logic
- below works.
-
- When a conforming SMTP server encounters this condition, it has at
- least 100 successful RCPT commands in its recipients buffer. If the
- server is able to accept the message, then at least these 100
- addresses will be removed from the SMTP client's queue. When the
- client attempts retransmission of those addresses which received 452
- responses, at least 100 of these will be able to fit in the SMTP
- server's recipients buffer. Each retransmission attempt which is
- able to deliver anything will be able to dispose of at least 100 of
- these recipients.
-
- If an SMTP server has an implementation limit on the number of RCPT
- commands and this limit is exhausted, it MUST use a response code of
- 452 (but the client SHOULD also be prepared for a 552, as noted
- above). If the server has a configured site-policy limitation on the
- number of RCPT commands, it MAY instead use a 5XX response code.
- This would be most appropriate if the policy limitation was intended
- to apply if the total recipient count for a particular message body
- were enforced even if that message body was sent in multiple mail
- transactions.
-
-4.5.3.2 Timeouts
-
- An SMTP client MUST provide a timeout mechanism. It MUST use per-
- command timeouts rather than somehow trying to time the entire mail
- transaction. Timeouts SHOULD be easily reconfigurable, preferably
- without recompiling the SMTP code. To implement this, a timer is set
-
-
-
-Klensin Standards Track [Page 56]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- for each SMTP command and for each buffer of the data transfer. The
- latter means that the overall timeout is inherently proportional to
- the size of the message.
-
- Based on extensive experience with busy mail-relay hosts, the minimum
- per-command timeout values SHOULD be as follows:
-
- Initial 220 Message: 5 minutes
- An SMTP client process needs to distinguish between a failed TCP
- connection and a delay in receiving the initial 220 greeting
- message. Many SMTP servers accept a TCP connection but delay
- delivery of the 220 message until their system load permits more
- mail to be processed.
-
- MAIL Command: 5 minutes
-
- RCPT Command: 5 minutes
- A longer timeout is required if processing of mailing lists and
- aliases is not deferred until after the message was accepted.
-
- DATA Initiation: 2 minutes
- This is while awaiting the "354 Start Input" reply to a DATA
- command.
-
- Data Block: 3 minutes
- This is while awaiting the completion of each TCP SEND call
- transmitting a chunk of data.
-
- DATA Termination: 10 minutes.
- This is while awaiting the "250 OK" reply. When the receiver gets
- the final period terminating the message data, it typically
- performs processing to deliver the message to a user mailbox. A
- spurious timeout at this point would be very wasteful and would
- typically result in delivery of multiple copies of the message,
- since it has been successfully sent and the server has accepted
- responsibility for delivery. See section 6.1 for additional
- discussion.
-
- An SMTP server SHOULD have a timeout of at least 5 minutes while it
- is awaiting the next command from the sender.
-
-4.5.4 Retry Strategies
-
- The common structure of a host SMTP implementation includes user
- mailboxes, one or more areas for queuing messages in transit, and one
- or more daemon processes for sending and receiving mail. The exact
- structure will vary depending on the needs of the users on the host
-
-
-
-
-Klensin Standards Track [Page 57]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- and the number and size of mailing lists supported by the host. We
- describe several optimizations that have proved helpful, particularly
- for mailers supporting high traffic levels.
-
- Any queuing strategy MUST include timeouts on all activities on a
- per-command basis. A queuing strategy MUST NOT send error messages
- in response to error messages under any circumstances.
-
-4.5.4.1 Sending Strategy
-
- The general model for an SMTP client is one or more processes that
- periodically attempt to transmit outgoing mail. In a typical system,
- the program that composes a message has some method for requesting
- immediate attention for a new piece of outgoing mail, while mail that
- cannot be transmitted immediately MUST be queued and periodically
- retried by the sender. A mail queue entry will include not only the
- message itself but also the envelope information.
-
- The sender MUST delay retrying a particular destination after one
- attempt has failed. In general, the retry interval SHOULD be at
- least 30 minutes; however, more sophisticated and variable strategies
- will be beneficial when the SMTP client can determine the reason for
- non-delivery.
-
- Retries continue until the message is transmitted or the sender gives
- up; the give-up time generally needs to be at least 4-5 days. The
- parameters to the retry algorithm MUST be configurable.
-
- A client SHOULD keep a list of hosts it cannot reach and
- corresponding connection timeouts, rather than just retrying queued
- mail items.
-
- Experience suggests that failures are typically transient (the target
- system or its connection has crashed), favoring a policy of two
- connection attempts in the first hour the message is in the queue,
- and then backing off to one every two or three hours.
-
- The SMTP client can shorten the queuing delay in cooperation with the
- SMTP server. For example, if mail is received from a particular
- address, it is likely that mail queued for that host can now be sent.
- Application of this principle may, in many cases, eliminate the
- requirement for an explicit "send queues now" function such as ETRN
- [9].
-
- The strategy may be further modified as a result of multiple
- addresses per host (see below) to optimize delivery time vs. resource
- usage.
-
-
-
-
-Klensin Standards Track [Page 58]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- An SMTP client may have a large queue of messages for each
- unavailable destination host. If all of these messages were retried
- in every retry cycle, there would be excessive Internet overhead and
- the sending system would be blocked for a long period. Note that an
- SMTP client can generally determine that a delivery attempt has
- failed only after a timeout of several minutes and even a one-minute
- timeout per connection will result in a very large delay if retries
- are repeated for dozens, or even hundreds, of queued messages to the
- same host.
-
- At the same time, SMTP clients SHOULD use great care in caching
- negative responses from servers. In an extreme case, if EHLO is
- issued multiple times during the same SMTP connection, different
- answers may be returned by the server. More significantly, 5yz
- responses to the MAIL command MUST NOT be cached.
-
- When a mail message is to be delivered to multiple recipients, and
- the SMTP server to which a copy of the message is to be sent is the
- same for multiple recipients, then only one copy of the message
- SHOULD be transmitted. That is, the SMTP client SHOULD use the
- command sequence: MAIL, RCPT, RCPT,... RCPT, DATA instead of the
- sequence: MAIL, RCPT, DATA, ..., MAIL, RCPT, DATA. However, if there
- are very many addresses, a limit on the number of RCPT commands per
- MAIL command MAY be imposed. Implementation of this efficiency
- feature is strongly encouraged.
-
- Similarly, to achieve timely delivery, the SMTP client MAY support
- multiple concurrent outgoing mail transactions. However, some limit
- may be appropriate to protect the host from devoting all its
- resources to mail.
-
-4.5.4.2 Receiving Strategy
-
- The SMTP server SHOULD attempt to keep a pending listen on the SMTP
- port at all times. This requires the support of multiple incoming
- TCP connections for SMTP. Some limit MAY be imposed but servers that
- cannot handle more than one SMTP transaction at a time are not in
- conformance with the intent of this specification.
-
- As discussed above, when the SMTP server receives mail from a
- particular host address, it could activate its own SMTP queuing
- mechanisms to retry any mail pending for that host address.
-
-4.5.5 Messages with a null reverse-path
-
- There are several types of notification messages which are required
- by existing and proposed standards to be sent with a null reverse
- path, namely non-delivery notifications as discussed in section 3.7,
-
-
-
-Klensin Standards Track [Page 59]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- other kinds of Delivery Status Notifications (DSNs) [24], and also
- Message Disposition Notifications (MDNs) [10]. All of these kinds of
- messages are notifications about a previous message, and they are
- sent to the reverse-path of the previous mail message. (If the
- delivery of such a notification message fails, that usually indicates
- a problem with the mail system of the host to which the notification
- message is addressed. For this reason, at some hosts the MTA is set
- up to forward such failed notification messages to someone who is
- able to fix problems with the mail system, e.g., via the postmaster
- alias.)
-
- All other types of messages (i.e., any message which is not required
- by a standards-track RFC to have a null reverse-path) SHOULD be sent
- with with a valid, non-null reverse-path.
-
- Implementors of automated email processors should be careful to make
- sure that the various kinds of messages with null reverse-path are
- handled correctly, in particular such systems SHOULD NOT reply to
- messages with null reverse-path.
-
-5. Address Resolution and Mail Handling
-
- Once an SMTP client lexically identifies a domain to which mail will
- be delivered for processing (as described in sections 3.6 and 3.7), a
- DNS lookup MUST be performed to resolve the domain name [22]. The
- names are expected to be fully-qualified domain names (FQDNs):
- mechanisms for inferring FQDNs from partial names or local aliases
- are outside of this specification and, due to a history of problems,
- are generally discouraged. The lookup first attempts to locate an MX
- record associated with the name. If a CNAME record is found instead,
- the resulting name is processed as if it were the initial name. If
- no MX records are found, but an A RR is found, the A RR is treated as
- if it was associated with an implicit MX RR, with a preference of 0,
- pointing to that host. If one or more MX RRs are found for a given
- name, SMTP systems MUST NOT utilize any A RRs associated with that
- name unless they are located using the MX RRs; the "implicit MX" rule
- above applies only if there are no MX records present. If MX records
- are present, but none of them are usable, this situation MUST be
- reported as an error.
-
- When the lookup succeeds, the mapping can result in a list of
- alternative delivery addresses rather than a single address, because
- of multiple MX records, multihoming, or both. To provide reliable
- mail transmission, the SMTP client MUST be able to try (and retry)
- each of the relevant addresses in this list in order, until a
- delivery attempt succeeds. However, there MAY also be a configurable
- limit on the number of alternate addresses that can be tried. In any
- case, the SMTP client SHOULD try at least two addresses.
-
-
-
-Klensin Standards Track [Page 60]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- Two types of information is used to rank the host addresses: multiple
- MX records, and multihomed hosts.
-
- Multiple MX records contain a preference indication that MUST be used
- in sorting (see below). Lower numbers are more preferred than higher
- ones. If there are multiple destinations with the same preference
- and there is no clear reason to favor one (e.g., by recognition of an
- easily-reached address), then the sender-SMTP MUST randomize them to
- spread the load across multiple mail exchangers for a specific
- organization.
-
- The destination host (perhaps taken from the preferred MX record) may
- be multihomed, in which case the domain name resolver will return a
- list of alternative IP addresses. It is the responsibility of the
- domain name resolver interface to have ordered this list by
- decreasing preference if necessary, and SMTP MUST try them in the
- order presented.
-
- Although the capability to try multiple alternative addresses is
- required, specific installations may want to limit or disable the use
- of alternative addresses. The question of whether a sender should
- attempt retries using the different addresses of a multihomed host
- has been controversial. The main argument for using the multiple
- addresses is that it maximizes the probability of timely delivery,
- and indeed sometimes the probability of any delivery; the counter-
- argument is that it may result in unnecessary resource use. Note
- that resource use is also strongly determined by the sending strategy
- discussed in section 4.5.4.1.
-
- If an SMTP server receives a message with a destination for which it
- is a designated Mail eXchanger, it MAY relay the message (potentially
- after having rewritten the MAIL FROM and/or RCPT TO addresses), make
- final delivery of the message, or hand it off using some mechanism
- outside the SMTP-provided transport environment. Of course, neither
- of the latter require that the list of MX records be examined
- further.
-
- If it determines that it should relay the message without rewriting
- the address, it MUST sort the MX records to determine candidates for
- delivery. The records are first ordered by preference, with the
- lowest-numbered records being most preferred. The relay host MUST
- then inspect the list for any of the names or addresses by which it
- might be known in mail transactions. If a matching record is found,
- all records at that preference level and higher-numbered ones MUST be
- discarded from consideration. If there are no records left at that
- point, it is an error condition, and the message MUST be returned as
- undeliverable. If records do remain, they SHOULD be tried, best
- preference first, as described above.
-
-
-
-Klensin Standards Track [Page 61]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
-6. Problem Detection and Handling
-
-6.1 Reliable Delivery and Replies by Email
-
- When the receiver-SMTP accepts a piece of mail (by sending a "250 OK"
- message in response to DATA), it is accepting responsibility for
- delivering or relaying the message. It must take this responsibility
- seriously. It MUST NOT lose the message for frivolous reasons, such
- as because the host later crashes or because of a predictable
- resource shortage.
-
- If there is a delivery failure after acceptance of a message, the
- receiver-SMTP MUST formulate and mail a notification message. This
- notification MUST be sent using a null ("<>") reverse path in the
- envelope. The recipient of this notification MUST be the address
- from the envelope return path (or the Return-Path: line). However,
- if this address is null ("<>"), the receiver-SMTP MUST NOT send a
- notification. Obviously, nothing in this section can or should
- prohibit local decisions (i.e., as part of the same system
- environment as the receiver-SMTP) to log or otherwise transmit
- information about null address events locally if that is desired. If
- the address is an explicit source route, it MUST be stripped down to
- its final hop.
-
- For example, suppose that an error notification must be sent for a
- message that arrived with:
-
- MAIL FROM:<@a,@b:user@d>
-
- The notification message MUST be sent using:
-
- RCPT TO:<user@d>
-
- Some delivery failures after the message is accepted by SMTP will be
- unavoidable. For example, it may be impossible for the receiving
- SMTP server to validate all the delivery addresses in RCPT command(s)
- due to a "soft" domain system error, because the target is a mailing
- list (see earlier discussion of RCPT), or because the server is
- acting as a relay and has no immediate access to the delivering
- system.
-
- To avoid receiving duplicate messages as the result of timeouts, a
- receiver-SMTP MUST seek to minimize the time required to respond to
- the final <CRLF>.<CRLF> end of data indicator. See RFC 1047 [28] for
- a discussion of this problem.
-
-
-
-
-
-
-Klensin Standards Track [Page 62]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
-6.2 Loop Detection
-
- Simple counting of the number of "Received:" headers in a message has
- proven to be an effective, although rarely optimal, method of
- detecting loops in mail systems. SMTP servers using this technique
- SHOULD use a large rejection threshold, normally at least 100
- Received entries. Whatever mechanisms are used, servers MUST contain
- provisions for detecting and stopping trivial loops.
-
-6.3 Compensating for Irregularities
-
- Unfortunately, variations, creative interpretations, and outright
- violations of Internet mail protocols do occur; some would suggest
- that they occur quite frequently. The debate as to whether a well-
- behaved SMTP receiver or relay should reject a malformed message,
- attempt to pass it on unchanged, or attempt to repair it to increase
- the odds of successful delivery (or subsequent reply) began almost
- with the dawn of structured network mail and shows no signs of
- abating. Advocates of rejection claim that attempted repairs are
- rarely completely adequate and that rejection of bad messages is the
- only way to get the offending software repaired. Advocates of
- "repair" or "deliver no matter what" argue that users prefer that
- mail go through it if at all possible and that there are significant
- market pressures in that direction. In practice, these market
- pressures may be more important to particular vendors than strict
- conformance to the standards, regardless of the preference of the
- actual developers.
-
- The problems associated with ill-formed messages were exacerbated by
- the introduction of the split-UA mail reading protocols [3, 26, 5,
- 21]. These protocols have encouraged the use of SMTP as a posting
- protocol, and SMTP servers as relay systems for these client hosts
- (which are often only intermittently connected to the Internet).
- Historically, many of those client machines lacked some of the
- mechanisms and information assumed by SMTP (and indeed, by the mail
- format protocol [7]). Some could not keep adequate track of time;
- others had no concept of time zones; still others could not identify
- their own names or addresses; and, of course, none could satisfy the
- assumptions that underlay RFC 822's conception of authenticated
- addresses.
-
- In response to these weak SMTP clients, many SMTP systems now
- complete messages that are delivered to them in incomplete or
- incorrect form. This strategy is generally considered appropriate
- when the server can identify or authenticate the client, and there
- are prior agreements between them. By contrast, there is at best
- great concern about fixes applied by a relay or delivery SMTP server
- that has little or no knowledge of the user or client machine.
-
-
-
-Klensin Standards Track [Page 63]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- The following changes to a message being processed MAY be applied
- when necessary by an originating SMTP server, or one used as the
- target of SMTP as an initial posting protocol:
-
- - Addition of a message-id field when none appears
-
- - Addition of a date, time or time zone when none appears
-
- - Correction of addresses to proper FQDN format
-
- The less information the server has about the client, the less likely
- these changes are to be correct and the more caution and conservatism
- should be applied when considering whether or not to perform fixes
- and how. These changes MUST NOT be applied by an SMTP server that
- provides an intermediate relay function.
-
- In all cases, properly-operating clients supplying correct
- information are preferred to corrections by the SMTP server. In all
- cases, documentation of actions performed by the servers (in trace
- fields and/or header comments) is strongly encouraged.
-
-7. Security Considerations
-
-7.1 Mail Security and Spoofing
-
- SMTP mail is inherently insecure in that it is feasible for even
- fairly casual users to negotiate directly with receiving and relaying
- SMTP servers and create messages that will trick a naive recipient
- into believing that they came from somewhere else. Constructing such
- a message so that the "spoofed" behavior cannot be detected by an
- expert is somewhat more difficult, but not sufficiently so as to be a
- deterrent to someone who is determined and knowledgeable.
- Consequently, as knowledge of Internet mail increases, so does the
- knowledge that SMTP mail inherently cannot be authenticated, or
- integrity checks provided, at the transport level. Real mail
- security lies only in end-to-end methods involving the message
- bodies, such as those which use digital signatures (see [14] and,
- e.g., PGP [4] or S/MIME [31]).
-
- Various protocol extensions and configuration options that provide
- authentication at the transport level (e.g., from an SMTP client to
- an SMTP server) improve somewhat on the traditional situation
- described above. However, unless they are accompanied by careful
- handoffs of responsibility in a carefully-designed trust environment,
- they remain inherently weaker than end-to-end mechanisms which use
- digitally signed messages rather than depending on the integrity of
- the transport system.
-
-
-
-
-Klensin Standards Track [Page 64]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- Efforts to make it more difficult for users to set envelope return
- path and header "From" fields to point to valid addresses other than
- their own are largely misguided: they frustrate legitimate
- applications in which mail is sent by one user on behalf of another
- or in which error (or normal) replies should be directed to a special
- address. (Systems that provide convenient ways for users to alter
- these fields on a per-message basis should attempt to establish a
- primary and permanent mailbox address for the user so that Sender
- fields within the message data can be generated sensibly.)
-
- This specification does not further address the authentication issues
- associated with SMTP other than to advocate that useful functionality
- not be disabled in the hope of providing some small margin of
- protection against an ignorant user who is trying to fake mail.
-
-7.2 "Blind" Copies
-
- Addresses that do not appear in the message headers may appear in the
- RCPT commands to an SMTP server for a number of reasons. The two
- most common involve the use of a mailing address as a "list exploder"
- (a single address that resolves into multiple addresses) and the
- appearance of "blind copies". Especially when more than one RCPT
- command is present, and in order to avoid defeating some of the
- purpose of these mechanisms, SMTP clients and servers SHOULD NOT copy
- the full set of RCPT command arguments into the headers, either as
- part of trace headers or as informational or private-extension
- headers. Since this rule is often violated in practice, and cannot
- be enforced, sending SMTP systems that are aware of "bcc" use MAY
- find it helpful to send each blind copy as a separate message
- transaction containing only a single RCPT command.
-
- There is no inherent relationship between either "reverse" (from
- MAIL, SAML, etc., commands) or "forward" (RCPT) addresses in the SMTP
- transaction ("envelope") and the addresses in the headers. Receiving
- systems SHOULD NOT attempt to deduce such relationships and use them
- to alter the headers of the message for delivery. The popular
- "Apparently-to" header is a violation of this principle as well as a
- common source of unintended information disclosure and SHOULD NOT be
- used.
-
-7.3 VRFY, EXPN, and Security
-
- As discussed in section 3.5, individual sites may want to disable
- either or both of VRFY or EXPN for security reasons. As a corollary
- to the above, implementations that permit this MUST NOT appear to
- have verified addresses that are not, in fact, verified. If a site
-
-
-
-
-
-Klensin Standards Track [Page 65]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- disables these commands for security reasons, the SMTP server MUST
- return a 252 response, rather than a code that could be confused with
- successful or unsuccessful verification.
-
- Returning a 250 reply code with the address listed in the VRFY
- command after having checked it only for syntax violates this rule.
- Of course, an implementation that "supports" VRFY by always returning
- 550 whether or not the address is valid is equally not in
- conformance.
-
- Within the last few years, the contents of mailing lists have become
- popular as an address information source for so-called "spammers."
- The use of EXPN to "harvest" addresses has increased as list
- administrators have installed protections against inappropriate uses
- of the lists themselves. Implementations SHOULD still provide
- support for EXPN, but sites SHOULD carefully evaluate the tradeoffs.
- As authentication mechanisms are introduced into SMTP, some sites may
- choose to make EXPN available only to authenticated requestors.
-
-7.4 Information Disclosure in Announcements
-
- There has been an ongoing debate about the tradeoffs between the
- debugging advantages of announcing server type and version (and,
- sometimes, even server domain name) in the greeting response or in
- response to the HELP command and the disadvantages of exposing
- information that might be useful in a potential hostile attack. The
- utility of the debugging information is beyond doubt. Those who
- argue for making it available point out that it is far better to
- actually secure an SMTP server rather than hope that trying to
- conceal known vulnerabilities by hiding the server's precise identity
- will provide more protection. Sites are encouraged to evaluate the
- tradeoff with that issue in mind; implementations are strongly
- encouraged to minimally provide for making type and version
- information available in some way to other network hosts.
-
-7.5 Information Disclosure in Trace Fields
-
- In some circumstances, such as when mail originates from within a LAN
- whose hosts are not directly on the public Internet, trace
- ("Received") fields produced in conformance with this specification
- may disclose host names and similar information that would not
- normally be available. This ordinarily does not pose a problem, but
- sites with special concerns about name disclosure should be aware of
- it. Also, the optional FOR clause should be supplied with caution or
- not at all when multiple recipients are involved lest it
- inadvertently disclose the identities of "blind copy" recipients to
- others.
-
-
-
-
-Klensin Standards Track [Page 66]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
-7.6 Information Disclosure in Message Forwarding
-
- As discussed in section 3.4, use of the 251 or 551 reply codes to
- identify the replacement address associated with a mailbox may
- inadvertently disclose sensitive information. Sites that are
- concerned about those issues should ensure that they select and
- configure servers appropriately.
-
-7.7 Scope of Operation of SMTP Servers
-
- It is a well-established principle that an SMTP server may refuse to
- accept mail for any operational or technical reason that makes sense
- to the site providing the server. However, cooperation among sites
- and installations makes the Internet possible. If sites take
- excessive advantage of the right to reject traffic, the ubiquity of
- email availability (one of the strengths of the Internet) will be
- threatened; considerable care should be taken and balance maintained
- if a site decides to be selective about the traffic it will accept
- and process.
-
- In recent years, use of the relay function through arbitrary sites
- has been used as part of hostile efforts to hide the actual origins
- of mail. Some sites have decided to limit the use of the relay
- function to known or identifiable sources, and implementations SHOULD
- provide the capability to perform this type of filtering. When mail
- is rejected for these or other policy reasons, a 550 code SHOULD be
- used in response to EHLO, MAIL, or RCPT as appropriate.
-
-8. IANA Considerations
-
- IANA will maintain three registries in support of this specification.
- The first consists of SMTP service extensions with the associated
- keywords, and, as needed, parameters and verbs. As specified in
- section 2.2.2, no entry may be made in this registry that starts in
- an "X". Entries may be made only for service extensions (and
- associated keywords, parameters, or verbs) that are defined in
- standards-track or experimental RFCs specifically approved by the
- IESG for this purpose.
-
- The second registry consists of "tags" that identify forms of domain
- literals other than those for IPv4 addresses (specified in RFC 821
- and in this document) and IPv6 addresses (specified in this
- document). Additional literal types require standardization before
- being used; none are anticipated at this time.
-
- The third, established by RFC 821 and renewed by this specification,
- is a registry of link and protocol identifiers to be used with the
- "via" and "with" subclauses of the time stamp ("Received: header")
-
-
-
-Klensin Standards Track [Page 67]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- described in section 4.4. Link and protocol identifiers in addition
- to those specified in this document may be registered only by
- standardization or by way of an RFC-documented, IESG-approved,
- Experimental protocol extension.
-
-9. References
-
- [1] American National Standards Institute (formerly United States of
- America Standards Institute), X3.4, 1968, "USA Code for
- Information Interchange". ANSI X3.4-1968 has been replaced by
- newer versions with slight modifications, but the 1968 version
- remains definitive for the Internet.
-
- [2] Braden, R., "Requirements for Internet hosts - application and
- support", STD 3, RFC 1123, October 1989.
-
- [3] Butler, M., Chase, D., Goldberger, J., Postel, J. and J.
- Reynolds, "Post Office Protocol - version 2", RFC 937, February
- 1985.
-
- [4] Callas, J., Donnerhacke, L., Finney, H. and R. Thayer, "OpenPGP
- Message Format", RFC 2440, November 1998.
-
- [5] Crispin, M., "Interactive Mail Access Protocol - Version 2", RFC
- 1176, August 1990.
-
- [6] Crispin, M., "Internet Message Access Protocol - Version 4", RFC
- 2060, December 1996.
-
- [7] Crocker, D., "Standard for the Format of ARPA Internet Text
- Messages", RFC 822, August 1982.
-
- [8] Crocker, D. and P. Overell, Eds., "Augmented BNF for Syntax
- Specifications: ABNF", RFC 2234, November 1997.
-
- [9] De Winter, J., "SMTP Service Extension for Remote Message Queue
- Starting", RFC 1985, August 1996.
-
- [10] Fajman, R., "An Extensible Message Format for Message
- Disposition Notifications", RFC 2298, March 1998.
-
- [11] Freed, N, "Behavior of and Requirements for Internet Firewalls",
- RFC 2979, October 2000.
-
- [12] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part One: Format of Internet Message Bodies",
- RFC 2045, December 1996.
-
-
-
-
-Klensin Standards Track [Page 68]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- [13] Freed, N., "SMTP Service Extension for Command Pipelining", RFC
- 2920, September 2000.
-
- [14] Galvin, J., Murphy, S., Crocker, S. and N. Freed, "Security
- Multiparts for MIME: Multipart/Signed and Multipart/Encrypted",
- RFC 1847, October 1995.
-
- [15] Gellens, R. and J. Klensin, "Message Submission", RFC 2476,
- December 1998.
-
- [16] Kille, S., "Mapping between X.400 and RFC822/MIME", RFC 2156,
- January 1998.
-
- [17] Hinden, R and S. Deering, Eds. "IP Version 6 Addressing
- Architecture", RFC 2373, July 1998.
-
- [18] Klensin, J., Freed, N. and K. Moore, "SMTP Service Extension for
- Message Size Declaration", STD 10, RFC 1870, November 1995.
-
- [19] Klensin, J., Freed, N., Rose, M., Stefferud, E. and D. Crocker,
- "SMTP Service Extensions", STD 10, RFC 1869, November 1995.
-
- [20] Klensin, J., Freed, N., Rose, M., Stefferud, E. and D. Crocker,
- "SMTP Service Extension for 8bit-MIMEtransport", RFC 1652, July
- 1994.
-
- [21] Lambert, M., "PCMAIL: A distributed mail system for personal
- computers", RFC 1056, July 1988.
-
- [22] Mockapetris, P., "Domain names - implementation and
- specification", STD 13, RFC 1035, November 1987.
-
- Mockapetris, P., "Domain names - concepts and facilities", STD
- 13, RFC 1034, November 1987.
-
- [23] Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part
- Three: Message Header Extensions for Non-ASCII Text", RFC 2047,
- December 1996.
-
- [24] Moore, K., "SMTP Service Extension for Delivery Status
- Notifications", RFC 1891, January 1996.
-
- [25] Moore, K., and G. Vaudreuil, "An Extensible Message Format for
- Delivery Status Notifications", RFC 1894, January 1996.
-
- [26] Myers, J. and M. Rose, "Post Office Protocol - Version 3", STD
- 53, RFC 1939, May 1996.
-
-
-
-
-Klensin Standards Track [Page 69]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- [27] Partridge, C., "Mail routing and the domain system", RFC 974,
- January 1986.
-
- [28] Partridge, C., "Duplicate messages and SMTP", RFC 1047, February
- 1988.
-
- [29] Postel, J., ed., "Transmission Control Protocol - DARPA Internet
- Program Protocol Specification", STD 7, RFC 793, September 1981.
-
- [30] Postel, J., "Simple Mail Transfer Protocol", RFC 821, August
- 1982.
-
- [31] Ramsdell, B., Ed., "S/MIME Version 3 Message Specification", RFC
- 2633, June 1999.
-
- [32] Resnick, P., Ed., "Internet Message Format", RFC 2822, April
- 2001.
-
- [33] Vaudreuil, G., "SMTP Service Extensions for Transmission of
- Large and Binary MIME Messages", RFC 1830, August 1995.
-
- [34] Vaudreuil, G., "Enhanced Mail System Status Codes", RFC 1893,
- January 1996.
-
-10. Editor's Address
-
- John C. Klensin
- AT&T Laboratories
- 99 Bedford St
- Boston, MA 02111 USA
-
- Phone: 617-574-3076
- EMail: klensin@research.att.com
-
-11. Acknowledgments
-
- Many people worked long and hard on the many iterations of this
- document. There was wide-ranging debate in the IETF DRUMS Working
- Group, both on its mailing list and in face to face discussions,
- about many technical issues and the role of a revised standard for
- Internet mail transport, and many contributors helped form the
- wording in this specification. The hundreds of participants in the
- many discussions since RFC 821 was produced are too numerous to
- mention, but they all helped this document become what it is.
-
-
-
-
-
-
-
-Klensin Standards Track [Page 70]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
-APPENDICES
-
-A. TCP Transport Service
-
- The TCP connection supports the transmission of 8-bit bytes. The
- SMTP data is 7-bit ASCII characters. Each character is transmitted
- as an 8-bit byte with the high-order bit cleared to zero. Service
- extensions may modify this rule to permit transmission of full 8-bit
- data bytes as part of the message body, but not in SMTP commands or
- responses.
-
-B. Generating SMTP Commands from RFC 822 Headers
-
- Some systems use RFC 822 headers (only) in a mail submission
- protocol, or otherwise generate SMTP commands from RFC 822 headers
- when such a message is handed to an MTA from a UA. While the MTA-UA
- protocol is a private matter, not covered by any Internet Standard,
- there are problems with this approach. For example, there have been
- repeated problems with proper handling of "bcc" copies and
- redistribution lists when information that conceptually belongs to a
- mail envelopes is not separated early in processing from header
- information (and kept separate).
-
- It is recommended that the UA provide its initial ("submission
- client") MTA with an envelope separate from the message itself.
- However, if the envelope is not supplied, SMTP commands SHOULD be
- generated as follows:
-
- 1. Each recipient address from a TO, CC, or BCC header field SHOULD
- be copied to a RCPT command (generating multiple message copies if
- that is required for queuing or delivery). This includes any
- addresses listed in a RFC 822 "group". Any BCC fields SHOULD then
- be removed from the headers. Once this process is completed, the
- remaining headers SHOULD be checked to verify that at least one
- To:, Cc:, or Bcc: header remains. If none do, then a bcc: header
- with no additional information SHOULD be inserted as specified in
- [32].
-
- 2. The return address in the MAIL command SHOULD, if possible, be
- derived from the system's identity for the submitting (local)
- user, and the "From:" header field otherwise. If there is a
- system identity available, it SHOULD also be copied to the Sender
- header field if it is different from the address in the From
- header field. (Any Sender field that was already there SHOULD be
- removed.) Systems may provide a way for submitters to override
- the envelope return address, but may want to restrict its use to
- privileged users. This will not prevent mail forgery, but may
- lessen its incidence; see section 7.1.
-
-
-
-Klensin Standards Track [Page 71]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- When an MTA is being used in this way, it bears responsibility for
- ensuring that the message being transmitted is valid. The mechanisms
- for checking that validity, and for handling (or returning) messages
- that are not valid at the time of arrival, are part of the MUA-MTA
- interface and not covered by this specification.
-
- A submission protocol based on Standard RFC 822 information alone
- MUST NOT be used to gateway a message from a foreign (non-SMTP) mail
- system into an SMTP environment. Additional information to construct
- an envelope must come from some source in the other environment,
- whether supplemental headers or the foreign system's envelope.
-
- Attempts to gateway messages using only their header "to" and "cc"
- fields have repeatedly caused mail loops and other behavior adverse
- to the proper functioning of the Internet mail environment. These
- problems have been especially common when the message originates from
- an Internet mailing list and is distributed into the foreign
- environment using envelope information. When these messages are then
- processed by a header-only remailer, loops back to the Internet
- environment (and the mailing list) are almost inevitable.
-
-C. Source Routes
-
- Historically, the <reverse-path> was a reverse source routing list of
- hosts and a source mailbox. The first host in the <reverse-path>
- SHOULD be the host sending the MAIL command. Similarly, the
- <forward-path> may be a source routing lists of hosts and a
- destination mailbox. However, in general, the <forward-path> SHOULD
- contain only a mailbox and domain name, relying on the domain name
- system to supply routing information if required. The use of source
- routes is deprecated; while servers MUST be prepared to receive and
- handle them as discussed in section 3.3 and F.2, clients SHOULD NOT
- transmit them and this section was included only to provide context.
-
- For relay purposes, the forward-path may be a source route of the
- form "@ONE,@TWO:JOE@THREE", where ONE, TWO, and THREE MUST BE fully-
- qualified domain names. This form is used to emphasize the
- distinction between an address and a route. The mailbox is an
- absolute address, and the route is information about how to get
- there. The two concepts should not be confused.
-
- If source routes are used, RFC 821 and the text below should be
- consulted for the mechanisms for constructing and updating the
- forward- and reverse-paths.
-
-
-
-
-
-
-
-Klensin Standards Track [Page 72]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- The SMTP server transforms the command arguments by moving its own
- identifier (its domain name or that of any domain for which it is
- acting as a mail exchanger), if it appears, from the forward-path to
- the beginning of the reverse-path.
-
- Notice that the forward-path and reverse-path appear in the SMTP
- commands and replies, but not necessarily in the message. That is,
- there is no need for these paths and especially this syntax to appear
- in the "To:" , "From:", "CC:", etc. fields of the message header.
- Conversely, SMTP servers MUST NOT derive final message delivery
- information from message header fields.
-
- When the list of hosts is present, it is a "reverse" source route and
- indicates that the mail was relayed through each host on the list
- (the first host in the list was the most recent relay). This list is
- used as a source route to return non-delivery notices to the sender.
- As each relay host adds itself to the beginning of the list, it MUST
- use its name as known in the transport environment to which it is
- relaying the mail rather than that of the transport environment from
- which the mail came (if they are different).
-
-D. Scenarios
-
- This section presents complete scenarios of several types of SMTP
- sessions. In the examples, "C:" indicates what is said by the SMTP
- client, and "S:" indicates what is said by the SMTP server.
-
-D.1 A Typical SMTP Transaction Scenario
-
- This SMTP example shows mail sent by Smith at host bar.com, to Jones,
- Green, and Brown at host foo.com. Here we assume that host bar.com
- contacts host foo.com directly. The mail is accepted for Jones and
- Brown. Green does not have a mailbox at host foo.com.
-
- S: 220 foo.com Simple Mail Transfer Service Ready
- C: EHLO bar.com
- S: 250-foo.com greets bar.com
- S: 250-8BITMIME
- S: 250-SIZE
- S: 250-DSN
- S: 250 HELP
- C: MAIL FROM:<Smith@bar.com>
- S: 250 OK
- C: RCPT TO:<Jones@foo.com>
- S: 250 OK
- C: RCPT TO:<Green@foo.com>
- S: 550 No such user here
- C: RCPT TO:<Brown@foo.com>
-
-
-
-Klensin Standards Track [Page 73]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- S: 250 OK
- C: DATA
- S: 354 Start mail input; end with <CRLF>.<CRLF>
- C: Blah blah blah...
- C: ...etc. etc. etc.
- C: .
- S: 250 OK
- C: QUIT
- S: 221 foo.com Service closing transmission channel
-
-D.2 Aborted SMTP Transaction Scenario
-
- S: 220 foo.com Simple Mail Transfer Service Ready
- C: EHLO bar.com
- S: 250-foo.com greets bar.com
- S: 250-8BITMIME
- S: 250-SIZE
- S: 250-DSN
- S: 250 HELP
- C: MAIL FROM:<Smith@bar.com>
- S: 250 OK
- C: RCPT TO:<Jones@foo.com>
- S: 250 OK
- C: RCPT TO:<Green@foo.com>
- S: 550 No such user here
- C: RSET
- S: 250 OK
- C: QUIT
- S: 221 foo.com Service closing transmission channel
-
-D.3 Relayed Mail Scenario
-
- Step 1 -- Source Host to Relay Host
-
- S: 220 foo.com Simple Mail Transfer Service Ready
- C: EHLO bar.com
- S: 250-foo.com greets bar.com
- S: 250-8BITMIME
- S: 250-SIZE
- S: 250-DSN
- S: 250 HELP
- C: MAIL FROM:<JQP@bar.com>
- S: 250 OK
- C: RCPT TO:<@foo.com:Jones@XYZ.COM>
- S: 250 OK
- C: DATA
- S: 354 Start mail input; end with <CRLF>.<CRLF>
- C: Date: Thu, 21 May 1998 05:33:29 -0700
-
-
-
-Klensin Standards Track [Page 74]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- C: From: John Q. Public <JQP@bar.com>
- C: Subject: The Next Meeting of the Board
- C: To: Jones@xyz.com
- C:
- C: Bill:
- C: The next meeting of the board of directors will be
- C: on Tuesday.
- C: John.
- C: .
- S: 250 OK
- C: QUIT
- S: 221 foo.com Service closing transmission channel
-
- Step 2 -- Relay Host to Destination Host
-
- S: 220 xyz.com Simple Mail Transfer Service Ready
- C: EHLO foo.com
- S: 250 xyz.com is on the air
- C: MAIL FROM:<@foo.com:JQP@bar.com>
- S: 250 OK
- C: RCPT TO:<Jones@XYZ.COM>
- S: 250 OK
- C: DATA
- S: 354 Start mail input; end with <CRLF>.<CRLF>
- C: Received: from bar.com by foo.com ; Thu, 21 May 1998
- C: 05:33:29 -0700
- C: Date: Thu, 21 May 1998 05:33:22 -0700
- C: From: John Q. Public <JQP@bar.com>
- C: Subject: The Next Meeting of the Board
- C: To: Jones@xyz.com
- C:
- C: Bill:
- C: The next meeting of the board of directors will be
- C: on Tuesday.
- C: John.
- C: .
- S: 250 OK
- C: QUIT
- S: 221 foo.com Service closing transmission channel
-
-D.4 Verifying and Sending Scenario
-
- S: 220 foo.com Simple Mail Transfer Service Ready
- C: EHLO bar.com
- S: 250-foo.com greets bar.com
- S: 250-8BITMIME
- S: 250-SIZE
- S: 250-DSN
-
-
-
-Klensin Standards Track [Page 75]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
- S: 250-VRFY
- S: 250 HELP
- C: VRFY Crispin
- S: 250 Mark Crispin <Admin.MRC@foo.com>
- C: SEND FROM:<EAK@bar.com>
- S: 250 OK
- C: RCPT TO:<Admin.MRC@foo.com>
- S: 250 OK
- C: DATA
- S: 354 Start mail input; end with <CRLF>.<CRLF>
- C: Blah blah blah...
- C: ...etc. etc. etc.
- C: .
- S: 250 OK
- C: QUIT
- S: 221 foo.com Service closing transmission channel
-
-E. Other Gateway Issues
-
- In general, gateways between the Internet and other mail systems
- SHOULD attempt to preserve any layering semantics across the
- boundaries between the two mail systems involved. Gateway-
- translation approaches that attempt to take shortcuts by mapping,
- (such as envelope information from one system to the message headers
- or body of another) have generally proven to be inadequate in
- important ways. Systems translating between environments that do not
- support both envelopes and headers and Internet mail must be written
- with the understanding that some information loss is almost
- inevitable.
-
-F. Deprecated Features of RFC 821
-
- A few features of RFC 821 have proven to be problematic and SHOULD
- NOT be used in Internet mail.
-
-F.1 TURN
-
- This command, described in RFC 821, raises important security issues
- since, in the absence of strong authentication of the host requesting
- that the client and server switch roles, it can easily be used to
- divert mail from its correct destination. Its use is deprecated;
- SMTP systems SHOULD NOT use it unless the server can authenticate the
- client.
-
-
-
-
-
-
-
-
-Klensin Standards Track [Page 76]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
-F.2 Source Routing
-
- RFC 821 utilized the concept of explicit source routing to get mail
- from one host to another via a series of relays. The requirement to
- utilize source routes in regular mail traffic was eliminated by the
- introduction of the domain name system "MX" record and the last
- significant justification for them was eliminated by the
- introduction, in RFC 1123, of a clear requirement that addresses
- following an "@" must all be fully-qualified domain names.
- Consequently, the only remaining justifications for the use of source
- routes are support for very old SMTP clients or MUAs and in mail
- system debugging. They can, however, still be useful in the latter
- circumstance and for routing mail around serious, but temporary,
- problems such as problems with the relevant DNS records.
-
- SMTP servers MUST continue to accept source route syntax as specified
- in the main body of this document and in RFC 1123. They MAY, if
- necessary, ignore the routes and utilize only the target domain in
- the address. If they do utilize the source route, the message MUST
- be sent to the first domain shown in the address. In particular, a
- server MUST NOT guess at shortcuts within the source route.
-
- Clients SHOULD NOT utilize explicit source routing except under
- unusual circumstances, such as debugging or potentially relaying
- around firewall or mail system configuration errors.
-
-F.3 HELO
-
- As discussed in sections 3.1 and 4.1.1, EHLO is strongly preferred to
- HELO when the server will accept the former. Servers must continue
- to accept and process HELO in order to support older clients.
-
-F.4 #-literals
-
- RFC 821 provided for specifying an Internet address as a decimal
- integer host number prefixed by a pound sign, "#". In practice, that
- form has been obsolete since the introduction of TCP/IP. It is
- deprecated and MUST NOT be used.
-
-F.5 Dates and Years
-
- When dates are inserted into messages by SMTP clients or servers
- (e.g., in trace fields), four-digit years MUST BE used. Two-digit
- years are deprecated; three-digit years were never permitted in the
- Internet mail system.
-
-
-
-
-
-
-Klensin Standards Track [Page 77]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
-F.6 Sending versus Mailing
-
- In addition to specifying a mechanism for delivering messages to
- user's mailboxes, RFC 821 provided additional, optional, commands to
- deliver messages directly to the user's terminal screen. These
- commands (SEND, SAML, SOML) were rarely implemented, and changes in
- workstation technology and the introduction of other protocols may
- have rendered them obsolete even where they are implemented.
-
- Clients SHOULD NOT provide SEND, SAML, or SOML as services. Servers
- MAY implement them. If they are implemented by servers, the
- implementation model specified in RFC 821 MUST be used and the
- command names MUST be published in the response to the EHLO command.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Klensin Standards Track [Page 78]
-\f
-RFC 2821 Simple Mail Transfer Protocol April 2001
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2001). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Klensin Standards Track [Page 79]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group P. Resnick, Editor
-Request for Comments: 2822 QUALCOMM Incorporated
-Obsoletes: 822 April 2001
-Category: Standards Track
-
-
- Internet Message Format
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2001). All Rights Reserved.
-
-Abstract
-
- This standard specifies a syntax for text messages that are sent
- between computer users, within the framework of "electronic mail"
- messages. This standard supersedes the one specified in Request For
- Comments (RFC) 822, "Standard for the Format of ARPA Internet Text
- Messages", updating it to reflect current practice and incorporating
- incremental changes that were specified in other RFCs.
-
-Table of Contents
-
- 1. Introduction ............................................... 3
- 1.1. Scope .................................................... 3
- 1.2. Notational conventions ................................... 4
- 1.2.1. Requirements notation .................................. 4
- 1.2.2. Syntactic notation ..................................... 4
- 1.3. Structure of this document ............................... 4
- 2. Lexical Analysis of Messages ............................... 5
- 2.1. General Description ...................................... 5
- 2.1.1. Line Length Limits ..................................... 6
- 2.2. Header Fields ............................................ 7
- 2.2.1. Unstructured Header Field Bodies ....................... 7
- 2.2.2. Structured Header Field Bodies ......................... 7
- 2.2.3. Long Header Fields ..................................... 7
- 2.3. Body ..................................................... 8
- 3. Syntax ..................................................... 9
- 3.1. Introduction ............................................. 9
- 3.2. Lexical Tokens ........................................... 9
-
-
-
-Resnick Standards Track [Page 1]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- 3.2.1. Primitive Tokens ....................................... 9
- 3.2.2. Quoted characters ......................................10
- 3.2.3. Folding white space and comments .......................11
- 3.2.4. Atom ...................................................12
- 3.2.5. Quoted strings .........................................13
- 3.2.6. Miscellaneous tokens ...................................13
- 3.3. Date and Time Specification ..............................14
- 3.4. Address Specification ....................................15
- 3.4.1. Addr-spec specification ................................16
- 3.5 Overall message syntax ....................................17
- 3.6. Field definitions ........................................18
- 3.6.1. The origination date field .............................20
- 3.6.2. Originator fields ......................................21
- 3.6.3. Destination address fields .............................22
- 3.6.4. Identification fields ..................................23
- 3.6.5. Informational fields ...................................26
- 3.6.6. Resent fields ..........................................26
- 3.6.7. Trace fields ...........................................28
- 3.6.8. Optional fields ........................................29
- 4. Obsolete Syntax ............................................29
- 4.1. Miscellaneous obsolete tokens ............................30
- 4.2. Obsolete folding white space .............................31
- 4.3. Obsolete Date and Time ...................................31
- 4.4. Obsolete Addressing ......................................33
- 4.5. Obsolete header fields ...................................33
- 4.5.1. Obsolete origination date field ........................34
- 4.5.2. Obsolete originator fields .............................34
- 4.5.3. Obsolete destination address fields ....................34
- 4.5.4. Obsolete identification fields .........................35
- 4.5.5. Obsolete informational fields ..........................35
- 4.5.6. Obsolete resent fields .................................35
- 4.5.7. Obsolete trace fields ..................................36
- 4.5.8. Obsolete optional fields ...............................36
- 5. Security Considerations ....................................36
- 6. Bibliography ...............................................37
- 7. Editor's Address ...........................................38
- 8. Acknowledgements ...........................................39
- Appendix A. Example messages ..................................41
- A.1. Addressing examples ......................................41
- A.1.1. A message from one person to another with simple
- addressing .............................................41
- A.1.2. Different types of mailboxes ...........................42
- A.1.3. Group addresses ........................................43
- A.2. Reply messages ...........................................43
- A.3. Resent messages ..........................................44
- A.4. Messages with trace fields ...............................46
- A.5. White space, comments, and other oddities ................47
- A.6. Obsoleted forms ..........................................47
-
-
-
-Resnick Standards Track [Page 2]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- A.6.1. Obsolete addressing ....................................48
- A.6.2. Obsolete dates .........................................48
- A.6.3. Obsolete white space and comments ......................48
- Appendix B. Differences from earlier standards ................49
- Appendix C. Notices ...........................................50
- Full Copyright Statement ......................................51
-
-1. Introduction
-
-1.1. Scope
-
- This standard specifies a syntax for text messages that are sent
- between computer users, within the framework of "electronic mail"
- messages. This standard supersedes the one specified in Request For
- Comments (RFC) 822, "Standard for the Format of ARPA Internet Text
- Messages" [RFC822], updating it to reflect current practice and
- incorporating incremental changes that were specified in other RFCs
- [STD3].
-
- This standard specifies a syntax only for text messages. In
- particular, it makes no provision for the transmission of images,
- audio, or other sorts of structured data in electronic mail messages.
- There are several extensions published, such as the MIME document
- series [RFC2045, RFC2046, RFC2049], which describe mechanisms for the
- transmission of such data through electronic mail, either by
- extending the syntax provided here or by structuring such messages to
- conform to this syntax. Those mechanisms are outside of the scope of
- this standard.
-
- In the context of electronic mail, messages are viewed as having an
- envelope and contents. The envelope contains whatever information is
- needed to accomplish transmission and delivery. (See [RFC2821] for a
- discussion of the envelope.) The contents comprise the object to be
- delivered to the recipient. This standard applies only to the format
- and some of the semantics of message contents. It contains no
- specification of the information in the envelope.
-
- However, some message systems may use information from the contents
- to create the envelope. It is intended that this standard facilitate
- the acquisition of such information by programs.
-
- This specification is intended as a definition of what message
- content format is to be passed between systems. Though some message
- systems locally store messages in this format (which eliminates the
- need for translation between formats) and others use formats that
- differ from the one specified in this standard, local storage is
- outside of the scope of this standard.
-
-
-
-
-Resnick Standards Track [Page 3]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- Note: This standard is not intended to dictate the internal formats
- used by sites, the specific message system features that they are
- expected to support, or any of the characteristics of user interface
- programs that create or read messages. In addition, this standard
- does not specify an encoding of the characters for either transport
- or storage; that is, it does not specify the number of bits used or
- how those bits are specifically transferred over the wire or stored
- on disk.
-
-1.2. Notational conventions
-
-1.2.1. Requirements notation
-
- This document occasionally uses terms that appear in capital letters.
- When the terms "MUST", "SHOULD", "RECOMMENDED", "MUST NOT", "SHOULD
- NOT", and "MAY" appear capitalized, they are being used to indicate
- particular requirements of this specification. A discussion of the
- meanings of these terms appears in [RFC2119].
-
-1.2.2. Syntactic notation
-
- This standard uses the Augmented Backus-Naur Form (ABNF) notation
- specified in [RFC2234] for the formal definitions of the syntax of
- messages. Characters will be specified either by a decimal value
- (e.g., the value %d65 for uppercase A and %d97 for lowercase A) or by
- a case-insensitive literal value enclosed in quotation marks (e.g.,
- "A" for either uppercase or lowercase A). See [RFC2234] for the full
- description of the notation.
-
-1.3. Structure of this document
-
- This document is divided into several sections.
-
- This section, section 1, is a short introduction to the document.
-
- Section 2 lays out the general description of a message and its
- constituent parts. This is an overview to help the reader understand
- some of the general principles used in the later portions of this
- document. Any examples in this section MUST NOT be taken as
- specification of the formal syntax of any part of a message.
-
- Section 3 specifies formal ABNF rules for the structure of each part
- of a message (the syntax) and describes the relationship between
- those parts and their meaning in the context of a message (the
- semantics). That is, it describes the actual rules for the structure
- of each part of a message (the syntax) as well as a description of
- the parts and instructions on how they ought to be interpreted (the
- semantics). This includes analysis of the syntax and semantics of
-
-
-
-Resnick Standards Track [Page 4]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- subparts of messages that have specific structure. The syntax
- included in section 3 represents messages as they MUST be created.
- There are also notes in section 3 to indicate if any of the options
- specified in the syntax SHOULD be used over any of the others.
-
- Both sections 2 and 3 describe messages that are legal to generate
- for purposes of this standard.
-
- Section 4 of this document specifies an "obsolete" syntax. There are
- references in section 3 to these obsolete syntactic elements. The
- rules of the obsolete syntax are elements that have appeared in
- earlier revisions of this standard or have previously been widely
- used in Internet messages. As such, these elements MUST be
- interpreted by parsers of messages in order to be conformant to this
- standard. However, since items in this syntax have been determined
- to be non-interoperable or to cause significant problems for
- recipients of messages, they MUST NOT be generated by creators of
- conformant messages.
-
- Section 5 details security considerations to take into account when
- implementing this standard.
-
- Section 6 is a bibliography of references in this document.
-
- Section 7 contains the editor's address.
-
- Section 8 contains acknowledgements.
-
- Appendix A lists examples of different sorts of messages. These
- examples are not exhaustive of the types of messages that appear on
- the Internet, but give a broad overview of certain syntactic forms.
-
- Appendix B lists the differences between this standard and earlier
- standards for Internet messages.
-
- Appendix C has copyright and intellectual property notices.
-
-2. Lexical Analysis of Messages
-
-2.1. General Description
-
- At the most basic level, a message is a series of characters. A
- message that is conformant with this standard is comprised of
- characters with values in the range 1 through 127 and interpreted as
- US-ASCII characters [ASCII]. For brevity, this document sometimes
- refers to this range of characters as simply "US-ASCII characters".
-
-
-
-
-
-Resnick Standards Track [Page 5]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- Note: This standard specifies that messages are made up of characters
- in the US-ASCII range of 1 through 127. There are other documents,
- specifically the MIME document series [RFC2045, RFC2046, RFC2047,
- RFC2048, RFC2049], that extend this standard to allow for values
- outside of that range. Discussion of those mechanisms is not within
- the scope of this standard.
-
- Messages are divided into lines of characters. A line is a series of
- characters that is delimited with the two characters carriage-return
- and line-feed; that is, the carriage return (CR) character (ASCII
- value 13) followed immediately by the line feed (LF) character (ASCII
- value 10). (The carriage-return/line-feed pair is usually written in
- this document as "CRLF".)
-
- A message consists of header fields (collectively called "the header
- of the message") followed, optionally, by a body. The header is a
- sequence of lines of characters with special syntax as defined in
- this standard. The body is simply a sequence of characters that
- follows the header and is separated from the header by an empty line
- (i.e., a line with nothing preceding the CRLF).
-
-2.1.1. Line Length Limits
-
- There are two limits that this standard places on the number of
- characters in a line. Each line of characters MUST be no more than
- 998 characters, and SHOULD be no more than 78 characters, excluding
- the CRLF.
-
- The 998 character limit is due to limitations in many implementations
- which send, receive, or store Internet Message Format messages that
- simply cannot handle more than 998 characters on a line. Receiving
- implementations would do well to handle an arbitrarily large number
- of characters in a line for robustness sake. However, there are so
- many implementations which (in compliance with the transport
- requirements of [RFC2821]) do not accept messages containing more
- than 1000 character including the CR and LF per line, it is important
- for implementations not to create such messages.
-
- The more conservative 78 character recommendation is to accommodate
- the many implementations of user interfaces that display these
- messages which may truncate, or disastrously wrap, the display of
- more than 78 characters per line, in spite of the fact that such
- implementations are non-conformant to the intent of this
- specification (and that of [RFC2821] if they actually cause
- information to be lost). Again, even though this limitation is put on
- messages, it is encumbant upon implementations which display messages
-
-
-
-
-
-Resnick Standards Track [Page 6]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- to handle an arbitrarily large number of characters in a line
- (certainly at least up to the 998 character limit) for the sake of
- robustness.
-
-2.2. Header Fields
-
- Header fields are lines composed of a field name, followed by a colon
- (":"), followed by a field body, and terminated by CRLF. A field
- name MUST be composed of printable US-ASCII characters (i.e.,
- characters that have values between 33 and 126, inclusive), except
- colon. A field body may be composed of any US-ASCII characters,
- except for CR and LF. However, a field body may contain CRLF when
- used in header "folding" and "unfolding" as described in section
- 2.2.3. All field bodies MUST conform to the syntax described in
- sections 3 and 4 of this standard.
-
-2.2.1. Unstructured Header Field Bodies
-
- Some field bodies in this standard are defined simply as
- "unstructured" (which is specified below as any US-ASCII characters,
- except for CR and LF) with no further restrictions. These are
- referred to as unstructured field bodies. Semantically, unstructured
- field bodies are simply to be treated as a single line of characters
- with no further processing (except for header "folding" and
- "unfolding" as described in section 2.2.3).
-
-2.2.2. Structured Header Field Bodies
-
- Some field bodies in this standard have specific syntactical
- structure more restrictive than the unstructured field bodies
- described above. These are referred to as "structured" field bodies.
- Structured field bodies are sequences of specific lexical tokens as
- described in sections 3 and 4 of this standard. Many of these tokens
- are allowed (according to their syntax) to be introduced or end with
- comments (as described in section 3.2.3) as well as the space (SP,
- ASCII value 32) and horizontal tab (HTAB, ASCII value 9) characters
- (together known as the white space characters, WSP), and those WSP
- characters are subject to header "folding" and "unfolding" as
- described in section 2.2.3. Semantic analysis of structured field
- bodies is given along with their syntax.
-
-2.2.3. Long Header Fields
-
- Each header field is logically a single line of characters comprising
- the field name, the colon, and the field body. For convenience
- however, and to deal with the 998/78 character limitations per line,
- the field body portion of a header field can be split into a multiple
- line representation; this is called "folding". The general rule is
-
-
-
-Resnick Standards Track [Page 7]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- that wherever this standard allows for folding white space (not
- simply WSP characters), a CRLF may be inserted before any WSP. For
- example, the header field:
-
- Subject: This is a test
-
- can be represented as:
-
- Subject: This
- is a test
-
- Note: Though structured field bodies are defined in such a way that
- folding can take place between many of the lexical tokens (and even
- within some of the lexical tokens), folding SHOULD be limited to
- placing the CRLF at higher-level syntactic breaks. For instance, if
- a field body is defined as comma-separated values, it is recommended
- that folding occur after the comma separating the structured items in
- preference to other places where the field could be folded, even if
- it is allowed elsewhere.
-
- The process of moving from this folded multiple-line representation
- of a header field to its single line representation is called
- "unfolding". Unfolding is accomplished by simply removing any CRLF
- that is immediately followed by WSP. Each header field should be
- treated in its unfolded form for further syntactic and semantic
- evaluation.
-
-2.3. Body
-
- The body of a message is simply lines of US-ASCII characters. The
- only two limitations on the body are as follows:
-
- - CR and LF MUST only occur together as CRLF; they MUST NOT appear
- independently in the body.
-
- - Lines of characters in the body MUST be limited to 998 characters,
- and SHOULD be limited to 78 characters, excluding the CRLF.
-
- Note: As was stated earlier, there are other standards documents,
- specifically the MIME documents [RFC2045, RFC2046, RFC2048, RFC2049]
- that extend this standard to allow for different sorts of message
- bodies. Again, these mechanisms are beyond the scope of this
- document.
-
-
-
-
-
-
-
-
-Resnick Standards Track [Page 8]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-3. Syntax
-
-3.1. Introduction
-
- The syntax as given in this section defines the legal syntax of
- Internet messages. Messages that are conformant to this standard
- MUST conform to the syntax in this section. If there are options in
- this section where one option SHOULD be generated, that is indicated
- either in the prose or in a comment next to the syntax.
-
- For the defined expressions, a short description of the syntax and
- use is given, followed by the syntax in ABNF, followed by a semantic
- analysis. Primitive tokens that are used but otherwise unspecified
- come from [RFC2234].
-
- In some of the definitions, there will be nonterminals whose names
- start with "obs-". These "obs-" elements refer to tokens defined in
- the obsolete syntax in section 4. In all cases, these productions
- are to be ignored for the purposes of generating legal Internet
- messages and MUST NOT be used as part of such a message. However,
- when interpreting messages, these tokens MUST be honored as part of
- the legal syntax. In this sense, section 3 defines a grammar for
- generation of messages, with "obs-" elements that are to be ignored,
- while section 4 adds grammar for interpretation of messages.
-
-3.2. Lexical Tokens
-
- The following rules are used to define an underlying lexical
- analyzer, which feeds tokens to the higher-level parsers. This
- section defines the tokens used in structured header field bodies.
-
- Note: Readers of this standard need to pay special attention to how
- these lexical tokens are used in both the lower-level and
- higher-level syntax later in the document. Particularly, the white
- space tokens and the comment tokens defined in section 3.2.3 get used
- in the lower-level tokens defined here, and those lower-level tokens
- are in turn used as parts of the higher-level tokens defined later.
- Therefore, the white space and comments may be allowed in the
- higher-level tokens even though they may not explicitly appear in a
- particular definition.
-
-3.2.1. Primitive Tokens
-
- The following are primitive tokens referred to elsewhere in this
- standard, but not otherwise defined in [RFC2234]. Some of them will
- not appear anywhere else in the syntax, but they are convenient to
- refer to in other parts of this document.
-
-
-
-
-Resnick Standards Track [Page 9]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- Note: The "specials" below are just such an example. Though the
- specials token does not appear anywhere else in this standard, it is
- useful for implementers who use tools that lexically analyze
- messages. Each of the characters in specials can be used to indicate
- a tokenization point in lexical analysis.
-
-NO-WS-CTL = %d1-8 / ; US-ASCII control characters
- %d11 / ; that do not include the
- %d12 / ; carriage return, line feed,
- %d14-31 / ; and white space characters
- %d127
-
-text = %d1-9 / ; Characters excluding CR and LF
- %d11 /
- %d12 /
- %d14-127 /
- obs-text
-
-specials = "(" / ")" / ; Special characters used in
- "<" / ">" / ; other parts of the syntax
- "[" / "]" /
- ":" / ";" /
- "@" / "\" /
- "," / "." /
- DQUOTE
-
- No special semantics are attached to these tokens. They are simply
- single characters.
-
-3.2.2. Quoted characters
-
- Some characters are reserved for special interpretation, such as
- delimiting lexical tokens. To permit use of these characters as
- uninterpreted data, a quoting mechanism is provided.
-
-quoted-pair = ("\" text) / obs-qp
-
- Where any quoted-pair appears, it is to be interpreted as the text
- character alone. That is to say, the "\" character that appears as
- part of a quoted-pair is semantically "invisible".
-
- Note: The "\" character may appear in a message where it is not part
- of a quoted-pair. A "\" character that does not appear in a
- quoted-pair is not semantically invisible. The only places in this
- standard where quoted-pair currently appears are ccontent, qcontent,
- dcontent, no-fold-quote, and no-fold-literal.
-
-
-
-
-
-Resnick Standards Track [Page 10]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-3.2.3. Folding white space and comments
-
- White space characters, including white space used in folding
- (described in section 2.2.3), may appear between many elements in
- header field bodies. Also, strings of characters that are treated as
- comments may be included in structured field bodies as characters
- enclosed in parentheses. The following defines the folding white
- space (FWS) and comment constructs.
-
- Strings of characters enclosed in parentheses are considered comments
- so long as they do not appear within a "quoted-string", as defined in
- section 3.2.5. Comments may nest.
-
- There are several places in this standard where comments and FWS may
- be freely inserted. To accommodate that syntax, an additional token
- for "CFWS" is defined for places where comments and/or FWS can occur.
- However, where CFWS occurs in this standard, it MUST NOT be inserted
- in such a way that any line of a folded header field is made up
- entirely of WSP characters and nothing else.
-
-FWS = ([*WSP CRLF] 1*WSP) / ; Folding white space
- obs-FWS
-
-ctext = NO-WS-CTL / ; Non white space controls
-
- %d33-39 / ; The rest of the US-ASCII
- %d42-91 / ; characters not including "(",
- %d93-126 ; ")", or "\"
-
-ccontent = ctext / quoted-pair / comment
-
-comment = "(" *([FWS] ccontent) [FWS] ")"
-
-CFWS = *([FWS] comment) (([FWS] comment) / FWS)
-
- Throughout this standard, where FWS (the folding white space token)
- appears, it indicates a place where header folding, as discussed in
- section 2.2.3, may take place. Wherever header folding appears in a
- message (that is, a header field body containing a CRLF followed by
- any WSP), header unfolding (removal of the CRLF) is performed before
- any further lexical analysis is performed on that header field
- according to this standard. That is to say, any CRLF that appears in
- FWS is semantically "invisible."
-
- A comment is normally used in a structured field body to provide some
- human readable informational text. Since a comment is allowed to
- contain FWS, folding is permitted within the comment. Also note that
- since quoted-pair is allowed in a comment, the parentheses and
-
-
-
-Resnick Standards Track [Page 11]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- backslash characters may appear in a comment so long as they appear
- as a quoted-pair. Semantically, the enclosing parentheses are not
- part of the comment; the comment is what is contained between the two
- parentheses. As stated earlier, the "\" in any quoted-pair and the
- CRLF in any FWS that appears within the comment are semantically
- "invisible" and therefore not part of the comment either.
-
- Runs of FWS, comment or CFWS that occur between lexical tokens in a
- structured field header are semantically interpreted as a single
- space character.
-
-3.2.4. Atom
-
- Several productions in structured header field bodies are simply
- strings of certain basic characters. Such productions are called
- atoms.
-
- Some of the structured header field bodies also allow the period
- character (".", ASCII value 46) within runs of atext. An additional
- "dot-atom" token is defined for those purposes.
-
-atext = ALPHA / DIGIT / ; Any character except controls,
- "!" / "#" / ; SP, and specials.
- "$" / "%" / ; Used for atoms
- "&" / "'" /
- "*" / "+" /
- "-" / "/" /
- "=" / "?" /
- "^" / "_" /
- "`" / "{" /
- "|" / "}" /
- "~"
-
-atom = [CFWS] 1*atext [CFWS]
-
-dot-atom = [CFWS] dot-atom-text [CFWS]
-
-dot-atom-text = 1*atext *("." 1*atext)
-
- Both atom and dot-atom are interpreted as a single unit, comprised of
- the string of characters that make it up. Semantically, the optional
- comments and FWS surrounding the rest of the characters are not part
- of the atom; the atom is only the run of atext characters in an atom,
- or the atext and "." characters in a dot-atom.
-
-
-
-
-
-
-
-Resnick Standards Track [Page 12]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-3.2.5. Quoted strings
-
- Strings of characters that include characters other than those
- allowed in atoms may be represented in a quoted string format, where
- the characters are surrounded by quote (DQUOTE, ASCII value 34)
- characters.
-
-qtext = NO-WS-CTL / ; Non white space controls
-
- %d33 / ; The rest of the US-ASCII
- %d35-91 / ; characters not including "\"
- %d93-126 ; or the quote character
-
-qcontent = qtext / quoted-pair
-
-quoted-string = [CFWS]
- DQUOTE *([FWS] qcontent) [FWS] DQUOTE
- [CFWS]
-
- A quoted-string is treated as a unit. That is, quoted-string is
- identical to atom, semantically. Since a quoted-string is allowed to
- contain FWS, folding is permitted. Also note that since quoted-pair
- is allowed in a quoted-string, the quote and backslash characters may
- appear in a quoted-string so long as they appear as a quoted-pair.
-
- Semantically, neither the optional CFWS outside of the quote
- characters nor the quote characters themselves are part of the
- quoted-string; the quoted-string is what is contained between the two
- quote characters. As stated earlier, the "\" in any quoted-pair and
- the CRLF in any FWS/CFWS that appears within the quoted-string are
- semantically "invisible" and therefore not part of the quoted-string
- either.
-
-3.2.6. Miscellaneous tokens
-
- Three additional tokens are defined, word and phrase for combinations
- of atoms and/or quoted-strings, and unstructured for use in
- unstructured header fields and in some places within structured
- header fields.
-
-word = atom / quoted-string
-
-phrase = 1*word / obs-phrase
-
-
-
-
-
-
-
-
-Resnick Standards Track [Page 13]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-utext = NO-WS-CTL / ; Non white space controls
- %d33-126 / ; The rest of US-ASCII
- obs-utext
-
-unstructured = *([FWS] utext) [FWS]
-
-3.3. Date and Time Specification
-
- Date and time occur in several header fields. This section specifies
- the syntax for a full date and time specification. Though folding
- white space is permitted throughout the date-time specification, it
- is RECOMMENDED that a single space be used in each place that FWS
- appears (whether it is required or optional); some older
- implementations may not interpret other occurrences of folding white
- space correctly.
-
-date-time = [ day-of-week "," ] date FWS time [CFWS]
-
-day-of-week = ([FWS] day-name) / obs-day-of-week
-
-day-name = "Mon" / "Tue" / "Wed" / "Thu" /
- "Fri" / "Sat" / "Sun"
-
-date = day month year
-
-year = 4*DIGIT / obs-year
-
-month = (FWS month-name FWS) / obs-month
-
-month-name = "Jan" / "Feb" / "Mar" / "Apr" /
- "May" / "Jun" / "Jul" / "Aug" /
- "Sep" / "Oct" / "Nov" / "Dec"
-
-day = ([FWS] 1*2DIGIT) / obs-day
-
-time = time-of-day FWS zone
-
-time-of-day = hour ":" minute [ ":" second ]
-
-hour = 2DIGIT / obs-hour
-
-minute = 2DIGIT / obs-minute
-
-second = 2DIGIT / obs-second
-
-zone = (( "+" / "-" ) 4DIGIT) / obs-zone
-
-
-
-
-
-Resnick Standards Track [Page 14]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- The day is the numeric day of the month. The year is any numeric
- year 1900 or later.
-
- The time-of-day specifies the number of hours, minutes, and
- optionally seconds since midnight of the date indicated.
-
- The date and time-of-day SHOULD express local time.
-
- The zone specifies the offset from Coordinated Universal Time (UTC,
- formerly referred to as "Greenwich Mean Time") that the date and
- time-of-day represent. The "+" or "-" indicates whether the
- time-of-day is ahead of (i.e., east of) or behind (i.e., west of)
- Universal Time. The first two digits indicate the number of hours
- difference from Universal Time, and the last two digits indicate the
- number of minutes difference from Universal Time. (Hence, +hhmm
- means +(hh * 60 + mm) minutes, and -hhmm means -(hh * 60 + mm)
- minutes). The form "+0000" SHOULD be used to indicate a time zone at
- Universal Time. Though "-0000" also indicates Universal Time, it is
- used to indicate that the time was generated on a system that may be
- in a local time zone other than Universal Time and therefore
- indicates that the date-time contains no information about the local
- time zone.
-
- A date-time specification MUST be semantically valid. That is, the
- day-of-the-week (if included) MUST be the day implied by the date,
- the numeric day-of-month MUST be between 1 and the number of days
- allowed for the specified month (in the specified year), the
- time-of-day MUST be in the range 00:00:00 through 23:59:60 (the
- number of seconds allowing for a leap second; see [STD12]), and the
- zone MUST be within the range -9959 through +9959.
-
-3.4. Address Specification
-
- Addresses occur in several message header fields to indicate senders
- and recipients of messages. An address may either be an individual
- mailbox, or a group of mailboxes.
-
-address = mailbox / group
-
-mailbox = name-addr / addr-spec
-
-name-addr = [display-name] angle-addr
-
-angle-addr = [CFWS] "<" addr-spec ">" [CFWS] / obs-angle-addr
-
-group = display-name ":" [mailbox-list / CFWS] ";"
- [CFWS]
-
-
-
-
-Resnick Standards Track [Page 15]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-display-name = phrase
-
-mailbox-list = (mailbox *("," mailbox)) / obs-mbox-list
-
-address-list = (address *("," address)) / obs-addr-list
-
- A mailbox receives mail. It is a conceptual entity which does not
- necessarily pertain to file storage. For example, some sites may
- choose to print mail on a printer and deliver the output to the
- addressee's desk. Normally, a mailbox is comprised of two parts: (1)
- an optional display name that indicates the name of the recipient
- (which could be a person or a system) that could be displayed to the
- user of a mail application, and (2) an addr-spec address enclosed in
- angle brackets ("<" and ">"). There is also an alternate simple form
- of a mailbox where the addr-spec address appears alone, without the
- recipient's name or the angle brackets. The Internet addr-spec
- address is described in section 3.4.1.
-
- Note: Some legacy implementations used the simple form where the
- addr-spec appears without the angle brackets, but included the name
- of the recipient in parentheses as a comment following the addr-spec.
- Since the meaning of the information in a comment is unspecified,
- implementations SHOULD use the full name-addr form of the mailbox,
- instead of the legacy form, to specify the display name associated
- with a mailbox. Also, because some legacy implementations interpret
- the comment, comments generally SHOULD NOT be used in address fields
- to avoid confusing such implementations.
-
- When it is desirable to treat several mailboxes as a single unit
- (i.e., in a distribution list), the group construct can be used. The
- group construct allows the sender to indicate a named group of
- recipients. This is done by giving a display name for the group,
- followed by a colon, followed by a comma separated list of any number
- of mailboxes (including zero and one), and ending with a semicolon.
- Because the list of mailboxes can be empty, using the group construct
- is also a simple way to communicate to recipients that the message
- was sent to one or more named sets of recipients, without actually
- providing the individual mailbox address for each of those
- recipients.
-
-3.4.1. Addr-spec specification
-
- An addr-spec is a specific Internet identifier that contains a
- locally interpreted string followed by the at-sign character ("@",
- ASCII value 64) followed by an Internet domain. The locally
- interpreted string is either a quoted-string or a dot-atom. If the
- string can be represented as a dot-atom (that is, it contains no
- characters other than atext characters or "." surrounded by atext
-
-
-
-Resnick Standards Track [Page 16]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- characters), then the dot-atom form SHOULD be used and the
- quoted-string form SHOULD NOT be used. Comments and folding white
- space SHOULD NOT be used around the "@" in the addr-spec.
-
-addr-spec = local-part "@" domain
-
-local-part = dot-atom / quoted-string / obs-local-part
-
-domain = dot-atom / domain-literal / obs-domain
-
-domain-literal = [CFWS] "[" *([FWS] dcontent) [FWS] "]" [CFWS]
-
-dcontent = dtext / quoted-pair
-
-dtext = NO-WS-CTL / ; Non white space controls
-
- %d33-90 / ; The rest of the US-ASCII
- %d94-126 ; characters not including "[",
- ; "]", or "\"
-
- The domain portion identifies the point to which the mail is
- delivered. In the dot-atom form, this is interpreted as an Internet
- domain name (either a host name or a mail exchanger name) as
- described in [STD3, STD13, STD14]. In the domain-literal form, the
- domain is interpreted as the literal Internet address of the
- particular host. In both cases, how addressing is used and how
- messages are transported to a particular host is covered in the mail
- transport document [RFC2821]. These mechanisms are outside of the
- scope of this document.
-
- The local-part portion is a domain dependent string. In addresses,
- it is simply interpreted on the particular host as a name of a
- particular mailbox.
-
-3.5 Overall message syntax
-
- A message consists of header fields, optionally followed by a message
- body. Lines in a message MUST be a maximum of 998 characters
- excluding the CRLF, but it is RECOMMENDED that lines be limited to 78
- characters excluding the CRLF. (See section 2.1.1 for explanation.)
- In a message body, though all of the characters listed in the text
- rule MAY be used, the use of US-ASCII control characters (values 1
- through 8, 11, 12, and 14 through 31) is discouraged since their
- interpretation by receivers for display is not guaranteed.
-
-
-
-
-
-
-
-Resnick Standards Track [Page 17]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-message = (fields / obs-fields)
- [CRLF body]
-
-body = *(*998text CRLF) *998text
-
- The header fields carry most of the semantic information and are
- defined in section 3.6. The body is simply a series of lines of text
- which are uninterpreted for the purposes of this standard.
-
-3.6. Field definitions
-
- The header fields of a message are defined here. All header fields
- have the same general syntactic structure: A field name, followed by
- a colon, followed by the field body. The specific syntax for each
- header field is defined in the subsequent sections.
-
- Note: In the ABNF syntax for each field in subsequent sections, each
- field name is followed by the required colon. However, for brevity
- sometimes the colon is not referred to in the textual description of
- the syntax. It is, nonetheless, required.
-
- It is important to note that the header fields are not guaranteed to
- be in a particular order. They may appear in any order, and they
- have been known to be reordered occasionally when transported over
- the Internet. However, for the purposes of this standard, header
- fields SHOULD NOT be reordered when a message is transported or
- transformed. More importantly, the trace header fields and resent
- header fields MUST NOT be reordered, and SHOULD be kept in blocks
- prepended to the message. See sections 3.6.6 and 3.6.7 for more
- information.
-
- The only required header fields are the origination date field and
- the originator address field(s). All other header fields are
- syntactically optional. More information is contained in the table
- following this definition.
-
-fields = *(trace
- *(resent-date /
- resent-from /
- resent-sender /
- resent-to /
- resent-cc /
- resent-bcc /
- resent-msg-id))
- *(orig-date /
- from /
- sender /
- reply-to /
-
-
-
-Resnick Standards Track [Page 18]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- to /
- cc /
- bcc /
- message-id /
- in-reply-to /
- references /
- subject /
- comments /
- keywords /
- optional-field)
-
- The following table indicates limits on the number of times each
- field may occur in a message header as well as any special
- limitations on the use of those fields. An asterisk next to a value
- in the minimum or maximum column indicates that a special restriction
- appears in the Notes column.
-
-Field Min number Max number Notes
-
-trace 0 unlimited Block prepended - see
- 3.6.7
-
-resent-date 0* unlimited* One per block, required
- if other resent fields
- present - see 3.6.6
-
-resent-from 0 unlimited* One per block - see
- 3.6.6
-
-resent-sender 0* unlimited* One per block, MUST
- occur with multi-address
- resent-from - see 3.6.6
-
-resent-to 0 unlimited* One per block - see
- 3.6.6
-
-resent-cc 0 unlimited* One per block - see
- 3.6.6
-
-resent-bcc 0 unlimited* One per block - see
- 3.6.6
-
-resent-msg-id 0 unlimited* One per block - see
- 3.6.6
-
-orig-date 1 1
-
-from 1 1 See sender and 3.6.2
-
-
-
-Resnick Standards Track [Page 19]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-sender 0* 1 MUST occur with multi-
- address from - see 3.6.2
-
-reply-to 0 1
-
-to 0 1
-
-cc 0 1
-
-bcc 0 1
-
-message-id 0* 1 SHOULD be present - see
- 3.6.4
-
-in-reply-to 0* 1 SHOULD occur in some
- replies - see 3.6.4
-
-references 0* 1 SHOULD occur in some
- replies - see 3.6.4
-
-subject 0 1
-
-comments 0 unlimited
-
-keywords 0 unlimited
-
-optional-field 0 unlimited
-
- The exact interpretation of each field is described in subsequent
- sections.
-
-3.6.1. The origination date field
-
- The origination date field consists of the field name "Date" followed
- by a date-time specification.
-
-orig-date = "Date:" date-time CRLF
-
- The origination date specifies the date and time at which the creator
- of the message indicated that the message was complete and ready to
- enter the mail delivery system. For instance, this might be the time
- that a user pushes the "send" or "submit" button in an application
- program. In any case, it is specifically not intended to convey the
- time that the message is actually transported, but rather the time at
- which the human or other creator of the message has put the message
- into its final form, ready for transport. (For example, a portable
- computer user who is not connected to a network might queue a message
-
-
-
-
-Resnick Standards Track [Page 20]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- for delivery. The origination date is intended to contain the date
- and time that the user queued the message, not the time when the user
- connected to the network to send the message.)
-
-3.6.2. Originator fields
-
- The originator fields of a message consist of the from field, the
- sender field (when applicable), and optionally the reply-to field.
- The from field consists of the field name "From" and a
- comma-separated list of one or more mailbox specifications. If the
- from field contains more than one mailbox specification in the
- mailbox-list, then the sender field, containing the field name
- "Sender" and a single mailbox specification, MUST appear in the
- message. In either case, an optional reply-to field MAY also be
- included, which contains the field name "Reply-To" and a
- comma-separated list of one or more addresses.
-
-from = "From:" mailbox-list CRLF
-
-sender = "Sender:" mailbox CRLF
-
-reply-to = "Reply-To:" address-list CRLF
-
- The originator fields indicate the mailbox(es) of the source of the
- message. The "From:" field specifies the author(s) of the message,
- that is, the mailbox(es) of the person(s) or system(s) responsible
- for the writing of the message. The "Sender:" field specifies the
- mailbox of the agent responsible for the actual transmission of the
- message. For example, if a secretary were to send a message for
- another person, the mailbox of the secretary would appear in the
- "Sender:" field and the mailbox of the actual author would appear in
- the "From:" field. If the originator of the message can be indicated
- by a single mailbox and the author and transmitter are identical, the
- "Sender:" field SHOULD NOT be used. Otherwise, both fields SHOULD
- appear.
-
- The originator fields also provide the information required when
- replying to a message. When the "Reply-To:" field is present, it
- indicates the mailbox(es) to which the author of the message suggests
- that replies be sent. In the absence of the "Reply-To:" field,
- replies SHOULD by default be sent to the mailbox(es) specified in the
- "From:" field unless otherwise specified by the person composing the
- reply.
-
- In all cases, the "From:" field SHOULD NOT contain any mailbox that
- does not belong to the author(s) of the message. See also section
- 3.6.3 for more information on forming the destination addresses for a
- reply.
-
-
-
-Resnick Standards Track [Page 21]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-3.6.3. Destination address fields
-
- The destination fields of a message consist of three possible fields,
- each of the same form: The field name, which is either "To", "Cc", or
- "Bcc", followed by a comma-separated list of one or more addresses
- (either mailbox or group syntax).
-
-to = "To:" address-list CRLF
-
-cc = "Cc:" address-list CRLF
-
-bcc = "Bcc:" (address-list / [CFWS]) CRLF
-
- The destination fields specify the recipients of the message. Each
- destination field may have one or more addresses, and each of the
- addresses indicate the intended recipients of the message. The only
- difference between the three fields is how each is used.
-
- The "To:" field contains the address(es) of the primary recipient(s)
- of the message.
-
- The "Cc:" field (where the "Cc" means "Carbon Copy" in the sense of
- making a copy on a typewriter using carbon paper) contains the
- addresses of others who are to receive the message, though the
- content of the message may not be directed at them.
-
- The "Bcc:" field (where the "Bcc" means "Blind Carbon Copy") contains
- addresses of recipients of the message whose addresses are not to be
- revealed to other recipients of the message. There are three ways in
- which the "Bcc:" field is used. In the first case, when a message
- containing a "Bcc:" field is prepared to be sent, the "Bcc:" line is
- removed even though all of the recipients (including those specified
- in the "Bcc:" field) are sent a copy of the message. In the second
- case, recipients specified in the "To:" and "Cc:" lines each are sent
- a copy of the message with the "Bcc:" line removed as above, but the
- recipients on the "Bcc:" line get a separate copy of the message
- containing a "Bcc:" line. (When there are multiple recipient
- addresses in the "Bcc:" field, some implementations actually send a
- separate copy of the message to each recipient with a "Bcc:"
- containing only the address of that particular recipient.) Finally,
- since a "Bcc:" field may contain no addresses, a "Bcc:" field can be
- sent without any addresses indicating to the recipients that blind
- copies were sent to someone. Which method to use with "Bcc:" fields
- is implementation dependent, but refer to the "Security
- Considerations" section of this document for a discussion of each.
-
-
-
-
-
-
-Resnick Standards Track [Page 22]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- When a message is a reply to another message, the mailboxes of the
- authors of the original message (the mailboxes in the "From:" field)
- or mailboxes specified in the "Reply-To:" field (if it exists) MAY
- appear in the "To:" field of the reply since these would normally be
- the primary recipients of the reply. If a reply is sent to a message
- that has destination fields, it is often desirable to send a copy of
- the reply to all of the recipients of the message, in addition to the
- author. When such a reply is formed, addresses in the "To:" and
- "Cc:" fields of the original message MAY appear in the "Cc:" field of
- the reply, since these are normally secondary recipients of the
- reply. If a "Bcc:" field is present in the original message,
- addresses in that field MAY appear in the "Bcc:" field of the reply,
- but SHOULD NOT appear in the "To:" or "Cc:" fields.
-
- Note: Some mail applications have automatic reply commands that
- include the destination addresses of the original message in the
- destination addresses of the reply. How those reply commands behave
- is implementation dependent and is beyond the scope of this document.
- In particular, whether or not to include the original destination
- addresses when the original message had a "Reply-To:" field is not
- addressed here.
-
-3.6.4. Identification fields
-
- Though optional, every message SHOULD have a "Message-ID:" field.
- Furthermore, reply messages SHOULD have "In-Reply-To:" and
- "References:" fields as appropriate, as described below.
-
- The "Message-ID:" field contains a single unique message identifier.
- The "References:" and "In-Reply-To:" field each contain one or more
- unique message identifiers, optionally separated by CFWS.
-
- The message identifier (msg-id) is similar in syntax to an angle-addr
- construct without the internal CFWS.
-
-message-id = "Message-ID:" msg-id CRLF
-
-in-reply-to = "In-Reply-To:" 1*msg-id CRLF
-
-references = "References:" 1*msg-id CRLF
-
-msg-id = [CFWS] "<" id-left "@" id-right ">" [CFWS]
-
-id-left = dot-atom-text / no-fold-quote / obs-id-left
-
-id-right = dot-atom-text / no-fold-literal / obs-id-right
-
-no-fold-quote = DQUOTE *(qtext / quoted-pair) DQUOTE
-
-
-
-Resnick Standards Track [Page 23]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-no-fold-literal = "[" *(dtext / quoted-pair) "]"
-
- The "Message-ID:" field provides a unique message identifier that
- refers to a particular version of a particular message. The
- uniqueness of the message identifier is guaranteed by the host that
- generates it (see below). This message identifier is intended to be
- machine readable and not necessarily meaningful to humans. A message
- identifier pertains to exactly one instantiation of a particular
- message; subsequent revisions to the message each receive new message
- identifiers.
-
- Note: There are many instances when messages are "changed", but those
- changes do not constitute a new instantiation of that message, and
- therefore the message would not get a new message identifier. For
- example, when messages are introduced into the transport system, they
- are often prepended with additional header fields such as trace
- fields (described in section 3.6.7) and resent fields (described in
- section 3.6.6). The addition of such header fields does not change
- the identity of the message and therefore the original "Message-ID:"
- field is retained. In all cases, it is the meaning that the sender
- of the message wishes to convey (i.e., whether this is the same
- message or a different message) that determines whether or not the
- "Message-ID:" field changes, not any particular syntactic difference
- that appears (or does not appear) in the message.
-
- The "In-Reply-To:" and "References:" fields are used when creating a
- reply to a message. They hold the message identifier of the original
- message and the message identifiers of other messages (for example,
- in the case of a reply to a message which was itself a reply). The
- "In-Reply-To:" field may be used to identify the message (or
- messages) to which the new message is a reply, while the
- "References:" field may be used to identify a "thread" of
- conversation.
-
- When creating a reply to a message, the "In-Reply-To:" and
- "References:" fields of the resultant message are constructed as
- follows:
-
- The "In-Reply-To:" field will contain the contents of the "Message-
- ID:" field of the message to which this one is a reply (the "parent
- message"). If there is more than one parent message, then the "In-
- Reply-To:" field will contain the contents of all of the parents'
- "Message-ID:" fields. If there is no "Message-ID:" field in any of
- the parent messages, then the new message will have no "In-Reply-To:"
- field.
-
-
-
-
-
-
-Resnick Standards Track [Page 24]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- The "References:" field will contain the contents of the parent's
- "References:" field (if any) followed by the contents of the parent's
- "Message-ID:" field (if any). If the parent message does not contain
- a "References:" field but does have an "In-Reply-To:" field
- containing a single message identifier, then the "References:" field
- will contain the contents of the parent's "In-Reply-To:" field
- followed by the contents of the parent's "Message-ID:" field (if
- any). If the parent has none of the "References:", "In-Reply-To:",
- or "Message-ID:" fields, then the new message will have no
- "References:" field.
-
- Note: Some implementations parse the "References:" field to display
- the "thread of the discussion". These implementations assume that
- each new message is a reply to a single parent and hence that they
- can walk backwards through the "References:" field to find the parent
- of each message listed there. Therefore, trying to form a
- "References:" field for a reply that has multiple parents is
- discouraged and how to do so is not defined in this document.
-
- The message identifier (msg-id) itself MUST be a globally unique
- identifier for a message. The generator of the message identifier
- MUST guarantee that the msg-id is unique. There are several
- algorithms that can be used to accomplish this. Since the msg-id has
- a similar syntax to angle-addr (identical except that comments and
- folding white space are not allowed), a good method is to put the
- domain name (or a domain literal IP address) of the host on which the
- message identifier was created on the right hand side of the "@", and
- put a combination of the current absolute date and time along with
- some other currently unique (perhaps sequential) identifier available
- on the system (for example, a process id number) on the left hand
- side. Using a date on the left hand side and a domain name or domain
- literal on the right hand side makes it possible to guarantee
- uniqueness since no two hosts use the same domain name or IP address
- at the same time. Though other algorithms will work, it is
- RECOMMENDED that the right hand side contain some domain identifier
- (either of the host itself or otherwise) such that the generator of
- the message identifier can guarantee the uniqueness of the left hand
- side within the scope of that domain.
-
- Semantically, the angle bracket characters are not part of the
- msg-id; the msg-id is what is contained between the two angle bracket
- characters.
-
-
-
-
-
-
-
-
-
-Resnick Standards Track [Page 25]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-3.6.5. Informational fields
-
- The informational fields are all optional. The "Keywords:" field
- contains a comma-separated list of one or more words or
- quoted-strings. The "Subject:" and "Comments:" fields are
- unstructured fields as defined in section 2.2.1, and therefore may
- contain text or folding white space.
-
-subject = "Subject:" unstructured CRLF
-
-comments = "Comments:" unstructured CRLF
-
-keywords = "Keywords:" phrase *("," phrase) CRLF
-
- These three fields are intended to have only human-readable content
- with information about the message. The "Subject:" field is the most
- common and contains a short string identifying the topic of the
- message. When used in a reply, the field body MAY start with the
- string "Re: " (from the Latin "res", in the matter of) followed by
- the contents of the "Subject:" field body of the original message.
- If this is done, only one instance of the literal string "Re: " ought
- to be used since use of other strings or more than one instance can
- lead to undesirable consequences. The "Comments:" field contains any
- additional comments on the text of the body of the message. The
- "Keywords:" field contains a comma-separated list of important words
- and phrases that might be useful for the recipient.
-
-3.6.6. Resent fields
-
- Resent fields SHOULD be added to any message that is reintroduced by
- a user into the transport system. A separate set of resent fields
- SHOULD be added each time this is done. All of the resent fields
- corresponding to a particular resending of the message SHOULD be
- together. Each new set of resent fields is prepended to the message;
- that is, the most recent set of resent fields appear earlier in the
- message. No other fields in the message are changed when resent
- fields are added.
-
- Each of the resent fields corresponds to a particular field elsewhere
- in the syntax. For instance, the "Resent-Date:" field corresponds to
- the "Date:" field and the "Resent-To:" field corresponds to the "To:"
- field. In each case, the syntax for the field body is identical to
- the syntax given previously for the corresponding field.
-
- When resent fields are used, the "Resent-From:" and "Resent-Date:"
- fields MUST be sent. The "Resent-Message-ID:" field SHOULD be sent.
- "Resent-Sender:" SHOULD NOT be used if "Resent-Sender:" would be
- identical to "Resent-From:".
-
-
-
-Resnick Standards Track [Page 26]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-resent-date = "Resent-Date:" date-time CRLF
-
-resent-from = "Resent-From:" mailbox-list CRLF
-
-resent-sender = "Resent-Sender:" mailbox CRLF
-
-resent-to = "Resent-To:" address-list CRLF
-
-resent-cc = "Resent-Cc:" address-list CRLF
-
-resent-bcc = "Resent-Bcc:" (address-list / [CFWS]) CRLF
-
-resent-msg-id = "Resent-Message-ID:" msg-id CRLF
-
- Resent fields are used to identify a message as having been
- reintroduced into the transport system by a user. The purpose of
- using resent fields is to have the message appear to the final
- recipient as if it were sent directly by the original sender, with
- all of the original fields remaining the same. Each set of resent
- fields correspond to a particular resending event. That is, if a
- message is resent multiple times, each set of resent fields gives
- identifying information for each individual time. Resent fields are
- strictly informational. They MUST NOT be used in the normal
- processing of replies or other such automatic actions on messages.
-
- Note: Reintroducing a message into the transport system and using
- resent fields is a different operation from "forwarding".
- "Forwarding" has two meanings: One sense of forwarding is that a mail
- reading program can be told by a user to forward a copy of a message
- to another person, making the forwarded message the body of the new
- message. A forwarded message in this sense does not appear to have
- come from the original sender, but is an entirely new message from
- the forwarder of the message. On the other hand, forwarding is also
- used to mean when a mail transport program gets a message and
- forwards it on to a different destination for final delivery. Resent
- header fields are not intended for use with either type of
- forwarding.
-
- The resent originator fields indicate the mailbox of the person(s) or
- system(s) that resent the message. As with the regular originator
- fields, there are two forms: a simple "Resent-From:" form which
- contains the mailbox of the individual doing the resending, and the
- more complex form, when one individual (identified in the
- "Resent-Sender:" field) resends a message on behalf of one or more
- others (identified in the "Resent-From:" field).
-
- Note: When replying to a resent message, replies behave just as they
- would with any other message, using the original "From:",
-
-
-
-Resnick Standards Track [Page 27]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- "Reply-To:", "Message-ID:", and other fields. The resent fields are
- only informational and MUST NOT be used in the normal processing of
- replies.
-
- The "Resent-Date:" indicates the date and time at which the resent
- message is dispatched by the resender of the message. Like the
- "Date:" field, it is not the date and time that the message was
- actually transported.
-
- The "Resent-To:", "Resent-Cc:", and "Resent-Bcc:" fields function
- identically to the "To:", "Cc:", and "Bcc:" fields respectively,
- except that they indicate the recipients of the resent message, not
- the recipients of the original message.
-
- The "Resent-Message-ID:" field provides a unique identifier for the
- resent message.
-
-3.6.7. Trace fields
-
- The trace fields are a group of header fields consisting of an
- optional "Return-Path:" field, and one or more "Received:" fields.
- The "Return-Path:" header field contains a pair of angle brackets
- that enclose an optional addr-spec. The "Received:" field contains a
- (possibly empty) list of name/value pairs followed by a semicolon and
- a date-time specification. The first item of the name/value pair is
- defined by item-name, and the second item is either an addr-spec, an
- atom, a domain, or a msg-id. Further restrictions may be applied to
- the syntax of the trace fields by standards that provide for their
- use, such as [RFC2821].
-
-trace = [return]
- 1*received
-
-return = "Return-Path:" path CRLF
-
-path = ([CFWS] "<" ([CFWS] / addr-spec) ">" [CFWS]) /
- obs-path
-
-received = "Received:" name-val-list ";" date-time CRLF
-
-name-val-list = [CFWS] [name-val-pair *(CFWS name-val-pair)]
-
-name-val-pair = item-name CFWS item-value
-
-item-name = ALPHA *(["-"] (ALPHA / DIGIT))
-
-item-value = 1*angle-addr / addr-spec /
- atom / domain / msg-id
-
-
-
-Resnick Standards Track [Page 28]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- A full discussion of the Internet mail use of trace fields is
- contained in [RFC2821]. For the purposes of this standard, the trace
- fields are strictly informational, and any formal interpretation of
- them is outside of the scope of this document.
-
-3.6.8. Optional fields
-
- Fields may appear in messages that are otherwise unspecified in this
- standard. They MUST conform to the syntax of an optional-field.
- This is a field name, made up of the printable US-ASCII characters
- except SP and colon, followed by a colon, followed by any text which
- conforms to unstructured.
-
- The field names of any optional-field MUST NOT be identical to any
- field name specified elsewhere in this standard.
-
-optional-field = field-name ":" unstructured CRLF
-
-field-name = 1*ftext
-
-ftext = %d33-57 / ; Any character except
- %d59-126 ; controls, SP, and
- ; ":".
-
- For the purposes of this standard, any optional field is
- uninterpreted.
-
-4. Obsolete Syntax
-
- Earlier versions of this standard allowed for different (usually more
- liberal) syntax than is allowed in this version. Also, there have
- been syntactic elements used in messages on the Internet whose
- interpretation have never been documented. Though some of these
- syntactic forms MUST NOT be generated according to the grammar in
- section 3, they MUST be accepted and parsed by a conformant receiver.
- This section documents many of these syntactic elements. Taking the
- grammar in section 3 and adding the definitions presented in this
- section will result in the grammar to use for interpretation of
- messages.
-
- Note: This section identifies syntactic forms that any implementation
- MUST reasonably interpret. However, there are certainly Internet
- messages which do not conform to even the additional syntax given in
- this section. The fact that a particular form does not appear in any
- section of this document is not justification for computer programs
- to crash or for malformed data to be irretrievably lost by any
- implementation. To repeat an example, though this document requires
- lines in messages to be no longer than 998 characters, silently
-
-
-
-Resnick Standards Track [Page 29]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- discarding the 999th and subsequent characters in a line without
- warning would still be bad behavior for an implementation. It is up
- to the implementation to deal with messages robustly.
-
- One important difference between the obsolete (interpreting) and the
- current (generating) syntax is that in structured header field bodies
- (i.e., between the colon and the CRLF of any structured header
- field), white space characters, including folding white space, and
- comments can be freely inserted between any syntactic tokens. This
- allows many complex forms that have proven difficult for some
- implementations to parse.
-
- Another key difference between the obsolete and the current syntax is
- that the rule in section 3.2.3 regarding lines composed entirely of
- white space in comments and folding white space does not apply. See
- the discussion of folding white space in section 4.2 below.
-
- Finally, certain characters that were formerly allowed in messages
- appear in this section. The NUL character (ASCII value 0) was once
- allowed, but is no longer for compatibility reasons. CR and LF were
- allowed to appear in messages other than as CRLF; this use is also
- shown here.
-
- Other differences in syntax and semantics are noted in the following
- sections.
-
-4.1. Miscellaneous obsolete tokens
-
- These syntactic elements are used elsewhere in the obsolete syntax or
- in the main syntax. The obs-char and obs-qp elements each add ASCII
- value 0. Bare CR and bare LF are added to obs-text and obs-utext.
- The period character is added to obs-phrase. The obs-phrase-list
- provides for "empty" elements in a comma-separated list of phrases.
-
- Note: The "period" (or "full stop") character (".") in obs-phrase is
- not a form that was allowed in earlier versions of this or any other
- standard. Period (nor any other character from specials) was not
- allowed in phrase because it introduced a parsing difficulty
- distinguishing between phrases and portions of an addr-spec (see
- section 4.4). It appears here because the period character is
- currently used in many messages in the display-name portion of
- addresses, especially for initials in names, and therefore must be
- interpreted properly. In the future, period may appear in the
- regular syntax of phrase.
-
-obs-qp = "\" (%d0-127)
-
-obs-text = *LF *CR *(obs-char *LF *CR)
-
-
-
-Resnick Standards Track [Page 30]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-obs-char = %d0-9 / %d11 / ; %d0-127 except CR and
- %d12 / %d14-127 ; LF
-
-obs-utext = obs-text
-
-obs-phrase = word *(word / "." / CFWS)
-
-obs-phrase-list = phrase / 1*([phrase] [CFWS] "," [CFWS]) [phrase]
-
- Bare CR and bare LF appear in messages with two different meanings.
- In many cases, bare CR or bare LF are used improperly instead of CRLF
- to indicate line separators. In other cases, bare CR and bare LF are
- used simply as ASCII control characters with their traditional ASCII
- meanings.
-
-4.2. Obsolete folding white space
-
- In the obsolete syntax, any amount of folding white space MAY be
- inserted where the obs-FWS rule is allowed. This creates the
- possibility of having two consecutive "folds" in a line, and
- therefore the possibility that a line which makes up a folded header
- field could be composed entirely of white space.
-
- obs-FWS = 1*WSP *(CRLF 1*WSP)
-
-4.3. Obsolete Date and Time
-
- The syntax for the obsolete date format allows a 2 digit year in the
- date field and allows for a list of alphabetic time zone
- specifications that were used in earlier versions of this standard.
- It also permits comments and folding white space between many of the
- tokens.
-
-obs-day-of-week = [CFWS] day-name [CFWS]
-
-obs-year = [CFWS] 2*DIGIT [CFWS]
-
-obs-month = CFWS month-name CFWS
-
-obs-day = [CFWS] 1*2DIGIT [CFWS]
-
-obs-hour = [CFWS] 2DIGIT [CFWS]
-
-obs-minute = [CFWS] 2DIGIT [CFWS]
-
-obs-second = [CFWS] 2DIGIT [CFWS]
-
-obs-zone = "UT" / "GMT" / ; Universal Time
-
-
-
-Resnick Standards Track [Page 31]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- ; North American UT
- ; offsets
- "EST" / "EDT" / ; Eastern: - 5/ - 4
- "CST" / "CDT" / ; Central: - 6/ - 5
- "MST" / "MDT" / ; Mountain: - 7/ - 6
- "PST" / "PDT" / ; Pacific: - 8/ - 7
-
- %d65-73 / ; Military zones - "A"
- %d75-90 / ; through "I" and "K"
- %d97-105 / ; through "Z", both
- %d107-122 ; upper and lower case
-
- Where a two or three digit year occurs in a date, the year is to be
- interpreted as follows: If a two digit year is encountered whose
- value is between 00 and 49, the year is interpreted by adding 2000,
- ending up with a value between 2000 and 2049. If a two digit year is
- encountered with a value between 50 and 99, or any three digit year
- is encountered, the year is interpreted by adding 1900.
-
- In the obsolete time zone, "UT" and "GMT" are indications of
- "Universal Time" and "Greenwich Mean Time" respectively and are both
- semantically identical to "+0000".
-
- The remaining three character zones are the US time zones. The first
- letter, "E", "C", "M", or "P" stands for "Eastern", "Central",
- "Mountain" and "Pacific". The second letter is either "S" for
- "Standard" time, or "D" for "Daylight" (or summer) time. Their
- interpretations are as follows:
-
- EDT is semantically equivalent to -0400
- EST is semantically equivalent to -0500
- CDT is semantically equivalent to -0500
- CST is semantically equivalent to -0600
- MDT is semantically equivalent to -0600
- MST is semantically equivalent to -0700
- PDT is semantically equivalent to -0700
- PST is semantically equivalent to -0800
-
- The 1 character military time zones were defined in a non-standard
- way in [RFC822] and are therefore unpredictable in their meaning.
- The original definitions of the military zones "A" through "I" are
- equivalent to "+0100" through "+0900" respectively; "K", "L", and "M"
- are equivalent to "+1000", "+1100", and "+1200" respectively; "N"
- through "Y" are equivalent to "-0100" through "-1200" respectively;
- and "Z" is equivalent to "+0000". However, because of the error in
- [RFC822], they SHOULD all be considered equivalent to "-0000" unless
- there is out-of-band information confirming their meaning.
-
-
-
-
-Resnick Standards Track [Page 32]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- Other multi-character (usually between 3 and 5) alphabetic time zones
- have been used in Internet messages. Any such time zone whose
- meaning is not known SHOULD be considered equivalent to "-0000"
- unless there is out-of-band information confirming their meaning.
-
-4.4. Obsolete Addressing
-
- There are three primary differences in addressing. First, mailbox
- addresses were allowed to have a route portion before the addr-spec
- when enclosed in "<" and ">". The route is simply a comma-separated
- list of domain names, each preceded by "@", and the list terminated
- by a colon. Second, CFWS were allowed between the period-separated
- elements of local-part and domain (i.e., dot-atom was not used). In
- addition, local-part is allowed to contain quoted-string in addition
- to just atom. Finally, mailbox-list and address-list were allowed to
- have "null" members. That is, there could be two or more commas in
- such a list with nothing in between them.
-
-obs-angle-addr = [CFWS] "<" [obs-route] addr-spec ">" [CFWS]
-
-obs-route = [CFWS] obs-domain-list ":" [CFWS]
-
-obs-domain-list = "@" domain *(*(CFWS / "," ) [CFWS] "@" domain)
-
-obs-local-part = word *("." word)
-
-obs-domain = atom *("." atom)
-
-obs-mbox-list = 1*([mailbox] [CFWS] "," [CFWS]) [mailbox]
-
-obs-addr-list = 1*([address] [CFWS] "," [CFWS]) [address]
-
- When interpreting addresses, the route portion SHOULD be ignored.
-
-4.5. Obsolete header fields
-
- Syntactically, the primary difference in the obsolete field syntax is
- that it allows multiple occurrences of any of the fields and they may
- occur in any order. Also, any amount of white space is allowed
- before the ":" at the end of the field name.
-
-obs-fields = *(obs-return /
- obs-received /
- obs-orig-date /
- obs-from /
- obs-sender /
- obs-reply-to /
- obs-to /
-
-
-
-Resnick Standards Track [Page 33]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- obs-cc /
- obs-bcc /
- obs-message-id /
- obs-in-reply-to /
- obs-references /
- obs-subject /
- obs-comments /
- obs-keywords /
- obs-resent-date /
- obs-resent-from /
- obs-resent-send /
- obs-resent-rply /
- obs-resent-to /
- obs-resent-cc /
- obs-resent-bcc /
- obs-resent-mid /
- obs-optional)
-
- Except for destination address fields (described in section 4.5.3),
- the interpretation of multiple occurrences of fields is unspecified.
- Also, the interpretation of trace fields and resent fields which do
- not occur in blocks prepended to the message is unspecified as well.
- Unless otherwise noted in the following sections, interpretation of
- other fields is identical to the interpretation of their non-obsolete
- counterparts in section 3.
-
-4.5.1. Obsolete origination date field
-
-obs-orig-date = "Date" *WSP ":" date-time CRLF
-
-4.5.2. Obsolete originator fields
-
-obs-from = "From" *WSP ":" mailbox-list CRLF
-
-obs-sender = "Sender" *WSP ":" mailbox CRLF
-
-obs-reply-to = "Reply-To" *WSP ":" mailbox-list CRLF
-
-4.5.3. Obsolete destination address fields
-
-obs-to = "To" *WSP ":" address-list CRLF
-
-obs-cc = "Cc" *WSP ":" address-list CRLF
-
-obs-bcc = "Bcc" *WSP ":" (address-list / [CFWS]) CRLF
-
-
-
-
-
-
-Resnick Standards Track [Page 34]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- When multiple occurrences of destination address fields occur in a
- message, they SHOULD be treated as if the address-list in the first
- occurrence of the field is combined with the address lists of the
- subsequent occurrences by adding a comma and concatenating.
-
-4.5.4. Obsolete identification fields
-
- The obsolete "In-Reply-To:" and "References:" fields differ from the
- current syntax in that they allow phrase (words or quoted strings) to
- appear. The obsolete forms of the left and right sides of msg-id
- allow interspersed CFWS, making them syntactically identical to
- local-part and domain respectively.
-
-obs-message-id = "Message-ID" *WSP ":" msg-id CRLF
-
-obs-in-reply-to = "In-Reply-To" *WSP ":" *(phrase / msg-id) CRLF
-
-obs-references = "References" *WSP ":" *(phrase / msg-id) CRLF
-
-obs-id-left = local-part
-
-obs-id-right = domain
-
- For purposes of interpretation, the phrases in the "In-Reply-To:" and
- "References:" fields are ignored.
-
- Semantically, none of the optional CFWS surrounding the local-part
- and the domain are part of the obs-id-left and obs-id-right
- respectively.
-
-4.5.5. Obsolete informational fields
-
-obs-subject = "Subject" *WSP ":" unstructured CRLF
-
-obs-comments = "Comments" *WSP ":" unstructured CRLF
-
-obs-keywords = "Keywords" *WSP ":" obs-phrase-list CRLF
-
-4.5.6. Obsolete resent fields
-
- The obsolete syntax adds a "Resent-Reply-To:" field, which consists
- of the field name, the optional comments and folding white space, the
- colon, and a comma separated list of addresses.
-
-obs-resent-from = "Resent-From" *WSP ":" mailbox-list CRLF
-
-obs-resent-send = "Resent-Sender" *WSP ":" mailbox CRLF
-
-
-
-
-Resnick Standards Track [Page 35]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-obs-resent-date = "Resent-Date" *WSP ":" date-time CRLF
-
-obs-resent-to = "Resent-To" *WSP ":" address-list CRLF
-
-obs-resent-cc = "Resent-Cc" *WSP ":" address-list CRLF
-
-obs-resent-bcc = "Resent-Bcc" *WSP ":"
- (address-list / [CFWS]) CRLF
-
-obs-resent-mid = "Resent-Message-ID" *WSP ":" msg-id CRLF
-
-obs-resent-rply = "Resent-Reply-To" *WSP ":" address-list CRLF
-
- As with other resent fields, the "Resent-Reply-To:" field is to be
- treated as trace information only.
-
-4.5.7. Obsolete trace fields
-
- The obs-return and obs-received are again given here as template
- definitions, just as return and received are in section 3. Their
- full syntax is given in [RFC2821].
-
-obs-return = "Return-Path" *WSP ":" path CRLF
-
-obs-received = "Received" *WSP ":" name-val-list CRLF
-
-obs-path = obs-angle-addr
-
-4.5.8. Obsolete optional fields
-
-obs-optional = field-name *WSP ":" unstructured CRLF
-
-5. Security Considerations
-
- Care needs to be taken when displaying messages on a terminal or
- terminal emulator. Powerful terminals may act on escape sequences
- and other combinations of ASCII control characters with a variety of
- consequences. They can remap the keyboard or permit other
- modifications to the terminal which could lead to denial of service
- or even damaged data. They can trigger (sometimes programmable)
- answerback messages which can allow a message to cause commands to be
- issued on the recipient's behalf. They can also effect the operation
- of terminal attached devices such as printers. Message viewers may
- wish to strip potentially dangerous terminal escape sequences from
- the message prior to display. However, other escape sequences appear
- in messages for useful purposes (cf. [RFC2045, RFC2046, RFC2047,
- RFC2048, RFC2049, ISO2022]) and therefore should not be stripped
- indiscriminately.
-
-
-
-Resnick Standards Track [Page 36]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- Transmission of non-text objects in messages raises additional
- security issues. These issues are discussed in [RFC2045, RFC2046,
- RFC2047, RFC2048, RFC2049].
-
- Many implementations use the "Bcc:" (blind carbon copy) field
- described in section 3.6.3 to facilitate sending messages to
- recipients without revealing the addresses of one or more of the
- addressees to the other recipients. Mishandling this use of "Bcc:"
- has implications for confidential information that might be revealed,
- which could eventually lead to security problems through knowledge of
- even the existence of a particular mail address. For example, if
- using the first method described in section 3.6.3, where the "Bcc:"
- line is removed from the message, blind recipients have no explicit
- indication that they have been sent a blind copy, except insofar as
- their address does not appear in the message header. Because of
- this, one of the blind addressees could potentially send a reply to
- all of the shown recipients and accidentally reveal that the message
- went to the blind recipient. When the second method from section
- 3.6.3 is used, the blind recipient's address appears in the "Bcc:"
- field of a separate copy of the message. If the "Bcc:" field sent
- contains all of the blind addressees, all of the "Bcc:" recipients
- will be seen by each "Bcc:" recipient. Even if a separate message is
- sent to each "Bcc:" recipient with only the individual's address,
- implementations still need to be careful to process replies to the
- message as per section 3.6.3 so as not to accidentally reveal the
- blind recipient to other recipients.
-
-6. Bibliography
-
- [ASCII] American National Standards Institute (ANSI), Coded
- Character Set - 7-Bit American National Standard Code for
- Information Interchange, ANSI X3.4, 1986.
-
- [ISO2022] International Organization for Standardization (ISO),
- Information processing - ISO 7-bit and 8-bit coded
- character sets - Code extension techniques, Third edition
- - 1986-05-01, ISO 2022, 1986.
-
- [RFC822] Crocker, D., "Standard for the Format of ARPA Internet
- Text Messages", RFC 822, August 1982.
-
- [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part One: Format of Internet Message
- Bodies", RFC 2045, November 1996.
-
- [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part Two: Media Types", RFC 2046,
- November 1996.
-
-
-
-Resnick Standards Track [Page 37]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- [RFC2047] Moore, K., "Multipurpose Internet Mail Extensions (MIME)
- Part Three: Message Header Extensions for Non-ASCII Text",
- RFC 2047, November 1996.
-
- [RFC2048] Freed, N., Klensin, J. and J. Postel, "Multipurpose
- Internet Mail Extensions (MIME) Part Four: Format of
- Internet Message Bodies", RFC 2048, November 1996.
-
- [RFC2049] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part Five: Conformance Criteria and
- Examples", RFC 2049, November 1996.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2234] Crocker, D., Editor, and P. Overell, "Augmented BNF for
- Syntax Specifications: ABNF", RFC 2234, November 1997.
-
- [RFC2821] Klensin, J., Editor, "Simple Mail Transfer Protocol", RFC
- 2821, March 2001.
-
- [STD3] Braden, R., "Host Requirements", STD 3, RFC 1122 and RFC
- 1123, October 1989.
-
- [STD12] Mills, D., "Network Time Protocol", STD 12, RFC 1119,
- September 1989.
-
- [STD13] Mockapetris, P., "Domain Name System", STD 13, RFC 1034
- and RFC 1035, November 1987.
-
- [STD14] Partridge, C., "Mail Routing and the Domain System", STD
- 14, RFC 974, January 1986.
-
-7. Editor's Address
-
- Peter W. Resnick
- QUALCOMM Incorporated
- 5775 Morehouse Drive
- San Diego, CA 92121-1714
- USA
-
- Phone: +1 858 651 4478
- Fax: +1 858 651 1102
- EMail: presnick@qualcomm.com
-
-
-
-
-
-
-
-Resnick Standards Track [Page 38]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-8. Acknowledgements
-
- Many people contributed to this document. They included folks who
- participated in the Detailed Revision and Update of Messaging
- Standards (DRUMS) Working Group of the Internet Engineering Task
- Force (IETF), the chair of DRUMS, the Area Directors of the IETF, and
- people who simply sent their comments in via e-mail. The editor is
- deeply indebted to them all and thanks them sincerely. The below
- list includes everyone who sent e-mail concerning this document.
- Hopefully, everyone who contributed is named here:
-
- Matti Aarnio Barry Finkel Larry Masinter
- Tanaka Akira Erik Forsberg Denis McKeon
- Russ Allbery Chuck Foster William P McQuillan
- Eric Allman Paul Fox Alexey Melnikov
- Harald Tveit Alvestrand Klaus M. Frank Perry E. Metzger
- Ran Atkinson Ned Freed Steven Miller
- Jos Backus Jochen Friedrich Keith Moore
- Bruce Balden Randall C. Gellens John Gardiner Myers
- Dave Barr Sukvinder Singh Gill Chris Newman
- Alan Barrett Tim Goodwin John W. Noerenberg
- John Beck Philip Guenther Eric Norman
- J. Robert von Behren Tony Hansen Mike O'Dell
- Jos den Bekker John Hawkinson Larry Osterman
- D. J. Bernstein Philip Hazel Paul Overell
- James Berriman Kai Henningsen Jacob Palme
- Norbert Bollow Robert Herriot Michael A. Patton
- Raj Bose Paul Hethmon Uzi Paz
- Antony Bowesman Jim Hill Michael A. Quinlan
- Scott Bradner Paul E. Hoffman Eric S. Raymond
- Randy Bush Steve Hole Sam Roberts
- Tom Byrer Kari Hurtta Hugh Sasse
- Bruce Campbell Marco S. Hyman Bart Schaefer
- Larry Campbell Ofer Inbar Tom Scola
- W. J. Carpenter Olle Jarnefors Wolfgang Segmuller
- Michael Chapman Kevin Johnson Nick Shelness
- Richard Clayton Sudish Joseph John Stanley
- Maurizio Codogno Maynard Kang Einar Stefferud
- Jim Conklin Prabhat Keni Jeff Stephenson
- R. Kelley Cook John C. Klensin Bernard Stern
- Steve Coya Graham Klyne Peter Sylvester
- Mark Crispin Brad Knowles Mark Symons
- Dave Crocker Shuhei Kobayashi Eric Thomas
- Matt Curtin Peter Koch Lee Thompson
- Michael D'Errico Dan Kohn Karel De Vriendt
- Cyrus Daboo Christian Kuhtz Matthew Wall
- Jutta Degener Anand Kumria Rolf Weber
- Mark Delany Steen Larsen Brent B. Welch
-
-
-
-Resnick Standards Track [Page 39]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- Steve Dorner Eliot Lear Dan Wing
- Harold A. Driscoll Barry Leiba Jack De Winter
- Michael Elkins Jay Levitt Gregory J. Woodhouse
- Robert Elz Lars-Johan Liman Greg A. Woods
- Johnny Eriksson Charles Lindsey Kazu Yamamoto
- Erik E. Fair Pete Loshin Alain Zahm
- Roger Fajman Simon Lyall Jamie Zawinski
- Patrik Faltstrom Bill Manning Timothy S. Zurcher
- Claus Andre Farber John Martin
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Resnick Standards Track [Page 40]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-Appendix A. Example messages
-
- This section presents a selection of messages. These are intended to
- assist in the implementation of this standard, but should not be
- taken as normative; that is to say, although the examples in this
- section were carefully reviewed, if there happens to be a conflict
- between these examples and the syntax described in sections 3 and 4
- of this document, the syntax in those sections is to be taken as
- correct.
-
- Messages are delimited in this section between lines of "----". The
- "----" lines are not part of the message itself.
-
-A.1. Addressing examples
-
- The following are examples of messages that might be sent between two
- individuals.
-
-A.1.1. A message from one person to another with simple addressing
-
- This could be called a canonical message. It has a single author,
- John Doe, a single recipient, Mary Smith, a subject, the date, a
- message identifier, and a textual message in the body.
-
-----
-From: John Doe <jdoe@machine.example>
-To: Mary Smith <mary@example.net>
-Subject: Saying Hello
-Date: Fri, 21 Nov 1997 09:55:06 -0600
-Message-ID: <1234@local.machine.example>
-
-This is a message just to say hello.
-So, "Hello".
-----
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Resnick Standards Track [Page 41]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- If John's secretary Michael actually sent the message, though John
- was the author and replies to this message should go back to him, the
- sender field would be used:
-
-----
-From: John Doe <jdoe@machine.example>
-Sender: Michael Jones <mjones@machine.example>
-To: Mary Smith <mary@example.net>
-Subject: Saying Hello
-Date: Fri, 21 Nov 1997 09:55:06 -0600
-Message-ID: <1234@local.machine.example>
-
-This is a message just to say hello.
-So, "Hello".
-----
-
-A.1.2. Different types of mailboxes
-
- This message includes multiple addresses in the destination fields
- and also uses several different forms of addresses.
-
-----
-From: "Joe Q. Public" <john.q.public@example.com>
-To: Mary Smith <mary@x.test>, jdoe@example.org, Who? <one@y.test>
-Cc: <boss@nil.test>, "Giant; \"Big\" Box" <sysservices@example.net>
-Date: Tue, 1 Jul 2003 10:52:37 +0200
-Message-ID: <5678.21-Nov-1997@example.com>
-
-Hi everyone.
-----
-
- Note that the display names for Joe Q. Public and Giant; "Big" Box
- needed to be enclosed in double-quotes because the former contains
- the period and the latter contains both semicolon and double-quote
- characters (the double-quote characters appearing as quoted-pair
- construct). Conversely, the display name for Who? could appear
- without them because the question mark is legal in an atom. Notice
- also that jdoe@example.org and boss@nil.test have no display names
- associated with them at all, and jdoe@example.org uses the simpler
- address form without the angle brackets.
-
-
-
-
-
-
-
-
-
-
-
-Resnick Standards Track [Page 42]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-A.1.3. Group addresses
-
-----
-From: Pete <pete@silly.example>
-To: A Group:Chris Jones <c@a.test>,joe@where.test,John <jdoe@one.test>;
-Cc: Undisclosed recipients:;
-Date: Thu, 13 Feb 1969 23:32:54 -0330
-Message-ID: <testabcd.1234@silly.example>
-
-Testing.
-----
-
- In this message, the "To:" field has a single group recipient named A
- Group which contains 3 addresses, and a "Cc:" field with an empty
- group recipient named Undisclosed recipients.
-
-A.2. Reply messages
-
- The following is a series of three messages that make up a
- conversation thread between John and Mary. John firsts sends a
- message to Mary, Mary then replies to John's message, and then John
- replies to Mary's reply message.
-
- Note especially the "Message-ID:", "References:", and "In-Reply-To:"
- fields in each message.
-
-----
-From: John Doe <jdoe@machine.example>
-To: Mary Smith <mary@example.net>
-Subject: Saying Hello
-Date: Fri, 21 Nov 1997 09:55:06 -0600
-Message-ID: <1234@local.machine.example>
-
-This is a message just to say hello.
-So, "Hello".
-----
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Resnick Standards Track [Page 43]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- When sending replies, the Subject field is often retained, though
- prepended with "Re: " as described in section 3.6.5.
-
-----
-From: Mary Smith <mary@example.net>
-To: John Doe <jdoe@machine.example>
-Reply-To: "Mary Smith: Personal Account" <smith@home.example>
-Subject: Re: Saying Hello
-Date: Fri, 21 Nov 1997 10:01:10 -0600
-Message-ID: <3456@example.net>
-In-Reply-To: <1234@local.machine.example>
-References: <1234@local.machine.example>
-
-This is a reply to your hello.
-----
-
- Note the "Reply-To:" field in the above message. When John replies
- to Mary's message above, the reply should go to the address in the
- "Reply-To:" field instead of the address in the "From:" field.
-
-----
-To: "Mary Smith: Personal Account" <smith@home.example>
-From: John Doe <jdoe@machine.example>
-Subject: Re: Saying Hello
-Date: Fri, 21 Nov 1997 11:00:00 -0600
-Message-ID: <abcd.1234@local.machine.tld>
-In-Reply-To: <3456@example.net>
-References: <1234@local.machine.example> <3456@example.net>
-
-This is a reply to your reply.
-----
-
-A.3. Resent messages
-
- Start with the message that has been used as an example several
- times:
-
-----
-From: John Doe <jdoe@machine.example>
-To: Mary Smith <mary@example.net>
-Subject: Saying Hello
-Date: Fri, 21 Nov 1997 09:55:06 -0600
-Message-ID: <1234@local.machine.example>
-
-This is a message just to say hello.
-So, "Hello".
-----
-
-
-
-
-Resnick Standards Track [Page 44]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- Say that Mary, upon receiving this message, wishes to send a copy of
- the message to Jane such that (a) the message would appear to have
- come straight from John; (b) if Jane replies to the message, the
- reply should go back to John; and (c) all of the original
- information, like the date the message was originally sent to Mary,
- the message identifier, and the original addressee, is preserved. In
- this case, resent fields are prepended to the message:
-
-----
-Resent-From: Mary Smith <mary@example.net>
-Resent-To: Jane Brown <j-brown@other.example>
-Resent-Date: Mon, 24 Nov 1997 14:22:01 -0800
-Resent-Message-ID: <78910@example.net>
-From: John Doe <jdoe@machine.example>
-To: Mary Smith <mary@example.net>
-Subject: Saying Hello
-Date: Fri, 21 Nov 1997 09:55:06 -0600
-Message-ID: <1234@local.machine.example>
-
-This is a message just to say hello.
-So, "Hello".
-----
-
- If Jane, in turn, wished to resend this message to another person,
- she would prepend her own set of resent header fields to the above
- and send that.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Resnick Standards Track [Page 45]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-A.4. Messages with trace fields
-
- As messages are sent through the transport system as described in
- [RFC2821], trace fields are prepended to the message. The following
- is an example of what those trace fields might look like. Note that
- there is some folding white space in the first one since these lines
- can be long.
-
-----
-Received: from x.y.test
- by example.net
- via TCP
- with ESMTP
- id ABC12345
- for <mary@example.net>; 21 Nov 1997 10:05:43 -0600
-Received: from machine.example by x.y.test; 21 Nov 1997 10:01:22 -0600
-From: John Doe <jdoe@machine.example>
-To: Mary Smith <mary@example.net>
-Subject: Saying Hello
-Date: Fri, 21 Nov 1997 09:55:06 -0600
-Message-ID: <1234@local.machine.example>
-
-This is a message just to say hello.
-So, "Hello".
-----
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Resnick Standards Track [Page 46]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-A.5. White space, comments, and other oddities
-
- White space, including folding white space, and comments can be
- inserted between many of the tokens of fields. Taking the example
- from A.1.3, white space and comments can be inserted into all of the
- fields.
-
-----
-From: Pete(A wonderful \) chap) <pete(his account)@silly.test(his host)>
-To:A Group(Some people)
- :Chris Jones <c@(Chris's host.)public.example>,
- joe@example.org,
- John <jdoe@one.test> (my dear friend); (the end of the group)
-Cc:(Empty list)(start)Undisclosed recipients :(nobody(that I know)) ;
-Date: Thu,
- 13
- Feb
- 1969
- 23:32
- -0330 (Newfoundland Time)
-Message-ID: <testabcd.1234@silly.test>
-
-Testing.
-----
-
- The above example is aesthetically displeasing, but perfectly legal.
- Note particularly (1) the comments in the "From:" field (including
- one that has a ")" character appearing as part of a quoted-pair); (2)
- the white space absent after the ":" in the "To:" field as well as
- the comment and folding white space after the group name, the special
- character (".") in the comment in Chris Jones's address, and the
- folding white space before and after "joe@example.org,"; (3) the
- multiple and nested comments in the "Cc:" field as well as the
- comment immediately following the ":" after "Cc"; (4) the folding
- white space (but no comments except at the end) and the missing
- seconds in the time of the date field; and (5) the white space before
- (but not within) the identifier in the "Message-ID:" field.
-
-A.6. Obsoleted forms
-
- The following are examples of obsolete (that is, the "MUST NOT
- generate") syntactic elements described in section 4 of this
- document.
-
-
-
-
-
-
-
-
-Resnick Standards Track [Page 47]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-A.6.1. Obsolete addressing
-
- Note in the below example the lack of quotes around Joe Q. Public,
- the route that appears in the address for Mary Smith, the two commas
- that appear in the "To:" field, and the spaces that appear around the
- "." in the jdoe address.
-
-----
-From: Joe Q. Public <john.q.public@example.com>
-To: Mary Smith <@machine.tld:mary@example.net>, , jdoe@test . example
-Date: Tue, 1 Jul 2003 10:52:37 +0200
-Message-ID: <5678.21-Nov-1997@example.com>
-
-Hi everyone.
-----
-
-A.6.2. Obsolete dates
-
- The following message uses an obsolete date format, including a non-
- numeric time zone and a two digit year. Note that although the
- day-of-week is missing, that is not specific to the obsolete syntax;
- it is optional in the current syntax as well.
-
-----
-From: John Doe <jdoe@machine.example>
-To: Mary Smith <mary@example.net>
-Subject: Saying Hello
-Date: 21 Nov 97 09:55:06 GMT
-Message-ID: <1234@local.machine.example>
-
-This is a message just to say hello.
-So, "Hello".
-----
-
-A.6.3. Obsolete white space and comments
-
- White space and comments can appear between many more elements than
- in the current syntax. Also, folding lines that are made up entirely
- of white space are legal.
-
-
-
-
-
-
-
-
-
-
-
-
-Resnick Standards Track [Page 48]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-----
-From : John Doe <jdoe@machine(comment). example>
-To : Mary Smith
-__
- <mary@example.net>
-Subject : Saying Hello
-Date : Fri, 21 Nov 1997 09(comment): 55 : 06 -0600
-Message-ID : <1234 @ local(blah) .machine .example>
-
-This is a message just to say hello.
-So, "Hello".
-----
-
- Note especially the second line of the "To:" field. It starts with
- two space characters. (Note that "__" represent blank spaces.)
- Therefore, it is considered part of the folding as described in
- section 4.2. Also, the comments and white space throughout
- addresses, dates, and message identifiers are all part of the
- obsolete syntax.
-
-Appendix B. Differences from earlier standards
-
- This appendix contains a list of changes that have been made in the
- Internet Message Format from earlier standards, specifically [RFC822]
- and [STD3]. Items marked with an asterisk (*) below are items which
- appear in section 4 of this document and therefore can no longer be
- generated.
-
- 1. Period allowed in obsolete form of phrase.
- 2. ABNF moved out of document to [RFC2234].
- 3. Four or more digits allowed for year.
- 4. Header field ordering (and lack thereof) made explicit.
- 5. Encrypted header field removed.
- 6. Received syntax loosened to allow any token/value pair.
- 7. Specifically allow and give meaning to "-0000" time zone.
- 8. Folding white space is not allowed between every token.
- 9. Requirement for destinations removed.
- 10. Forwarding and resending redefined.
- 11. Extension header fields no longer specifically called out.
- 12. ASCII 0 (null) removed.*
- 13. Folding continuation lines cannot contain only white space.*
- 14. Free insertion of comments not allowed in date.*
- 15. Non-numeric time zones not allowed.*
- 16. Two digit years not allowed.*
- 17. Three digit years interpreted, but not allowed for generation.
- 18. Routes in addresses not allowed.*
- 19. CFWS within local-parts and domains not allowed.*
- 20. Empty members of address lists not allowed.*
-
-
-
-Resnick Standards Track [Page 49]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
- 21. Folding white space between field name and colon not allowed.*
- 22. Comments between field name and colon not allowed.
- 23. Tightened syntax of in-reply-to and references.*
- 24. CFWS within msg-id not allowed.*
- 25. Tightened semantics of resent fields as informational only.
- 26. Resent-Reply-To not allowed.*
- 27. No multiple occurrences of fields (except resent and received).*
- 28. Free CR and LF not allowed.*
- 29. Routes in return path not allowed.*
- 30. Line length limits specified.
- 31. Bcc more clearly specified.
-
-Appendix C. Notices
-
- Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- intellectual property or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; neither does it represent that it
- has made any effort to identify any such rights. Information on the
- IETF's procedures with respect to rights in standards-track and
- standards-related documentation can be found in BCP-11. Copies of
- claims of rights made available for publication and any assurances of
- licenses to be made available, or the result of an attempt made to
- obtain a general license or permission for the use of such
- proprietary rights by implementors or users of this specification can
- be obtained from the IETF Secretariat.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Resnick Standards Track [Page 50]
-\f
-RFC 2822 Internet Message Format April 2001
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2001). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Resnick Standards Track [Page 51]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group R. Herriot, Editor
-Request for Comments: 2910 Xerox Corporation
-Obsoletes: 2565 S. Butler
-Category: Standards Track Hewlett-Packard
- P. Moore
- Peerless Systems Networking
- R. Turner
- 2wire.com
- J. Wenn
- Xerox Corporation
- September 2000
-
-
- Internet Printing Protocol/1.1: Encoding and Transport
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2000). All Rights Reserved.
-
-Abstract
-
- This document is one of a set of documents, which together describe
- all aspects of a new Internet Printing Protocol (IPP). IPP is an
- application level protocol that can be used for distributed printing
- using Internet tools and technologies. This document defines the
- rules for encoding IPP operations and IPP attributes into a new
- Internet mime media type called "application/ipp". This document
- also defines the rules for transporting over Hypertext Transfer
- Protocol (HTTP) a message body whose Content-Type is
- "application/ipp". This document defines a new scheme named 'ipp' for
- identifying IPP printers and jobs.
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 1]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- The full set of IPP documents includes:
-
- Design Goals for an Internet Printing Protocol [RFC2567]
- Rationale for the Structure and Model and Protocol for the Internet
- Printing Protocol [RFC2568]
- Internet Printing Protocol/1.1: Model and Semantics [RFC2911]
- Internet Printing Protocol/1.1: Encoding and Transport (this
- document)
- Internet Printing Protocol/1.1: Implementer's Guide [ipp-iig]
- Mapping between LPD and IPP Protocols [RFC2569]
-
- The document, "Design Goals for an Internet Printing Protocol", takes
- a broad look at distributed printing functionality, and it enumerates
- real-life scenarios that help to clarify the features that need to be
- included in a printing protocol for the Internet. It identifies
- requirements for three types of users: end users, operators, and
- administrators. It calls out a subset of end user requirements that
- are satisfied in IPP/1.1. A few OPTIONAL operator operations have
- been added to IPP/1.1.
-
- The document, "Rationale for the Structure and Model and Protocol for
- the Internet Printing Protocol", describes IPP from a high level
- view, defines a roadmap for the various documents that form the suite
- of IPP specification documents, and gives background and rationale
- for the IETF working group's major decisions.
-
- The document, "Internet Printing Protocol/1.1: Model and Semantics",
- describes a simplified model with abstract objects, their attributes,
- and their operations that are independent of encoding and transport.
- It introduces a Printer and a Job object. The Job object optionally
- supports multiple documents per Job. It also addresses security,
- internationalization, and directory issues.
-
- The document "Internet Printing Protocol/1.1: Implementer's Guide",
- gives advice to implementers of IPP clients and IPP objects.
-
- The document "Mapping between LPD and IPP Protocols", gives some
- advice to implementers of gateways between IPP and LPD (Line Printer
- Daemon) implementations.
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 2]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
-Table of Contents
-
- 1. Introduction ...................................................4
- 2. Conformance Terminology ........................................4
- 3. Encoding of the Operation Layer ...............................4
- 3.1 Picture of the Encoding ...................................6
- 3.1.1 Request and Response...................................6
- 3.1.2 Attribute Group........................................6
- 3.1.3 Attribute..............................................7
- 3.1.4 Picture of the Encoding of an Attribute-with-one-value.7
- 3.1.5 Additional-value.......................................8
- 3.1.6 Alternative Picture of the Encoding of a Request Or a
- Response...............................................9
- 3.2 Syntax of Encoding ........................................9
- 3.3 Attribute-group ..........................................11
- 3.4 Required Parameters ......................................12
- 3.4.1 Version-number........................................12
- 3.4.2 Operation-id..........................................12
- 3.4.3 Status-code...........................................12
- 3.4.4 Request-id............................................13
- 3.5 Tags .....................................................13
- 3.5.1 Delimiter Tags........................................13
- 3.5.2 Value Tags............................................14
- 3.6 Name-Length ..............................................16
- 3.7 (Attribute) Name .........................................16
- 3.8 Value Length .............................................16
- 3.9 (Attribute) Value ........................................17
- 3.10 Data .....................................................18
- 4. Encoding of Transport Layer ...................................18
- 4.1 Printer-uri and job-uri ..................................19
- 5. IPP URL Scheme ................................................20
- 6. IANA Considerations ...........................................22
- 7. Internationalization Considerations ...........................23
- 8. Security Considerations .......................................23
- 8.1 Security Conformance Requirements ........................23
- 8.1.1 Digest Authentication.................................23
- 8.1.2 Transport Layer Security (TLS)........................24
- 8.2 Using IPP with TLS .......................................25
- 9. Interoperability with IPP/1.0 Implementations .................25
- 9.1 The "version-number" Parameter ...........................25
- 9.2 Security and URL Schemes .................................26
- 10. References ...................................................27
- 11. Authors' Addresses ...........................................29
- 12. Other Participants: ..........................................31
- 13. Appendix A: Protocol Examples ................................33
- 13.1 Print-Job Request ........................................33
- 13.2 Print-Job Response (successful) ..........................34
- 13.3 Print-Job Response (failure) .............................35
-
-
-
-Herriot, et al. Standards Track [Page 3]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- 13.4 Print-Job Response (success with attributes ignored) .....36
- 13.5 Print-URI Request ........................................38
- 13.6 Create-Job Request .......................................39
- 13.7 Get-Jobs Request .........................................40
- 13.8 Get-Jobs Response ........................................41
- 14. Appendix B: Registration of MIME Media Type Information for
- "application/ipp".............................................42
- 15. Appendix C: Changes from IPP/1.0 .............................44
- 16. Full Copyright Statement .....................................45
-
-1. Introduction
-
- This document contains the rules for encoding IPP operations and
- describes two layers: the transport layer and the operation layer.
-
- The transport layer consists of an HTTP/1.1 request or response. RFC
- 2616 [RFC2616] describes HTTP/1.1. This document specifies the HTTP
- headers that an IPP implementation supports.
-
- The operation layer consists of a message body in an HTTP request or
- response. The document "Internet Printing Protocol/1.1: Model and
- Semantics" [RFC2911] defines the semantics of such a message body and
- the supported values. This document specifies the encoding of an IPP
- operation. The aforementioned document [RFC2911] is henceforth
- referred to as the "IPP model document" or simply "model document".
-
- Note: the version number of IPP (1.1) and HTTP (1.1) are not linked.
- They both just happen to be 1.1.
-
-2. Conformance Terminology
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT",
- "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
- interpreted as described in RFC 2119 [RFC2119].
-
-3. Encoding of the Operation Layer
-
- The operation layer is the message body part of the HTTP request or
- response and it MUST contain a single IPP operation request or IPP
- operation response. Each request or response consists of a sequence
- of values and attribute groups. Attribute groups consist of a
- sequence of attributes each of which is a name and value. Names and
- values are ultimately sequences of octets.
-
- The encoding consists of octets as the most primitive type. There are
- several types built from octets, but three important types are
- integers, character strings and octet strings, on which most other
- data types are built. Every character string in this encoding MUST be
-
-
-
-Herriot, et al. Standards Track [Page 4]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- a sequence of characters where the characters are associated with
- some charset and some natural language. A character string MUST be in
- "reading order" with the first character in the value (according to
- reading order) being the first character in the encoding. A character
- string whose associated charset is US-ASCII whose associated natural
- language is US English is henceforth called a US-ASCII-STRING. A
- character string whose associated charset and natural language are
- specified in a request or response as described in the model document
- is henceforth called a LOCALIZED-STRING. An octet string MUST be in
- "IPP model document order" with the first octet in the value
- (according to the IPP model document order) being the first octet in
- the encoding. Every integer in this encoding MUST be encoded as a
- signed integer using two's-complement binary encoding with big-endian
- format (also known as "network order" and "most significant byte
- first"). The number of octets for an integer MUST be 1, 2 or 4,
- depending on usage in the protocol. Such one-octet integers,
- henceforth called SIGNED-BYTE, are used for the version-number and
- tag fields. Such two-byte integers, henceforth called SIGNED-SHORT
- are used for the operation-id, status-code and length fields. Four
- byte integers, henceforth called SIGNED-INTEGER, are used for value
- fields and the request-id.
-
- The following two sections present the encoding of the operation
- layer in two ways:
-
- - informally through pictures and description
- - formally through Augmented Backus-Naur Form (ABNF), as
- specified by RFC 2234 [RFC2234]
-
- An operation request or response MUST use the encoding described in
- these two sections.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 5]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
-3.1 Picture of the Encoding
-
-3.1.1 Request and Response
-
- An operation request or response is encoded as follows:
-
- -----------------------------------------------
- | version-number | 2 bytes - required
- -----------------------------------------------
- | operation-id (request) |
- | or | 2 bytes - required
- | status-code (response) |
- -----------------------------------------------
- | request-id | 4 bytes - required
- -----------------------------------------------
- | attribute-group | n bytes - 0 or more
- -----------------------------------------------
- | end-of-attributes-tag | 1 byte - required
- -----------------------------------------------
- | data | q bytes - optional
- -----------------------------------------------
-
- The first three fields in the above diagram contain the value of
- attributes described in section 3.1.1 of the Model document.
-
- The fourth field is the "attribute-group" field, and it occurs 0 or
- more times. Each "attribute-group" field represents a single group of
- attributes, such as an Operation Attributes group or a Job Attributes
- group (see the Model document). The IPP model document specifies the
- required attribute groups and their order for each operation request
- and response.
-
- The "end-of-attributes-tag" field is always present, even when the
- "data" is not present. The Model document specifies for each
- operation request and response whether the "data" field is present or
- absent.
-
-3.1.2 Attribute Group
-
- Each "attribute-group" field is encoded as follows:
-
- -----------------------------------------------
- | begin-attribute-group-tag | 1 byte
- ----------------------------------------------------------
- | attribute | p bytes |- 0 or more
- ----------------------------------------------------------
-
-
-
-
-
-Herriot, et al. Standards Track [Page 6]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- The "begin-attribute-group-tag" field marks the beginning of an
- "attribute-group" field and its value identifies the type of
- attribute group, e.g. Operations Attributes group versus a Job
- Attributes group. The "begin-attribute-group-tag" field also marks
- the end of the previous attribute group except for the "begin-
- attribute-group-tag" field in the first "attribute-group" field of a
- request or response. The "begin-attribute-group-tag" field acts as
- an "attribute-group" terminator because an "attribute-group" field
- cannot nest inside another "attribute-group" field.
-
- An "attribute-group" field contains zero or more "attribute" fields.
-
- Note, the values of the "begin-attribute-group-tag" field and the
- "end-of-attributes-tag" field are called "delimiter-tags".
-
-3.1.3 Attribute
-
- An "attribute" field is encoded as follows:
-
- -----------------------------------------------
- | attribute-with-one-value | q bytes
- ----------------------------------------------------------
- | additional-value | r bytes |- 0 or more
- ----------------------------------------------------------
-
- When an attribute is single valued (e.g. "copies" with value of 10)
- or multi-valued with one value (e.g. "sides-supported" with just the
- value 'one-sided') it is encoded with just an "attribute-with-one-
- value" field. When an attribute is multi-valued with n values (e.g.
- "sides-supported" with the values 'one-sided' and 'two-sided-long-
- edge'), it is encoded with an "attribute-with-one-value" field
- followed by n-1 "additional-value" fields.
-
-3.1.4 Picture of the Encoding of an Attribute-with-one-value
-
- Each "attribute-with-one-value" field is encoded as follows:
-
- -----------------------------------------------
- | value-tag | 1 byte
- -----------------------------------------------
- | name-length (value is u) | 2 bytes
- -----------------------------------------------
- | name | u bytes
- -----------------------------------------------
- | value-length (value is v) | 2 bytes
- -----------------------------------------------
- | value | v bytes
- -----------------------------------------------
-
-
-
-Herriot, et al. Standards Track [Page 7]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- An "attribute-with-one-value" field is encoded with five subfields:
-
- The "value-tag" field specifies the attribute syntax, e.g. 0x44
- for the attribute syntax 'keyword'.
-
- The "name-length" field specifies the length of the "name" field
- in bytes, e.g. u in the above diagram or 15 for the name "sides-
- supported".
-
- The "name" field contains the textual name of the attribute, e.g.
- "sides-supported".
-
- The "value-length" field specifies the length of the "value" field
- in bytes, e.g. v in the above diagram or 9 for the (keyword) value
- 'one-sided'.
-
- The "value" field contains the value of the attribute, e.g. the
- textual value 'one-sided'.
-
-3.1.5 Additional-value
-
- Each "additional-value" field is encoded as follows:
-
- -----------------------------------------------
- | value-tag | 1 byte
- -----------------------------------------------
- | name-length (value is 0x0000) | 2 bytes
- -----------------------------------------------
- | value-length (value is w) | 2 bytes
- -----------------------------------------------
- | value | w bytes
- -----------------------------------------------
-
- An "additional-value" is encoded with four subfields:
-
- The "value-tag" field specifies the attribute syntax, e.g. 0x44
- for the attribute syntax 'keyword'.
-
- The "name-length" field has the value of 0 in order to signify
- that it is an "additional-value". The value of the "name-length"
- field distinguishes an "additional-value" field ("name-length" is
- 0) from an "attribute-with-one-value" field ("name-length" is not
- 0).
-
- The "value-length" field specifies the length of the "value" field
- in bytes, e.g. w in the above diagram or 19 for the (keyword)
- value 'two-sided-long-edge'.
-
-
-
-
-Herriot, et al. Standards Track [Page 8]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- The "value" field contains the value of the attribute, e.g. the
- textual value 'two-sided-long-edge'.
-
-3.1.6 Alternative Picture of the Encoding of a Request Or a Response
-
- From the standpoint of a parser that performs an action based on a
- "tag" value, the encoding consists of:
-
- -----------------------------------------------
- | version-number | 2 bytes - required
- -----------------------------------------------
- | operation-id (request) |
- | or | 2 bytes - required
- | status-code (response) |
- -----------------------------------------------
- | request-id | 4 bytes - required
- -----------------------------------------------------------
- | tag (delimiter-tag or value-tag) | 1 byte |
- ----------------------------------------------- |-0 or more
- | empty or rest of attribute | x bytes |
- -----------------------------------------------------------
- | end-of-attributes-tag | 1 byte - required
- -----------------------------------------------
- | data | y bytes - optional
- -----------------------------------------------
-
- The following show what fields the parser would expect after each
- type of "tag":
-
- - "begin-attribute-group-tag": expect zero or more "attribute"
- fields
- - "value-tag": expect the remainder of an "attribute-with-one-
- value" or an "additional-value".
- - "end-of-attributes-tag": expect that "attribute" fields are
- complete and there is optional "data"
-
-3.2 Syntax of Encoding
-
- The syntax below is ABNF [RFC2234] except 'strings of literals' MUST
- be case sensitive. For example 'a' means lower case 'a' and not
- upper case 'A'. In addition, SIGNED-BYTE and SIGNED-SHORT fields
- are represented as '%x' values which show their range of values.
-
- ipp-message = ipp-request / ipp-response
- ipp-request = version-number operation-id request-id
- *attribute-group end-of-attributes-tag data
- ipp-response = version-number status-code request-id
- *attribute-group end-of-attributes-tag data
-
-
-
-Herriot, et al. Standards Track [Page 9]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- attribute-group = begin-attribute-group-tag *attribute
-
- version-number = major-version-number minor-version-number
- major-version-number = SIGNED-BYTE
- minor-version-number = SIGNED-BYTE
-
- operation-id = SIGNED-SHORT ; mapping from model defined below
- status-code = SIGNED-SHORT ; mapping from model defined below
- request-id = SIGNED-INTEGER ; whose value is > 0
-
- attribute = attribute-with-one-value *additional-value
-
- attribute-with-one-value = value-tag name-length name
- value-length value
- additional-value = value-tag zero-name-length value-length value
-
- name-length = SIGNED-SHORT ; number of octets of 'name'
- name = LALPHA *( LALPHA / DIGIT / "-" / "_" / "." )
- value-length = SIGNED-SHORT ; number of octets of 'value'
- value = OCTET-STRING
-
- data = OCTET-STRING
-
- zero-name-length = %x00.00 ; name-length of 0
- value-tag = %x10-FF ;see section 3.7.2
- begin-attribute-group-tag = %x00-02 / %04-0F ; see section 3.7.1
- end-of-attributes-tag = %x03 ; tag of 3
- ; see section 3.7.1
- SIGNED-BYTE = BYTE
- SIGNED-SHORT = 2BYTE
- SIGNED-INTEGER = 4BYTE
- DIGIT = %x30-39 ; "0" to "9"
- LALPHA = %x61-7A ; "a" to "z"
- BYTE = %x00-FF
- OCTET-STRING = *BYTE
-
- The syntax below defines additional terms that are referenced in this
- document. This syntax provides an alternate grouping of the delimiter
- tags.
-
- delimiter-tag = begin-attribute-group-tag / ; see section 3.7.1
- end-of-attributes-tag
- delimiter-tag = %x00-0F ; see section 3.7.1
-
- begin-attribute-group-tag = %x00 / operation-attributes-tag /
- job-attributes-tag / printer-attributes-tag /
- unsupported-attributes-tag / %x06-0F
- operation-attributes-tag = %x01 ; tag of 1
-
-
-
-Herriot, et al. Standards Track [Page 10]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- job-attributes-tag = %x02 ; tag of 2
- printer-attributes-tag = %x04 ; tag of 4
- unsupported-attributes-tag = %x05 ; tag of 5
-
-3.3 Attribute-group
-
- Each "attribute-group" field MUST be encoded with the "begin-
- attribute-group-tag" field followed by zero or more "attribute" sub-
- fields.
-
- The table below maps the model document group name to value of the
- "begin-attribute-group-tag" field:
-
- Model Document Group "begin-attribute-group-tag" field
- values
-
- Operation Attributes "operations-attributes-tag"
- Job Template Attributes "job-attributes-tag"
- Job Object Attributes "job-attributes-tag"
- Unsupported Attributes "unsupported-attributes-tag"
- Requested Attributes "job-attributes-tag"
- (Get-Job-Attributes)
- Requested Attributes "printer-attributes-tag"
- (Get-Printer-Attributes)
- Document Content in a special position as
- described above
-
- For each operation request and response, the model document
- prescribes the required and optional attribute groups, along with
- their order. Within each attribute group, the model document
- prescribes the required and optional attributes, along with their
- order.
-
- When the Model document requires an attribute group in a request or
- response and the attribute group contains zero attributes, a request
- or response SHOULD encode the attribute group with the "begin-
- attribute-group-tag" field followed by zero "attribute" fields. For
- example, if the client requests a single unsupported attribute with
- the Get-Printer-Attributes operation, the Printer MUST return no
- "attribute" fields, and it SHOULD return a "begin-attribute-group-
- tag" field for the Printer Attributes Group. The Unsupported
- Attributes group is not such an example. According to the model
- document, the Unsupported Attributes Group SHOULD be present only if
- the unsupported attributes group contains at least one attribute.
-
- A receiver of a request MUST be able to process the following as
- equivalent empty attribute groups:
-
-
-
-
-Herriot, et al. Standards Track [Page 11]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- a) A "begin-attribute-group-tag" field with zero following
- "attribute" fields.
-
- b) An expected but missing "begin-attribute-group-tag" field.
-
- When the Model document requires a sequence of an unknown number of
- attribute groups, each of the same type, the encoding MUST contain
- one "begin-attribute-group-tag" field for each attribute group even
- when an "attribute-group" field contains zero "attribute" sub-fields.
- For example, for the Get-Jobs operation may return zero attributes
- for some jobs and not others. The "begin-attribute-group-tag" field
- followed by zero "attribute" fields tells the recipient that there is
- a job in queue for which no information is available except that it
- is in the queue.
-
-3.4 Required Parameters
-
- Some operation elements are called parameters in the model document
- [RFC2911]. They MUST be encoded in a special position and they MUST
- NOT appear as operation attributes. These parameters are described
- in the subsections below.
-
-3.4.1 Version-number
-
- The "version-number" field MUST consist of a major and minor
- version-number, each of which MUST be represented by a SIGNED-BYTE.
- The major version-number MUST be the first byte of the encoding and
- the minor version-number MUST be the second byte of the encoding. The
- protocol described in this document MUST have a major version-number
- of 1 (0x01) and a minor version-number of 1 (0x01). The ABNF for
- these two bytes MUST be %x01.01.
-
-3.4.2 Operation-id
-
- The "operation-id" field MUST contain an operation-id value defined
- in the model document. The value MUST be encoded as a SIGNED-SHORT
- and it MUST be in the third and fourth bytes of the encoding of an
- operation request.
-
-3.4.3 Status-code
-
- The "status-code" field MUST contain a status-code value defined in
- the model document. The value MUST be encoded as a SIGNED-SHORT and
- it MUST be in the third and fourth bytes of the encoding of an
- operation response.
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 12]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- The status-code is an operation attribute in the model document. In
- the protocol, the status-code is in a special position, outside of
- the operation attributes.
-
- If an IPP status-code is returned, then the HTTP Status-Code MUST be
- 200 (successful-ok). With any other HTTP Status-Code value, the HTTP
- response MUST NOT contain an IPP message-body, and thus no IPP
- status-code is returned.
-
-3.4.4 Request-id
-
- The "request-id" field MUST contain a request-id value as defined in
- the model document. The value MUST be encoded as a SIGNED-INTEGER and
- it MUST be in the fifth through eighth bytes of the encoding.
-
-3.5 Tags
-
- There are two kinds of tags:
-
- - delimiter tags: delimit major sections of the protocol, namely
- attributes and data
- - value tags: specify the type of each attribute value
-
-3.5.1 Delimiter Tags
-
- The following table specifies the values for the delimiter tags:
-
- Tag Value (Hex) Meaning
-
- 0x00 reserved for definition in a future IETF
- standards track document
- 0x01 "operation-attributes-tag"
- 0x02 "job-attributes-tag"
- 0x03 "end-of-attributes-tag"
- 0x04 "printer-attributes-tag"
- 0x05 "unsupported-attributes-tag"
- 0x06-0x0f reserved for future delimiters in IETF
- standards track documents
-
- When a "begin-attribute-group-tag" field occurs in the protocol, it
- means that zero or more following attributes up to the next delimiter
- tag MUST be attributes belonging to the attribute group specified by
- the value of the "begin-attribute-group-tag". For example, if the
- value of "begin-attribute-group-tag" is 0x01, the following
- attributes MUST be members of the Operations Attributes group.
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 13]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- The "end-of-attributes-tag" (value 0x03) MUST occur exactly once in
- an operation. It MUST be the last "delimiter-tag". If the operation
- has a document-content group, the document data in that group MUST
- follow the "end-of-attributes-tag".
-
- The order and presence of "attribute-group" fields (whose beginning
- is marked by the "begin-attribute-group-tag" subfield) for each
- operation request and each operation response MUST be that defined in
- the model document. For further details, see section 3.7 "(Attribute)
- Name" and 13 "Appendix A: Protocol Examples".
-
- A Printer MUST treat a "delimiter-tag" (values from 0x00 through
- 0x0F) differently from a "value-tag" (values from 0x10 through 0xFF)
- so that the Printer knows that there is an entire attribute group
- that it doesn't understand as opposed to a single value that it
- doesn't understand.
-
-3.5.2 Value Tags
-
- The remaining tables show values for the "value-tag" field, which is
- the first octet of an attribute. The "value-tag" field specifies the
- type of the value of the attribute.
-
- The following table specifies the "out-of-band" values for the
- "value-tag" field.
-
- Tag Value (Hex) Meaning
-
- 0x10 unsupported
- 0x11 reserved for 'default' for definition in a future
- IETF standards track document
- 0x12 unknown
- 0x13 no-value
- 0x14-0x1F reserved for "out-of-band" values in future IETF
- standards track documents.
-
- The following table specifies the integer values for the "value-tag"
- field:
-
- Tag Value (Hex) Meaning
-
- 0x20 reserved for definition in a future IETF
- standards track document
- 0x21 integer
- 0x22 boolean
- 0x23 enum
- 0x24-0x2F reserved for integer types for definition in
- future IETF standards track documents
-
-
-
-Herriot, et al. Standards Track [Page 14]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- NOTE: 0x20 is reserved for "generic integer" if it should ever be
- needed.
-
- The following table specifies the octetString values for the "value-
- tag" field:
-
- Tag Value (Hex) Meaning
-
- 0x30 octetString with an unspecified format
- 0x31 dateTime
- 0x32 resolution
- 0x33 rangeOfInteger
- 0x34 reserved for definition in a future IETF
- standards track document
- 0x35 textWithLanguage
- 0x36 nameWithLanguage
- 0x37-0x3F reserved for octetString type definitions in
- future IETF standards track documents
-
- The following table specifies the character-string values for the
- "value-tag" field:
-
- Tag Value (Hex) Meaning
-
- 0x40 reserved for definition in a future IETF
- standards track document
- 0x41 textWithoutLanguage
- 0x42 nameWithoutLanguage
- 0x43 reserved for definition in a future IETF
- standards track document
- 0x44 keyword
- 0x45 uri
- 0x46 uriScheme
- 0x47 charset
- 0x48 naturalLanguage
- 0x49 mimeMediaType
- 0x4A-0x5F reserved for character string type definitions
- in future IETF standards track documents
-
- NOTE: 0x40 is reserved for "generic character-string" if it should
- ever be needed.
-
- NOTE: an attribute value always has a type, which is explicitly
- specified by its tag; one such tag value is "nameWithoutLanguage".
- An attribute's name has an implicit type, which is keyword.
-
- The values 0x60-0xFF are reserved for future type definitions in IETF
- standards track documents.
-
-
-
-Herriot, et al. Standards Track [Page 15]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- The tag 0x7F is reserved for extending types beyond the 255 values
- available with a single byte. A tag value of 0x7F MUST signify that
- the first 4 bytes of the value field are interpreted as the tag
- value. Note this future extension doesn't affect parsers that are
- unaware of this special tag. The tag is like any other unknown tag,
- and the value length specifies the length of a value, which contains
- a value that the parser treats atomically. Values from 0x00 to
- 0x37777777 are reserved for definition in future IETF standard track
- documents. The values 0x40000000 to 0x7FFFFFFF are reserved for
- vendor extensions.
-
-3.6 Name-Length
-
- The "name-length" field MUST consist of a SIGNED-SHORT. This field
- MUST specify the number of octets in the immediately following "name"
- field. The value of this field excludes the two bytes of the "name-
- length" field. For example, if the "name" field contains "sides", the
- value of this field is 5.
-
- If a "name-length" field has a value of zero, the following "name"
- field MUST be empty, and the following value MUST be treated as an
- additional value for the attribute encoded in the nearest preceding
- "attribute-with-one-value" field. Within an attribute group, if two
- or more attributes have the same name, the attribute group is mal-
- formed (see [RFC2911] section 3.1.3). The zero-length name is the
- only mechanism for multi-valued attributes.
-
-3.7 (Attribute) Name
-
- The "name" field MUST contain the name of an attribute. The model
- document [RFC2911] specifies such names.
-
-3.8 Value Length
-
- The "value-length" field MUST consist of a SIGNED-SHORT. This field
- MUST specify the number of octets in the immediately following
- "value" field. The value of this field excludes the two bytes of the
- "value-length" field. For example, if the "value" field contains the
- keyword (text) value 'one-sided', the value of this field is 9.
-
- For any of the types represented by binary signed integers, the
- sender MUST encode the value in exactly four octets.
-
- For any of the types represented by character-strings, the sender
- MUST encode the value with all the characters of the string and
- without any padding characters.
-
-
-
-
-
-Herriot, et al. Standards Track [Page 16]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- For "out-of-band" "value-tag" fields defined in this document, such
- as "unsupported", the "value-length" MUST be 0 and the "value" empty;
- the "value" has no meaning when the "value-tag" has one of these
- "out-of-band" values. For future "out-of-band" "value-tag" fields,
- the same rule holds unless the definition explicitly states that the
- "value-length" MAY be non-zero and the "value" non-empty.
-
-3.9 (Attribute) Value
-
- The syntax types (specified by the "value-tag" field) and most of the
- details of the representation of attribute values are defined in the
- IPP model document. The table below augments the information in the
- model document, and defines the syntax types from the model document
- in terms of the 5 basic types defined in section 3, "Encoding of the
- Operation Layer". The 5 types are US-ASCII-STRING, LOCALIZED-STRING,
- SIGNED-INTEGER, SIGNED-SHORT, SIGNED-BYTE, and OCTET-STRING.
-
- Syntax of Attribute Encoding
- Value
-
- textWithoutLanguage, LOCALIZED-STRING.
- nameWithoutLanguage
-
- textWithLanguage OCTET-STRING consisting of 4 fields:
- a. a SIGNED-SHORT which is the number of
- octets in the following field
- b. a value of type natural-language,
- c. a SIGNED-SHORT which is the number of
- octets in the following field,
- d. a value of type textWithoutLanguage.
- The length of a textWithLanguage value MUST be
- 4 + the value of field a + the value of field c.
-
- nameWithLanguage OCTET-STRING consisting of 4 fields:
- a. a SIGNED-SHORT which is the number of
- octets in the following field
- b. a value of type natural-language,
- c. a SIGNED-SHORT which is the number of
- octets in the following field
- d. a value of type nameWithoutLanguage.
- The length of a nameWithLanguage value MUST be
- 4 + the value of field a + the value of field c.
-
- charset, US-ASCII-STRING.
- naturalLanguage,
- mimeMediaType,
- keyword, uri, and
- uriScheme
-
-
-
-Herriot, et al. Standards Track [Page 17]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- Syntax of Attribute Encoding
- Value
-
- boolean SIGNED-BYTE where 0x00 is 'false' and 0x01 is
- 'true'.
-
- integer and enum a SIGNED-INTEGER.
-
- dateTime OCTET-STRING consisting of eleven octets whose
- contents are defined by "DateAndTime" in RFC
- 1903 [RFC1903].
-
- resolution OCTET-STRING consisting of nine octets of 2
- SIGNED-INTEGERs followed by a SIGNED-BYTE. The
- first SIGNED-INTEGER contains the value of
- cross feed direction resolution. The second
- SIGNED-INTEGER contains the value of feed
- direction resolution. The SIGNED-BYTE contains
- the units
-
- rangeOfInteger Eight octets consisting of 2 SIGNED-INTEGERs.
- The first SIGNED-INTEGER contains the lower
- bound and the second SIGNED-INTEGER contains
- the upper bound.
-
- 1setOf X Encoding according to the rules for an
- attribute with more than 1 value. Each value
- X is encoded according to the rules for
- encoding its type.
-
- octetString OCTET-STRING
-
-
- The attribute syntax type of the value determines its encoding and
- the value of its "value-tag".
-
-3.10 Data
-
- The "data" field MUST include any data required by the operation
-
-4. Encoding of Transport Layer
-
- HTTP/1.1 [RFC2616] is the transport layer for this protocol.
-
- The operation layer has been designed with the assumption that the
- transport layer contains the following information:
-
-
-
-
-
-Herriot, et al. Standards Track [Page 18]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- - the URI of the target job or printer operation
- - the total length of the data in the operation layer, either as
- a single length or as a sequence of chunks each with a length.
-
- It is REQUIRED that a printer implementation support HTTP over the
- IANA assigned Well Known Port 631 (the IPP default port), though a
- printer implementation may support HTTP over some other port as well.
-
- Each HTTP operation MUST use the POST method where the request-URI is
- the object target of the operation, and where the "Content-Type" of
- the message-body in each request and response MUST be
- "application/ipp". The message-body MUST contain the operation layer
- and MUST have the syntax described in section 3.2 "Syntax of
- Encoding". A client implementation MUST adhere to the rules for a
- client described for HTTP1.1 [RFC2616]. A printer (server)
- implementation MUST adhere the rules for an origin server described
- for HTTP1.1 [RFC2616].
-
- An IPP server sends a response for each request that it receives. If
- an IPP server detects an error, it MAY send a response before it has
- read the entire request. If the HTTP layer of the IPP server
- completes processing the HTTP headers successfully, it MAY send an
- intermediate response, such as "100 Continue", with no IPP data
- before sending the IPP response. A client MUST expect such a variety
- of responses from an IPP server. For further information on HTTP/1.1,
- consult the HTTP documents [RFC2616].
-
- An HTTP server MUST support chunking for IPP requests, and an IPP
- client MUST support chunking for IPP responses according to HTTP/1.1
- [RFC2616]. Note: this rule causes a conflict with non-compliant
- implementations of HTTP/1.1 that don't support chunking for POST
- methods, and this rule may cause a conflict with non-compliant
- implementations of HTTP/1.1 that don't support chunking for CGI
- scripts.
-
-4.1 Printer-uri and job-uri
-
- All Printer and Job objects are identified by a Uniform Resource
- Identifier (URI) [RFC2396] so that they can be persistently and
- unambiguously referenced. Since every URL is a specialized form of a
- URI, even though the more generic term URI is used throughout the
- rest of this document, its usage is intended to cover the more
- specific notion of URL as well.
-
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 19]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- Some operation elements are encoded twice, once as the request-URI on
- the HTTP Request-Line and a second time as a REQUIRED operation
- attribute in the application/ipp entity. These attributes are the
- target URI for the operation and are called printer-uri and job-uri.
- Note: The target URI is included twice in an operation referencing
- the same IPP object, but the two URIs NEED NOT be literally
- identical. One can be a relative URI and the other can be an absolute
- URI. HTTP/1.1 allows clients to generate and send a relative URI
- rather than an absolute URI. A relative URI identifies a resource
- with the scope of the HTTP server, but does not include scheme, host
- or port. The following statements characterize how URLs should be
- used in the mapping of IPP onto HTTP/1.1:
-
- 1. Although potentially redundant, a client MUST supply the target
- of the operation both as an operation attribute and as a URI at
- the HTTP layer. The rationale for this decision is to maintain
- a consistent set of rules for mapping application/ipp to
- possibly many communication layers, even where URLs are not
- used as the addressing mechanism in the transport layer.
- 2. Even though these two URLs might not be literally identical
- (one being relative and the other being absolute), they MUST
- both reference the same IPP object. However, a Printer NEED NOT
- verify that the two URLs reference the same IPP object, and
- NEED NOT take any action if it determines the two URLs to be
- different.
- 3. The URI in the HTTP layer is either relative or absolute and is
- used by the HTTP server to route the HTTP request to the
- correct resource relative to that HTTP server. The HTTP server
- need not be aware of the URI within the operation request.
- 4. Once the HTTP server resource begins to process the HTTP
- request, it might get the reference to the appropriate IPP
- Printer object from either the HTTP URI (using to the context
- of the HTTP server for relative URLs) or from the URI within
- the operation request; the choice is up to the implementation.
- 5. HTTP URIs can be relative or absolute, but the target URI in
- the operation MUST be an absolute URI.
-
-5. IPP URL Scheme
-
- The IPP/1.1 document defines a new scheme 'ipp' as the value of a URL
- that identifies either an IPP printer object or an IPP job object.
- The IPP attributes using the 'ipp' scheme are specified below.
- Because the HTTP layer does not support the 'ipp' scheme, a client
- MUST map 'ipp' URLs to 'http' URLs, and then follows the HTTP
- [RFC2616][RFC2617] rules for constructing a Request-Line and HTTP
- headers. The mapping is simple because the 'ipp' scheme implies all
- of the same protocol semantics as that of the 'http' scheme
-
-
-
-
-Herriot, et al. Standards Track [Page 20]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- [RFC2616], except that it represents a print service and the implicit
- (default) port number that clients use to connect to a server is port
- 631.
-
- In the remainder of this section the term 'ipp-URL' means a URL whose
- scheme is 'ipp' and whose implicit (default) port is 631. The term
- 'http-URL' means a URL whose scheme is 'http', and the term 'https-
- URL' means a URL whose scheme is 'https',
-
- A client and an IPP object (i.e. the server) MUST support the ipp-URL
- value in the following IPP attributes.
- job attributes:
- job-uri
- job-printer-uri
- printer attributes:
- printer-uri-supported
- operation attributes:
- job-uri
- printer-uri
- Each of the above attributes identifies a printer or job object. The
- ipp-URL is intended as the value of the attributes in this list, and
- for no other attributes. All of these attributes have a syntax type
- of 'uri', but there are attributes with a syntax type of 'uri' that
- do not use the 'ipp' scheme, e.g. 'job-more-info'.
-
- If a printer registers its URL with a directory service, the printer
- MUST register an ipp-URL.
-
- User interfaces are beyond the scope of this document. But if
- software exposes the ipp-URL values of any of the above five
- attributes to a human user, it is REQUIRED that the human see the
- ipp-URL as is.
-
- When a client sends a request, it MUST convert a target ipp-URL to a
- target http-URL for the HTTP layer according to the following rules:
-
- 1. change the 'ipp' scheme to 'http'
- 2. add an explicit port 631 if the URL does not contain an
- explicit port. Note: port 631 is the IANA assigned Well Known
- Port for the 'ipp' scheme.
-
- The client MUST use the target http-URL in both the HTTP Request-
- Line and HTTP headers, as specified by HTTP [RFC2616] [RFC2617] .
- However, the client MUST use the target ipp-URL for the value of the
- "printer-uri" or "job-uri" operation attribute within the
- application/ipp body of the request. The server MUST use the ipp-URL
-
-
-
-
-
-Herriot, et al. Standards Track [Page 21]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- for the value of the "printer-uri", "job-uri" or "printer-uri-
- supported" attributes within the application/ipp body of the
- response.
-
- For example, when an IPP client sends a request directly (i.e. no
- proxy) to an ipp-URL "ipp://myhost.com/myprinter/myqueue", it opens a
- TCP connection to port 631 (the ipp implicit port) on the host
- "myhost.com" and sends the following data:
-
- POST /myprinter/myqueue HTTP/1.1
- Host: myhost.com:631
- Content-type: application/ipp
- Transfer-Encoding: chunked
- ...
- "printer-uri" "ipp://myhost.com/myprinter/myqueue"
- (encoded in application/ipp message body)
- ...
-
- As another example, when an IPP client sends the same request as
- above via a proxy "myproxy.com", it opens a TCP connection to the
- proxy port 8080 on the proxy host "myproxy.com" and sends the
- following data:
-
- POST http://myhost.com:631/myprinter/myqueue HTTP/1.1
- Host: myhost.com:631
- Content-type: application/ipp
- Transfer-Encoding: chunked
- ...
- "printer-uri" "ipp://myhost.com/myprinter/myqueue"
- (encoded in application/ipp message body)
- ...
-
- The proxy then connects to the IPP origin server with headers that
- are the same as the "no-proxy" example above.
-
-6. IANA Considerations
-
- This section describes the procedures for allocating encoding for the
- following IETF standards track extensions and vendor extensions to
- the IPP/1.1 Encoding and Transport document:
-
- 1. attribute syntaxes - see [RFC2911] section 6.3
- 2. attribute groups - see [RFC2911] section 6.5
- 3. out-of-band attribute values - see [RFC2911] section 6.7
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 22]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- These extensions follow the "type2" registration procedures defined
- in [RFC2911] section 6. Extensions registered for use with IPP/1.1
- are OPTIONAL for client and IPP object conformance to the IPP/1.1
- Encoding and Transport document.
-
- These extension procedures are aligned with the guidelines as set
- forth by the IESG [IANA-CON]. The [RFC2911] Section 11 describes how
- to propose new registrations for consideration. IANA will reject
- registration proposals that leave out required information or do not
- follow the appropriate format described in [RFC2911] Section 11. The
- IPP/1.1 Encoding and Transport document may also be extended by an
- appropriate RFC that specifies any of the above extensions.
-
-7. Internationalization Considerations
-
- See the section on "Internationalization Considerations" in the
- document "Internet Printing Protocol/1.1: Model and Semantics"
- [RFC2911] for information on internationalization. This document adds
- no additional issues.
-
-8. Security Considerations
-
- The IPP Model and Semantics document [RFC2911] discusses high level
- security requirements (Client Authentication, Server Authentication
- and Operation Privacy). Client Authentication is the mechanism by
- which the client proves its identity to the server in a secure
- manner. Server Authentication is the mechanism by which the server
- proves its identity to the client in a secure manner. Operation
- Privacy is defined as a mechanism for protecting operations from
- eavesdropping.
-
-8.1 Security Conformance Requirements
-
- This section defines the security requirements for IPP clients and
- IPP objects.
-
-8.1.1 Digest Authentication
-
- IPP clients MUST support:
-
- Digest Authentication [RFC2617].
-
- MD5 and MD5-sess MUST be implemented and supported.
-
- The Message Integrity feature NEED NOT be used.
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 23]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- IPP Printers SHOULD support:
-
- Digest Authentication [RFC2617].
-
- MD5 and MD5-sess MUST be implemented and supported.
-
- The Message Integrity feature NEED NOT be used.
-
- The reasons that IPP Printers SHOULD (rather than MUST) support
- Digest Authentication are:
-
- 1. While Client Authentication is important, there is a certain class
- of printer devices where it does not make sense. Specifically, a
- low-end device with limited ROM space and low paper throughput may
- not need Client Authentication. This class of device typically
- requires firmware designers to make trade-offs between protocols
- and functionality to arrive at the lowest-cost solution possible.
- Factored into the designer's decisions is not just the size of the
- code, but also the testing, maintenance, usefulness, and time-to-
- market impact for each feature delivered to the customer. Forcing
- such low-end devices to provide security in order to claim IPP/1.1
- conformance would not make business sense and could potentially
- stall the adoption of the standard.
-
- 2. Print devices that have high-volume throughput and have available
- ROM space have a compelling argument to provide support for Client
- Authentication that safeguards the device from unauthorized
- access. These devices are prone to a high loss of consumables and
- paper if unauthorized access should occur.
-
-8.1.2 Transport Layer Security (TLS)
-
- IPP Printers SHOULD support Transport Layer Security (TLS) [RFC2246]
- for Server Authentication and Operation Privacy. IPP Printers MAY
- also support TLS for Client Authentication. If an IPP Printer
- supports TLS, it MUST support the TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
- cipher suite as mandated by RFC 2246 [RFC2246]. All other cipher
- suites are OPTIONAL. An IPP Printer MAY support Basic Authentication
- (described in HTTP/1.1 [RFC2617]) for Client Authentication if the
- channel is secure. TLS with the above mandated cipher suite can
- provide such a secure channel.
-
- If a IPP client supports TLS, it MUST support the
- TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA cipher suite as mandated by RFC
- 2246 [RFC2246]. All other cipher suites are OPTIONAL.
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 24]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- The IPP Model and Semantics document defines two printer attributes
- ("uri-authentication-supported" and "uri-security-supported") that
- the client can use to discover the security policy of a printer. That
- document also outlines IPP-specific security considerations and
- should be the primary reference for security implications with regard
- to the IPP protocol itself. For backward compatibility with IPP
- version 1.0, IPP clients and printers may also support SSL3 [ssl].
- This is in addition to the security required in this document.
-
-8.2 Using IPP with TLS
-
- IPP/1.1 uses the "Upgrading to TLS Within HTTP/1.1" mechanism
- [RFC2817]. An initial IPP request never uses TLS. The client
- requests a secure TLS connection by using the HTTP "Upgrade" header,
- while the server agrees in the HTTP response. The switch to TLS
- occurs either because the server grants the client's request to
- upgrade to TLS, or a server asks to switch to TLS in its response.
- Secure communication begins with a server's response to switch to
- TLS.
-
-9. Interoperability with IPP/1.0 Implementations
-
- It is beyond the scope of this specification to mandate conformance
- with previous versions. IPP/1.1 was deliberately designed, however,
- to make supporting previous versions easy. It is worth noting that,
- at the time of composing this specification (1999), we would expect
- IPP/1.1 Printer implementations to:
-
- understand any valid request in the format of IPP/1.0, or 1.1;
-
- respond appropriately with a response containing the same
- "version-number" parameter value used by the client in the
- request.
-
- And we would expect IPP/1.1 clients to:
-
- understand any valid response in the format of IPP/1.0, or 1.1.
-
-9.1 The "version-number" Parameter
-
- The following are rules regarding the "version-number" parameter (see
- section 3.3):
-
- 1. Clients MUST send requests containing a "version-number"
- parameter with a '1.1' value and SHOULD try supplying alternate
- version numbers if they receive a 'server-error-version-not-
- supported' error return in a response.
-
-
-
-
-Herriot, et al. Standards Track [Page 25]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- 2. IPP objects MUST accept requests containing a "version-number"
- parameter with a '1.1' value (or reject the request for reasons
- other than 'server-error-version-not-supported').
-
- 3. It is recommended that IPP objects accept any request with the
- major version '1' (or reject the request for reasons other than
- 'server-error-version-not-supported'). See [RFC2911]
- "versions" sub-section.
-
- 4. In any case, security MUST NOT be compromised when a client
- supplies a lower "version-number" parameter in a request. For
- example, if an IPP/1.1 conforming Printer object accepts
- version '1.0' requests and is configured to enforce Digest
- Authentication, it MUST do the same for a version '1.0'
- request.
-
-9.2 Security and URL Schemes
-
- The following are rules regarding security, the "version-number"
- parameter, and the URL scheme supplied in target attributes and
- responses:
-
- 1. When a client supplies a request, the "printer-uri" or "job-
- uri" target operation attribute MUST have the same scheme as
- that indicated in one of the values of the "printer-uri-
- supported" Printer attribute.
-
- 2. When the server returns the "job-printer-uri" or "job-uri" Job
- Description attributes, it SHOULD return the same scheme
- ('ipp', 'https', 'http', etc.) that the client supplied in the
- "printer-uri" or "job-uri" target operation attributes in the
- Get-Job-Attributes or Get-Jobs request, rather than the scheme
- used when the job was created. However, when a client requests
- job attributes using the Get-Job-Attributes or Get-Jobs
- operations, the jobs and job attributes that the server returns
- depends on: (1) the security in effect when the job was
- created, (2) the security in effect in the query request, and
- (3) the security policy in force.
-
- 3. It is recommended that if a server registers a non-secure ipp-
- URL with a directory service (see [RFC2911] "Generic Directory
- Schema" Appendix), then it also register an http-URL for
- interoperability with IPP/1.0 clients (see section 9).
-
- 4. In any case, security MUST NOT be compromised when a client
- supplies an 'http' or other non-secure URL scheme in the target
- "printer-uri" and "job-uri" operation attributes in a request.
-
-
-
-
-Herriot, et al. Standards Track [Page 26]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
-10. References
-
- [dpa] ISO/IEC 10175 Document Printing Application (DPA), June
- 1996.
-
- [iana] IANA Registry of Coded Character Sets:
- ftp://ftp.isi.edu/in-notes/iana/assignments/character-
- sets.
-
- [IANA-CON] Narten, T. and H. Alvestrand, "Guidelines for Writing an
- IANA Considerations Section in RFCs", BCP 26, RFC 2434,
- October 1998.
-
- [ipp-iig] Hastings, Tom, et al., "Internet Printing Protocol/1.1:
- Implementer's Guide", Work in Progress.
-
- [RFC822] Crocker, D., "Standard for the Format of ARPA Internet
- Text Messages", STD 11, RFC 822, August 1982.
-
- [RFC1123] Braden, S., "Requirements for Internet Hosts - Application
- and Support", STD 3, RFC 1123, October, 1989.
-
- [RFC1179] McLaughlin, L. III, (editor), "Line Printer Daemon
- Protocol", RFC 1179, August 1990.
-
- [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors",
- RFC 2223, October 1997.
-
- [RFC1738] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform
- Resource Locators (URL)", RFC 1738, December 1994.
-
- [RFC1759] Smith, R., Wright, F., Hastings, T., Zilles, S. and J.
- Gyllenskog, "Printer MIB", RFC 1759, March 1995.
-
- [RFC1766] Alvestrand, H., "Tags for the Identification of
- Languages", RFC 1766, March 1995.
-
- [RFC1808] Fielding, R., "Relative Uniform Resource Locators", RFC
- 1808, June 1995.
-
- [RFC1903] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser,
- "Textual Conventions for Version 2 of the Simple Network
- Management Protocol (SNMPv2)", RFC 1903, January 1996.
-
- [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part Two: Media Types", RFC 2046,
- November 1996.
-
-
-
-
-Herriot, et al. Standards Track [Page 27]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- [RFC2048] Freed, N., Klensin, J. and J. Postel, "Multipurpose
- Internet Mail Extension (MIME) Part Four: Registration
- Procedures", BCP 13, RFC 2048, November 1996.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2184] Freed, N. and K. Moore, "MIME Parameter Value and Encoded
- Word Extensions: Character Sets, Languages, and
- Continuations", RFC 2184, August 1997.
-
- [RFC2234] Crocker, D. and P. Overall, "Augmented BNF for Syntax
- Specifications: ABNF", RFC 2234, November 1997.
-
- [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol", RFC 2246.
- January 1999.
-
- [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
- Resource Identifiers (URI): Generic Syntax", RFC 2396,
- August 1998.
-
- [RFC2565] Herriot, R., Butler, S., Moore, P. and R. Turner,
- "Internet Printing Protocol/1.0: Encoding and Transport",
- RFC 2565, April 1999.
-
- [RFC2566] deBry, R., Hastings, T., Herriot, R., Isaacson, S. and P.
- Powell, "Internet Printing Protocol/1.0: Model and
- Semantics", RFC 2566, April 1999.
-
- [RFC2567] Wright, D., "Design Goals for an Internet Printing
- Protocol", RFC2567, April 1999.
-
- [RFC2568] Zilles, S., "Rationale for the Structure and Model and
- Protocol for the Internet Printing Protocol", RFC 2568,
- April 1999.
-
- [RFC2569] Herriot, R., Hastings, T., Jacobs, N. and J. Martin,
- "Mapping between LPD and IPP Protocols", RFC 2569, April
- 1999.
-
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
- Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext
- Transfer Protocol - HTTP/1.1", RFC 2616, June 1999.
-
- [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
- Leach, P., Luotonen, A. and L. Stewart, "HTTP
- Authentication: Basic and Digest Access Authentication",
- RFC 2617, June 1999.
-
-
-
-Herriot, et al. Standards Track [Page 28]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within
- HTTP/1.1", RFC 2817, May 2000.
-
- [RFC2910] Herriot, R., Butler, S., Moore, P., Turner, R. and J.
- Wenn, "Internet Printing Protocol/1.1: Encoding and
- Transport", RFC 2910, September 2000.
-
- [RFC2911] Hastings, T., Herriot, R., deBry, R., Isaacson, S. and P.
- Powell, "Internet Printing Protocol/1.1: Model and
- Semantics", RFC 2911, September 2000.
-
- [SSL] Netscape, The SSL Protocol, Version 3, (Text version
- 3.02), November 1996.
-
-11. Authors' Addresses
-
- Robert Herriot, Editor
- Xerox Corporation
- 3400 Hillview Ave., Bldg #1
- Palo Alto, CA 94304
-
- Phone: 650-813-7696
- Fax: 650-813-6860
- EMail: robert.herriot@pahv.xerox.com
-
-
- Sylvan Butler
- Hewlett-Packard
- 11311 Chinden Blvd.
- Boise, ID 83714
-
- Phone: 208-396-6000
- Fax: 208-396-3457
- EMail: sbutler@boi.hp.com
-
-
- Paul Moore
- Peerless Systems Networking
- 10900 NE 8th St #900
- Bellevue, WA 98004
-
- Phone: 425-462-5852
- EMail: pmoore@peerless.com
-
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 29]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- Randy Turner
- 2Wire, Inc.
- 694 Tasman Dr.
- Milpitas, CA 95035
-
- Phone: 408-546-1273
-
-
- John Wenn
- Xerox Corporation
- 737 Hawaii St
- El Segundo, CA 90245
-
- Phone: 310-333-5764
- Fax: 310-333-5514
- EMail: jwenn@cp10.es.xerox.com
-
-
- IPP Web Page: http://www.pwg.org/ipp/
- IPP Mailing List: ipp@pwg.org
-
- To subscribe to the ipp mailing list, send the following email:
- 1) send it to majordomo@pwg.org
- 2) leave the subject line blank
- 3) put the following two lines in the message body:
- subscribe ipp
- end
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 30]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
-12. Other Participants:
-
- Chuck Adams - Tektronix Shivaun Albright - HP
- Stefan Andersson - Axis Jeff Barnett - IBM
- Ron Bergman - Hitachi Koki Imaging Dennis Carney - IBM
- Systems
- Keith Carter - IBM Angelo Caruso - Xerox
- Rajesh Chawla - TR Computing Nancy Chen - Okidata
- Solutions
- Josh Cohen - Microsoft Jeff Copeland - QMS
- Andy Davidson - Tektronix Roger deBry - IBM
- Maulik Desai - Auco Mabry Dozier - QMS
- Lee Farrell - Canon Information Satoshi Fujitami - Ricoh
- Systems
- Steve Gebert - IBM Sue Gleeson - Digital
- Charles Gordon - Osicom Brian Grimshaw - Apple
- Jerry Hadsell - IBM Richard Hart - Digital
- Tom Hastings - Xerox Henrik Holst - I-data
- Stephen Holmstead Zhi-Hong Huang - Zenographics
- Scott Isaacson - Novell Babek Jahromi - Microsoft
- Swen Johnson - Xerox David Kellerman - Northlake
- Software
- Robert Kline - TrueSpectra Charles Kong - Panasonic
- Carl Kugler - IBM Dave Kuntz - Hewlett-Packard
- Takami Kurono - Brother Rick Landau - Digital
- Scott Lawrence - Agranot Systems Greg LeClair - Epson
- Dwight Lewis - Lexmark Harry Lewis - IBM
- Tony Liao - Vivid Image Roy Lomicka - Digital
- Pete Loya - HP Ray Lutz - Cognisys
- Mike MacKay - Novell, Inc. David Manchala - Xerox
- Carl-Uno Manros - Xerox Jay Martin - Underscore
- Stan McConnell - Xerox Larry Masinter - Xerox
- Sandra Matts - Hewlett Packard Peter Michalek - Shinesoft
- Ira McDonald - High North Inc. Mike Moldovan - G3 Nova
- Tetsuya Morita - Ricoh Yuichi Niwa - Ricoh
- Pat Nogay - IBM Ron Norton - Printronics
- Hugo Parra, Novell Bob Pentecost - Hewlett-Packard
- Patrick Powell - Astart Jeff Rackowitz - Intermec
- Technologies
- Eric Random - Peerless Rob Rhoads - Intel
- Xavier Riley - Xerox Gary Roberts - Ricoh
- David Roach - Unisys Stuart Rowley - Kyocera
- Yuji Sasaki - Japan Computer Richard Schneider - Epson
- Industry
- Kris Schoff - HP Katsuaki Sekiguchi - Canon
- Information Systems
-
-
-
-
-
-Herriot, et al. Standards Track [Page 31]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- Bob Setterbo - Adobe Gail Songer - Peerless
- Hideki Tanaka - Cannon Information Devon Taylor - Novell, Inc.
- Systems
- Mike Timperman - Lexmark Atsushi Uchino - Epson
- Shigeru Ueda - Canon Bob Von Andel - Allegro Software
- William Wagner - NetSilicon/DPI Jim Walker - DAZEL
- Chris Wellens - Interworking Labs Trevor Wells - Hewlett Packard
- Craig Whittle - Sharp Labs Rob Whittle - Novell, Inc.
- Jasper Wong - Xionics Don Wright - Lexmark
- Michael Wu - Heidelberg Digital Rick Yardumian - Xerox
- Michael Yeung - Canon Information Lloyd Young - Lexmark
- Systems
- Atsushi Yuki - Kyocera Peter Zehler - Xerox
- William Zhang - Canon Information Frank Zhao - Panasonic
- Systems
- Steve Zilles - Adobe Rob Zirnstein - Canon Information
- Systems
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 32]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
-13. Appendix A: Protocol Examples
-
-13.1 Print-Job Request
-
- The following is an example of a Print-Job request with job-name,
- copies, and sides specified. The "ipp-attribute-fidelity" attribute
- is set to 'true' so that the print request will fail if the "copies"
- or the "sides" attribute are not supported or their values are not
- supported.
-
- Octets Symbolic Value Protocol field
-
- 0x0101 1.1 version-number
- 0x0002 Print-Job operation-id
- 0x00000001 1 request-id
- 0x01 start operation-attributes operation-attributes-tag
- 0x47 charset type value-tag
- 0x0012 name-length
- attributes- attributes-charset name
- charset
- 0x0008 value-length
- us-ascii US-ASCII value
- 0x48 natural-language type value-tag
- 0x001B name-length
- attributes- name
- natural- attributes-natural-language
- language
- 0x0005 value-length
- en-us en-US value
- 0x45 uri type value-tag
- 0x000B name-length
- printer-uri printer-uri name
- 0x0015 value-length
- ipp://forest/ printer pinetree value
- pinetree
- 0x42 nameWithoutLanguage type value-tag
- 0x0008 name-length
- job-name job-name name
- 0x0006 value-length
- foobar foobar value
- 0x22 boolean type value-tag
- 0x0016 name-length
- ipp-attribute- ipp-attribute-fidelity name
- fidelity
- 0x0001 value-length
- 0x01 true value
-
-
-
-
-
-Herriot, et al. Standards Track [Page 33]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- Octets Symbolic Value Protocol field
-
- 0x02 start job-attributes job-attributes-tag
- 0x21 integer type value-tag
- 0x0006 name-length
- copies copies name
- 0x0004 value-length
- 0x00000014 20 value
- 0x44 keyword type value-tag
- 0x0005 name-length
- sides sides name
- 0x0013 value-length
- two-sided- two-sided-long-edge value
- long-edge
- 0x03 end-of-attributes end-of-attributes-tag
- %!PS... <PostScript> data
-
-13.2 Print-Job Response (successful)
-
- Here is an example of a successful Print-Job response to the previous
- Print-Job request. The printer supported the "copies" and "sides"
- attributes and their supplied values. The status code returned is
- 'successful-ok'.
-
- Octets Symbolic Value Protocol field
-
- 0x0101 1.1 version-number
- 0x0000 successful-ok status-code
- 0x00000001 1 request-id
- 0x01 start operation-attributes operation-attributes-tag
- 0x47 charset type value-tag
- 0x0012 name-length
- attributes- attributes-charset name
- charset
- 0x0008 value-length
- us-ascii US-ASCII value
- 0x48 natural-language type value-tag
- 0x001B name-length
- attributes- attributes-natural- name
- natural-language language
- 0x0005 value-length
- en-us en-US value
- 0x41 textWithoutLanguage type value-tag
- 0x000E name-length
- status-message status-message name
- 0x000D value-length
-
-
-
-
-
-Herriot, et al. Standards Track [Page 34]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- Octets Symbolic Value Protocol field
-
- successful-ok successful-ok value
- 0x02 start job-attributes job-attributes-tag
- 0x21 integer value-tag
- 0x0006 name-length
- job-id job-id name
- 0x0004 value-length
- 147 147 value
- 0x45 uri type value-tag
- 0x0007 name-length
- job-uri job-uri name
- 0x0019 value-length
- ipp://forest/ job 123 on pinetree value
- pinetree/123
- 0x23 enum type value-tag
- 0x0009 name-length
- job-state job-state name
- 0x0004 value-length
- 0x0003 pending value
- 0x03 end-of-attributes end-of-attributes-tag
-
-13.3 Print-Job Response (failure)
-
- Here is an example of an unsuccessful Print-Job response to the
- previous Print-Job request. It fails because, in this case, the
- printer does not support the "sides" attribute and because the value
- '20' for the "copies" attribute is not supported. Therefore, no job
- is created, and neither a "job-id" nor a "job-uri" operation
- attribute is returned. The error code returned is 'client-error-
- attributes-or-values-not-supported' (0x040B).
-
- 0x0101 1.1 version-number
- 0x040B client-error-attributes-or- status-code
- values-not-supported
- 0x00000001 1 request-id
- 0x01 start operation-attributes operation-attributes tag
- 0x47 charset type value-tag
- 0x0012 name-length
- attributes- attributes-charset name
- charset
- 0x0008 value-length
- us-ascii US-ASCII value
-
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 35]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- Octets Symbolic Value Protocol field
-
- 0x48 natural-language type value-tag
- 0x001B name-length
- attributes- attributes-natural-language name
- natural-
- language
- 0x0005 value-length
- en-us en-US value
- 0x41 textWithoutLanguage type value-tag
- 0x000E name-length
- status- status-message name
- message
- 0x002F value-length
- client-error- value
- attributes- values-not-supported
- or-values- client-error-attributes-or-
- not-supported
- 0x05 start unsupported-attributes unsupported-attributes tag
- 0x21 integer type value-tag
- 0x0006 name-length
- copies copies name
- 0x0004 value-length
- 0x00000014 20 value
- 0x10 unsupported (type) value-tag
- 0x0005 name-length
- sides sides name
- 0x0000 value-length
- 0x03 end-of-attributes end-of-attributes-tag
-
-13.4 Print-Job Response (success with attributes ignored)
-
- Here is an example of a successful Print-Job response to a Print-Job
- request like the previous Print-Job request, except that the value of
- 'ipp-attribute-fidelity' is false. The print request succeeds, even
- though, in this case, the printer supports neither the "sides"
- attribute nor the value '20' for the "copies" attribute. Therefore, a
- job is created, and both a "job-id" and a "job-uri" operation
- attribute are returned. The unsupported attributes are also returned
- in an Unsupported Attributes Group. The error code returned is
- 'successful-ok-ignored-or-substituted-attributes' (0x0001).
-
- Octets Symbolic Value Protocol field
-
- 0x0101 1.1 version-number
- 0x0001 successful-ok-ignored-or- status-code
-
-
-
-
-
-Herriot, et al. Standards Track [Page 36]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- Octets Symbolic Value Protocol field
-
- substituted-attributes
- 0x00000001 1 request-id
- 0x01 start operation-attributes operation-attributes-tag
- 0x47 charset type value-tag
- 0x0012 name-length
- attributes- attributes-charset name
- charset
- 0x0008 value-length
- us-ascii US-ASCII value
- 0x48 natural-language type value-tag
- 0x001B name-length
- attributes- attributes-natural- name
- natural-language language
- 0x0005 value-length
- en-us en-US value
- 0x41 textWithoutLanguage type value-tag
- 0x000E name-length
- status-message status-message name
- 0x002F value-length
- successful-ok- successful-ok-ignored-or- value
- ignored-or- substituted-attributes
- substituted-
- attributes
- 0x05 start unsupported- unsupported-attributes
- attributes tag
- 0x21 integer type value-tag
- 0x0006 name-length
- copies copies name
- 0x0004 value-length
- 0x00000014 20 value
- 0x10 unsupported (type) value-tag
- 0x0005 name-length
- sides sides name
- 0x0000 value-length
- 0x02 start job-attributes job-attributes-tag
- 0x21 integer value-tag
- 0x0006 name-length
- job-id job-id name
- 0x0004 value-length
- 147 147 value
- 0x45 uri type value-tag
- 0x0007 name-length
- job-uri job-uri name
- 0x0019 value-length
- ipp://forest/ job 123 on pinetree value
- pinetree/123
-
-
-
-Herriot, et al. Standards Track [Page 37]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- Octets Symbolic Value Protocol field
-
- 0x23 enum type value-tag
- 0x0009 name-length
- job-state job-state name
- 0x0004 value-length
- 0x0003 pending value
- 0x03 end-of-attributes end-of-attributes-tag
-
-13.5 Print-URI Request
-
- The following is an example of Print-URI request with copies and
- job-name parameters:
-
- Octets Symbolic Value Protocol field
-
- 0x0101 1.1 version-number
- 0x0003 Print-URI operation-id
- 0x00000001 1 request-id
- 0x01 start operation-attributes operation-attributes-tag
- 0x47 charset type value-tag
- 0x0012 name-length
- attributes- attributes-charset name
- charset
- 0x0008 value-length
- us-ascii US-ASCII value
- 0x48 natural-language type value-tag
- 0x001B name-length
- attributes- attributes-natural-language name
- natural-
- language
- 0x0005 value-length
- en-us en-US value
- 0x45 uri type value-tag
- 0x000B name-length
- printer-uri printer-uri name
- 0x0015 value-length
- ipp://forest/ printer pinetree value
- pinetree
- 0x45 uri type value-tag
- 0x000C name-length
- document-uri document-uri name
- 0x0011 value-length
- ftp://foo.com ftp://foo.com/foo value
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 38]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- Octets Symbolic Value Protocol field
-
- /foo
- 0x42 nameWithoutLanguage type value-tag
- 0x0008 name-length
- job-name job-name name
- 0x0006 value-length
- foobar foobar value
- 0x02 start job-attributes job-attributes-tag
- 0x21 integer type value-tag
- 0x0006 name-length
- copies copies name
- 0x0004 value-length
- 0x00000001 1 value
- 0x03 end-of-attributes end-of-attributes-tag
-
-13.6 Create-Job Request
-
- The following is an example of Create-Job request with no parameters
- and no attributes:
-
- Octets Symbolic Value Protocol field
-
- 0x0101 1.1 version-number
- 0x0005 Create-Job operation-id
- 0x00000001 1 request-id
- 0x01 start operation-attributes operation-attributes-tag
- 0x47 charset type value-tag
- 0x0012 name-length
- attributes- attributes-charset name
- charset
- 0x0008 value-length
- us-ascii US-ASCII value
- 0x48 natural-language type value-tag
- 0x001B name-length
- attributes- attributes-natural-language name
- natural-
- language
- 0x0005 value-length
- en-us en-US value
- 0x45 uri type value-tag
- 0x000B name-length
- printer-uri printer-uri name
- 0x0015 value-length
- ipp://forest/ printer pinetree value
- pinetree
-
-
-
-
-
-Herriot, et al. Standards Track [Page 39]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- Octets Symbolic Value Protocol field
-
- inetree
- 0x03 end-of-attributes end-of-attributes-tag
-
-13.7 Get-Jobs Request
-
- The following is an example of Get-Jobs request with parameters but
- no attributes:
-
- Octets Symbolic Value Protocol field
-
- 0x0101 1.1 version-number
- 0x000A Get-Jobs operation-id
- 0x00000123 0x123 request-id
- 0x01 start operation-attributes operation-attributes-tag
- 0x47 charset type value-tag
- 0x0012 name-length
- attributes- attributes-charset name
- charset
- 0x0008 value-length
- us-ascii US-ASCII value
- 0x48 natural-language type value-tag
- 0x001B name-length
- attributes- attributes-natural-language name
- natural-
- language
- 0x0005 value-length
- en-us en-US value
- 0x45 uri type value-tag
- 0x000B name-length
- printer-uri printer-uri name
- 0x0015 value-length
- ipp://forest/ printer pinetree value
- pinetree
- 0x21 integer type value-tag
- 0x0005 name-length
- limit limit name
- 0x0004 value-length
- 0x00000032 50 value
- 0x44 keyword type value-tag
- 0x0014 name-length
- requested- requested-attributes name
- attributes
- 0x0006 value-length
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 40]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- Octets Symbolic Value Protocol field
-
- job-id job-id value
- 0x44 keyword type value-tag
- 0x0000 additional value name-length
- 0x0008 value-length
- job-name job-name value
- 0x44 keyword type value-tag
- 0x0000 additional value name-length
- 0x000F value-length
- document-format document-format value
- 0x03 end-of-attributes end-of-attributes-tag
-
-13.8 Get-Jobs Response
-
- The following is an of Get-Jobs response from previous request with 3
- jobs. The Printer returns no information about the second job
- (because of security reasons):
-
- Octets Symbolic Value Protocol field
-
- 0x0101 1.1 version-number
- 0x0000 successful-ok status-code
- 0x00000123 0x123 request-id (echoed
- back)
- 0x01 start operation-attributes operation-attributes-tag
- 0x47 charset type value-tag
- 0x0012 name-length
- attributes- attributes-charset name
- charset
- 0x000A value-length
- ISO-8859-1 ISO-8859-1 value
- 0x48 natural-language type value-tag
- 0x001B name-length
- attributes- attributes-natural-language name
- natural-
- language
- 0x0005 value-length
- en-us en-US value
- 0x41 textWithoutLanguage type value-tag
- 0x000E name-length
- status-message status-message name
- 0x000D value-length
- successful-ok successful-ok value
- 0x02 start job-attributes (1st job-attributes-tag
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 41]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- Octets Symbolic Value Protocol field
-
- object)
- 0x21 integer type value-tag
- 0x0006 name-length
- job-id job-id name
- 0x0004 value-length
- 147 147 value
- 0x36 nameWithLanguage value-tag
- 0x0008 name-length
- job-name job-name name
- 0x000C value-length
- 0x0005 sub-value-length
- fr-ca fr-CA value
- 0x0003 sub-value-length
- fou fou name
- 0x02 start job-attributes (2nd job-attributes-tag
- object)
- 0x02 start job-attributes (3rd job-attributes-tag
- object)
- 0x21 integer type value-tag
- 0x0006 name-length
- job-id job-id name
- 0x0004 value-length
- 148 149 value
- 0x36 nameWithLanguage value-tag
- 0x0008 name-length
- job-name job-name name
- 0x0012 value-length
- 0x0005 sub-value-length
- de-CH de-CH value
- 0x0009 sub-value-length
- isch guet isch guet name
- 0x03 end-of-attributes end-of-attributes-tag
-
-14. Appendix B: Registration of MIME Media Type Information for
- "application/ipp"
-
- This appendix contains the information that IANA requires for
- registering a MIME media type. The information following this
- paragraph will be forwarded to IANA to register application/ipp whose
- contents are defined in Section 3 "Encoding of the Operation Layer"
- in this document:
-
- MIME type name: application
-
- MIME subtype name: ipp
-
-
-
-
-Herriot, et al. Standards Track [Page 42]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- A Content-Type of "application/ipp" indicates an Internet Printing
- Protocol message body (request or response). Currently there is one
- version: IPP/1.1, whose syntax is described in Section 3 "Encoding of
- the Operation Layer" of [RFC2910], and whose semantics are described
- in [RFC2911].
-
- Required parameters: none
-
- Optional parameters: none
-
- Encoding considerations:
-
- IPP/1.1 protocol requests/responses MAY contain long lines and ALWAYS
- contain binary data (for example attribute value lengths).
-
- Security considerations:
-
- IPP/1.1 protocol requests/responses do not introduce any security
- risks not already inherent in the underlying transport protocols.
- Protocol mixed-version interworking rules in [RFC2911] as well as
- protocol encoding rules in [RFC2910] are complete and unambiguous.
-
- Interoperability considerations:
-
- IPP/1.1 requests (generated by clients) and responses (generated by
- servers) MUST comply with all conformance requirements imposed by the
- normative specifications [RFC2911] and [RFC2910]. Protocol encoding
- rules specified in [RFC2910] are comprehensive, so that
- interoperability between conforming implementations is guaranteed
- (although support for specific optional features is not ensured).
- Both the "charset" and "natural-language" of all IPP/1.1 attribute
- values which are a LOCALIZED-STRING are explicit within IPP protocol
- requests/responses (without recourse to any external information in
- HTTP, SMTP, or other message transport headers).
-
- Published specifications:
-
- [RFC2911] Hastings, T., Herriot, R., deBry, R., Isaacson, S. and P.
- Powell, "Internet Printing Protocol/1.1: Model and
- Semantics", RFC 2911, September 2000.
-
- [RFC2910] Herriot, R., Butler, S., Moore, P., Turner, R. and J.
- Wenn, "Internet Printing Protocol/1.1: Encoding and
- Transport", RFC 2910, September 2000.
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 43]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- Applications which use this media type:
-
- Internet Printing Protocol (IPP) print clients and print servers,
- communicating using HTTP/1.1 (see [RFC2910]), SMTP/ESMTP, FTP, or
- other transport protocol. Messages of type "application/ipp" are
- self-contained and transport-independent, including "charset" and
- "natural-language" context for any LOCALIZED-STRING value.
-
- Person & email address to contact for further information:
-
- Tom Hastings
- Xerox Corporation
- 737 Hawaii St. ESAE-231
- El Segundo, CA
-
- Phone: 310-333-6413
- Fax: 310-333-5514
- EMail: hastings@cp10.es.xerox.com
-
- or
-
- Robert Herriot
- Xerox Corporation
- 3400 Hillview Ave., Bldg #1
- Palo Alto, CA 94304
-
- Phone: 650-813-7696
- Fax: 650-813-6860
- EMail: robert.herriot@pahv.xerox.com
-
- Intended usage:
-
- COMMON
-
-15. Appendix C: Changes from IPP/1.0
-
- IPP/1.1 is identical to IPP/1.0 [RFC2565] with the follow changes:
-
- 1. Attributes values that identify a printer or job object use a new
- 'ipp' scheme. The 'http' and 'https' schemes are supported only
- for backward compatibility. See section 5.
-
- 2. Clients MUST support of Digest Authentication, IPP Printers SHOULD
- support Digest Authentication. See Section 8.1.1
-
- 3. TLS is recommended for channel security. In addition, SSL3 may be
- supported for backward compatibility. See Section 8.1.2
-
-
-
-
-Herriot, et al. Standards Track [Page 44]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
- 4. It is recommended that IPP/1.1 objects accept any request with
- major version number '1'. See section 9.1.
-
- 5. IPP objects SHOULD return the URL scheme requested for "job-
- printer-uri" and "job-uri" Job Attributes, rather than the URL
- scheme used to create the job. See section 9.2.
-
- 6. The IANA and Internationalization sections have been added. The
- terms "private use" and "experimental" have been changed to
- "vendor extension". The reserved allocations for attribute group
- tags, attribute syntax tags, and out-of-band attribute values have
- been clarified as to which are reserved to future IETF standards
- track documents and which are reserved to vendor extension. Both
- kinds of extensions use the type2 registration procedures as
- defined in [RFC2911].
-
- 7. Clarified that future "out-of-band" value definitions may use the
- value field if additional information is needed.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 45]
-\f
-RFC 2910 IPP/1.1: Encoding and Transport September 2000
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2000). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 46]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group T. Hastings, Editor
-Request for Comments: 2911 R. Herriot
-Obsoletes: 2566 Xerox Corporation
-Category: Standards Track R. deBry
- Utah Valley State College
- S. Isaacson
- Novell, Inc.
- P. Powell
- Astart Technologies
- September 2000
-
-
- Internet Printing Protocol/1.1: Model and Semantics
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2000). All Rights Reserved.
-
-Abstract
-
- This document is one of a set of documents, which together describe
- all aspects of a new Internet Printing Protocol (IPP). IPP is an
- application level protocol that can be used for distributed printing
- using Internet tools and technologies. This document describes a
- simplified model consisting of abstract objects, their attributes,
- and their operations that is independent of encoding and transport.
- The model consists of a Printer and a Job object. A Job optionally
- supports multiple documents. IPP 1.1 semantics allow end-users and
- operators to query printer capabilities, submit print jobs, inquire
- about the status of print jobs and printers, cancel, hold, release,
- and restart print jobs. IPP 1.1 semantics allow operators to pause,
- resume, and purge (jobs from) Printer objects. This document also
- addresses security, internationalization, and directory issues.
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 1]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- The full set of IPP documents includes:
-
- Design Goals for an Internet Printing Protocol [RFC2567]
- Rationale for the Structure and Model and Protocol for the Internet
- Printing Protocol [RFC2568]
- Internet Printing Protocol/1.1: Model and Semantics (this document)
- Internet Printing Protocol/1.1: Encoding and Transport [RFC2910]
- Internet Printing Protocol/1.1: Implementer's Guide [IPP-IIG]
- Mapping between LPD and IPP Protocols [RFC2569]
-
- The "Design Goals for an Internet Printing Protocol" document takes a
- broad look at distributed printing functionality, and it enumerates
- real-life scenarios that help to clarify the features that need to be
- included in a printing protocol for the Internet. It identifies
- requirements for three types of users: end users, operators, and
- administrators. It calls out a subset of end user requirements that
- are satisfied in IPP/1.0. A few OPTIONAL operator operations have
- been added to IPP/1.1.
-
- The "Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol" document describes IPP from a high level
- view, defines a roadmap for the various documents that form the suite
- of IPP specification documents, and gives background and rationale
- for the IETF working group's major decisions.
-
- The "Internet Printing Protocol/1.1: Encoding and Transport" document
- is a formal mapping of the abstract operations and attributes defined
- in the model document onto HTTP/1.1 [RFC2616]. It defines the
- encoding rules for a new Internet MIME media type called
- "application/ipp". This document also defines the rules for
- transporting over HTTP a message body whose Content-Type is
- "application/ipp". This document defines a new scheme named 'ipp'
- for identifying IPP printers and jobs.
-
- The "Internet Printing Protocol/1.1: Implementer's Guide" document
- gives insight and advice to implementers of IPP clients and IPP
- objects. It is intended to help them understand IPP/1.1 and some of
- the considerations that may assist them in the design of their client
- and/or IPP object implementations. For example, a typical order of
- processing requests is given, including error checking. Motivation
- for some of the specification decisions is also included.
-
- The "Mapping between LPD and IPP Protocols" document gives some
- advice to implementers of gateways between IPP and LPD (Line Printer
- Daemon) implementations.
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 2]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-Table of Contents
-
- 1. Introduction 9
- 1.1 Simplified Printing Model 10
- 2. IPP Objects 12
- 2.1 Printer Object 13
- 2.2 Job Object 15
- 2.3 Object Relationships 16
- 2.4 Object Identity 17
- 3. IPP Operations 20
- 3.1 Common Semantics 21
- 3.1.1 Required Parameters 21
- 3.1.2 Operation IDs and Request IDs 22
- 3.1.3 Attributes 22
- 3.1.4 Character Set and Natural Language Operation Attribute 24
- 3.1.4.1 Request Operation Attributes 25
- 3.1.4.2 Response Operation Attributes 29
- 3.1.5 Operation Targets 30
- 3.1.6 Operation Response Status Codes and Status Messages 32
- 3.1.6.1 "status-code" (type2 enum) 32
- 3.1.6.2 "status-message" (text(255)) 33
- 3.1.6.3 "detailed-status-message" (text(MAX)) 33
- 3.1.6.4 "document-access-error" (text(MAX)) 34
- 3.1.7 Unsupported Attributes 34
- 3.1.8 Versions 36
- 3.1.9 Job Creation Operations 38
- 3.2 Printer Operations 41
- 3.2.1 Print-Job Operation 41
- 3.2.1.1 Print-Job Request 41
- 3.2.1.2 Print-Job Response 46
- 3.2.2 Print-URI Operation 48
- 3.2.3 Validate-Job Operation 49
- 3.2.4 Create-Job Operation 49
- 3.2.5 Get-Printer-Attributes Operation 50
- 3.2.5.1 Get-Printer-Attributes Request 51
- 3.2.5.2 Get-Printer-Attributes Response 53
- 3.2.6 Get-Jobs Operation 54
- 3.2.6.1 Get-Jobs Request 54
- 3.2.6.2 Get-Jobs Response 56
- 3.2.7 Pause-Printer Operation 57
- 3.2.7.1 Pause-Printer Request 59
- 3.2.7.2 Pause-Printer Response 60
- 3.2.8 Resume-Printer Operation 60
- 3.2.9 Purge-Jobs Operation 61
- 3.3 Job Operations 62
- 3.3.1 Send-Document Operation 62
- 3.3.1.1 Send-Document Request 64
- 3.3.1.2 Send-Document Response 65
-
-
-
-Hastings, et al. Standards Track [Page 3]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 3.3.2 Send-URI Operation 66
- 3.3.3 Cancel-Job Operation 66
- 3.3.3.1 Cancel-Job Request 67
- 3.3.3.2 Cancel-Job Response 68
- 3.3.4 Get-Job-Attributes Operation 69
- 3.3.4.1 Get-Job-Attributes Request 69
- 3.3.4.2 Get-Job-Attributes Response 70
- 3.3.5 Hold-Job Operation 71
- 3.3.5.1 Hold-Job Request 72
- 3.3.5.2 Hold-Job Response 73
- 3.3.6 Release-Job Operation 74
- 3.3.7 Restart-Job Operation 75
- 3.3.7.1 Restart-Job Request 76
- 3.3.7.2 Restart-Job Response 78
- 4. Object Attributes 78
- 4.1 Attribute Syntaxes 78
- 4.1.1 'text' 79
- 4.1.1.1 'textWithoutLanguage' 80
- 4.1.1.2 'textWithLanguage' 80
- 4.1.2 'name' 81
- 4.1.2.1 'nameWithoutLanguage' 82
- 4.1.2.2 'nameWithLanguage' 82
- 4.1.2.3 Matching 'name' attribute values 83
- 4.1.3 'keyword' 84
- 4.1.4 'enum' 85
- 4.1.5 'uri' 85
- 4.1.6 'uriScheme' 86
- 4.1.7 'charset' 86
- 4.1.8 'naturalLanguage' 87
- 4.1.9 'mimeMediaType' 87
- 4.1.9.1 Application/octet-stream -- Auto-Sensing 88
- the document format
- 4.1.10 'octetString' 89
- 4.1.11 'boolean' 89
- 4.1.12 'integer' 89
- 4.1.13 'rangeOfInteger' 90
- 4.1.14 'dateTime' 90
- 4.1.15 'resolution' 90
- 4.1.16 '1setOf X' 90
- 4.2 Job Template Attributes 91
- 4.2.1 job-priority (integer(1:100)) 94
- 4.2.2 job-hold-until (type3 keyword | name (MAX)) 95
- 4.2.3 job-sheets (type3 keyword | name(MAX)) 96
- 4.2.4 multiple-document-handling (type2 keyword) 96
- 4.2.5 copies (integer(1:MAX)) 98
- 4.2.6 finishings (1setOf type2 enum) 98
- 4.2.7 page-ranges (1setOf rangeOfInteger (1:MAX)) 101
- 4.2.8 sides (type2 keyword) 102
-
-
-
-Hastings, et al. Standards Track [Page 4]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 4.2.9 number-up (integer(1:MAX)) 102
- 4.2.10 orientation-requested (type2 enum) 103
- 4.2.11 media (type3 keyword | name(MAX)) 104
- 4.2.12 printer-resolution (resolution) 105
- 4.2.13 print-quality (type2 enum) 105
- 4.3 Job Description Attributes 106
- 4.3.1 job-uri (uri) 107
- 4.3.2 job-id (integer(1:MAX)) 108
- 4.3.3 job-printer-uri (uri) 108
- 4.3.4 job-more-info (uri) 108
- 4.3.5 job-name (name(MAX)) 108
- 4.3.6 job-originating-user-name (name(MAX)) 109
- 4.3.7 job-state (type1 enum) 109
- 4.3.7.1 Forwarding Servers 112
- 4.3.7.2 Partitioning of Job States 112
- 4.3.8 job-state-reasons (1setOf type2 keyword) 113
- 4.3.9 job-state-message (text(MAX)) 118
- 4.3.10 job-detailed-status-messages (1setOf text(MAX)) 118
- 4.3.11 job-document-access-errors (1setOf text(MAX)) 118
- 4.3.12 number-of-documents (integer(0:MAX)) 119
- 4.3.13 output-device-assigned (name(127)) 119
- 4.3.14 Event Time Job Description Attributes 119
- 4.3.14.1 time-at-creation (integer(MIN:MAX)) 120
- 4.3.14.2 time-at-processing (integer(MIN:MAX)) 120
- 4.3.14.3 time-at-completed (integer(MIN:MAX)) 120
- 4.3.14.4 job-printer-up-time (integer(1:MAX)) 120
- 4.3.14.5 date-time-at-creation (dateTime) 121
- 4.3.14.6 date-time-at-processing (dateTime) 121
- 4.3.14.7 date-time-at-completed (dateTime) 121
- 4.3.15 number-of-intervening-jobs (integer(0:MAX)) 121
- 4.3.16 job-message-from-operator (text(127)) 121
- 4.3.17 Job Size Attributes 121
- 4.3.17.1 job-k-octets (integer(0:MAX)) 122
- 4.3.17.2 job-impressions (integer(0:MAX)) 122
- 4.3.17.3 job-media-sheets (integer(0:MAX)) 123
- 4.3.18 Job Progress Attributes 123
- 4.3.18.1 job-k-octets-processed (integer(0:MAX)) 123
- 4.3.18.2 job-impressions-completed (integer(0:MAX)) 123
- 4.3.18.3 job-media-sheets-completed (integer(0:MAX)) 124
- 4.3.19 attributes-charset (charset) 124
- 4.3.20 attributes-natural-language (naturalLanguage) 124
- 4.4 Printer Description Attributes 124
- 4.4.1 printer-uri-supported (1setOf uri) 126
- 4.4.2 uri-authentication-supported (1setOf type2 keyword) 127
- 4.4.3 uri-security-supported (1setOf type2 keyword) 128
- 4.4.4 printer-name (name(127)) 129
- 4.4.5 printer-location (text(127)) 129
- 4.4.6 printer-info (text(127)) 130
-
-
-
-Hastings, et al. Standards Track [Page 5]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 4.4.7 printer-more-info (uri) 130
- 4.4.8 printer-driver-installer (uri) 130
- 4.4.9 printer-make-and-model (text(127)) 130
- 4.4.10 printer-more-info-manufacturer (uri) 130
- 4.4.11 printer-state (type1 enum) 131
- 4.4.12 printer-state-reasons (1setOf type2 keyword) 131
- 4.4.13 printer-state-message (text(MAX)) 134
- 4.4.14 ipp-versions-supported (1setOf type2 keyword) 134
- 4.4.15 operations-supported (1setOf type2 enum) 135
- 4.4.16 multiple-document-jobs-supported (boolean) 136
- 4.4.17 charset-configured (charset) 136
- 4.4.18 charset-supported (1setOf charset) 137
- 4.4.19 natural-language-configured (naturalLanguage) 137
- 4.4.20 generated-natural-language-supported
- (1setOf naturalLanguage) 137
- 4.4.21 document-format-default (mimeMediaType) 138
- 4.4.22 document-format-supported (1setOf mimeMediaType) 138
- 4.4.23 printer-is-accepting-jobs (boolean) 138
- 4.4.24 queued-job-count (integer(0:MAX)) 138
- 4.4.25 printer-message-from-operator (text(127)) 139
- 4.4.26 color-supported (boolean) 139
- 4.4.27 reference-uri-schemes-supported (1setOf uriScheme) 139
- 4.4.28 pdl-override-supported (type2 keyword) 139
- 4.4.29 printer-up-time (integer(1:MAX)) 140
- 4.4.30 printer-current-time (dateTime) 140
- 4.4.31 multiple-operation-time-out (integer(1:MAX)) 141
- 4.4.32 compression-supported (1setOf type3 keyword) 141
- 4.4.33 job-k-octets-supported (rangeOfInteger(0:MAX)) 142
- 4.4.34 job-impressions-supported (rangeOfInteger(0:MAX)) 142
- 4.4.35 job-media-sheets-supported (rangeOfInteger(0:MAX)) 142
- 4.4.36 pages-per-minute (integer(0:MAX)) 142
- 4.4.37 pages-per-minute-color (integer(0:MAX)) 142
- 5. Conformance 143
- 5.1 Client Conformance Requirements 143
- 5.2 IPP Object Conformance Requirements 145
- 5.2.1 Objects 145
- 5.2.2 Operations 145
- 5.2.3 IPP Object Attributes 146
- 5.2.4 Versions 146
- 5.2.5 Extensions 147
- 5.2.6 Attribute Syntaxes 147
- 5.2.7 Security 148
- 5.3 Charset and Natural Language Requirements 148
- 6. IANA Considerations 148
- 6.1 Typed 'keyword' and 'enum' Extensions 149
- 6.2 Attribute Extensibility 151
- 6.3 Attribute Syntax Extensibility 152
- 6.4 Operation Extensibility 152
-
-
-
-Hastings, et al. Standards Track [Page 6]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 6.5 Attribute Group Extensibility 153
- 6.6 Status Code Extensibility 153
- 6.7 Out-of-band Attribute Value Extensibility 154
- 6.8 Registration of MIME types/sub-types for document-formats 154
- 6.9 Registration of charsets for use in 'charset'
- attribute values 154
- 7. Internationalization Considerations 154
- 8. Security Considerations 158
- 8.1 Security Scenarios 159
- 8.1.1 Client and Server in the Same Security Domain 159
- 8.1.2 Client and Server in Different Security Domains 159
- 8.1.3 Print by Reference 160
- 8.2 URIs in Operation, Job, and Printer attributes 160
- 8.3 URIs for each authentication mechanisms 160
- 8.4 Restricted Queries 161
- 8.5 Operations performed by operators and system
- administrators 161
- 8.6 Queries on jobs submitted using non-IPP protocols 162
- 9. References 162
- 10. Authors' Addresses 166
- 11. Formats for IPP Registration Proposals 168
- 11.1 Type2 keyword attribute values registration 169
- 11.2 Type3 keyword attribute values registration 169
- 11.3 Type2 enum attribute values registration 169
- 11.4 Type3 enum attribute values registration 170
- 11.5 Attribute registration 170
- 11.6 Attribute Syntax registration 171
- 11.7 Operation registration 171
- 11.8 Attribute Group registration 171
- 11.9 Status code registration 172
- 11.10 Out-of-band Attribute Value registration 172
- 12. APPENDIX A: Terminology 173
- 12.1 Conformance Terminology 173
- 12.1.1 NEED NOT 173
- 12.2 Model Terminology 173
- 12.2.1 Keyword 173
- 12.2.2 Attributes 173
- 12.2.2.1 Attribute Name 173
- 12.2.2.2 Attribute Group Name 174
- 12.2.2.3 Attribute Value 174
- 12.2.2.4 Attribute Syntax 174
- 12.2.3 Supports 174
- 12.2.4 print-stream page 176
- 12.2.5 impression 177
- 13. APPENDIX B: Status Codes and Suggested Status Code Messages 177
- 13.1 Status Codes 178
- 13.1.1 Informational 178
- 13.1.2 Successful Status Codes 178
-
-
-
-Hastings, et al. Standards Track [Page 7]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 13.1.2.1 successful-ok (0x0000) 178
- 13.1.2.2 successful-ok-ignored-or-substituted-attributes
- (0x0001) 179
- 13.1.2.3 successful-ok-conflicting-attributes (0x0002) 179
- 13.1.3 Redirection Status Codes 179
- 13.1.4 Client Error Status Codes 179
- 13.1.4.1 client-error-bad-request (0x0400) 180
- 13.1.4.2 client-error-forbidden (0x0401) 180
- 13.1.4.3 client-error-not-authenticated (0x0402) 180
- 13.1.4.4 client-error-not-authorized (0x0403) 180
- 13.1.4.5 client-error-not-possible (0x0404) 180
- 13.1.4.6 client-error-timeout (0x0405) 181
- 13.1.4.7 client-error-not-found (0x0406) 181
- 13.1.4.8 client-error-gone (0x0407) 181
- 13.1.4.9 client-error-request-entity-too-large (0x0408) 182
- 13.1.4.10 client-error-request-value-too-long (0x0409) 182
- 13.1.4.11 client-error-document-format-not-supported (0x040A) 182
- 13.1.4.12 client-error-attributes-or-values-not-supported
- (0x040B) 183
- 13.1.4.13 client-error-uri-scheme-not-supported (0x040C) 183
- 13.1.4.14 client-error-charset-not-supported (0x040D) 183
- 13.1.4.15 client-error-conflicting-attributes (0x040E) 183
- 13.1.4.16 client-error-compression-not-supported (0x040F) 184
- 13.1.4.17 client-error-compression-error (0x0410) 184
- 13.1.4.18 client-error-document-format-error (0x0411) 184
- 13.1.4.19 client-error-document-access-error (0x0412) 184
- 13.1.5 Server Error Status Codes 185
- 13.1.5.1 server-error-internal-error (0x0500) 185
- 13.1.5.2 server-error-operation-not-supported (0x0501) 185
- 13.1.5.3 server-error-service-unavailable (0x0502) 185
- 13.1.5.4 server-error-version-not-supported (0x0503) 185
- 13.1.5.5 server-error-device-error (0x0504) 186
- 13.1.5.6 server-error-temporary-error (0x0505) 186
- 13.1.5.7 server-error-not-accepting-jobs (0x0506) 187
- 13.1.5.8 server-error-busy (0x0507) 187
- 13.1.5.9 server-error-job-canceled (0x0508) 187
- 13.1.5.10 server-error-multiple-document-jobs-not-supported
- (0x0509) 187
- 13.2 Status Codes for IPP Operations 187
- 14. APPENDIX C: "media" keyword values 190
- 15. APPENDIX D: Processing IPP Attributes 208
- 15.1 Fidelity 209
- 15.2 Page Description Language (PDL) Override 210
- 15.3 Using Job Template Attributes During Document Processing 212
- 16. APPENDIX E: Generic Directory Schema 214
- 17. APPENDIX F: Differences between the IPP/1.0 and IPP/1.1
- "Model and Semantics" Documents 215
- 18. Full Copyright Statement 224
-
-
-
-Hastings, et al. Standards Track [Page 8]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-1. Introduction
-
- The Internet Printing Protocol (IPP) is an application level protocol
- that can be used for distributed printing using Internet tools and
- technologies. IPP version 1.1 (IPP/1.1) focuses primarily on end
- user functionality with a few administrative operations included.
- This document is just one of a suite of documents that fully define
- IPP. The full set of IPP documents includes:
-
- Design Goals for an Internet Printing Protocol [RFC2567]
- Rationale for the Structure and Model and Protocol for the Internet
- Printing Protocol [RFC2568]
- Internet Printing Protocol/1.1: Model and Semantics (this document)
- Internet Printing Protocol/1.1: Encoding and Transport [RFC2910]
- Internet Printing Protocol/1.1: Implementer's Guide [IPP-IIG]
- Mapping between LPD and IPP Protocols [RFC2569]
-
- Anyone reading these documents for the first time is strongly
- encouraged to read the IPP documents in the above order.
-
- This document is laid out as follows:
-
- - The rest of Section 1 is an introduction to the IPP simplified
- model for distributed printing.
- - Section 2 introduces the object types covered in the model with
- their basic behaviors, attributes, and interactions.
- - Section 3 defines the operations included in IPP/1.1. IPP
- operations are synchronous, therefore, for each operation, there is
- a both request and a response.
- - Section 4 defines the attributes (and their syntaxes) that are used
- in the model.
- - Sections 5 - 6 summarizes the implementation conformance
- requirements for objects that support the protocol and IANA
- considerations, respectively.
- - Sections 7 - 11 cover the Internationalization and Security
- considerations as well as References, Author contact information,
- and Formats for Registration Proposals.
- - Sections 12 - 14 are appendices that cover Terminology, Status
- Codes and Messages, and "media" keyword values.
-
- Note: This document uses terms such as "attributes", "keywords",
- and "support". These terms have special meaning and are defined
- in the model terminology section 12.2. Capitalized terms, such
- as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, MAY, NEED NOT,
- and OPTIONAL, have special meaning relating to conformance.
- These terms are defined in section 12.1 on conformance
- terminology, most of which is taken from RFC 2119 [RFC2119].
-
-
-
-
-Hastings, et al. Standards Track [Page 9]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- - Section 15 is an appendix that helps to clarify the effects of
- interactions between related attributes and their values.
- - Section 16 is an appendix that enumerates the subset of Printer
- attributes that form a generic directory schema. These attributes
- are useful when registering a Printer so that a client can find the
- Printer not just by name, but by filtered searches as well.
- - Section 17 is an appendix summarizing the additions and changes
- from the IPP/1.0 "Model and Semantics" document [RFC2566] to make
- this IPP/1.1 document.
- - Section 18 is the full copyright notice.
-
-1.1 Simplified Printing Model
-
- In order to achieve its goal of realizing a workable printing
- protocol for the Internet, the Internet Printing Protocol (IPP) is
- based on a simplified printing model that abstracts the many
- components of real world printing solutions. The Internet is a
- distributed computing environment where requesters of print services
- (clients, applications, printer drivers, etc.) cooperate and interact
- with print service providers. This model and semantics document
- describes a simple, abstract model for IPP even though the underlying
- configurations may be complex "n-tier" client/server systems. An
- important simplifying step in the IPP model is to expose only the key
- objects and interfaces required for printing. The model described in
- this model document does not include features, interfaces, and
- relationships that are beyond the scope of the first version of IPP
- (IPP/1.1). IPP/1.1 incorporates many of the relevant ideas and
- lessons learned from other specification and development efforts
- [HTPP] [ISO10175] [LDPA] [P1387.4] [PSIS] [RFC1179] [SWP]. IPP is
- heavily influenced by the printing model introduced in the Document
- Printing Application (DPA) [ISO10175] standard. Although DPA
- specifies both end user and administrative features, IPP version 1.1
- (IPP/1.1) focuses primarily on end user functionality with a few
- additional OPTIONAL operator operations.
-
- The IPP/1.1 model encapsulates the important components of
- distributed printing into two object types:
-
- - Printer (Section 2.1)
- - Job (Section 2.2)
-
- Each object type has an associated set of operations (see section 3)
- and attributes (see section 4).
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 10]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- It is important, however, to understand that in real system
- implementations (which lie underneath the abstracted IPP/1.1 model),
- there are other components of a print service which are not
- explicitly defined in the IPP/1.1 model. The following figure
- illustrates where IPP/1.1 fits with respect to these other
- components.
-
- +--------------+
- | Application |
- o +. . . . . . . |
- \|/ | Spooler |
- / \ +. . . . . . . | +---------+
- End-User | Print Driver |---| File |
- +-----------+ +-----+ +------+-------+ +----+----+
- | Browser | | GUI | | |
- +-----+-----+ +--+--+ | |
- | | | |
- | +---+------------+---+ |
- N D S | | IPP Client |------------+
- O I E | +---------+----------+
- T R C | |
- I E U |
- F C R -------------- Transport ------------------
- I T I
- C O T | --+
- A R Y +--------+--------+ |
- T Y | IPP Server | |
- I +--------+--------+ |
- O | |
- N +-----------------+ | IPP Printer
- | Print Service | |
- +-----------------+ |
- | --+
- +-----------------+
- | Output Device(s)|
- +-----------------+
-
- An IPP Printer object encapsulates the functions normally associated
- with physical output devices along with the spooling, scheduling and
- multiple device management functions often associated with a print
- server. Printer objects are optionally registered as entries in a
- directory where end users find and select them based on some sort of
- filtered and context based searching mechanism (see section 16). The
- directory is used to store relatively static information about the
- Printer, allowing end users to search for and find Printers that
- match their search criteria, for example: name, context, printer
- capabilities, etc. The more dynamic information, such as state,
- currently loaded and ready media, number of jobs at the Printer,
-
-
-
-Hastings, et al. Standards Track [Page 11]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- errors, warnings, and so forth, is directly associated with the
- Printer object itself rather than with the entry in the directory
- which only represents the Printer object.
-
- IPP clients implement the IPP protocol on the client side and give
- end users (or programs running on behalf of end users) the ability to
- query Printer objects and submit and manage print jobs. An IPP
- server is just that part of the Printer object that implements the
- server-side protocol. The rest of the Printer object implements (or
- gateways into) the application semantics of the print service itself.
- The Printer objects may be embedded in an output device or may be
- implemented on a host on the network that communicates with an output
- device.
-
- When a job is submitted to the Printer object and the Printer object
- validates the attributes in the submission request, the Printer
- object creates a new Job object. The end user then interacts with
- this new Job object to query its status and monitor the progress of
- the job. An end user can also cancel their print jobs by using the
- Job object's Cancel-Job operation. An end-user can also hold,
- release, and restart their print jobs using the Job object's OPTIONAL
- Hold-Job, Release-Job, and Restart-Job operations, if implemented.
-
- A privileged operator or administrator of a Printer object can
- cancel, hold, release, and restart any user's job using the REQUIRED
- Cancel-Job and the OPTIONAL Hold-Job, Release-Job, and Restart-Job
- operations. In additional privileged operator or administrator of a
- Printer object can pause, resume, or purge (jobs from) a Printer
- object using the OPTIONAL Pause-Printer, Resume-Printer, and Purge-
- Jobs operations, if implemented.
-
- The notification service is out of scope for this IPP/1.1 document,
- but using such a notification service, the end user is able to
- register for and receive Printer specific and Job specific events.
- An end user can query the status of Printer objects and can follow
- the progress of Job objects by polling using the Get-Printer-
- Attributes, Get-Jobs, and Get-Job-Attributes operations.
-
-2. IPP Objects
-
- The IPP/1.1 model introduces objects of type Printer and Job. Each
- type of object models relevant aspects of a real-world entity such as
- a real printer or real print job. Each object type is defined as a
- set of possible attributes that may be supported by instances of that
- object type. For each object (instance), the actual set of supported
- attributes and values describe a specific implementation. The
- object's attributes and values describe its state, capabilities,
- realizable features, job processing functions, and default behaviors
-
-
-
-Hastings, et al. Standards Track [Page 12]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- and characteristics. For example, the Printer object type is defined
- as a set of attributes that each Printer object potentially supports.
- In the same manner, the Job object type is defined as a set of
- attributes that are potentially supported by each Job object.
-
- Each attribute included in the set of attributes defining an object
- type is labeled as:
-
- - "REQUIRED": each object MUST support the attribute.
- - "RECOMMENDED": each object SHOULD support the attribute.
- - "OPTIONAL": each object MAY support the attribute.
-
- Some definitions of attribute values indicate that an object MUST or
- SHOULD support the value; otherwise, support of the value is
- OPTIONAL.
-
- However, if an implementation supports an attribute, it MUST support
- at least one of the possible values for that attribute.
-
-2.1 Printer Object
-
- The major component of the IPP/1.1 model is the Printer object. A
- Printer object implements the server-side of the IPP/1.1 protocol.
- Using the protocol, end users may query the attributes of the Printer
- object and submit print jobs to the Printer object. The actual
- implementation components behind the Printer abstraction may take on
- different forms and different configurations. However, the model
- abstraction allows the details of the configuration of real
- components to remain opaque to the end user. Section 3 describes
- each of the Printer operations in detail.
-
- The capabilities and state of a Printer object are described by its
- attributes. Printer attributes are divided into two groups:
-
- - "job-template" attributes: These attributes describe supported job
- processing capabilities and defaults for the Printer object. (See
- section 4.2)
- - "printer-description" attributes: These attributes describe the
- Printer object's identification, state, location, references to
- other sources of information about the Printer object, etc. (see
- section 4.4)
-
- Since a Printer object is an abstraction of a generic document output
- device and print service provider, a Printer object could be used to
- represent any real or virtual device with semantics consistent with
- the Printer object, such as a fax device, an imager, or even a CD
- writer.
-
-
-
-
-Hastings, et al. Standards Track [Page 13]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Some examples of configurations supporting a Printer object include:
-
- 1) An output device with no spooling capabilities
- 2) An output device with a built-in spooler
- 3) A print server supporting IPP with one or more associated
- output devices
- 3a) The associated output devices may or may not be capable of
- spooling jobs
- 3b) The associated output devices may or may not support IPP
-
- The following figures show some examples of how Printer objects can
- be realized on top of various distributed printing configurations.
- The embedded case below represents configurations 1 and 2. The hosted
- and fan-out figures below represent configurations 3a and 3b.
-
- In this document the term "client" refers to a software entity that
- sends IPP operation requests to an IPP Printer object and accepts IPP
- operation responses. A client MAY be:
-
- 1. contained within software controlled by an end user, e.g.
- activated by the "Print" menu item in an application or
-
- 2. the print server component that sends IPP requests to either an
- output device or another "downstream" print server.
-
- The term "IPP Printer" is a network entity that accepts IPP operation
- requests and returns IPP operation responses. As such, an IPP object
- MAY be:
-
- 1. an (embedded) device component that accepts IPP requests and
- controls the device or
-
- 2. a component of a print server that accepts IPP requests (where
- the print server controls one or more networked devices using
- IPP or other protocols).
-
- Legend:
-
- ##### indicates a Printer object which is
- either embedded in an output device or is
- hosted in a server. The Printer object
- might or might not be capable of queuing/spooling.
-
- any indicates any network protocol or direct
- connect, including IPP
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 14]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- embedded printer:
- output device
- +---------------+
- O +--------+ | ########### |
- /|\ | client |------------IPP------------># Printer # |
- / \ +--------+ | # Object # |
- | ########### |
- +---------------+
-
- hosted printer:
- +---------------+
- O +--------+ ########### | |
- /|\ | client |--IPP--># Printer #-any->| output device |
- / \ +--------+ # Object # | |
- ########### +---------------+
-
-
- +---------------+
- fan out: | |
- +-->| output device |
- any/ | |
- O +--------+ ########### / +---------------+
- /|\ | client |-IPP-># Printer #--*
- / \ +--------+ # Object # \ +---------------+
- ########### any\ | |
- +-->| output device |
- | |
- +---------------+
-
-2.2 Job Object
-
- A Job object is used to model a print job. A Job object contains
- documents. The information required to create a Job object is sent
- in a create request from the end user via an IPP Client to the
- Printer object. The Printer object validates the create request, and
- if the Printer object accepts the request, the Printer object creates
- the new Job object. Section 3 describes each of the Job operations
- in detail.
-
- The characteristics and state of a Job object are described by its
- attributes. Job attributes are grouped into two groups as follows:
-
- - "job-template" attributes: These attributes can be supplied by
- the client or end user and include job processing instructions
- which are intended to override any Printer object defaults
- and/or instructions embedded within the document data. (See
- section 4.2)
-
-
-
-
-Hastings, et al. Standards Track [Page 15]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- - "job-description" attributes: These attributes describe the Job
- object's identification, state, size, etc. The client supplies
- some of these attributes, and the Printer object generates
- others. (See section 4.3)
-
- An implementation MUST support at least one document per Job object.
- An implementation MAY support multiple documents per Job object. A
- document is either:
-
- - a stream of document data in a format supported by the Printer
- object (typically a Page Description Language - PDL), or
- - a reference to such a stream of document data
-
- In IPP/1.1, a document is not modeled as an IPP object, therefore it
- has no object identifier or associated attributes. All job
- processing instructions are modeled as Job object attributes. These
- attributes are called Job Template attributes and they apply equally
- to all documents within a Job object.
-
-2.3 Object Relationships
-
- IPP objects have relationships that are maintained persistently along
- with the persistent storage of the object attributes.
-
- A Printer object can represent either one or more physical output
- devices or a logical device which "processes" jobs but never actually
- uses a physical output device to put marks on paper. Examples of
- logical devices include a Web page publisher or a gateway into an
- online document archive or repository. A Printer object contains
- zero or more Job objects.
-
- A Job object is contained by exactly one Printer object, however the
- identical document data associated with a Job object could be sent to
- either the same or a different Printer object. In this case, a
- second Job object would be created which would be almost identical to
- the first Job object, however it would have new (different) Job
- object identifiers (see section 2.4).
-
- A Job object is either empty (before any documents have been added)
- or contains one or more documents. If the contained document is a
- stream of document data, that stream can be contained in only one
- document. However, there can be identical copies of the stream in
- other documents in the same or different Job objects. If the
- contained document is just a reference to a stream of document data,
- other documents (in the same or different Job object(s)) may contain
- the same reference.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 16]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-2.4 Object Identity
-
- All Printer and Job objects are identified by a Uniform Resource
- Identifier (URI) [RFC2396] so that they can be persistently and
- unambiguously referenced. Since every URL is a specialized form of a
- URI, even though the more generic term URI is used throughout the
- rest of this document, its usage is intended to cover the more
- specific notion of URL as well.
-
- An administrator configures Printer objects to either support or not
- support authentication and/or message privacy using Transport Layer
- Security (TLS) [RFC2246] (the mechanism for security configuration is
- outside the scope of this IPP/1.1 document). In some situations,
- both types of connections (both authenticated and unauthenticated)
- can be established using a single communication channel that has some
- sort of negotiation mechanism. In other situations, multiple
- communication channels are used, one for each type of security
- configuration. Section 8 provides a full description of all security
- considerations and configurations.
-
- If a Printer object supports more than one communication channel,
- some or all of those channels might support and/or require different
- security mechanisms. In such cases, an administrator could expose
- the simultaneous support for these multiple communication channels as
- multiple URIs for a single Printer object where each URI represents
- one of the communication channels to the Printer object. To support
- this flexibility, the IPP Printer object type defines a multi-valued
- identification attribute called the "printer-uri-supported"
- attribute. It MUST contain at least one URI. It MAY contain more
- than one URI. That is, every Printer object will have at least one
- URI that identifies at least one communication channel to the Printer
- object, but it may have more than one URI where each URI identifies a
- different communication channel to the Printer object. The
- "printer-uri-supported" attribute has two companion attributes, the
- "uri-security-supported" attribute and the "uri-authentication-
- supported". Both have the same cardinality as "printer-uri-
- supported". The purpose of the "uri-security-supported" attribute is
- to indicate the security mechanisms (if any) used for each URI listed
- in "printer-uri-supported". The purpose of the "uri-authentication-
- supported" attribute is to indicate the authentication mechanisms (if
- any) used for each URI listed in "printer-uri-supported". These
- three attributes are fully described in sections 4.4.1, 4.4.2, and
- 4.4.3.
-
- When a job is submitted to the Printer object via a create request,
- the client supplies only a single Printer object URI. The client
- supplied Printer object URI MUST be one of the values in the
- "printer-uri-supported" Printer attribute.
-
-
-
-Hastings, et al. Standards Track [Page 17]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- IPP/1.1 does not specify how the client obtains the client supplied
- URI, but it is RECOMMENDED that a Printer object be registered as an
- entry in a directory service. End-users and programs can then
- interrogate the directory searching for Printers. Section 16 defines
- a generic schema for Printer object entries in the directory service
- and describes how the entry acts as a bridge to the actual IPP
- Printer object. The entry in the directory that represents the IPP
- Printer object includes the possibly many URIs for that Printer
- object as values in one its attributes.
-
- When a client submits a create request to the Printer object, the
- Printer object validates the request and creates a new Job object.
- The Printer object assigns the new Job object a URI which is stored
- in the "job-uri" Job attribute. This URI is then used by clients as
- the target for subsequent Job operations. The Printer object
- generates a Job URI based on its configured security policy and the
- URI used by the client in the create request.
-
- For example, consider a Printer object that supports both a
- communication channel secured by the use of SSL3 (using HTTP over
- SSL3 with an "https" schemed URI) and another open communication
- channel that is not secured with SSL3 (using a simple "http" schemed
- URI). If a client were to submit a job using the secure URI, the
- Printer object would assign the new Job object a secure URI as well.
- If a client were to submit a job using the open-channel URI, the
- Printer would assign the new Job object an open-channel URI.
-
- In addition, the Printer object also populates the Job object's
- "job-printer-uri" attribute. This is a reference back to the Printer
- object that created the Job object. If a client only has access to a
- Job object's "job-uri" identifier, the client can query the Job's
- "job-printer-uri" attribute in order to determine which Printer
- object created the Job object. If the Printer object supports more
- than one URI, the Printer object picks the one URI supplied by the
- client when creating the job to build the value for and to populate
- the Job's "job-printer-uri" attribute.
-
- Allowing Job objects to have URIs allows for flexibility and
- scalability. For example, in some implementations, the Printer
- object might create Jobs that are processed in the same local
- environment as the Printer object itself. In this case, the Job URI
- might just be a composition of the Printer's URI and some unique
- component for the Job object, such as the unique 32-bit positive
- integer mentioned later in this paragraph. In other implementations,
- the Printer object might be a central clearing-house for validating
- all Job object creation requests, but the Job object itself might be
- created in some environment that is remote from the Printer object.
- In this case, the Job object's URI may have no physical-location
-
-
-
-Hastings, et al. Standards Track [Page 18]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- relationship at all to the Printer object's URI. Again, the fact
- that Job objects have URIs allows for flexibility and scalability,
- however, many existing printing systems have local models or
- interface constraints that force print jobs to be identified using
- only a 32-bit positive integer rather than an independent URI. This
- numeric Job ID is only unique within the context of the Printer
- object to which the create request was originally submitted.
- Therefore, in order to allow both types of client access to IPP Job
- objects (either by Job URI or by numeric Job ID), when the Printer
- object successfully processes a create request and creates a new Job
- object, the Printer object MUST generate both a Job URI and a Job ID.
- The Job ID (stored in the "job-id" attribute) only has meaning in the
- context of the Printer object to which the create request was
- originally submitted. This requirement to support both Job URIs and
- Job IDs allows all types of clients to access Printer objects and Job
- objects no matter the local constraints imposed on the client
- implementation.
-
- In addition to identifiers, Printer objects and Job objects have
- names ("printer-name" and "job-name"). An object name NEED NOT be
- unique across all instances of all objects. A Printer object's name
- is chosen and set by an administrator through some mechanism outside
- the scope of this IPP/1.1 document. A Job object's name is
- optionally chosen and supplied by the IPP client submitting the job.
- If the client does not supply a Job object name, the Printer object
- generates a name for the new Job object. In all cases, the name only
- has local meaning.
-
- To summarize:
-
- - Each Printer object is identified with one or more URIs. The
- Printer's "printer-uri-supported" attribute contains the URI(s).
- - The Printer object's "uri-security-supported" attribute
- identifies the communication channel security protocols that may
- or may not have been configured for the various Printer object
- URIs (e.g., 'tls' or 'none').
- - The Printer object's "uri-authentication-supported" attribute
- identifies the authentication mechanisms that may or may not
- have been configured for the various Printer object URIs (e.g.,
- 'digest' or 'none').
- - Each Job object is identified with a Job URI. The Job's "job-
- uri" attribute contains the URI.
- - Each Job object is also identified with Job ID which is a 32-
- bit, positive integer. The Job's "job-id" attribute contains
- the Job ID. The Job ID is only unique within the context of the
- Printer object which created the Job object.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 19]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- - Each Job object has a "job-printer-uri" attribute which contains
- the URI of the Printer object that was used to create the Job
- object. This attribute is used to determine the Printer object
- that created a Job object when given only the URI for the Job
- object. This linkage is necessary to determine the languages,
- charsets, and operations which are supported on that Job (the
- basis for such support comes from the creating Printer object).
- - Each Printer object has a name (which is not necessarily
- unique). The administrator chooses and sets this name through
- some mechanism outside the scope of this IPP/1.1 document. The
- Printer object's "printer-name" attribute contains the name.
- - Each Job object has a name (which is not necessarily unique).
- The client optionally supplies this name in the create request.
- If the client does not supply this name, the Printer object
- generates a name for the Job object. The Job object's "job-name"
- attribute contains the name.
-
-3. IPP Operations
-
- IPP objects support operations. An operation consists of a request
- and a response. When a client communicates with an IPP object, the
- client issues an operation request to the URI for that object.
- Operation requests and responses have parameters that identify the
- operation. Operations also have attributes that affect the run-time
- characteristics of the operation (the intended target, localization
- information, etc.). These operation-specific attributes are called
- operation attributes (as compared to object attributes such as
- Printer object attributes or Job object attributes). Each request
- carries along with it any operation attributes, object attributes,
- and/or document data required to perform the operation. Each request
- requires a response from the object. Each response indicates success
- or failure of the operation with a status code as a response
- parameter. The response contains any operation attributes, object
- attributes, and/or status messages generated during the execution of
- the operation request.
-
- This section describes the semantics of the IPP operations, both
- requests and responses, in terms of the parameters, attributes, and
- other data associated with each operation.
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 20]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- The IPP/1.1 Printer operations are:
-
- Print-Job (section 3.2.1)
- Print-URI (section 3.2.2)
- Validate-Job (section 3.2.3)
- Create-Job (section 3.2.4)
- Get-Printer-Attributes (section 3.2.5)
- Get-Jobs (section 3.2.6)
- Pause-Printer (section 3.3.5)
- Resume-Printer (section 3.3.6)
- Purge-Jobs (section 3.3.7)
-
- The Job operations are:
-
- Send-Document (section 3.3.1)
- Send-URI (section 3.3.2)
- Cancel-Job (section 3.3.3)
- Get-Job-Attributes (section 3.3.4)
- Hold-Job (section 3.3.5)
- Release-Job (section 3.3.6)
- Restart-Job (section 3.3.7)
-
- The Send-Document and Send-URI Job operations are used to add a new
- document to an existing multi-document Job object created using the
- Create-Job operation.
-
-3.1 Common Semantics
-
- All IPP operations require some common parameters and operation
- attributes. These common elements and their semantic characteristics
- are defined and described in more detail in the following sections.
-
-3.1.1 Required Parameters
-
- Every operation request contains the following REQUIRED parameters:
-
- - a "version-number",
- - an "operation-id",
- - a "request-id", and
- - the attributes that are REQUIRED for that type of request.
-
- Every operation response contains the following REQUIRED parameters:
-
- - a "version-number",
- - a "status-code",
- - the "request-id" that was supplied in the corresponding request,
- and
- - the attributes that are REQUIRED for that type of response.
-
-
-
-Hastings, et al. Standards Track [Page 21]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- The "Encoding and Transport" document [RFC2910] defines special rules
- for the encoding of these parameters. All other operation elements
- are represented using the more generic encoding rules for attributes
- and groups of attributes.
-
-3.1.2 Operation IDs and Request IDs
-
- Each IPP operation request includes an identifying "operation-id"
- value. Valid values are defined in the "operations-supported"
- Printer attribute section (see section 4.4.15). The client specifies
- which operation is being requested by supplying the correct
- "operation-id" value.
-
- In addition, every invocation of an operation is identified by a
- "request-id" value. For each request, the client chooses the
- "request-id" which MUST be an integer (possibly unique depending on
- client requirements) in the range from 1 to 2**31 - 1 (inclusive).
- This "request-id" allows clients to manage multiple outstanding
- requests. The receiving IPP object copies all 32-bits of the client-
- supplied "request-id" attribute into the response so that the client
- can match the response with the correct outstanding request, even if
- the "request-id" is out of range. If the request is terminated
- before the complete "request-id" is received, the IPP object rejects
- the request and returns a response with a "request-id" of 0.
-
- Note: In some cases, the transport protocol underneath IPP might be a
- connection oriented protocol that would make it impossible for a
- client to receive responses in any order other than the order in
- which the corresponding requests were sent. In such cases, the
- "request-id" attribute would not be essential for correct protocol
- operation. However, in other mappings, the operation responses can
- come back in any order. In these cases, the "request-id" would be
- essential.
-
-3.1.3 Attributes
-
- Operation requests and responses are both composed of groups of
- attributes and/or document data. The attributes groups are:
-
- - Operation Attributes: These attributes are passed in the
- operation and affect the IPP object's behavior while processing
- the operation request and may affect other attributes or groups
- of attributes. Some operation attributes describe the document
- data associated with the print job and are associated with new
- Job objects, however most operation attributes do not persist
- beyond the life of the operation. The description of each
- operation attribute includes conformance statements indicating
- which operation attributes are REQUIRED and which are OPTIONAL
-
-
-
-Hastings, et al. Standards Track [Page 22]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- for an IPP object to support and which attributes a client MUST
- supply in a request and an IPP object MUST supply in a response.
- - Job Template Attributes: These attributes affect the processing
- of a job. A client OPTIONALLY supplies Job Template Attributes
- in a create request, and the receiving object MUST be prepared
- to receive all supported attributes. The Job object can later
- be queried to find out what Job Template attributes were
- originally requested in the create request, and such attributes
- are returned in the response as Job Object Attributes. The
- Printer object can be queried about its Job Template attributes
- to find out what type of job processing capabilities are
- supported and/or what the default job processing behaviors are,
- though such attributes are returned in the response as Printer
- Object Attributes. The "ipp-attribute-fidelity" operation
- attribute affects processing of all client-supplied Job Template
- attributes (see sections 3.2.1.2 and 15 for a full description
- of "ipp-attribute-fidelity" and its relationship to other
- attributes).
- - Job Object Attributes: These attributes are returned in response
- to a query operation directed at a Job object.
- - Printer Object Attributes: These attributes are returned in
- response to a query operation directed at a Printer object.
- - Unsupported Attributes: In a create request, the client supplies
- a set of Operation and Job Template attributes. If any of these
- attributes or their values is unsupported by the Printer object,
- the Printer object returns the set of unsupported attributes in
- the response. Sections 3.1.7, 3.2.1.2, and 15 give a full
- description of how Job Template attributes supplied by the
- client in a create request are processed by the Printer object
- and how unsupported attributes are returned to the client.
- Because of extensibility, any IPP object might receive a request
- that contains new or unknown attributes or values for which it
- has no support. In such cases, the IPP object processes what it
- can and returns the unsupported attributes in the response. The
- Unsupported Attribute group is defined for all operation
- responses for returning unsupported attributes that the client
- supplied in the request.
-
- Later in this section, each operation is formally defined by
- identifying the allowed and expected groups of attributes for each
- request and response. The model identifies a specific order for each
- group in each request or response, but the attributes within each
- group may be in any order, unless specified otherwise.
-
- The attributes within a group MUST be unique; if an attribute with
- the same name occurs more than once, the group is mal-formed.
- Clients MUST NOT submit such malformed requests and Printers MUST NOT
- return such malformed responses. If such a malformed request is
-
-
-
-Hastings, et al. Standards Track [Page 23]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- submitted to a Printer, the Printer MUST either (1) reject the
- request with the 'client-error-bad-request' status code (see section
- 13.1.4.1) or (2) process the request normally after selecting only
- one of the attribute instances, depending on implementation. Which
- attribute is selected when there are duplicate attributes depends on
- implementation. The IPP Printer MUST NOT use the values from more
- than one such duplicate attribute instance.
-
- Each attribute definition includes the attribute's name followed by
- the name of its attribute syntax(es) in parenthesizes. In addition,
- each 'integer' attribute is followed by the allowed range in
- parentheses, (m:n), for values of that attribute. Each 'text' or
- 'name' attribute is followed by the maximum size in octets in
- parentheses, (size), for values of that attribute. For more details
- on attribute syntax notation, see the descriptions of these
- attributes syntaxes in section 4.1.
-
- Note: Document data included in the operation is not strictly an
- attribute, but it is treated as a special attribute group for
- ordering purposes. The only operations that support supplying the
- document data within an operation request are Print-Job and Send-
- Document. There are no operation responses that include document
- data.
-
- Some operations are REQUIRED for IPP objects to support; the others
- are OPTIONAL (see section 5.2.2). Therefore, before using an
- OPTIONAL operation, a client SHOULD first use the REQUIRED Get-
- Printer-Attributes operation to query the Printer's "operations-
- supported" attribute in order to determine which OPTIONAL Printer and
- Job operations are actually supported. The client SHOULD NOT use an
- OPTIONAL operation that is not supported. When an IPP object
- receives a request to perform an operation it does not support, it
- returns the 'server-error-operation-not-supported' status code (see
- section 13.1.5.2). An IPP object is non-conformant if it does not
- support a REQUIRED operation.
-
-3.1.4 Character Set and Natural Language Operation Attributes
-
- Some Job and Printer attributes have values that are text strings and
- names intended for human understanding rather than machine
- understanding (see the 'text' and 'name' attribute syntax
- descriptions in section 4.1). The following sections describe two
- special Operation Attributes called "attributes-charset" and
- "attributes-natural-language". These attributes are always part of
- the Operation Attributes group. For most attribute groups, the order
- of the attributes within the group is not important. However, for
- these two attributes within the Operation Attributes group, the order
- is critical. The "attributes-charset" attribute MUST be the first
-
-
-
-Hastings, et al. Standards Track [Page 24]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- attribute in the group and the "attributes-natural-language"
- attribute MUST be the second attribute in the group. In other words,
- these attributes MUST be supplied in every IPP request and response,
- they MUST come first in the group, and MUST come in the specified
- order. For job creation operations, the IPP Printer implementation
- saves these two attributes with the new Job object as Job Description
- attributes. For the sake of brevity in this document, these
- operation attribute descriptions are not repeated with every
- operation request and response, but have a reference back to this
- section instead.
-
-3.1.4.1 Request Operation Attributes
-
- The client MUST supply and the Printer object MUST support the
- following REQUIRED operation attributes in every IPP/1.1 operation
- request:
-
- "attributes-charset" (charset):
- This operation attribute identifies the charset (coded
- character set and encoding method) used by any 'text' and
- 'name' attributes that the client is supplying in this request.
- It also identifies the charset that the Printer object MUST use
- (if supported) for all 'text' and 'name' attributes and status
- messages that the Printer object returns in the response to
- this request. See Sections 4.1.1 and 4.1.2 for the definition
- of the 'text' and 'name' attribute syntaxes.
-
- All clients and IPP objects MUST support the 'utf-8' charset
- [RFC2279] and MAY support additional charsets provided that
- they are registered with IANA [IANA-CS]. If the Printer object
- does not support the client supplied charset value, the Printer
- object MUST reject the request, set the "attributes-charset" to
- 'utf-8' in the response, and return the 'client-error-charset-
- not-supported' status code and any 'text' or 'name' attributes
- using the 'utf-8' charset. The Printer NEED NOT return any
- attributes in the Unsupported Attributes Group (See sections
- 3.1.7 and 3.2.1.2). The Printer object MUST indicate the
- charset(s) supported as the values of the "charset-supported"
- Printer attribute (see Section 4.4.18), so that the client can
- query to determine which charset(s) are supported.
-
- Note to client implementers: Since IPP objects are only
- required to support the 'utf-8' charset, in order to maximize
- interoperability with multiple IPP object implementations, a
- client may want to supply 'utf-8' in the "attributes-charset"
- operation attribute, even though the client is only passing and
- able to present a simpler charset, such as US-ASCII [ASCII] or
- ISO-8859-1 [ISO8859-1]. Then the client will have to filter
-
-
-
-Hastings, et al. Standards Track [Page 25]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- out (or charset convert) those characters that are returned in
- the response that it cannot present to its user. On the other
- hand, if both the client and the IPP objects also support a
- charset in common besides utf-8, the client may want to use
- that charset in order to avoid charset conversion or data loss.
-
- See the 'charset' attribute syntax description in Section 4.1.7
- for the syntax and semantic interpretation of the values of
- this attribute and for example values.
-
- "attributes-natural-language" (naturalLanguage):
- This operation attribute identifies the natural language used
- by any 'text' and 'name' attributes that the client is
- supplying in this request. This attribute also identifies the
- natural language that the Printer object SHOULD use for all
- 'text' and 'name' attributes and status messages that the
- Printer object returns in the response to this request. See
- the 'naturalLanguage' attribute syntax description in section
- 4.1.8 for the syntax and semantic interpretation of the values
- of this attribute and for example values.
-
- There are no REQUIRED natural languages required for the
- Printer object to support. However, the Printer object's
- "generated-natural-language-supported" attribute identifies the
- natural languages supported by the Printer object and any
- contained Job objects for all text strings generated by the IPP
- object. A client MAY query this attribute to determine which
- natural language(s) are supported for generated messages.
-
- For any of the attributes for which the Printer object
- generates text, i.e., for the "job-state-message", "printer-
- state-message", and status messages (see Section 3.1.6), the
- Printer object MUST be able to generate these text strings in
- any of its supported natural languages. If the client requests
- a natural language that is not supported, the Printer object
- MUST return these generated messages in the Printer's
- configured natural language as specified by the Printer's
- "natural-language-configured" attribute" (see Section 4.4.19).
-
- For other 'text' and 'name' attributes supplied by the client,
- authentication system, operator, system administrator, or
- manufacturer (i.e., for "job-originating-user-name", "printer-
- name" (name), "printer-location" (text), "printer-info" (text),
- and "printer-make-and-model" (text)), the Printer object is
- only required to support the configured natural language of the
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 26]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Printer identified by the Printer object's "natural-language-
- configured" attribute, though support of additional natural
- languages for these attributes is permitted.
-
- For any 'text' or 'name' attribute in the request that is in a
- different natural language than the value supplied in the
- "attributes-natural-language" operation attribute, the client
- MUST use the Natural Language Override mechanism (see sections
- 4.1.1.2 and 4.1.2.2) for each such attribute value supplied.
- The client MAY use the Natural Language Override mechanism
- redundantly, i.e., use it even when the value is in the same
- natural language as the value supplied in the "attributes-
- natural-language" operation attribute of the request.
-
- The IPP object MUST accept any natural language and any Natural
- Language Override, whether the IPP object supports that natural
- language or not (and independent of the value of the "ipp-
- attribute-fidelity" Operation attribute). That is the IPP
- object accepts all client supplied values no matter what the
- values are in the Printer object's "generated-natural-
- language-supported" attribute. That attribute, "generated-
- natural-language-supported", only applies to generated
- messages, not client supplied messages. The IPP object MUST
- remember that natural language for all client-supplied
- attributes, and when returning those attributes in response to
- a query, the IPP object MUST indicate that natural language.
-
- Each value whose attribute syntax type is 'text' or 'name' (see
- sections 4.1.1 and 4.1.2) has an Associated Natural-Language.
- This document does not specify how this association is stored
- in a Printer or Job object. When such a value is encoded in a
- request or response, the natural language is either implicit or
- explicit:
-
- - In the implicit case, the value contains only the text/name
- value, and the language is specified by the "attributes-
- natural-language" operation attribute in the request or
- response (see sections 4.1.1.1 textWithoutLanguage and
- 4.1.2.1 nameWithoutLanguage).
-
- - In the explicit case (also known as the Natural-Language
- Override case), the value contains both the language and the
- text/name value (see sections 4.1.1.2 textWithLanguage and
- 4.1.2.2 nameWithLanguage).
-
- For example, the "job-name" attribute MAY be supplied by the
- client in a create request. The text value for this attribute
- will be in the natural language identified by the "attribute-
-
-
-
-Hastings, et al. Standards Track [Page 27]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- natural-language" attribute, or if different, as identified by
- the Natural Language Override mechanism. If supplied, the IPP
- object will use the value of the "job-name" attribute to
- populate the Job object's "job-name" attribute. Whenever any
- client queries the Job object's "job-name" attribute, the IPP
- object returns the attribute as stored and uses the Natural
- Language Override mechanism to specify the natural language, if
- it is different from that reported in the "attributes-natural-
- language" operation attribute of the response. The IPP object
- MAY use the Natural Language Override mechanism redundantly,
- i.e., use it even when the value is in the same natural
- language as the value supplied in the "attributes-natural-
- language" operation attribute of the response.
-
- An IPP object MUST NOT reject a request based on a supplied
- natural language in an "attributes-natural-language" Operation
- attribute or in any attribute that uses the Natural Language
- Override.
-
- Clients SHOULD NOT supply 'text' or 'name' attributes that use an
- illegal combination of natural language and charset. For example,
- suppose a Printer object supports charsets 'utf-8', 'iso-8859-1', and
- 'iso-8859-7'. Suppose also, that it supports natural languages 'en'
- (English), 'fr' (French), and 'el' (Greek). Although the Printer
- object supports the charset 'iso-8859-1' and natural language 'el',
- it probably does not support the combination of Greek text strings
- using the 'iso-8859-1' charset. The Printer object handles this
- apparent incompatibility differently depending on the context in
- which it occurs:
-
- - In a create request: If the client supplies a text or name
- attribute (for example, the "job-name" operation attribute) that
- uses an apparently incompatible combination, it is a client
- choice that does not affect the Printer object or its correct
- operation. Therefore, the Printer object simply accepts the
- client supplied value, stores it with the Job object, and
- responds back with the same combination whenever the client (or
- any client) queries for that attribute.
- - In a query-type operation, like Get-Printer-Attributes: If the
- client requests an apparently incompatible combination, the
- Printer object responds (as described in section 3.1.4.2) using
- the Printer's configured natural language rather than the
- natural language requested by the client.
-
- In either case, the Printer object does not reject the request
- because of the apparent incompatibility. The potential incompatible
- combination of charset and natural language can occur either at the
- global operation level or at the Natural Language Override
-
-
-
-Hastings, et al. Standards Track [Page 28]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- attribute-by-attribute level. In addition, since the response always
- includes explicit charset and natural language information, there is
- never any question or ambiguity in how the client interprets the
- response.
-
-3.1.4.2 Response Operation Attributes
-
- The Printer object MUST supply and the client MUST support the
- following REQUIRED operation attributes in every IPP/1.1 operation
- response:
-
- "attributes-charset" (charset):
- This operation attribute identifies the charset used by any
- 'text' and 'name' attributes that the Printer object is
- returning in this response. The value in this response MUST be
- the same value as the "attributes-charset" operation attribute
- supplied by the client in the request. If this is not possible
- (i.e., the charset requested is not supported), the request
- would have been rejected. See "attributes-charset" described
- in Section 3.1.4.1 above.
-
- If the Printer object supports more than just the 'utf-8'
- charset, the Printer object MUST be able to code convert
- between each of the charsets supported on a highest fidelity
- possible basis in order to return the 'text' and 'name'
- attributes in the charset requested by the client. However,
- some information loss MAY occur during the charset conversion
- depending on the charsets involved. For example, the Printer
- object may convert from a UTF-8 'a' to a US-ASCII 'a' (with no
- loss of information), from an ISO Latin 1 CAPITAL LETTER A WITH
- ACUTE ACCENT to US-ASCII 'A' (losing the accent), or from a
- UTF-8 Japanese Kanji character to some ISO Latin 1 error
- character indication such as '?', decimal code equivalent, or
- to the absence of a character, depending on implementation.
-
- Whether an implementation that supports more than one charset
- stores the data in the charset supplied by the client or code
- converts to one of the other supported charsets, depends on
- implementation. The strategy should try to minimize loss of
- information during code conversion. On each response, such an
- implementation converts from its internal charset to that
- requested.
-
- "attributes-natural-language" (naturalLanguage):
- This operation attribute identifies the natural language used
- by any 'text' and 'name' attributes that the IPP object is
- returning in this response. Unlike the "attributes-charset"
- operation attribute, the IPP object NEED NOT return the same
-
-
-
-Hastings, et al. Standards Track [Page 29]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- value as that supplied by the client in the request. The IPP
- object MAY return the natural language of the Job object or the
- Printer's configured natural language as identified by the
- Printer object's "natural-language-configured" attribute,
- rather than the natural language supplied by the client. For
- any 'text' or 'name' attribute or status message in the
- response that is in a different natural language than the value
- returned in the "attributes-natural-language" operation
- attribute, the IPP object MUST use the Natural Language
- Override mechanism (see sections 4.1.1.2 and 4.1.2.2) on each
- attribute value returned. The IPP object MAY use the Natural
- Language Override mechanism redundantly, i.e., use it even when
- the value is in the same natural language as the value supplied
- in the "attributes-natural-language" operation attribute of the
- response.
-
-3.1.5 Operation Targets
-
- All IPP operations are directed at IPP objects. For Printer
- operations, the operation is always directed at a Printer object
- using one of its URIs (i.e., one of the values in the Printer
- object's "printer-uri-supported" attribute). Even if the Printer
- object supports more than one URI, the client supplies only one URI
- as the target of the operation. The client identifies the target
- object by supplying the correct URI in the "printer-uri (uri)"
- operation attribute.
-
- For Job operations, the operation is directed at either:
-
- - The Job object itself using the Job object's URI. In this case,
- the client identifies the target object by supplying the correct
- URI in the "job-uri (uri)" operation attribute.
- - The Printer object that created the Job object using both the
- Printer objects URI and the Job object's Job ID. Since the
- Printer object that created the Job object generated the Job ID,
- it MUST be able to correctly associate the client supplied Job
- ID with the correct Job object. The client supplies the Printer
- object's URI in the "printer-uri (uri)" operation attribute and
- the Job object's Job ID in the "job-id (integer(1:MAX))"
- operation attribute.
-
- If the operation is directed at the Job object directly using the Job
- object's URI, the client MUST NOT include the redundant "job-id"
- operation attribute.
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 30]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- The operation target attributes are REQUIRED operation attributes
- that MUST be included in every operation request. Like the charset
- and natural language attributes (see section 3.1.4), the operation
- target attributes are specially ordered operation attributes. In all
- cases, the operation target attributes immediately follow the
- "attributes-charset" and "attributes-natural-language" attributes
- within the operation attribute group, however the specific ordering
- rules are:
-
- - In the case where there is only one operation target attribute
- (i.e., either only the "printer-uri" attribute or only the
- "job-uri" attribute), that attribute MUST be the third attribute
- in the operation attributes group.
- - In the case where Job operations use two operation target
- attributes (i.e., the "printer-uri" and "job-id" attributes),
- the "printer-uri" attribute MUST be the third attribute and the
- "job-id" attribute MUST be the fourth attribute.
-
- In all cases, the target URIs contained within the body of IPP
- operation requests and responses must be in absolute format rather
- than relative format (a relative URL identifies a resource with the
- scope of the HTTP server, but does not include scheme, host or port).
-
- The following rules apply to the use of port numbers in URIs that
- identify IPP objects:
-
- 1. If the URI scheme allows the port number to be explicitly
- included in the URI string, and a port number is specified
- within the URI, then that port number MUST be used by the
- client to contact the IPP object.
-
- 2. If the URI scheme allows the port number to be explicitly
- included in the URI string, and a port number is not specified
- within the URI, then default port number implied by that URI
- scheme MUST be used by the client to contact the IPP object.
-
- 3. If the URI scheme does not allow an explicit port number to be
- specified within the URI, then the default port number implied
- by that URI MUST be used by the client to contact the IPP
- object.
-
- Note: The IPP "Encoding and Transport document [RFC2910] shows a
- mapping of IPP onto HTTP/1.1 [RFC2616] and defines a new default port
- number for using IPP over HTTP/1.1.
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 31]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-3.1.6 Operation Response Status Codes and Status Messages
-
- Every operation response includes a REQUIRED "status-code" parameter
- and an OPTIONAL "status-message" operation attribute, and an OPTIONAL
- "detailed-status-message" operation attribute. The Print-URI and
- Send-URI response MAY include an OPTIONAL "document-access-error"
- operation attribute.
-
-3.1.6.1 "status-code" (type2 enum)
-
- The REQUIRED "status-code" parameter provides information on the
- processing of a request.
-
- The status code is intended for use by automata. A client
- implementation of IPP SHOULD convert status code values into any
- localized message that has semantic meaning to the end user.
-
- The "status-code" value is a numeric value that has semantic meaning.
- The "status-code" syntax is similar to a "type2 enum" (see section
- 4.1 on "Attribute Syntaxes") except that values can range only from
- 0x0000 to 0x7FFF. Section 13 describes the status codes, assigns the
- numeric values, and suggests a corresponding status message for each
- status code for use by the client when the user's natural language is
- English.
-
- If the Printer performs an operation with no errors and it encounters
- no problems, it MUST return the status code 'successful-ok' in the
- response. See section 13.
-
- If the client supplies unsupported values for the following
- parameters or Operation attributes, the Printer object MUST reject
- the operation, NEED NOT return the unsupported attribute value in the
- Unsupported Attributes group, and MUST return the indicated status
- code:
-
- Parameter/Attribute Status code
-
- version-number server-error-version-not-supported
- operation-id server-error-operation-not-supported
- attributes-charset client-error-charset-not-supported
- compression client-error-compression-not-supported
- document-format client-error-document-format-not-supported
- document-uri client-error-uri-scheme-not-supported,
- client-error-document-access-error
-
- If the client supplies unsupported values for other attributes, or
- unsupported attributes, the Printer returns the status code defined
- in section 3.1.7 on Unsupported Attributes.
-
-
-
-Hastings, et al. Standards Track [Page 32]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-3.1.6.2 "status-message" (text(255))
-
- The OPTIONAL "status-message" operation attribute provides a short
- textual description of the status of the operation. The "status-
- message" attribute's syntax is "text(255)", so the maximum length is
- 255 octets (see section 4.1.1). The status message is intended for
- the human end user. If a response does include a "status-message"
- attribute, an IPP client NEED NOT examine or display the messages,
- however it SHOULD do so in some implementation specific manner. The
- "status-message" is especially useful for a later version of a
- Printer object to return as supplemental information for the human
- user to accompany a status code that an earlier version of a client
- might not understand.
-
- If the Printer object supports the "status-message" operation
- attribute, the Printer object MUST be able to generate this message
- in any of the natural languages identified by the Printer object's
- "generated-natural-language-supported" attribute (see the
- "attributes-natural-language" operation attribute specified in
- section 3.1.4.1. Section 13 suggests the text for the status message
- returned by the Printer for use with the English natural language.
-
- As described in section 3.1.4.1 for any returned 'text' attribute, if
- there is a choice for generating this message, the Printer object
- uses the natural language indicated by the value of the "attributes-
- natural-language" in the client request if supported, otherwise the
- Printer object uses the value in the Printer object's own "natural-
- language-configured" attribute.
-
- If the Printer object supports the "status-message" operation
- attribute, it SHOULD use the REQUIRED 'utf-8' charset to return a
- status message for the following error status codes (see section 13):
- 'client-error-bad-request', 'client-error-charset-not-supported',
- 'server-error-internal-error', 'server-error-operation-not-
- supported', and 'server-error-version-not-supported'. In this case,
- it MUST set the value of the "attributes-charset" operation attribute
- to 'utf-8' in the error response.
-
-3.1.6.3 "detailed-status-message" (text(MAX))
-
- The OPTIONAL "detailed-status-message" operation attribute provides
- additional more detailed technical and implementation-specific
- information about the operation. The "detailed-status-message"
- attribute's syntax is "text(MAX)", so the maximum length is 1023
- octets (see section 4.1.1). If the Printer objects supports the
- "detailed-status-message" operation attribute, the Printer NEED NOT
- localize the message, since it is intended for use by the system
- administrator or other experienced technical persons. Localization
-
-
-
-Hastings, et al. Standards Track [Page 33]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- might obscure the technical meaning of such messages. Clients MUST
- NOT attempt to parse the value of this attribute. See the
- "document-access-error" operation attribute (section 3.1.6.4) for
- additional errors that a program can process.
-
-3.1.6.4 "document-access-error" (text(MAX))
-
- This OPTIONAL operation attribute provides additional information
- about any document access errors encountered by the Printer before it
- returned a response to the Print-URI (section 3.2.2) or Send-URI
- (section 3.3.1) operation. For errors in the protocol identified by
- the URI scheme in the "document-uri" operation attribute, such as
- 'http:' or 'ftp:', the error code is returned in parentheses,
- followed by the URI. For example:
-
- (404) http://ftp.pwg.org/pub/pwg/ipp/new_MOD/ipp-model-v11.pdf
-
- Most Internet protocols use decimal error codes (unlike IPP), so the
- ASCII error code representation is in decimal.
-
-3.1.7 Unsupported Attributes
-
- The Unsupported Attributes group contains attributes that are not
- supported by the operation. This group is primarily for the job
- creation operations, but all operations can return this group.
-
- A Printer object MUST include an Unsupported Attributes group in a
- response if the status code is one of the following: 'successful-
- ok-ignored-or-substituted-attributes', 'successful-ok-conflicting-
- attributes', 'client-error-attributes-or-values-not-supported' or
- 'client-error-conflicting-attributes'.
-
- If the status code is one of the four specified in the preceding
- paragraph, the Unsupported Attributes group MUST contain all of those
- attributes and only those attributes that are:
-
- a. an Operation or Job Template attribute supplied in the request,
- and
-
- b. unsupported by the printer. See below for details on the three
- categories "unsupported" attributes.
-
- If the status code is one of those in the table in section 3.1.6.1,
- the Unsupported Attributes group NEED NOT contain the unsupported
- parameter or attribute indicated in that table.
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 34]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- If the Printer object is not returning any Unsupported Attributes in
- the response, the Printer object SHOULD omit Group 2 rather than
- sending an empty group. However, a client MUST be able to accept an
- empty group.
-
- Unsupported attributes fall into three categories:
-
- 1. The Printer object does not support the supplied attribute (no
- matter what the attribute syntax or value).
-
- 2. The Printer object does support the attribute, but does not
- support some or all of the particular attribute syntaxes or
- values supplied by the client (i.e., the Printer object does
- not have those attribute syntaxes or values in its
- corresponding "xxx-supported" attribute).
-
- 3. The Printer object does support the attributes and values
- supplied, but the particular values are in conflict with one
- another, because they violate a constraint, such as not being
- able to staple transparencies.
-
- In the case of an unsupported attribute name, the Printer object
- returns the client-supplied attribute with a substituted value of
- 'unsupported'. This value's syntax type is "out-of-band" and its
- encoding is defined by special rules for "out-of-band" values in the
- "Encoding and Transport" document [RFC2910]. Its value indicates no
- support for the attribute itself (see the beginning of section 4.1).
-
- In the case of a supported attribute with one or more unsupported
- attribute syntaxes or values, the Printer object simply returns the
- client-supplied attribute with the unsupported attribute syntaxes or
- values as supplied by the client. This indicates support for the
- attribute, but no support for that particular attribute syntax or
- value. If the client supplies a multi-valued attribute with more
- than one value and the Printer object supports the attribute but only
- supports a subset of the client-supplied attribute syntaxes or
- values, the Printer object
-
- MUST return only those attribute syntaxes or values that are
- unsupported.
-
- In the case of two (or more) supported attribute values that are in
- conflict with one another (although each is supported independently,
- the values conflict when requested together within the same job), the
- Printer object MUST return all the values that it ignores or
- substitutes to resolve the conflict, but not any of the values that
-
-
-
-
-
-Hastings, et al. Standards Track [Page 35]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- it is still using. The choice for exactly how to resolve the
- conflict is implementation dependent. See sections 3.2.1.2 and 15.
- See The Implementer's Guide [IPP-IIG] for an example.
-
-3.1.8 Versions
-
- Each operation request and response carries with it a "version-
- number" parameter. Each value of the "version-number" is in the form
- "X.Y" where X is the major version number and Y is the minor version
- number. By including a version number in the client request, it
- allows the client to identify which version of IPP it is interested
- in using, i.e., the version whose conformance requirements the client
- may be depending upon the Printer to meet.
-
- If the IPP object does not support that major version number supplied
- by the client, i.e., the major version field of the "version-number"
- parameter does not match any of the values of the Printer's "ipp-
- versions-supported" (see section 4.4.14), the object MUST respond
- with a status code of 'server-error-version-not-supported' along with
- the closest version number that is supported (see section 13.1.5.4).
- If the major version number is supported, but the minor version
- number is not, the IPP object SHOULD accept and attempt to perform
- the request (or reject the request if the operation is not
- supported), else it rejects the request and returns the 'server-
- error-version-not-supported' status code. In all cases, the IPP
- object MUST return the "version-number" that it supports that is
- closest to the version number supplied by the client in the request.
-
- There is no version negotiation per se. However, if after receiving
- a 'server-error-version-not-supported' status code from an IPP
- object, a client SHOULD try again with a different version number. A
- client MAY also determine the versions supported either from a
- directory that conforms to Appendix E (see section 16) or by querying
- the Printer object's "ipp-versions-supported" attribute (see section
- 4.4.14) to determine which versions are supported.
-
- An IPP object implementation MUST support version '1.1', i.e., meet
- the conformance requirements for IPP/1.1 as specified in this
- document and [RFC2910]. It is recommended that IPP object
- implementations accept any request with the major version '1' (or
- reject the request if the operation is not supported).
-
- There is only one notion of "version number" that covers both IPP
- Model and IPP Protocol changes. Thus the version number MUST change
- when introducing a new version of the Model and Semantics document
- (this document) or a new version of the "Encoding and Transport"
- document [RFC2910].
-
-
-
-
-Hastings, et al. Standards Track [Page 36]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Changes to the major version number of the Model and Semantics
- document indicate structural or syntactic changes that make it
- impossible for older version of IPP clients and Printer objects to
- correctly parse and correctly process the new or changed attributes,
- operations and responses. If the major version number changes, the
- minor version numbers is set to zero. As an example, adding the
- REQUIRED "ipp-attribute-fidelity" attribute to version '1.1' (if it
- had not been part of version '1.0'), would have required a change to
- the major version number, since an IPP/1.0 Printer would not have
- processed a request with the correct semantics that contained the
- "ipp-attribute-fidelity" attribute that it did not know about. Items
- that might affect the changing of the major version number include
- any changes to the Model and Semantics document (this document) or
- the "Encoding and Transport" document [RFC2910] itself, such as:
-
- - reordering of ordered attributes or attribute sets
- - changes to the syntax of existing attributes
- - adding REQUIRED (for an IPP object to support) operation
- attribute groups
- - adding values to existing REQUIRED operation attributes
- - adding REQUIRED operations
-
- Changes to the minor version number indicate the addition of new
- features, attributes and attribute values that may not be understood
- by all IPP objects, but which can be ignored if not understood.
- Items that might affect the changing of the minor version number
- include any changes to the model objects and attributes but not the
- encoding and transport rules [RFC2910] (except adding attribute
- syntaxes). Examples of such changes are:
-
- - grouping all extensions not included in a previous version into
- a new version
- - adding new attribute values
- - adding new object attributes
- - adding OPTIONAL (for an IPP object to support) operation
- attributes (i.e., those attributes that an IPP object can ignore
- without confusing clients)
- - adding OPTIONAL (for an IPP object to support) operation
- attribute groups (i.e., those attributes that an IPP object can
- ignore without confusing clients)
- - adding new attribute syntaxes
- - adding OPTIONAL operations
- - changing Job Description attributes or Printer Description
- attributes from OPTIONAL to REQUIRED or vice versa.
- - adding OPTIONAL attribute syntaxes to an existing attribute.
-
- The encoding of the "version-number" MUST NOT change over any version
- number (either major or minor). This rule guarantees that all future
-
-
-
-Hastings, et al. Standards Track [Page 37]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- versions will be backwards compatible with all previous versions (at
- least for checking the "version-number"). In addition, any protocol
- elements (attributes, error codes, tags, etc.) that are not carried
- forward from one version to the next are deprecated so that they can
- never be reused with new semantics.
-
- Implementations that support a certain version NEED NOT support ALL
- previous versions. As each new version is defined (through the
- release of a new IPP specification document), that version will
- specify which previous versions MUST and which versions SHOULD be
- supported in compliant implementations.
-
-3.1.9 Job Creation Operations
-
- In order to "submit a print job" and create a new Job object, a
- client issues a create request. A create request is any one of
- following three operation requests:
-
- - The Print-Job Request: A client that wants to submit a print job
- with only a single document uses the Print-Job operation. The
- operation allows for the client to "push" the document data to
- the Printer object by including the document data in the request
- itself.
-
- - The Print-URI Request: A client that wants to submit a print job
- with only a single document (where the Printer object "pulls"
- the document data instead of the client "pushing" the data to
- the Printer object) uses the Print-URI operation. In this
- case, the client includes in the request only a URI reference to
- the document data (not the document data itself).
-
- - The Create-Job Request: A client that wants to submit a print
- job with multiple documents uses the Create-Job operation. This
- operation is followed by an arbitrary number (one or more) of
- Send-Document and/or Send-URI operations (each creating another
- document for the newly create Job object). The Send-Document
- operation includes the document data in the request (the client
- "pushes" the document data to the printer), and the Send-URI
- operation includes only a URI reference to the document data in
- the request (the Printer "pulls" the document data from the
- referenced location). The last Send-Document or Send-URI
- request for a given Job object includes a "last-document"
- operation attribute set to 'true' indicating that this is the
- last request.
-
- Throughout this model document, the term "create request" is used to
- refer to any of these three operation requests.
-
-
-
-
-Hastings, et al. Standards Track [Page 38]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- A Create-Job operation followed by only one Send-Document operation
- is semantically equivalent to a Print-Job operation, however, for
- performance reasons, the client SHOULD use the Print-Job operation
- for all single document jobs. Also, Print-Job is a REQUIRED
- operation (all implementations MUST support it) whereas Create-Job is
- an OPTIONAL operation, hence some implementations might not support
- it.
-
- Job submission time is the point in time when a client issues a
- create request. The initial state of every Job object is the
- 'pending', 'pending-held', or 'processing' state (see section 4.3.7).
- When the Printer object begins processing the print job, the Job
- object's state moves to 'processing'. This is known as job
- processing time. There are validation checks that must be done at
- job submission time and others that must be performed at job
- processing time.
-
- At job submission time and at the time a Validate-Job operation is
- received, the Printer MUST do the following:
-
- 1. Process the client supplied attributes and either accept or
- reject the request
- 2. Validate the syntax of and support for the scheme of any client
- supplied URI
-
- At job submission time the Printer object MUST validate whether or
- not the supplied attributes, attribute syntaxes, and values are
- supported by matching them with the Printer object's corresponding
- "xxx-supported" attributes. See section 3.1.7 for details. [IPP-
- IIG] presents suggested steps for an IPP object to either accept or
- reject any request and additional steps for processing create
- requests.
-
- At job submission time the Printer object NEED NOT perform the
- validation checks reserved for job processing time such as:
-
- 1. Validating the document data
- 2. Validating the actual contents of any client supplied URI
- (resolve the reference and follow the link to the document
- data)
-
- At job submission time, these additional job processing time
- validation checks are essentially useless, since they require
- actually parsing and interpreting the document data, are not
- guaranteed to be 100% accurate, and MUST be done, yet again, at job
- processing time. Also, in the case of a URI, checking for
- availability at job submission time does not guarantee availability
-
-
-
-
-Hastings, et al. Standards Track [Page 39]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- at job processing time. In addition, at job processing time, the
- Printer object might discover any of the following conditions that
- were not detectable at job submission time:
-
- - runtime errors in the document data,
- - nested document data that is in an unsupported format,
- - the URI reference is no longer valid (i.e., the server hosting
- the document might be down), or
- - any other job processing error
-
- At job submission time, a Printer object, especially a non-spooling
- Printer, MAY accept jobs that it does not have enough space for. In
- such a situation, a Printer object MAY stop reading data from a
- client for an indefinite period of time. A client MUST be prepared
- for a write operation to block for an indefinite period of time (see
- section 5.1 on client conformance).
-
- When a Printer object has too little space for starting a new job, it
- MAY reject a new create request. In this case, a Printer object MUST
- return a response (in reply to the rejected request) with a status-
- code of 'server-error-busy' (see section 14.1.5.8) and it MAY close
- the connection before receiving all bytes of the operation. A
- Printer SHOULD indicate that it is temporarily unable to accept jobs
- by setting the 'spool-space-full' value in its "printer-state-
- reasons" attribute and removing the value when it can accept another
- job (see section 4.4.12).
-
- When receiving a 'server-error-busy' status-code in an operation
- response, a client MUST be prepared for the Printer object to close
- the connection before the client has sent all of the data (especially
- for the Print-Job operation). A client MUST be prepared to keep
- submitting a create request until the IPP Printer object accepts the
- create request.
-
- At job processing time, since the Printer object has already
- responded with a successful status code in the response to the create
- request, if the Printer object detects an error, the Printer object
- is unable to inform the end user of the error with an operation
- status code. In this case, the Printer, depending on the error, can
- set the job object's "job-state", "job-state-reasons", or "job-
- state-message" attributes to the appropriate value(s) so that later
- queries can report the correct job status.
-
- Note: Asynchronous notification of events is outside the scope of
- this IPP/1.1 document.
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 40]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-3.2 Printer Operations
-
- All Printer operations are directed at Printer objects. A client
- MUST always supply the "printer-uri" operation attribute in order to
- identify the correct target of the operation.
-
-3.2.1 Print-Job Operation
-
- This REQUIRED operation allows a client to submit a print job with
- only one document and supply the document data (rather than just a
- reference to the data). See Section 15 for the suggested steps for
- processing create operations and their Operation and Job Template
- attributes.
-
-3.2.1.1 Print-Job Request
-
- The following groups of attributes are supplied as part of the
- Print-Job Request:
-
- Group 1: Operation Attributes
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in section 3.1.4.1. The Printer object
- MUST copy these values to the corresponding Job Description
- attributes described in sections 4.3.19 and 4.3.20.
-
- Target:
- The "printer-uri" (uri) operation attribute which is the target
- for this operation as described in section 3.1.5.
-
- Requesting User Name:
- The "requesting-user-name" (name(MAX)) attribute SHOULD be
- supplied by the client as described in section 8.3.
-
- "job-name" (name(MAX)):
- The client OPTIONALLY supplies this attribute. The Printer
- object MUST support this attribute. It contains the client
- supplied Job name. If this attribute is supplied by the
- client, its value is used for the "job-name" attribute of the
- newly created Job object. The client MAY automatically include
- any information that will help the end-user distinguish amongst
- his/her jobs, such as the name of the application program along
- with information from the document, such as the document name,
- document subject, or source file name. If this attribute is
- not supplied by the client, the Printer generates a name to use
- in the "job-name" attribute of the newly created Job object
- (see Section 4.3.5).
-
-
-
-Hastings, et al. Standards Track [Page 41]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- "ipp-attribute-fidelity" (boolean):
- The client OPTIONALLY supplies this attribute. The Printer
- object MUST support this attribute. The value 'true' indicates
- that total fidelity to client supplied Job Template attributes
- and values is required, else the Printer object MUST reject the
- Print-Job request. The value 'false' indicates that a
- reasonable attempt to print the Job object is acceptable and
- the Printer object MUST accept the Print-Job request. If not
- supplied, the Printer object assumes the value is 'false'. All
- Printer objects MUST support both types of job processing. See
- section 15 for a full description of "ipp-attribute-fidelity"
- and its relationship to other attributes, especially the
- Printer object's "pdl-override-supported" attribute.
-
- "document-name" (name(MAX)):
- The client OPTIONALLY supplies this attribute. The Printer
- object MUST support this attribute. It contains the client
- supplied document name. The document name MAY be different
- than the Job name. Typically, the client software
- automatically supplies the document name on behalf of the end
- user by using a file name or an application generated name. If
- this attribute is supplied, its value can be used in a manner
- defined by each implementation. Examples include: printed
- along with the Job (job start sheet, page adornments, etc.),
- used by accounting or resource tracking management tools, or
- even stored along with the document as a document level
- attribute. IPP/1.1 does not support the concept of document
- level attributes.
-
- "compression" (type3 keyword):
- The client OPTIONALLY supplies this attribute. The Printer
- object MUST support this attribute and the "compression-
- supported" attribute (see section 4.4.32). The client supplied
- "compression" operation attribute identifies the compression
- algorithm used on the document data. The following cases exist:
-
- a) If the client omits this attribute, the Printer object MUST
- assume that the data is not compressed (i.e. the Printer
- follows the rules below as if the client supplied the
- "compression" attribute with a value of 'none').
- b) If the client supplies this attribute, but the value is not
- supported by the Printer object, i.e., the value is not one
- of the values of the Printer object's "compression-
- supported" attribute, the Printer object MUST reject the
- request, and return the 'client-error-compression-not-
- supported' status code. See section 3.1.7 for returning
- unsupported attributes and values.
-
-
-
-
-Hastings, et al. Standards Track [Page 42]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- c) If the client supplies the attribute and the Printer object
- supports the attribute value, the Printer object uses the
- corresponding decompression algorithm on the document data.
- d) If the decompression algorithm fails before the Printer
- returns an operation response, the Printer object MUST
- reject the request and return the 'client-error-
- compression-error' status code.
- e) If the decompression algorithm fails after the Printer
- returns an operation response, the Printer object MUST abort
- the job and add the 'compression-error' value to the job's
- "job-state-reasons" attribute.
- f) If the decompression algorithm succeeds, the document data
- MUST then have the format specified by the job's "document-
- format" attribute, if supplied (see "document-format"
- operation attribute definition below).
-
- "document-format" (mimeMediaType):
- The client OPTIONALLY supplies this attribute. The Printer
- object MUST support this attribute. The value of this
- attribute identifies the format of the supplied document data.
- The following cases exist:
-
- a) If the client does not supply this attribute, the Printer
- object assumes that the document data is in the format
- defined by the Printer object's "document-format-default"
- attribute. (i.e. the Printer follows the rules below as if
- the client supplied the "document-format" attribute with a
- value equal to the printer's default value).
- b) If the client supplies this attribute, but the value is not
- supported by the Printer object, i.e., the value is not one
- of the values of the Printer object's "document-format-
- supported" attribute, the Printer object MUST reject the
- request and return the 'client-error-document-format-not-
- supported' status code.
- c) If the client supplies this attribute and its value is
- 'application/octet-stream' (i.e. to be auto-sensed, see
- Section 4.1.9.1), and the format is not one of the
- document-formats that the Printer can auto-sense, and this
- check occurs before the Printer returns an operation
- response, then the Printer MUST reject the request and
- return the 'client-error-document-format-not-supported'
- status code.
- d) If the client supplies this attribute, and the value is
- supported by the Printer object, the Printer is capable of
- interpreting the document data.
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 43]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- e) If interpreting of the document data fails before the
- Printer returns an operation response, the Printer object
- MUST reject the request and return the 'client-error-
- document-format-error' status code.
- f) If interpreting of the document data fails after the Printer
- returns an operation response, the Printer object MUST abort
- the job and add the 'document-format-error' value to the
- job's "job-state-reasons" attribute.
-
- "document-natural-language" (naturalLanguage):
- The client OPTIONALLY supplies this attribute. The Printer
- object OPTIONALLY supports this attribute. This attribute
- specifies the natural language of the document for those
- document-formats that require a specification of the natural
- language in order to image the document unambiguously. There
- are no particular values required for the Printer object to
- support.
-
- "job-k-octets" (integer(0:MAX)):
- The client OPTIONALLY supplies this attribute. The Printer
- object OPTIONALLY supports this attribute and the "job-k-
- octets-supported" attribute (see section 4.4.33). The client
- supplied "job-k-octets" operation attribute identifies the
- total size of the document(s) in K octets being submitted (see
- section 4.3.17.1 for the complete semantics). If the client
- supplies the attribute and the Printer object supports the
- attribute, the value of the attribute is used to populate the
- Job object's "job-k-octets" Job Description attribute.
-
- For this attribute and the following two attributes ("job-
- impressions", and "job-media-sheets"), if the client supplies
- the attribute, but the Printer object does not support the
- attribute, the Printer object ignores the client-supplied
- value. If the client supplies the attribute and the Printer
- supports the attribute, and the value is within the range of
- the corresponding Printer object's "xxx-supported" attribute,
- the Printer object MUST use the value to populate the Job
- object's "xxx" attribute. If the client supplies the attribute
- and the Printer supports the attribute, but the value is
- outside the range of the corresponding Printer object's "xxx-
- supported" attribute, the Printer object MUST copy the
- attribute and its value to the Unsupported Attributes response
- group, reject the request, and return the 'client-error-
- attributes-or-values-not-supported' status code. If the client
- does not supply the attribute, the Printer object MAY choose to
- populate the corresponding Job object attribute depending on
- whether the Printer object supports the attribute and is able
- to calculate or discern the correct value.
-
-
-
-Hastings, et al. Standards Track [Page 44]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- "job-impressions" (integer(0:MAX)):
- The client OPTIONALLY supplies this attribute. The Printer
- object OPTIONALLY supports this attribute and the "job-
- impressions-supported" attribute (see section 4.4.34). The
- client supplied "job-impressions" operation attribute
- identifies the total size in number of impressions of the
- document(s) being submitted (see section 4.3.17.2 for the
- complete semantics).
-
- See last paragraph under "job-k-octets".
-
- "job-media-sheets" (integer(0:MAX)):
- The client OPTIONALLY supplies this attribute. The Printer
- object OPTIONALLY supports this attribute and the "job-media-
- sheets-supported" attribute (see section 4.4.35). The client
- supplied "job-media-sheets" operation attribute identifies the
- total number of media sheets to be produced for this job (see
- section 4.3.17.3 for the complete semantics).
-
- See last paragraph under "job-k-octets".
-
- Group 2: Job Template Attributes
-
- The client OPTIONALLY supplies a set of Job Template attributes as
- defined in section 4.2. If the client is not supplying any Job
- Template attributes in the request, the client SHOULD omit Group 2
- rather than sending an empty group. However, a Printer object
- MUST be able to accept an empty group.
-
- Group 3: Document Content
-
- The client MUST supply the document data to be processed.
-
- In addition to the MANDATORY parameters required for every
- operation request, the simplest Print-Job Request consists of just
- the "attributes-charset" and "attributes-natural-language"
- operation attributes; the "printer-uri" target operation
- attribute; the Document Content and nothing else. In this simple
- case, the Printer object:
-
- - creates a new Job object (the Job object contains a single
- document),
- - stores a generated Job name in the "job-name" attribute in the
- natural language and charset requested (see Section 3.1.4.1) (if
- those are supported, otherwise using the Printer object's
- default natural language and charset), and
-
-
-
-
-
-Hastings, et al. Standards Track [Page 45]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- - at job processing time, uses its corresponding default value
- attributes for the supported Job Template attributes that were
- not supplied by the client as IPP attribute or embedded
- instructions in the document data.
-
-3.2.1.2 Print-Job Response
-
- The Printer object MUST return to the client the following sets of
- attributes as part of the Print-Job Response:
-
- Group 1: Operation Attributes
-
- Status Message:
- In addition to the REQUIRED status code returned in every
- response, the response OPTIONALLY includes a "status-message"
- (text(255)) and/or a "detailed-status-message" (text(MAX))
- operation attribute as described in sections 13 and 3.1.6. If
- the client supplies unsupported or conflicting Job Template
- attributes or values, the Printer object MUST reject or accept
- the Print-Job request depending on the whether the client
- supplied a 'true' or 'false' value for the "ipp-attribute-
- fidelity" operation attribute. See the Implementer's Guide
- [IPP-IIG] for a complete description of the suggested steps for
- processing a create request.
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in section 3.1.4.2.
-
- Group 2: Unsupported Attributes
-
- See section 3.1.7 for details on returning Unsupported Attributes.
-
- The value of the "ipp-attribute-fidelity" supplied by the client
- does not affect what attributes the Printer object returns in this
- group. The value of "ipp-attribute-fidelity" only affects whether
- the Print-Job operation is accepted or rejected. If the job is
- accepted, the client may query the job using the Get-Job-
- Attributes operation requesting the unsupported attributes that
- were returned in the create response to see which attributes were
- ignored (not stored on the Job object) and which attributes were
- stored with other (substituted) values.
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 46]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Group 3: Job Object Attributes
-
- "job-uri" (uri):
- The Printer object MUST return the Job object's URI by
- returning the contents of the REQUIRED "job-uri" Job object
- attribute. The client uses the Job object's URI when directing
- operations at the Job object. The Printer object always uses
- its configured security policy when creating the new URI.
- However, if the Printer object supports more than one URI, the
- Printer object also uses information about which URI was used
- in the Print-Job Request to generated the new URI so that the
- new URI references the correct access channel. In other words,
- if the Print-Job Request comes in over a secure channel, the
- Printer object MUST generate a Job URI that uses the secure
- channel as well.
-
- "job-id" (integer(1:MAX)):
- The Printer object MUST return the Job object's Job ID by
- returning the REQUIRED "job-id" Job object attribute. The
- client uses this "job-id" attribute in conjunction with the
- "printer-uri" attribute used in the Print-Job Request when
- directing Job operations at the Printer object.
-
- "job-state" (type1 enum):
- The Printer object MUST return the Job object's REQUIRED "job-
- state" attribute. The value of this attribute (along with the
- value of the next attribute: "job-state-reasons") is taken
- from a "snapshot" of the new Job object at some meaningful
- point in time (implementation defined) between when the Printer
- object receives the Print-Job Request and when the Printer
- object returns the response.
-
- "job-state-reasons" (1setOf type2 keyword):
- The Printer object MUST return the Job object's REQUIRED "job-
- state-reasons" attribute.
-
- "job-state-message" (text(MAX)):
- The Printer object OPTIONALLY returns the Job object's OPTIONAL
- "job-state-message" attribute. If the Printer object supports
- this attribute then it MUST be returned in the response. If
- this attribute is not returned in the response, the client can
- assume that the "job-state-message" attribute is not supported
- and will not be returned in a subsequent Job object query.
-
- "number-of-intervening-jobs" (integer(0:MAX)):
- The Printer object OPTIONALLY returns the Job object's OPTIONAL
- "number-of-intervening-jobs" attribute. If the Printer object
- supports this attribute then it MUST be returned in the
-
-
-
-Hastings, et al. Standards Track [Page 47]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- response. If this attribute is not returned in the response,
- the client can assume that the "number-of-intervening-jobs"
- attribute is not supported and will not be returned in a
- subsequent Job object query.
-
- Note: Since any printer state information which affects a job's
- state is reflected in the "job-state" and "job-state-reasons"
- attributes, it is sufficient to return only these attributes
- and no specific printer status attributes.
-
- Note: In addition to the MANDATORY parameters required for every
- operation response, the simplest response consists of the just the
- "attributes-charset" and "attributes-natural-language" operation
- attributes and the "job-uri", "job-id", and "job-state" Job Object
- Attributes. In this simplest case, the status code is 'successful-
- ok' and there is no "status-message" or "detailed-status-message"
- operation attribute.
-
-3.2.2 Print-URI Operation
-
- This OPTIONAL operation is identical to the Print-Job operation
- (section 3.2.1) except that a client supplies a URI reference to the
- document data using the "document-uri" (uri) operation attribute (in
- Group 1) rather than including the document data itself. Before
- returning the response, the Printer MUST validate that the Printer
- supports the retrieval method (e.g., http, ftp, etc.) implied by the
- URI, and MUST check for valid URI syntax. If the client-supplied URI
- scheme is not supported, i.e. the value is not in the Printer
- object's "referenced-uri-scheme-supported" attribute, the Printer
- object MUST reject the request and return the 'client-error-uri-
- scheme-not-supported' status code.
-
- The IPP Printer MAY validate the accessibility of the document as
- part of the operation or subsequently. If the Printer determines an
- accessibility problem before returning an operation response, it
- rejects the request and returns the 'client-error-document-access-
- error' status code. The Printer MAY also return a specific document
- access error code using the "document-access-error" operation
- attribute (see section 3.1.6.4).
-
- If the Printer determines this document accessibility problem after
- accepting the request and returning an operation response with one of
- the successful status codes, the Printer adds the 'document-access-
- error' value to the job's "job-state-reasons" attribute and MAY
- populate the job's "job-document-access-errors" Job Description
- attribute (see section 4.3.11). See The Implementer's Guide [IPP-
- IIG] for suggested additional checks.
-
-
-
-
-Hastings, et al. Standards Track [Page 48]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- If the Printer object supports this operation, it MUST support the
- "reference-uri-schemes-supported" Printer attribute (see section
- 4.4.27).
-
- It is up to the IPP object to interpret the URI and subsequently
- "pull" the document from the source referenced by the URI string.
-
-3.2.3 Validate-Job Operation
-
- This REQUIRED operation is similar to the Print-Job operation
- (section 3.2.1) except that a client supplies no document data and
- the Printer allocates no resources (i.e., it does not create a new
- Job object). This operation is used only to verify capabilities of a
- printer object against whatever attributes are supplied by the client
- in the Validate-Job request. By using the Validate-Job operation a
- client can validate that an identical Print-Job operation (with the
- document data) would be accepted. The Validate-Job operation also
- performs the same security negotiation as the Print-Job operation
- (see section 8), so that a client can check that the client and
- Printer object security requirements can be met before performing a
- Print-Job operation.
-
- The Validate-Job operation does not accept a "document-uri" attribute
- in order to allow a client to check that the same Print-URI operation
- will be accepted, since the client doesn't send the data with the
- Print-URI operation. The client SHOULD just issue the Print-URI
- request.
-
- The Printer object returns the same status codes, Operation
- Attributes (Group 1) and Unsupported Attributes (Group 2) as the
- Print-Job operation. However, no Job Object Attributes (Group 3) are
- returned, since no Job object is created.
-
-3.2.4 Create-Job Operation
-
- This OPTIONAL operation is similar to the Print-Job operation
- (section 3.2.1) except that in the Create-Job request, a client does
- not supply document data or any reference to document data. Also,
- the client does not supply any of the "document-name", "document-
- format", "compression", or "document-natural-language" operation
- attributes. This operation is followed by one or more Send-Document
- or Send-URI operations. In each of those operation requests, the
- client OPTIONALLY supplies the "document-name", "document-format",
- and "document-natural-language" attributes for each document in the
- multi-document Job object.
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 49]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- If a Printer object supports the Create-Job operation, it MUST also
- support the Send-Document operation and also MAY support the Send-URI
- operation.
-
- If the Printer object supports this operation, it MUST support the
- "multiple-operation-time-out" Printer attribute (see section 4.4.31).
-
- If the Printer object supports this operation, then it MUST support
- the "multiple-document-jobs-supported" Printer Description attribute
- (see section 4.4.16) and indicate whether or not it supports
- multiple-document jobs.
-
- If the Printer object supports this operation and supports multiple
- documents in a job, then it MUST support the "multiple-document-
- handling" Job Template job attribute with at least one value (see
- section 4.2.4) and the associated "multiple-document-handling-
- default" and "multiple-document-handling-supported" Job Template
- Printer attributes (see section 4.2).
-
- After the Create-Job operation has completed, the value of the "job-
- state" attribute is similar to the "job-state" after a Print-Job,
- even though no document-data has arrived. A Printer MAY set the
- 'job-data-insufficient' value of the job's "job-state-reason"
- attribute to indicate that processing cannot begin until sufficient
- data has arrived and set the "job-state" to either 'pending' or
- 'pending-held'. A non-spooling printer that doesn't implement the
- 'pending' job state may even set the "job-state" to 'processing',
- even though there is not yet any data to process. See sections 4.3.7
- and 4.3.8.
-
-3.2.5 Get-Printer-Attributes Operation
-
- This REQUIRED operation allows a client to request the values of the
- attributes of a Printer object. In the request, the client supplies
- the set of Printer attribute names and/or attribute group names in
- which the requester is interested. In the response, the Printer
- object returns a corresponding attribute set with the appropriate
- attribute values filled in.
-
- For Printer objects, the possible names of attribute groups are:
-
- - 'job-template': the subset of the Job Template attributes that
- apply to a Printer object (the last two columns of the table in
- Section 4.2) that the implementation supports for Printer
- objects.
- - 'printer-description': the subset of the attributes specified in
- Section 4.4 that the implementation supports for Printer
- objects.
-
-
-
-Hastings, et al. Standards Track [Page 50]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- - 'all': the special group 'all' that includes all attributes that
- the implementation supports for Printer objects.
-
- Since a client MAY request specific attributes or named groups, there
- is a potential that there is some overlap. For example, if a client
- requests, 'printer-name' and 'all', the client is actually requesting
- the "printer-name" attribute twice: once by naming it explicitly, and
- once by inclusion in the 'all' group. In such cases, the Printer
- object NEED NOT return each attribute only once in the response even
- if it is requested multiple times. The client SHOULD NOT request the
- same attribute in multiple ways.
-
- It is NOT REQUIRED that a Printer object support all attributes
- belonging to a group (since some attributes are OPTIONAL). However,
- it is REQUIRED that each Printer object support all group names.
-
-3.2.5.1 Get-Printer-Attributes Request
-
- The following sets of attributes are part of the Get-Printer-
- Attributes Request:
-
- Group 1: Operation Attributes
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in section 3.1.4.1.
-
- Target:
- The "printer-uri" (uri) operation attribute which is the target
- for this operation as described in section 3.1.5.
-
- Requesting User Name:
- The "requesting-user-name" (name(MAX)) attribute SHOULD be
- supplied by the client as described in section 8.3.
-
- "requested-attributes" (1setOf keyword):
- The client OPTIONALLY supplies a set of attribute names and/or
- attribute group names in whose values the requester is
- interested. The Printer object MUST support this attribute.
- If the client omits this attribute, the Printer MUST respond as
- if this attribute had been supplied with a value of 'all'.
-
- "document-format" (mimeMediaType):
- The client OPTIONALLY supplies this attribute. The Printer
- object MUST support this attribute. This attribute is useful
- for a Printer object to determine the set of supported
- attribute values that relate to the requested document format.
- The Printer object MUST return the attributes and values that
-
-
-
-Hastings, et al. Standards Track [Page 51]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- it uses to validate a job on a create or Validate-Job operation
- in which this document format is supplied. The Printer object
- SHOULD return only (1) those attributes that are supported for
- the specified format and (2) the attribute values that are
- supported for the specified document format. By specifying the
- document format, the client can get the Printer object to
- eliminate the attributes and values that are not supported for
- a specific document format. For example, a Printer object
- might have multiple interpreters to support both
- 'application/postscript' (for PostScript) and 'text/plain' (for
- text) documents. However, for only one of those interpreters
- might the Printer object be able to support "number-up" with
- values of '1', '2', and '4'. For the other interpreter it
- might be able to only support "number-up" with a value of '1'.
- Thus a client can use the Get-Printer-Attributes operation to
- obtain the attributes and values that will be used to
- accept/reject a create job operation.
-
- If the Printer object does not distinguish between different
- sets of supported values for each different document format
- when validating jobs in the create and Validate-Job operations,
- it MUST NOT distinguish between different document formats in
- the Get-Printer-Attributes operation. If the Printer object
- does distinguish between different sets of supported values for
- each different document format specified by the client, this
- specialization applies only to the following Printer object
- attributes:
-
- - Printer attributes that are Job Template attributes ("xxx-
- default" "xxx-supported", and "xxx-ready" in the Table in
- Section 4.2),
- - "pdl-override-supported",
- - "compression-supported",
- - "job-k-octets-supported",
- - "job-impressions-supported",
- - "job-media-sheets-supported",
- - "printer-driver-installer",
- - "color-supported", and
- - "reference-uri-schemes-supported"
-
- The values of all other Printer object attributes (including
- "document-format-supported") remain invariant with respect to the
- client supplied document format (except for new Printer
- description attribute as registered according to section 6.2).
-
- If the client omits this "document-format" operation attribute,
- the Printer object MUST respond as if the attribute had been
- supplied with the value of the Printer object's "document-format-
-
-
-
-Hastings, et al. Standards Track [Page 52]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- default" attribute. It is RECOMMENDED that the client always
- supply a value for "document-format", since the Printer object's
- "document-format-default" may be 'application/octet-stream', in
- which case the returned attributes and values are for the union of
- the document formats that the Printer can automatically sense.
- For more details, see the description of the 'mimeMediaType'
- attribute syntax in section 4.1.9.
-
- If the client supplies a value for the "document-format" Operation
- attribute that is not supported by the Printer, i.e., is not among
- the values of the Printer object's "document-format-supported"
- attribute, the Printer object MUST reject the operation and return
- the 'client-error-document-format-not-supported' status code.
-
-3.2.5.2 Get-Printer-Attributes Response
-
- The Printer object returns the following sets of attributes as part
- of the Get-Printer-Attributes Response:
-
- Group 1: Operation Attributes
-
- Status Message:
- In addition to the REQUIRED status code returned in every
- response, the response OPTIONALLY includes a "status-message"
- (text(255)) and/or a "detailed-status-message" (text(MAX))
- operation attribute as described in sections 13 and 3.1.6.
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in section 3.1.4.2.
-
- Group 2: Unsupported Attributes
-
- See section 3.1.7 for details on returning Unsupported Attributes.
-
- The response NEED NOT contain the "requested-attributes" operation
- attribute with any supplied values (attribute keywords) that were
- requested by the client but are not supported by the IPP object.
- If the Printer object does return unsupported attributes
- referenced in the "requested-attributes" operation attribute and
- that attribute included group names, such as 'all', the
- unsupported attributes MUST NOT include attributes described in
- the standard but not supported by the implementation.
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 53]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Group 3: Printer Object Attributes
-
- This is the set of requested attributes and their current values.
- The Printer object ignores (does not respond with) any requested
- attribute which is not supported. The Printer object MAY respond
- with a subset of the supported attributes and values, depending on
- the security policy in force. However, the Printer object MUST
- respond with the 'unknown' value for any supported attribute
- (including all REQUIRED attributes) for which the Printer object
- does not know the value. Also the Printer object MUST respond
- with the 'no-value' for any supported attribute (including all
- REQUIRED attributes) for which the system administrator has not
- configured a value. See the description of the "out-of-band"
- values in the beginning of Section 4.1.
-
-3.2.6 Get-Jobs Operation
-
- This REQUIRED operation allows a client to retrieve the list of Job
- objects belonging to the target Printer object. The client may also
- supply a list of Job attribute names and/or attribute group names. A
- group of Job object attributes will be returned for each Job object
- that is returned.
-
- This operation is similar to the Get-Job-Attributes operation, except
- that this Get-Jobs operation returns attributes from possibly more
- than one object.
-
-3.2.6.1 Get-Jobs Request
-
- The client submits the Get-Jobs request to a Printer object.
-
- The following groups of attributes are part of the Get-Jobs Request:
-
- Group 1: Operation Attributes
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in section 3.1.4.1.
-
- Target:
- The "printer-uri" (uri) operation attribute which is the target
- for this operation as described in section 3.1.5.
-
- Requesting User Name:
- The "requesting-user-name" (name(MAX)) attribute SHOULD be
- supplied by the client as described in section 8.3.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 54]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- "limit" (integer(1:MAX)):
- The client OPTIONALLY supplies this attribute. The Printer
- object MUST support this attribute. It is an integer value that
- determines the maximum number of jobs that a client will
- receive from the Printer even if "which-jobs" or "my-jobs"
- constrain which jobs are returned. The limit is a "stateless
- limit" in that if the value supplied by the client is 'N', then
- only the first 'N' jobs are returned in the Get-Jobs Response.
- There is no mechanism to allow for the next 'M' jobs after the
- first 'N' jobs. If the client does not supply this attribute,
- the Printer object responds with all applicable jobs.
-
- "requested-attributes" (1setOf type2 keyword):
- The client OPTIONALLY supplies this attribute. The Printer
- object MUST support this attribute. It is a set of Job
- attribute names and/or attribute groups names in whose values
- the requester is interested. This set of attributes is
- returned for each Job object that is returned. The allowed
- attribute group names are the same as those defined in the
- Get-Job-Attributes operation in section 3.3.4. If the client
- does not supply this attribute, the Printer MUST respond as if
- the client had supplied this attribute with two values: 'job-
- uri' and 'job-id'.
-
- "which-jobs" (type2 keyword):
- The client OPTIONALLY supplies this attribute. The Printer
- object MUST support this attribute. It indicates which Job
- objects MUST be returned by the Printer object. The values for
- this attribute are:
-
- 'completed': This includes any Job object whose state is
- 'completed', 'canceled', or 'aborted'.
- 'not-completed': This includes any Job object whose state is
- 'pending', 'processing', 'processing-stopped', or 'pending-
- held'.
-
- A Printer object MUST support both values. However, if the
- implementation does not keep jobs in the 'completed',
- 'canceled', and 'aborted' states, then it returns no jobs when
- the 'completed' value is supplied.
-
- If a client supplies some other value, the Printer object MUST
- copy the attribute and the unsupported value to the Unsupported
- Attributes response group, reject the request, and return the
- 'client-error-attributes-or-values-not-supported' status code.
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 55]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- If the client does not supply this attribute, the Printer
- object MUST respond as if the client had supplied the attribute
- with a value of 'not-completed'.
-
- "my-jobs" (boolean):
- The client OPTIONALLY supplies this attribute. The Printer
- object MUST support this attribute. It indicates whether jobs
- from all users or just the jobs submitted by the requesting
- user of this request MUST be considered as candidate jobs to be
- returned by the Printer object. If the client does not supply
- this attribute, the Printer object MUST respond as if the
- client had supplied the attribute with a value of 'false',
- i.e., jobs from all users. The means for authenticating the
- requesting user and matching the jobs is described in section
- 8.
-
-3.2.6.2 Get-Jobs Response
-
- The Printer object returns all of the Job objects up to the number
- specified by the "limit" attribute that match the criteria as defined
- by the attribute values supplied by the client in the request. It is
- possible that no Job objects are returned since there may literally
- be no Job objects at the Printer, or there may be no Job objects that
- match the criteria supplied by the client. If the client requests
- any Job attributes at all, there is a set of Job Object Attributes
- returned for each Job object.
-
- It is not an error for the Printer to return 0 jobs. If the response
- returns 0 jobs because there are no jobs matching the criteria, and
- the request would have returned 1 or more jobs with a status code of
- 'successful-ok' if there had been jobs matching the criteria, then
- the status code for 0 jobs MUST be 'successful-ok'.
-
- Group 1: Operation Attributes
-
- Status Message:
- In addition to the REQUIRED status code returned in every
- response, the response OPTIONALLY includes a "status-message"
- (text(255)) and/or a "detailed-status-message" (text(MAX))
- operation attribute as described in sections 13 and 3.1.6.
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in section 3.1.4.2.
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 56]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Group 2: Unsupported Attributes
-
- See section 3.1.7 for details on returning Unsupported Attributes.
-
- The response NEED NOT contain the "requested-attributes" operation
- attribute with any supplied values (attribute keywords) that were
- requested by the client but are not supported by the IPP object.
- If the Printer object does return unsupported attributes
- referenced in the "requested-attributes" operation attribute and
- that attribute included group names, such as 'all', the
- unsupported attributes MUST NOT include attributes described in
- the standard but not supported by the implementation.
-
- Groups 3 to N: Job Object Attributes
-
- The Printer object responds with one set of Job Object Attributes
- for each returned Job object. The Printer object ignores (does
- not respond with) any requested attribute or value which is not
- supported or which is restricted by the security policy in force,
- including whether the requesting user is the user that submitted
- the job (job originating user) or not (see section 8). However,
- the Printer object MUST respond with the 'unknown' value for any
- supported attribute (including all REQUIRED attributes) for which
- the Printer object does not know the value, unless it would
- violate the security policy. See the description of the "out-of-
- band" values in the beginning of Section 4.1.
-
- Jobs are returned in the following order:
-
- - If the client requests all 'completed' Jobs (Jobs in the
- 'completed', 'aborted', or 'canceled' states), then the Jobs are
- returned newest to oldest (with respect to actual completion
- time)
- - If the client requests all 'not-completed' Jobs (Jobs in the
- 'pending', 'processing', 'pending-held', and 'processing-
- stopped' states), then Jobs are returned in relative
- chronological order of expected time to complete (based on
- whatever scheduling algorithm is configured for the Printer
- object).
-
-3.2.7 Pause-Printer Operation
-
- This OPTIONAL operation allows a client to stop the Printer object
- from scheduling jobs on all its devices. Depending on
- implementation, the Pause-Printer operation MAY also stop the Printer
- from processing the current job or jobs. Any job that is currently
- being printed is either stopped as soon as the implementation permits
-
-
-
-
-Hastings, et al. Standards Track [Page 57]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- or is completed, depending on implementation. The Printer object
- MUST still accept create operations to create new jobs, but MUST
- prevent any jobs from entering the 'processing' state.
-
- If the Pause-Printer operation is supported, then the Resume-Printer
- operation MUST be supported, and vice-versa.
-
- The IPP Printer stops the current job(s) on its device(s) that were
- in the 'processing' or 'processing-stopped' states as soon as the
- implementation permits. If the implementation will take appreciable
- time to stop, the IPP Printer adds the 'moving-to-paused' value to
- the Printer object's "printer-state-reasons" attribute (see section
- 4.4.12). When the device(s) have all stopped, the IPP Printer
- transitions the Printer object to the 'stopped' state, removes the
- 'moving-to-paused' value, if present, and adds the 'paused' value to
- the Printer object's "printer-state-reasons" attribute.
-
- When the current job(s) complete that were in the 'processing' state,
- the IPP Printer transitions them to the 'completed' state. When the
- current job(s) stop in mid processing that were in the 'processing'
- state, the IPP Printer transitions them to the 'processing-stopped'
- state and adds the 'printer-stopped' value to the job's "job-state-
- reasons" attribute.
-
- For any jobs that are 'pending' or 'pending-held', the 'printer-
- stopped' value of the jobs' "job-state-reasons" attribute also
- applies. However, the IPP Printer NEED NOT update those jobs' "job-
- state-reasons" attributes and only need return the 'printer-stopped'
- value when those jobs are queried (so-called "lazy evaluation").
-
- Whether the Pause-Printer operation affects jobs that were submitted
- to the device from other sources than the IPP Printer object in the
- same way that the Pause-Printer operation affects jobs that were
- submitted to the IPP Printer object using IPP, depends on
- implementation, i.e., on whether the IPP protocol is being used as a
- universal management protocol or just to manage IPP jobs,
- respectively.
-
- The IPP Printer MUST accept the request in any state and transition
- the Printer to the indicated new "printer-state" before returning as
- follows:
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 58]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Current New "printer IPP Printer's response status
- "printer- "printer- -state- code and action:
- state" state" reasons"
-
- 'idle' 'stopped' 'paused' 'successful-ok'
- 'processing' 'processing' 'moving- OPTION 1: 'successful-ok';
- to- Later, when all output has
- paused' stopped, the "printer-state"
- becomes 'stopped', and the
- 'paused' value replaces the
- 'moving-to-paused' value in the
- "printer-state-reasons"
- attribute
- 'processing' 'stopped' 'paused' OPTION 2: 'successful-ok';
- all device output stopped
- immediately
- 'stopped' 'stopped' 'paused' 'successful-ok'
-
- Access Rights: The authenticated user (see section 8.3) performing
- this operation must be an operator or administrator of the Printer
- object (see Sections 1 and 8.5). Otherwise, the IPP Printer MUST
- reject the operation and return: 'client-error-forbidden', 'client-
- error-not-authenticated', or 'client-error-not-authorized' as
- appropriate.
-
-3.2.7.1 Pause-Printer Request
-
- The following groups of attributes are part of the Pause-Printer
- Request:
-
- Group 1: Operation Attributes
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in section 3.1.4.1.
-
- Target:
- The "printer-uri" (uri) operation attribute which is the target
- for this operation as described in section 3.1.5.
-
- Requesting User Name:
- The "requesting-user-name" (name(MAX)) attribute SHOULD be
- supplied by the client as described in section 8.3.
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 59]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-3.2.7.2 Pause-Printer Response
-
- The following groups of attributes are part of the Pause-Printer
- Response:
-
- Group 1: Operation Attributes
-
- Status Message:
- In addition to the REQUIRED status code returned in every
- response, the response OPTIONALLY includes a "status-message"
- (text(255)) and/or a "detailed-status-message" (text(MAX))
- operation attribute as described in sections 13 and 3.1.6.
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in section 3.1.4.2.
-
- Group 2: Unsupported Attributes
-
- See section 3.1.7 for details on returning Unsupported Attributes.
-
-3.2.8 Resume-Printer Operation
-
- This operation allows a client to resume the Printer object
- scheduling jobs on all its devices. The Printer object MUST remove
- the 'paused' and 'moving-to-paused' values from the Printer object's
- "printer-state-reasons" attribute, if present. If there are no other
- reasons to keep a device paused (such as media-jam), the IPP Printer
- is free to transition itself to the 'processing' or 'idle' states,
- depending on whether there are jobs to be processed or not,
- respectively, and the device(s) resume processing jobs.
-
- If the Pause-Printer operation is supported, then the Resume-Printer
- operation MUST be supported, and vice-versa.
-
- The IPP Printer removes the 'printer-stopped' value from any job's
- "job-state-reasons" attributes contained in that Printer.
-
- The IPP Printer MUST accept the request in any state, transition the
- Printer object to the indicated new state as follows:
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 60]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Current New "printer- IPP Printer's response status code and
- "printer- state" action:
- state"
-
- 'idle' 'idle' 'successful-ok'
- 'processing' 'processing' 'successful-ok'
-
- 'stopped' 'processing' 'successful-ok';
- when there are jobs to be processed
- 'stopped' 'idle' 'successful-ok';
- when there are no jobs to be processed.
-
- Access Rights: The authenticated user (see section 8.3) performing
- this operation must be an operator or administrator of the Printer
- object (see Sections 1 and 8.5). Otherwise, the IPP Printer MUST
- reject the operation and return: 'client-error-forbidden', 'client-
- error-not-authenticated', or 'client-error-not-authorized' as
- appropriate.
-
- The Resume-Printer Request and Resume-Printer Response have the same
- attribute groups and attributes as the Pause-Printer operation (see
- sections 3.2.7.1 and 3.2.7.2).
-
-3.2.9 Purge-Jobs Operation
-
- This OPTIONAL operation allows a client to remove all jobs from an
- IPP Printer object, regardless of their job states, including jobs in
- the Printer object's Job History (see Section 4.3.7.2). After a
- Purge-Jobs operation has been performed, a Printer object MUST return
- no jobs in subsequent Get-Job-Attributes and Get-Jobs responses
- (until new jobs are submitted).
-
- Whether the Purge-Jobs (and Get-Jobs) operation affects jobs that
- were submitted to the device from other sources than the IPP Printer
- object in the same way that the Purge-Jobs operation affects jobs
- that were submitted to the IPP Printer object using IPP, depends on
- implementation, i.e., on whether the IPP protocol is being used as a
- universal management protocol or just to manage IPP jobs,
- respectively.
-
- Note: if an operator wants to cancel all jobs without clearing out
- the Job History, the operator uses the Cancel-Job operation on each
- job instead of using the Purge-Jobs operation.
-
- The Printer object MUST accept this operation in any state and
- transition the Printer object to the 'idle' state.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 61]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Access Rights: The authenticated user (see section 8.3) performing
- this operation must be an operator or administrator of the Printer
- object (see Sections 1 and 8.5). Otherwise, the IPP object MUST
- reject the operation and return: client-error-forbidden, client-
- error-not-authenticated, and client-error-not-authorized as
- appropriate.
-
- The Purge-Jobs Request and Purge-Jobs Response have the same
- attribute groups and attributes as the Pause-Printer operation (see
- sections 3.2.7.1 and 3.2.7.2).
-
-3.3 Job Operations
-
- All Job operations are directed at Job objects. A client MUST always
- supply some means of identifying the Job object in order to identify
- the correct target of the operation. That job identification MAY
- either be a single Job URI or a combination of a Printer URI with a
- Job ID. The IPP object implementation MUST support both forms of
- identification for every job.
-
-3.3.1 Send-Document Operation
-
- This OPTIONAL operation allows a client to create a multi-document
- Job object that is initially "empty" (contains no documents). In the
- Create-Job response, the Printer object returns the Job object's URI
- (the "job-uri" attribute) and the Job object's 32-bit identifier (the
- "job-id" attribute). For each new document that the client desires
- to add, the client uses a Send-Document operation. Each Send-
- Document Request contains the entire stream of document data for one
- document.
-
- If the Printer supports this operation but does not support multiple
- documents per job, the Printer MUST reject subsequent Send-Document
- operations supplied with data and return the 'server-error-multiple-
- document-jobs-not-supported'. However, the Printer MUST accept the
- first document with a 'true' or 'false' value for the "last-document"
- operation attribute (see below), so that clients MAY always submit
- one document jobs with a 'false' value for "last-document" in the
- first Send-Document and a 'true' for "last-document" in the second
- Send-Document (with no data).
-
- Since the Create-Job and the send operations (Send-Document or Send-
- URI operations) that follow could occur over an arbitrarily long
- period of time for a particular job, a client MUST send another send
- operation within an IPP Printer defined minimum time interval after
- the receipt of the previous request for the job. If a Printer object
- supports the Create-Job and Send-Document operations, the Printer
- object MUST support the "multiple-operation-time-out" attribute (see
-
-
-
-Hastings, et al. Standards Track [Page 62]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- section 4.4.31). This attribute indicates the minimum number of
- seconds the Printer object will wait for the next send operation
- before taking some recovery action.
-
- An IPP object MUST recover from an errant client that does not supply
- a send operation, sometime after the minimum time interval specified
- by the Printer object's "multiple-operation-time-out" attribute.
- Such recovery MAY include any of the following or other recovery
- actions:
-
- 1. Assume that the Job is an invalid job, start the process of
- changing the job state to 'aborted', add the 'aborted-by-
- system' value to the job's "job-state-reasons" attribute (see
- section 4.3.8), and clean up all resources associated with the
- Job. In this case, if another send operation is finally
- received, the Printer responds with an "client-error-not-
- possible" or "client-error-not-found" depending on whether or
- not the Job object is still around when the send operation
- finally arrives.
- 2. Assume that the last send operation received was in fact the
- last document (as if the "last-document" flag had been set to
- 'true'), close the Job object, and proceed to process it (i.e.,
- move the Job's state to 'pending').
- 3. Assume that the last send operation received was in fact the
- last document, close the Job, but move it to the 'pending-held'
- and add the 'submission-interrupted' value to the job's "job-
- state-reasons" attribute (see section 4.3.8). This action
- allows the user or an operator to determine whether to continue
- processing the Job by moving it back to the 'pending' state
- using the Release-Job operation (see section 3.3.6) or to
- cancel the job using the Cancel-Job operation (see section
- 3.3.3).
-
- Each implementation is free to decide the "best" action to take
- depending on local policy, whether any documents have been added,
- whether the implementation spools jobs or not, and/or any other
- piece of information available to it. If the choice is to abort the
- Job object, it is possible that the Job object may already have been
- processed to the point that some media sheet pages have been printed.
-
- Access Rights: The authenticated user (see section 8.3) performing
- this operation must either be the job owner (as determined in the
- Create-Job operation) or an operator or administrator of the Printer
- object (see Sections 1 and 8.5). Otherwise, the IPP object MUST
- reject the operation and return: 'client-error-forbidden', 'client-
- error-not-authenticated', or 'client-error-not-authorized' as
- appropriate.
-
-
-
-
-Hastings, et al. Standards Track [Page 63]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-3.3.1.1 Send-Document Request
-
- The following attribute sets are part of the Send-Document Request:
-
- Group 1: Operation Attributes
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in section 3.1.4.1.
-
- Target:
- Either (1) the "printer-uri" (uri) plus "job-id"
- (integer(1:MAX))or (2) the "job-uri" (uri) operation
- attribute(s) which define the target for this operation as
- described in section 3.1.5.
-
- Requesting User Name:
- The "requesting-user-name" (name(MAX)) attribute SHOULD be
- supplied by the client as described in section 8.3.
-
- "document-name" (name(MAX)):
- The client OPTIONALLY supplies this attribute. The Printer
- object MUST support this attribute. It contains the client
- supplied document name. The document name MAY be different than
- the Job name. It might be helpful, but NEED NOT be unique
- across multiple documents in the same Job. Typically, the
- client software automatically supplies the document name on
- behalf of the end user by using a file name or an application
- generated name. See the description of the "document-name"
- operation attribute in the Print-Job Request (section 3.2.1.1)
- for more information about this attribute.
-
- "compression" (type3 keyword):
- See the description of "compression" for the Print-Job operation
- in Section 3.2.1.1.
-
- "document-format" (mimeMediaType):
- See the description of "document-format" for the Print-Job
- operation in Section 3.2.1.1.
-
- "document-natural-language" (naturalLanguage):
- The client OPTIONALLY supplies this attribute. The Printer
- object OPTIONALLY supports this attribute. This attribute
- specifies the natural language of the document for those
- document-formats that require a specification of the natural
- language in order to image the document unambiguously. There
- are no particular values required for the Printer object to
- support.
-
-
-
-Hastings, et al. Standards Track [Page 64]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- "last-document" (boolean):
- The client MUST supply this attribute. The Printer object MUST
- support this attribute. It is a boolean flag that is set to
- 'true' if this is the last document for the Job, 'false'
- otherwise.
-
- Group 2: Document Content
-
- The client MUST supply the document data if the "last-document"
- flag is set to 'false'. However, since a client might not know
- that the previous document sent with a Send-Document (or Send-URI)
- operation was the last document (i.e., the "last-document"
- attribute was set to 'false'), it is legal to send a Send-Document
- request with no document data where the "last-document" flag is
- set to 'true'. Such a request MUST NOT increment the value of the
- Job object's "number-of-documents" attribute, since no real
- document was added to the job. It is not an error for a client to
- submit a job with no actual document data, i.e., only a single
- Create-Job and Send-Document request with a "last-document"
- operation attribute set to 'true' with no document data.
-
-3.3.1.2 Send-Document Response
-
- The following sets of attributes are part of the Send-Document
- Response:
-
- Group 1: Operation Attributes
-
- Status Message:
- In addition to the REQUIRED status code returned in every
- response, the response OPTIONALLY includes a "status-message"
- (text(255)) and/or a "detailed-status-message" (text(MAX))
- operation attribute as described in sections 13 and 3.1.6.
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in section 3.1.4.2.
-
- Group 2: Unsupported Attributes
-
- See section 3.1.7 for details on returning Unsupported Attributes.
-
- Group 3: Job Object Attributes
-
- This is the same set of attributes as described in the Print-Job
- response (see section 3.2.1.2).
-
-
-
-
-
-Hastings, et al. Standards Track [Page 65]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-3.3.2 Send-URI Operation
-
- This OPTIONAL operation is identical to the Send-Document operation
- (see section 3.3.1) except that a client MUST supply a URI reference
- ("document-uri" operation attribute) rather than the document data
- itself. If a Printer object supports this operation, clients can use
- both Send-URI or Send-Document operations to add new documents to an
- existing multi-document Job object. However, if a client needs to
- indicate that the previous Send-URI or Send-Document was the last
- document, the client MUST use the Send-Document operation with no
- document data and the "last-document" flag set to 'true' (rather than
- using a Send-URI operation with no "document-uri" operation
- attribute).
-
- If a Printer object supports this operation, it MUST also support the
- Print-URI operation (see section 3.2.2).
-
- The Printer object MUST validate the syntax and URI scheme of the
- supplied URI before returning a response, just as in the Print-URI
- operation. The IPP Printer MAY validate the accessibility of the
- document as part of the operation or subsequently (see section
- 3.2.2).
-
-3.3.3 Cancel-Job Operation
-
- This REQUIRED operation allows a client to cancel a Print Job from
- the time the job is created up to the time it is completed, canceled,
- or aborted. Since a Job might already be printing by the time a
- Cancel-Job is received, some media sheet pages might be printed
- before the job is actually terminated.
-
- The IPP object MUST accept or reject the request based on the job's
- current state and transition the job to the indicated new state as
- follows:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 66]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Current "job- New "job- IPP object's response status
- state" state" code and action:
-
- 'pending' 'canceled' 'successful-ok'
- 'pending-held' 'canceled' 'successful-ok'
- 'processing' 'canceled' 'successful-ok'
- 'processing' 'processing' 'successful-ok' See Rule 1
- 'processing' 'processing' 'client-error-not-possible'
- See Rule 2
- 'processing- 'canceled' 'successful-ok'
- stopped'
- 'processing- 'processing- 'successful-ok' See Rule 1
- stopped' stopped'
- 'processing- 'processing- 'client-error-not-possible'
- stopped' stopped' See Rule 2
- 'completed' 'completed' 'client-error-not-possible'
- 'canceled' 'canceled' 'client-error-not-possible'
- 'aborted' 'aborted' 'client-error-not-possible'
-
- Rule 1: If the implementation requires some measurable time to
- cancel the job in the 'processing' or 'processing-stopped' job
- states, the IPP object MUST add the 'processing-to-stop-point' value
- to the job's "job-state-reasons" attribute and then transition the
- job to the 'canceled' state when the processing ceases (see section
- 4.3.8).
-
- Rule 2: If the Job object already has the 'processing-to-stop-point'
- value in its "job-state-reasons" attribute, then the Printer object
- MUST reject a Cancel-Job operation.
-
- Access Rights: The authenticated user (see section 8.3) performing
- this operation must either be the job owner or an operator or
- administrator of the Printer object (see Sections 1 and 8.5).
- Otherwise, the IPP object MUST reject the operation and return:
- 'client-error-forbidden', 'client-error-not-authenticated', or
- 'client-error-not-authorized' as appropriate.
-
-3.3.3.1 Cancel-Job Request
-
- The following groups of attributes are part of the Cancel-Job
- Request:
-
- Group 1: Operation Attributes
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in section 3.1.4.1.
-
-
-
-
-Hastings, et al. Standards Track [Page 67]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Target:
- Either (1) the "printer-uri" (uri) plus "job-id"
- (integer(1:MAX))or (2) the "job-uri" (uri) operation
- attribute(s) which define the target for this operation as
- described in section 3.1.5.
-
- Requesting User Name:
- The "requesting-user-name" (name(MAX)) attribute SHOULD be
- supplied by the client as described in section 8.3.
-
- "message" (text(127)):
- The client OPTIONALLY supplies this attribute. The Printer
- object OPTIONALLY supports this attribute. It is a message to
- the operator. This "message" attribute is not the same as the
- "job-message-from-operator" attribute. That attribute is used
- to report a message from the operator to the end user that
- queries that attribute. This "message" operation attribute is
- used to send a message from the client to the operator along
- with the operation request. It is an implementation decision
- of how or where to display this message to the operator (if at
- all).
-
-3.3.3.2 Cancel-Job Response
-
- The following sets of attributes are part of the Cancel-Job Response:
-
- Group 1: Operation Attributes
-
- Status Message:
- In addition to the REQUIRED status code returned in every
- response, the response OPTIONALLY includes a "status-message"
- (text(255)) and/or a "detailed-status-message" (text(MAX))
- operation attribute as described in sections 13 and 3.1.6.
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in section 3.1.4.2.
-
- Group 2: Unsupported Attributes
-
- See section 3.1.7 for details on returning Unsupported Attributes.
-
- Once a successful response has been sent, the implementation
- guarantees that the Job will eventually end up in the 'canceled'
- state. Between the time of the Cancel-Job operation is accepted and
- when the job enters the 'canceled' job-state (see section 4.3.7), the
- "job-state-reasons" attribute SHOULD contain the 'processing-to-
- stop-point'
-
-
-
-Hastings, et al. Standards Track [Page 68]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- value which indicates to later queries that although the Job might
- still be 'processing', it will eventually end up in the
- 'canceled' state, not the 'completed' state.
-
-3.3.4 Get-Job-Attributes Operation
-
- This REQUIRED operation allows a client to request the values of
- attributes of a Job object and it is almost identical to the Get-
- Printer-Attributes operation (see section 3.2.5). The only
- differences are that the operation is directed at a Job object rather
- than a Printer object, there is no "document-format" operation
- attribute used when querying a Job object, and the returned attribute
- group is a set of Job object attributes rather than a set of Printer
- object attributes.
-
- For Jobs, the possible names of attribute groups are:
-
- - 'job-template': the subset of the Job Template attributes that
- apply to a Job object (the first column of the table in Section
- 4.2) that the implementation supports for Job objects.
- - 'job-description': the subset of the Job Description attributes
- specified in Section 4.3 that the implementation supports for
- Job objects.
- - 'all': the special group 'all' that includes all attributes that
- the implementation supports for Job objects.
-
- Since a client MAY request specific attributes or named groups, there
- is a potential that there is some overlap. For example, if a client
- requests, 'job-name' and 'job-description', the client is actually
- requesting the "job-name" attribute once by naming it explicitly, and
- once by inclusion in the 'job-description' group. In such cases, the
- Printer object NEED NOT return the attribute only once in the
- response even if it is requested multiple times. The client SHOULD
- NOT request the same attribute in multiple ways.
-
- It is NOT REQUIRED that a Job object support all attributes belonging
- to a group (since some attributes are OPTIONAL). However it is
- REQUIRED that each Job object support all these group names.
-
-3.3.4.1 Get-Job-Attributes Request
-
- The following groups of attributes are part of the Get-Job-Attributes
- Request when the request is directed at a Job object:
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 69]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Group 1: Operation Attributes
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in section 3.1.4.1.
-
- Target:
- Either (1) the "printer-uri" (uri) plus "job-id"
- (integer(1:MAX)) or (2) the "job-uri" (uri) operation
- attribute(s) which define the target for this operation as
- described in section 3.1.5.
-
- Requesting User Name:
- The "requesting-user-name" (name(MAX)) attribute SHOULD be
- supplied by the client as described in section 8.3.
-
- "requested-attributes" (1setOf keyword):
- The client OPTIONALLY supplies this attribute. The IPP object
- MUST support this attribute. It is a set of attribute names
- and/or attribute group names in whose values the requester is
- interested. If the client omits this attribute, the IPP object
- MUST respond as if this attribute had been supplied with a value
- of 'all'.
-
-3.3.4.2 Get-Job-Attributes Response
-
- The Printer object returns the following sets of attributes as part
- of the Get-Job-Attributes Response:
-
- Group 1: Operation Attributes
-
- Status Message:
- In addition to the REQUIRED status code returned in every
- response, the response OPTIONALLY includes a "status-message"
- (text(255)) and/or a "detailed-status-message" (text(MAX))
- operation attribute as described in sections 13 and 3.1.6.
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in section 3.1.4.2. The "attributes-
- natural-language" MAY be the natural language of the Job
- object, rather than the one requested.
-
- Group 2: Unsupported Attributes
-
- See section 3.1.7 for details on returning Unsupported Attributes.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 70]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- The response NEED NOT contain the "requested-attributes" operation
- attribute with any supplied values (attribute keywords) that were
- requested by the client but are not supported by the IPP object.
- If the Printer object does return unsupported attributes
- referenced in the "requested-attributes" operation attribute and
- that attribute included group names, such as 'all', the
- unsupported attributes MUST NOT include attributes described in
- the standard but not supported by the implementation.
-
- Group 3: Job Object Attributes
-
- This is the set of requested attributes and their current values.
- The IPP object ignores (does not respond with) any requested
- attribute or value which is not supported or which is restricted
- by the security policy in force, including whether the requesting
- user is the user that submitted the job (job originating user) or
- not (see section 8). However, the IPP object MUST respond with
- the 'unknown' value for any supported attribute (including all
- REQUIRED attributes) for which the IPP object does not know the
- value, unless it would violate the security policy. See the
- description of the "out-of-band" values in the beginning of
- Section 4.1.
-
-3.3.5 Hold-Job Operation
-
- This OPTIONAL operation allows a client to hold a pending job in the
- queue so that it is not eligible for scheduling. If the Hold-Job
- operation is supported, then the Release-Job operation MUST be
- supported, and vice-versa. The OPTIONAL "job-hold-until" operation
- attribute allows a client to specify whether to hold the job
- indefinitely or until a specified time period, if supported.
-
- The IPP object MUST accept or reject the request based on the job's
- current state and transition the job to the indicated new state as
- follows:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 71]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Current "job- New "job-state" IPP object's response status
- state" code and action:
-
- 'pending' 'pending-held' 'successful-ok' See Rule 1
- 'pending' 'pending' 'successful-ok' See Rule 2
- 'pending-held' 'pending-held' 'successful-ok' See Rule 1
- 'pending-held' 'pending' 'successful-ok' See Rule 2
- 'processing' 'processing' 'client-error-not-possible'
- 'processing- 'processing- 'client-error-not-possible'
- stopped' stopped'
- 'completed' 'completed' 'client-error-not-possible'
- 'canceled' 'canceled' 'client-error-not-possible'
- 'aborted' 'aborted' 'client-error-not-possible'
-
- Rule 1: If the implementation supports multiple reasons for a job to
- be in the 'pending-held' state, the IPP object MUST add the 'job-
- hold-until-specified' value to the job's "job-state-reasons"
- attribute.
-
- Rule 2: If the IPP object supports the "job-hold-until" operation
- attribute, but the specified time period has already started (or is
- the 'no-hold' value) and there are no other reasons to hold the job,
- the IPP object MUST make the job be a candidate for processing
- immediately (see Section 4.2.2) by putting the job in the 'pending'
- state.
-
- Note: In order to keep the Hold-Job operation simple, such a request
- is rejected when the job is in the 'processing' or 'processing-
- stopped' states. If an operation is needed to hold jobs while in
- these states, it will be added as an additional operation, rather
- than overloading the Hold-Job operation. Then it is clear to clients
- by querying the Printer object's "operations-supported" (see Section
- 4.4.15) and the Job object's "job-state" (see Section 4.3.7)
- attributes which operations are possible.
-
- Access Rights: The authenticated user (see section 8.3) performing
- this operation must either be the job owner or an operator or
- administrator of the Printer object (see Sections 1 and 8.5).
- Otherwise, the IPP object MUST reject the operation and return:
- 'client-error-forbidden', 'client-error-not-authenticated', or
- 'client-error-not-authorized' as appropriate.
-
-3.3.5.1 Hold-Job Request
-
- The groups and operation attributes are the same as for a Cancel-Job
- request (see section 3.3.3.1), with the addition of the following
- Group 1 Operation attribute:
-
-
-
-
-Hastings, et al. Standards Track [Page 72]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- "job-hold-until" (type3 keyword | name(MAX)):
- The client OPTIONALLY supplies this Operation attribute. The
- IPP object MUST support this operation attribute in a Hold-Job
- request, if it supports the "job-hold-until" Job template
- attribute in create operations. See section 4.2.2. The IPP
- object SHOULD support the "job-hold-until" Job Template
- attribute for use in job create operations with at least the
- 'indefinite' value, if it supports the Hold-Job operation.
- Otherwise, a client cannot create a job and hold it immediately
- (without picking some supported time period in the future).
-
- If supplied and supported as specified in the Printer's "job-
- hold-until-supported" attribute, the IPP object copies the
- supplied operation attribute to the Job object, replacing the
- job's previous "job-hold-until" attribute, if present, and
- makes the job a candidate for scheduling during the supplied
- named time period.
-
- If supplied, but either the "job-hold-until" Operation
- attribute itself or the value supplied is not supported, the
- IPP object accepts the request, returns the unsupported
- attribute or value in the Unsupported Attributes Group
- according to section 3.1.7, returns the 'successful-ok-
- ignored-or-substituted-attributes, and holds the job
- indefinitely until a client performs a subsequent Release-Job
- operation.
-
- If the client (1) supplies a value that specifies a time period
- that has already started or the 'no-hold' value (meaning don't
- hold the job) and (2) the IPP object supports the "job-hold-
- until" operation attribute and there are no other reasons to
- hold the job, the IPP object MUST accept the operation and make
- the job be a candidate for processing immediately (see Section
- 4.2.2).
-
- If the client does not supply a "job-hold-until" Operation
- attribute in the request, the IPP object MUST populate the job
- object with a "job-hold-until" attribute with the 'indefinite'
- value (if IPP object supports the "job-hold-until" attribute)
- and hold the job indefinitely, until a client performs a
- Release-Job operation.
-
-3.3.5.2 Hold-Job Response
-
- The groups and attributes are the same as for a Cancel-Job response
- (see section 3.3.3.2).
-
-
-
-
-
-Hastings, et al. Standards Track [Page 73]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-3.3.6 Release-Job Operation
-
- This OPTIONAL operation allows a client to release a previously held
- job so that it is again eligible for scheduling. If the Hold-Job
- operation is supported, then the Release-Job operation MUST be
- supported, and vice-versa.
-
- This operation removes the "job-hold-until" job attribute, if
- present, from the job object that had been supplied in the create or
- most recent Hold-Job or Restart-Job operation and removes its effect
- on the job. The IPP object MUST remove the 'job-hold-until-
- specified' value from the job's "job-state-reasons" attribute, if
- present. See section 4.3.8.
-
- The IPP object MUST accept or reject the request based on the job's
- current state and transition the job to the indicated new state as
- follows:
-
- Current "job- New "job-state" IPP object's response status
- state" code and action:
-
- 'pending' 'pending' 'successful-ok'
- No effect on the job.
- 'pending-held' 'pending-held' 'successful-ok' See Rule 1
- 'pending-held' 'pending' 'successful-ok'
- 'processing' 'processing' 'successful-ok'
- No effect on the job.
- 'processing- 'processing- 'successful-ok'
- stopped' stopped' No effect on the job.
- 'completed' 'completed' 'client-error-not-possible'
- 'canceled' 'canceled' 'client-error-not-possible'
- 'aborted' 'aborted' 'client-error-not-possible'
-
- Rule 1: If there are other reasons to keep the job in the 'pending-
- held' state, such as 'resources-are-not-ready', the job remains in
- the 'pending-held' state. Thus the 'pending-held' state is not just
- for jobs that have the 'job-hold-until' applied to them, but are for
- any reason to keep the job from being a candidate for scheduling and
- processing, such as 'resources-are-not-ready'. See the "job-hold-
- until" attribute (section 4.2.2).
-
- Access Rights: The authenticated user (see section 8.3) performing
- this operation must either be the job owner or an operator or
- administrator of the Printer object (see Sections 1 and 8.5).
- Otherwise, the IPP object MUST reject the operation and return:
- 'client-error-forbidden', 'client-error-not-authenticated', or
- 'client-error-not-authorized' as appropriate.
-
-
-
-
-Hastings, et al. Standards Track [Page 74]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- The Release-Job Request and Release-Job Response have the same
- attribute groups and attributes as the Cancel-Job operation (see
- section 3.3.3.1 and 3.3.3.2).
-
-3.3.7 Restart-Job Operation
-
- This OPTIONAL operation allows a client to restart a job that is
- retained in the queue after processing has completed (see section
- 4.3.7.2).
-
- The job is moved to the 'pending' or 'pending-held' job state and
- restarts at the beginning on the same IPP Printer object with the
- same attribute values. If any of the documents in the job were
- passed by reference (Print-URI or Send-URI), the Printer MUST re-
- fetch the data, since the semantics of Restart-Job are to repeat all
- Job processing. The Job Description attributes that accumulate job
- progress, such as "job-impressions-completed", "job-media-sheets-
- completed", and "job-k-octets-processed", MUST be reset to 0 so that
- they give an accurate record of the job from its restart point. The
- job object MUST continue to use the same "job-uri" and "job-id"
- attribute values.
-
- Note: If in the future an operation is needed that does not reset
- the job progress attributes, then a new operation will be defined
- which makes a copy of the job, assigns a new "job-uri" and "job-id"
- to the copy and resets the job progress attributes in the new copy
- only.
-
- The IPP object MUST accept or reject the request based on the job's
- current state, transition the job to the indicated new state as
- follows:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 75]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Current "job- New "job-state" IPP object's response status
- state" code and action:
-
- 'pending' 'pending' 'client-error-not-possible'
- 'pending-held' 'pending-held' 'client-error-not-possible'
- 'processing' 'processing' 'client-error-not-possible'
- 'processing- 'processing- 'client-error-not-possible'
- stopped' stopped'
- 'completed' 'pending' or 'successful-ok' - job is started
- 'pending-held' over.
- 'completed' 'completed' 'client-error-not-possible' -
- see Rule 1
- 'canceled' 'pending' or 'successful-ok' - job is started
- 'pending-held' over.
- 'canceled' 'canceled' 'client-error-not-possible' -
- see Rule 1
- 'aborted' 'pending' or 'successful-ok' - job is started
- 'pending-held' over.
- 'aborted' 'aborted' 'client-error-not-possible' -
- see Rule 1
-
- Rule 1: If the Job Retention Period has expired for the job in this
- state, then the IPP object rejects the operation. See section
- 4.3.7.2.
-
- Note: In order to prevent a user from inadvertently restarting a job
- in the middle, the Restart-Job request is rejected when the job is in
- the 'processing' or 'processing-stopped' states. If in the future an
- operation is needed to hold or restart jobs while in these states, it
- will be added as an additional operation, rather than overloading the
- Restart-Job operation, so that it is clear that the user intended
- that the current job not be completed.
-
- Access Rights: The authenticated user (see section 8.3) performing
- this operation must either be the job owner or an operator or
- administrator of the Printer object (see Sections 1 and 8.5).
- Otherwise, the IPP object MUST reject the operation and return:
- 'client-error-forbidden', 'client-error-not-authenticated', or
- 'client-error-not-authorized' as appropriate.
-
-3.3.7.1 Restart-Job Request
-
- The groups and attributes are the same as for a Cancel-Job request
- (see section 3.3.3.1), with the addition of the following Group 1
- Operation attribute:
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 76]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- "job-hold-until" (type3 keyword | name(MAX)):
- The client OPTIONALLY supplies this attribute. The IPP object
- MUST support this Operation attribute in a Restart-Job request,
- if it supports the "job-hold-until" Job Template attribute in
- create operations. See section 4.2.2. Otherwise, the IPP
- object NEED NOT support the "job-hold-until" Operation
- attribute in a Restart-Job request.
-
- If supplied and supported as specified in the Printer's "job-
- hold-until-supported" attribute, the IPP object copies the
- supplied Operation attribute to the Job object, replacing the
- job's previous "job-hold-until" attribute, if present, and
- makes the job a candidate for scheduling during the supplied
- named time period. See section 4.2.2.
-
- If supplied, but the value is not supported, the IPP object
- accepts the request, returns the unsupported attribute or value
- in the Unsupported Attributes Group according to section 3.1.7,
- returns the 'successful-ok-ignored-or-substituted-attributes'
- status code, and holds the job indefinitely until a client
- performs a subsequent Release-Job operation.
-
- If supplied, but the "job-hold-until" Operation attribute
- itself is not supported, the IPP object accepts the request,
- returns the unsupported attribute with the out-of-band
- 'unsupported' value in the Unsupported Attributes Group
- according to section 3.1.7, returns the 'successful-ok-
- ignored-or-substituted-attributes' status code, and restarts
- the job, i.e., ignores the "job-hold-until" attribute.
-
- If the client (1) supplies a value that specifies a time period
- that has already started or the 'no-hold' value (meaning don't
- hold the job) and (2) the IPP object supports the "job-hold-
- until" operation attribute and there are no other reasons to
- hold the job, the IPP object makes the job a candidate for
- processing immediately (see Section 4.2.2).
-
- If the client does not supply a "job-hold-until" operation
- attribute in the request, the IPP object removes the "job-
- hold-until" attribute, if present, from the job. If there are
- no other reasons to hold the job, the Restart-Job operation
- makes the job a candidate for processing immediately (see
- Section 4.2.2).
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 77]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-3.3.7.2 Restart-Job Response
-
- The groups and attributes are the same as for a Cancel-Job response
- (see section 3.3.3.2).
-
- Note: In the future an OPTIONAL Modify-Job or Set-Job-Attributes
- operation may be specified that allows the client to modify other
- attributes before releasing the restarted job.
-
-4. Object Attributes
-
- This section describes the attributes with their corresponding
- attribute syntaxes and values that are part of the IPP model. The
- sections below show the objects and their associated attributes which
- are included within the scope of this protocol. Many of these
- attributes are derived from other relevant documents:
-
- - Document Printing Application (DPA) [ISO10175]
- - RFC 1759 Printer MIB [RFC1759]
-
- Each attribute is uniquely identified in this document using a
- "keyword" (see section 12.2.1) which is the name of the attribute.
- The keyword is included in the section header describing that
- attribute.
-
- Note: Not only are keywords used to identify attributes, but one of
- the attribute syntaxes described below is "keyword" so that some
- attributes have keyword values. Therefore, these attributes are
- defined as having an attribute syntax that is a set of keywords.
-
-4.1 Attribute Syntaxes
-
- This section defines the basic attribute syntax types that all
- clients and IPP objects MUST be able to accept in responses and
- accept in requests, respectively. Each attribute description in
- sections 3 and 4 includes the name of attribute syntax(es) in the
- heading (in parentheses). A conforming implementation of an
- attribute MUST include the semantics of the attribute syntax(es) so
- identified. Section 6.3 describes how the protocol can be extended
- with new attribute syntaxes.
-
- The attribute syntaxes are specified in the following sub-sections,
- where the sub-section heading is the keyword name of the attribute
- syntax inside the single quotes. In operation requests and responses
- each attribute value MUST be represented as one of the attribute
- syntaxes specified in the sub-section heading for the attribute. In
- addition, the value of an attribute in a response (but not in a
-
-
-
-
-Hastings, et al. Standards Track [Page 78]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- request) MAY be one of the "out-of-band" values whose special
- encoding rules are defined in the "Encoding and Transport" document
- [RFC2910]. Standard "out-of-band" values are:
-
- 'unknown': The attribute is supported by the IPP object, but the
- value is unknown to the IPP object for some reason.
- 'unsupported': The attribute is unsupported by the IPP object.
- This value MUST be returned only as the value of an attribute
- in the Unsupported Attributes Group.
- 'no-value': The attribute is supported by the Printer object, but
- the administrator has not yet configured a value.
-
- All attributes in a request MUST have one or more values as defined
- in Sections 4.2 to 4.4. Thus clients MUST NOT supply attributes with
- "out-of-band" values for operations defined in this document. All
- attributes in a response MUST have one or more values as defined in
- Sections 4.2 to 4.4 or a single "out-of-band" value.
-
- Most attributes are defined to have a single attribute syntax.
- However, a few attributes (e.g., "job-sheet", "media", "job-hold-
- until") are defined to have several attribute syntaxes, depending on
- the value. These multiple attribute syntaxes are separated by the
- "|" character in the sub-section heading to indicate the choice.
- Since each value MUST be tagged as to its attribute syntax in the
- protocol, a single-valued attribute instance may have any one of its
- attribute syntaxes and a multi-valued attribute instance may have a
- mixture of its defined attribute syntaxes.
-
-4.1.1 'text'
-
- A text attribute is an attribute whose value is a sequence of zero or
- more characters encoded in a maximum of 1023 ('MAX') octets. MAX is
- the maximum length for each value of any text attribute. However, if
- an attribute will always contain values whose maximum length is much
- less than MAX, the definition of that attribute will include a
- qualifier that defines the maximum length for values of that
- attribute. For example: the "printer-location" attribute is
- specified as "printer-location (text(127))". In this case, text
- values for "printer-location" MUST NOT exceed 127 octets; if supplied
- with a longer text string via some external interface (other than the
- protocol), implementations are free to truncate to this shorter
- length limitation.
-
- In this document, all text attributes are defined using the 'text'
- syntax. However, 'text' is used only for brevity; the formal
- interpretation of 'text' is: 'textWithoutLanguage |
- textWithLanguage'. That is, for any attribute defined in this
- document using the 'text' attribute syntax, all IPP objects and
-
-
-
-Hastings, et al. Standards Track [Page 79]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- clients MUST support both the 'textWithoutLanguage' and
- 'textWithLanguage' attribute syntaxes. However, in actual usage and
- protocol execution, objects and clients accept and return only one of
- the two syntax per attribute. The syntax 'text' never appears "on-
- the-wire".
-
- Both 'textWithoutLanguage' and 'textWithLanguage' are needed to
- support the real world needs of interoperability between sites and
- systems that use different natural languages as the basis for human
- communication. Generally, one natural language applies to all text
- attributes in a given request or response. The language is indicated
- by the "attributes-natural-language" operation attribute defined in
- section 3.1.4 or "attributes-natural-language" job attribute defined
- in section 4.3.20, and there is no need to identify the natural
- language for each text string on a value-by-value basis. In these
- cases, the attribute syntax 'textWithoutLanguage' is used for text
- attributes. In other cases, the client needs to supply or the
- Printer object needs to return a text value in a natural language
- that is different from the rest of the text values in the request or
- response. In these cases, the client or Printer object uses the
- attribute syntax 'textWithLanguage' for text attributes (this is the
- Natural Language Override mechanism described in section 3.1.4).
-
- The 'textWithoutLanguage' and 'textWithLanguage' attribute syntaxes
- are described in more detail in the following sections.
-
-4.1.1.1 'textWithoutLanguage'
-
- The 'textWithoutLanguage' syntax indicates a value that is sequence
- of zero or more characters encoded in a maximum of 1023 (MAX) octets.
- Text strings are encoded using the rules of some charset. The
- Printer object MUST support the UTF-8 charset [RFC2279] and MAY
- support additional charsets to represent 'text' values, provided that
- the charsets are registered with IANA [IANA-CS]. See Section 4.1.7
- for the definition of the 'charset' attribute syntax, including
- restricted semantics and examples of charsets.
-
-4.1.1.2 'textWithLanguage'
-
- The 'textWithLanguage' attribute syntax is a compound attribute
- syntax consisting of two parts: a 'textWithoutLanguage' part encoded
- in a maximum of 1023 (MAX) octets plus an additional
- 'naturalLanguage' (see section 4.1.8) part that overrides the natural
- language in force. The 'naturalLanguage' part explicitly identifies
- the natural language that applies to the text part of that value and
- that value alone. For any give text attribute, the
- 'textWithoutLanguage' part is limited to the maximum length defined
- for that 'text' attribute, and the 'naturalLanguage' part is always
-
-
-
-Hastings, et al. Standards Track [Page 80]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- limited to 63 (additional) octets. Using the 'textWithLanguage'
- attribute syntax rather than the normal 'textWithoutLanguage' syntax
- is the so-called Natural Language Override mechanism and MUST be
- supported by all IPP objects and clients.
-
- If the attribute is multi-valued (1setOf text), then the
- 'textWithLanguage' attribute syntax MUST be used to explicitly
- specify each attribute value whose natural language needs to be
- overridden. Other values in a multi-valued 'text' attribute in a
- request or a response revert to the natural language of the operation
- attribute.
-
- In a create request, the Printer object MUST accept and store with
- the Job object any natural language in the "attributes-natural-
- language" operation attribute, whether the Printer object supports
- that natural language or not. Furthermore, the Printer object MUST
- accept and store any 'textWithLanguage' attribute value, whether the
- Printer object supports that natural language or not. These
- requirements are independent of the value of the "ipp-attribute-
- fidelity" operation attribute that the client MAY supply.
-
- Example: If the client supplies the "attributes-natural-language"
- operation attribute with the value: 'en' indicating English, but the
- value of the "job-name" attribute is in French, the client MUST use
- the 'textWithLanguage' attribute syntax with the following two
- values:
-
- 'fr': Natural Language Override indicating French
- 'Rapport Mensuel': the job name in French
-
- See the "Encoding and Transport" document [RFC2910] section 3.9 for
- the encoding of the two parts and Appendix A for a detailed example
- of the 'textWithLanguage' attribute syntax.
-
-4.1.2 'name'
-
- This syntax type is used for user-friendly strings, such as a Printer
- name, that, for humans, are more meaningful than identifiers. Names
- are never translated from one natural language to another. The
- 'name' attribute syntax is essentially the same as 'text', including
- the REQUIRED support of UTF-8 except that the sequence of characters
- is limited so that its encoded form MUST NOT exceed 255 (MAX) octets.
-
- Also like 'text', 'name' is really an abbreviated notation for either
- 'nameWithoutLanguage' or 'nameWithLanguage'. That is, all IPP
- objects and clients MUST support both the 'nameWithoutLanguage' and
- 'nameWithLanguage' attribute syntaxes. However, in actual usage and
-
-
-
-
-Hastings, et al. Standards Track [Page 81]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- protocol execution, objects and clients accept and return only one of
- the two syntax per attribute. The syntax 'name' never appears "on-
- the-wire".
-
- Only the 'text' and 'name' attribute syntaxes permit the Natural
- Language Override mechanism.
-
- Some attributes are defined as 'type3 keyword | name'. These
- attributes support values that are either type3 keywords or names.
- This dual-syntax mechanism enables a site administrator to extend
- these attributes to legally include values that are locally defined
- by the site administrator. Such names are not registered with IANA.
-
-4.1.2.1 'nameWithoutLanguage'
-
- The 'nameWithoutLanguage' syntax indicates a value that is sequence
- of zero or more characters encoded in a maximum of 255 (MAX) octets.
-
-4.1.2.2 'nameWithLanguage'
-
- The 'nameWithLanguage' attribute syntax is a compound attribute
- syntax consisting of two parts: a 'nameWithoutLanguage' part encoded
- in a maximum of 1023 (MAX) octets plus an additional
- 'naturalLanguage' (see section 4.1.8) part that overrides the natural
- language in force. The 'naturalLanguage' part explicitly identifies
- the natural language that applies to that name value and that name
- value alone. For any give text attribute, the 'textWithoutLanguage'
- part is limited to the maximum length defined for that 'text'
- attribute, and the 'naturalLanguage' part is always limited to 63
- (additional) octets. Using the 'textWithLanguage' attribute syntax
- rather than the normal 'textWithoutLanguage' syntax is the so-called
- Natural Language Override mechanism and MUST be supported by all IPP
- objects and clients.
-
- The 'nameWithLanguage' attribute syntax behaves the same as the
- 'textWithLanguage' syntax. Using the 'textWithLanguage' attribute
- syntax rather than the normal 'textWithoutLanguage' syntax is the
- so-called Natural Language Override mechanism and MUST be supported
- by all IPP objects and clients. If a name is in a language that is
- different than the rest of the object or operation, then this
- 'nameWithLanguage' syntax is used rather than the generic
- 'nameWithoutLanguage' syntax.
-
- If the attribute is multi-valued (1setOf text), then the
- 'nameWithLanguage' attribute syntax MUST be used to explicitly
- specify each attribute value whose natural language needs to be
- overridden.
-
-
-
-
-Hastings, et al. Standards Track [Page 82]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Other values in a multi-valued 'name' attribute in a request or a
- response revert to the natural language of the operation attribute.
-
- In a create request, the Printer object MUST accept and store with
- the Job object any natural language in the "attributes-natural-
- language" operation attribute, whether the Printer object supports
- that natural language or not. Furthermore, the Printer object MUST
- accept and store any 'nameWithLanguage' attribute value, whether the
- Printer object supports that natural language or not. These
- requirements are independent of the value of the "ipp-attribute-
- fidelity" operation attribute that the client MAY supply.
-
- Example: If the client supplies the "attributes-natural-language"
- operation attribute with the value: 'en' indicating English, but the
- "printer-name" attribute is in German, the client MUST use the
- 'nameWithLanguage' attribute syntax as follows:
-
- 'de': Natural Language Override indicating German
- 'Farbdrucker': the Printer name in German
-
- See the "Encoding and Transport" document [RFC2910] section 3.9 for
- the encoding of the two parts and Appendix A for a detailed example
- of the 'nameWithLanguage' attribute syntax.
-
-4.1.2.3 Matching 'name' attribute values
-
- For purposes of matching two 'name' attribute values for equality,
- such as in job validation (where a client-supplied value for
- attribute "xxx" is checked to see if the value is among the values of
- the Printer object's corresponding "xxx-supported" attribute), the
- following match rules apply:
-
- 1. 'keyword' values never match 'name' values.
-
- 2. 'name' (nameWithoutLanguage and nameWithLanguage) values match
- if (1) the name parts match and (2) the Associated Natural-
- Language parts (see section 3.1.4.1) match. The matching rules
- are:
-
- a. the name parts match if the two names are identical
- character by character, except it is RECOMMENDED that case
- be ignored. For example: 'Ajax-letter-head-white' MUST
- match 'Ajax-letter-head-white' and SHOULD match 'ajax-
- letter-head-white' and 'AJAX-LETTER-HEAD-WHITE'.
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 83]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- b. the Associated Natural-Language parts match if the shorter
- of the two meets the syntactic requirements of RFC 1766
- [RFC1766] and matches byte for byte with the longer. For
- example, 'en' matches 'en', 'en-us' and 'en-gb', but matches
- neither 'fr' nor 'e'.
-
-4.1.3 'keyword'
-
- The 'keyword' attribute syntax is a sequence of characters, length: 1
- to 255, containing only the US-ASCII [ASCII] encoded values for
- lowercase letters ("a" - "z"), digits ("0" - "9"), hyphen ("-"), dot
- ("."), and underscore ("_"). The first character MUST be a lowercase
- letter. Furthermore, keywords MUST be in U.S. English.
-
- This syntax type is used for enumerating semantic identifiers of
- entities in the abstract protocol, i.e., entities identified in this
- document. Keywords are used as attribute names or values of
- attributes. Unlike 'text' and 'name' attribute values, 'keyword'
- values MUST NOT use the Natural Language Override mechanism, since
- they MUST always be US-ASCII and U.S. English.
-
- Keywords are for use in the protocol. A user interface will likely
- provide a mapping between protocol keywords and displayable user-
- friendly words and phrases which are localized to the natural
- language of the user. While the keywords specified in this document
- MAY be displayed to users whose natural language is U.S. English,
- they MAY be mapped to other U.S. English words for U.S. English
- users, since the user interface is outside the scope of this
- document.
-
- In the definition for each attribute of this syntax type, the full
- set of defined keyword values for that attribute are listed.
-
- When a keyword is used to represent an attribute (its name), it MUST
- be unique within the full scope of all IPP objects and attributes.
- When a keyword is used to represent a value of an attribute, it MUST
- be unique just within the scope of that attribute. That is, the same
- keyword MUST NOT be used for two different values within the same
- attribute to mean two different semantic ideas. However, the same
- keyword MAY be used across two or more attributes, representing
- different semantic ideas for each attribute. Section 6.1 describes
- how the protocol can be extended with new keyword values. Examples
- of attribute name keywords:
-
- "job-name"
- "attributes-charset"
-
-
-
-
-
-Hastings, et al. Standards Track [Page 84]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Note: This document uses "type1", "type2", and "type3" prefixes to
- the "keyword" basic syntax to indicate different levels of review for
- extensions (see section 6.1).
-
-4.1.4 'enum'
-
- The 'enum' attribute syntax is an enumerated integer value that is in
- the range from 1 to 2**31 - 1 (MAX). Each value has an associated
- 'keyword' name. In the definition for each attribute of this syntax
- type, the full set of possible values for that attribute are listed.
- This syntax type is used for attributes for which there are enum
- values assigned by other standards, such as SNMP MIBs. A number of
- attribute enum values in this document are also used for
- corresponding attributes in other standards [RFC1759]. This syntax
- type is not used for attributes to which the administrator may assign
- values. Section 6.1 describes how the protocol can be extended with
- new enum values.
-
- Enum values are for use in the protocol. A user interface will
- provide a mapping between protocol enum values and displayable user-
- friendly words and phrases which are localized to the natural
- language of the user. While the enum symbols specified in this
- document MAY be displayed to users whose natural language is U.S.
- English, they MAY be mapped to other U.S. English words for U.S.
- English users, since the user interface is outside the scope of this
- document.
-
- Note: SNMP MIBs use '2' for 'unknown' which corresponds to the IPP
- "out-of-band" value 'unknown'. See the description of the "out-of-
- band" values at the beginning of Section 4.1. Therefore, attributes
- of type 'enum' start at '3'.
-
- Note: This document uses "type1", "type2", and "type3" prefixes to
- the "enum" basic syntax to indicate different levels of review for
- extensions (see section 6.1).
-
-4.1.5 'uri'
-
- The 'uri' attribute syntax is any valid Uniform Resource Identifier
- or URI [RFC2396]. Most often, URIs are simply Uniform Resource
- Locators or URLs. The maximum length of URIs used as values of IPP
- attributes is 1023 octets. Although most other IPP attribute syntax
- types allow for only lower-cased values, this attribute syntax type
- conforms to the case-sensitive and case-insensitive rules specified
- in [RFC2396]. See also [IPP-IIG] for a discussion of case in URIs.
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 85]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-4.1.6 'uriScheme'
-
- The 'uriScheme' attribute syntax is a sequence of characters
- representing a URI scheme according to RFC 2396 [RFC2396]. Though
- RFC 2396 requires that the values be case-insensitive, IPP requires
- all lower case values in IPP attributes to simplify comparing by IPP
- clients and Printer objects.
-
- Standard values for this syntax type are the following keywords:
-
- 'ipp': for IPP schemed URIs (e.g., "ipp:...")
- 'http': for HTTP schemed URIs (e.g., "http:...")
- 'https': for use with HTTPS schemed URIs (e.g., "https:...") (not
- on IETF standards track)
- 'ftp': for FTP schemed URIs (e.g., "ftp:...")
- 'mailto': for SMTP schemed URIs (e.g., "mailto:...")
- 'file': for file schemed URIs (e.g., "file:...")
-
- A Printer object MAY support any URI 'scheme' that has been
- registered with IANA [IANA-MT]. The maximum length of URI 'scheme'
- values used to represent IPP attribute values is 63 octets.
-
-4.1.7 'charset'
-
- The 'charset' attribute syntax is a standard identifier for a
- charset. A charset is a coded character set and encoding scheme.
- Charsets are used for labeling certain document contents and 'text'
- and 'name' attribute values. The syntax and semantics of this
- attribute syntax are specified in RFC 2046 [RFC2046] and contained in
- the IANA character-set Registry [IANA-CS] according to the IANA
- procedures [RFC2278]. Though RFC 2046 requires that the values be
- case-insensitive US-ASCII [ASCII], IPP requires all lower case values
- in IPP attributes to simplify comparing by IPP clients and Printer
- objects. When a character-set in the IANA registry has more than one
- name (alias), the name labeled as "(preferred MIME name)", if
- present, MUST be used.
-
- The maximum length of 'charset' values used to represent IPP
- attribute values is 63 octets.
-
- Some examples are:
-
- 'utf-8': ISO 10646 Universal Multiple-Octet Coded Character Set
- (UCS) represented as the UTF-8 [RFC2279] transfer encoding
- scheme in which US-ASCII is a subset charset.
- 'us-ascii': 7-bit American Standard Code for Information
- Interchange (ASCII), ANSI X3.4-1986 [ASCII]. That standard
-
-
-
-
-Hastings, et al. Standards Track [Page 86]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- defines US-ASCII, but RFC 2045 [RFC2045] eliminates most of the
- control characters from conformant usage in MIME and IPP.
- 'iso-8859-1': 8-bit One-Byte Coded Character Set, Latin Alphabet
- Nr 1 [ISO8859-1]. That standard defines a coded character set
- that is used by Latin languages in the Western Hemisphere and
- Western Europe. US-ASCII is a subset charset.
-
- Some attribute descriptions MAY place additional requirements on
- charset values that may be used, such as REQUIRED values that MUST be
- supported or additional restrictions, such as requiring that the
- charset have US- ASCII as a subset charset.
-
-4.1.8 'naturalLanguage'
-
- The 'naturalLanguage' attribute syntax is a standard identifier for a
- natural language and optionally a country. The values for this
- syntax type are defined by RFC 1766 [RFC1766]. Though RFC 1766
- requires that the values be case-insensitive US-ASCII [ASCII], IPP
- requires all lower case to simplify comparing by IPP clients and
- Printer objects. Examples include:
-
- 'en': for English
- 'en-us': for US English
- 'fr': for French
- 'de': for German
-
- The maximum length of 'naturalLanguage' values used to represent IPP
- attribute values is 63 octets.
-
-4.1.9 'mimeMediaType'
-
- The 'mimeMediaType' attribute syntax is the Internet Media Type
- (sometimes called MIME type) as defined by RFC 2046 [RFC2046] and
- registered according to the procedures of RFC 2048 [RFC2048] for
- identifying a document format. The value MAY include a charset, or
- other, parameter, depending on the specification of the Media Type in
- the IANA Registry [IANA-MT]. Although most other IPP syntax types
- allow for only lower-cased values, this syntax type allows for
- mixed-case values which are case-insensitive.
-
- Examples are:
- 'text/html': An HTML document
- 'text/plain': A plain text document in US-ASCII (RFC 2046
- indicates that in the absence of the charset parameter MUST
- mean US-ASCII rather than simply unspecified) [RFC2046].
- 'text/plain; charset=US-ASCII': A plain text document in US-ASCII
- [52, 56].
-
-
-
-
-Hastings, et al. Standards Track [Page 87]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'text/plain; charset=ISO-8859-1': A plain text document in ISO
- 8859-1 (Latin 1) [ISO8859-1].
- 'text/plain; charset=utf-8': A plain text document in ISO 10646
- represented as UTF-8 [RFC2279]
- 'application/postscript': A PostScript document [RFC2046]
- 'application/vnd.hp-PCL': A PCL document [IANA-MT] (charset
- escape sequence embedded in the document data)
- 'application/pdf': Portable Document Format - see IANA MIME Media
- Type registry
- 'application/octet-stream': Auto-sense - see section 4.1.9.1
-
- The maximum length of a 'mimeMediaType' value to represent IPP
- attribute values is 255 octets.
-
-4.1.9.1 Application/octet-stream -- Auto-Sensing the document format
-
- One special type is 'application/octet-stream'. If the Printer
- object supports this value, the Printer object MUST be capable of
- auto-sensing the format of the document data using an
- implementation-dependent method that examines some number of octets
- of the document data, either as part of the create operation and/or
- at document processing time. During auto-sensing, a Printer may
- determine that the document-data has a format that the Printer
- doesn't recognize. If the Printer determines this problem before
- returning an operation response, it rejects the request and returns
- the 'client-error-document-format-not-supported' status code. If the
- Printer determines this problem after accepting the request and
- returning an operation response with one of the successful status
- codes, the Printer adds the 'unsupported-document-format' value to
- the job's "job-state-reasons" attribute.
-
- If the Printer object's default value attribute "document-format-
- default" is set to 'application/octet-stream', the Printer object not
- only supports auto-sensing of the document format, but will depend on
- the result of applying its auto-sensing when the client does not
- supply the "document-format" attribute. If the client supplies a
- document format value, the Printer MUST rely on the supplied
- attribute, rather than trust its auto-sensing algorithm. To
- summarize:
-
- 1. If the client does not supply a document format value, the
- Printer MUST rely on its default value setting (which may be
- 'application/octet-stream' indicating an auto-sensing
- mechanism).
- 2. If the client supplies a value other than 'application/octet-
- stream', the client is supplying valid information about the
- format of the document data and the Printer object MUST trust
- the client supplied value more than the outcome of applying an
-
-
-
-Hastings, et al. Standards Track [Page 88]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- automatic format detection mechanism. For example, the client
- may be requesting the printing of a PostScript file as a
- 'text/plain' document. The Printer object MUST print a text
- representation of the PostScript commands rather than interpret
- the stream of PostScript commands and print the result.
- 3. If the client supplies a value of 'application/octet-stream',
- the client is indicating that the Printer object MUST use its
- auto-sensing mechanism on the client supplied document data
- whether auto-sensing is the Printer object's default or not.
-
- Note: Since the auto-sensing algorithm is probabilistic, if the
- client requests both auto-sensing ("document-format" set to
- 'application/octet-stream') and true fidelity ("ipp-attribute-
- fidelity" set to 'true'), the Printer object might not be able to
- guarantee exactly what the end user intended (the auto-sensing
- algorithm might mistake one document format for another), but it is
- able to guarantee that its auto-sensing mechanism be used.
-
- When a Printer performs auto-sensing of a document in a submitted
- job, it is RECOMMENDED that the Printer indicate to the user that
- such auto-sensing has occurred and which document-format was auto-
- sensed by printing that information on the job's job-start-sheet.
-
-4.1.10 'octetString'
-
- The 'octetString' attribute syntax is a sequence of octets encoded in
- a maximum of 1023 octets which is indicated in sub-section headers
- using the notation: octetString(MAX). This syntax type is used for
- opaque data.
-
-4.1.11 'boolean'
-
- The 'boolean' attribute syntax has only two values: 'true' and
- 'false'.
-
-4.1.12 'integer'
-
- The 'integer' attribute syntax is an integer value that is in the
- range from -2**31 (MIN) to 2**31 - 1 (MAX). Each individual
- attribute may specify the range constraint explicitly in sub-section
- headers if the range is different from the full range of possible
- integer values. For example: job-priority (integer(1:100)) for the
- "job-priority" attribute. However, the enforcement of that
- additional constraint is up to the IPP objects, not the protocol.
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 89]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-4.1.13 'rangeOfInteger'
-
- The 'rangeOfInteger' attribute syntax is an ordered pair of integers
- that defines an inclusive range of integer values. The first integer
- specifies the lower bound and the second specifies the upper bound.
- If a range constraint is specified in the header description for an
- attribute in this document whose attribute syntax is 'rangeOfInteger'
- (i.e., 'X:Y' indicating X as a minimum value and Y as a maximum
- value), then the constraint applies to both integers.
-
-4.1.14 'dateTime'
-
- The 'dateTime' attribute syntax is a standard, fixed length, 11 octet
- representation of the "DateAndTime" syntax as defined in RFC 2579
- [RFC2579]. RFC 2579 also identifies an 8 octet representation of a
- "DateAndTime" value, but IPP objects MUST use the 11 octet
- representation. A user interface will provide a mapping between
- protocol dateTime values and displayable user-friendly words or
- presentation values and phrases which are localized to the natural
- language and date format of the user, including time zone.
-
-4.1.15 'resolution'
-
- The 'resolution' attribute syntax specifies a two-dimensional
- resolution in the indicated units. It consists of 3 values: a cross
- feed direction resolution (positive integer value), a feed direction
- resolution (positive integer value), and a units value. The
- semantics of these three components are taken from the Printer MIB
- [RFC1759] suggested values. That is, the cross feed direction
- component resolution component is the same as the
- prtMarkerAddressabilityXFeedDir object in the Printer MIB, the feed
- direction component resolution component is the same as the
- prtMarkerAddressabilityFeedDir in the Printer MIB, and the units
- component is the same as the prtMarkerAddressabilityUnit object in
- the Printer MIB (namely, '3' indicates dots per inch and '4'
- indicates dots per centimeter). All three values MUST be present
- even if the first two values are the same. Example: '300', '600',
- '3' indicates a 300 dpi cross-feed direction resolution, a 600 dpi
- feed direction resolution, since a '3' indicates dots per inch (dpi).
-
-4.1.16 '1setOf X'
-
- The '1setOf X' attribute syntax is 1 or more values of attribute
- syntax type X. This syntax type is used for multi-valued attributes.
- The syntax type is called '1setOf' rather than just 'setOf' as a
- reminder that the set of values MUST NOT be empty (i.e., a set of
-
-
-
-
-
-Hastings, et al. Standards Track [Page 90]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- size 0). Sets are normally unordered. However each attribute
- description of this type may specify that the values MUST be in a
- certain order for that attribute.
-
-4.2 Job Template Attributes
-
- Job Template attributes describe job processing behavior. Support
- for Job Template attributes by a Printer object is OPTIONAL (see
- section 12.2.3 for a description of support for OPTIONAL attributes).
- Also, clients OPTIONALLY supply Job Template attributes in create
- requests.
-
- Job Template attributes conform to the following rules. For each Job
- Template attribute called "xxx":
-
- 1. If the Printer object supports "xxx" then it MUST support both
- a "xxx-default" attribute (unless there is a "No" in the table
- below) and a "xxx-supported" attribute. If the Printer object
- doesn't support "xxx", then it MUST support neither an "xxx-
- default" attribute nor an "xxx-supported" attribute, and it
- MUST treat an attribute "xxx" supplied by a client as
- unsupported. An attribute "xxx" may be supported for some
- document formats and not supported for other document formats.
- For example, it is expected that a Printer object would only
- support "orientation-requested" for some document formats (such
- as 'text/plain' or 'text/html') but not others (such as
- 'application/postscript').
-
- 2. "xxx" is OPTIONALLY supplied by the client in a create request.
- If "xxx" is supplied, the client is indicating a desired job
- processing behavior for this Job. When "xxx" is not supplied,
- the client is indicating that the Printer object apply its
- default job processing behavior at job processing time if the
- document content does not contain an embedded instruction
- indicating an xxx-related behavior.
-
- Since an administrator MAY change the default value attribute
- after a Job object has been submitted but before it has been
- processed, the default value used by the Printer object at job
- processing time may be different that the default value in
- effect at job submission time.
-
- 3. The "xxx-supported" attribute is a Printer object attribute
- that describes which job processing behaviors are supported by
- that Printer object. A client can query the Printer object to
- find out what xxx-related behaviors are supported by inspecting
- the returned values of the "xxx-supported" attribute.
-
-
-
-
-Hastings, et al. Standards Track [Page 91]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Note: The "xxx" in each "xxx-supported" attribute name is
- singular, even though an "xxx-supported" attribute usually has
- more than one value, such as "job-sheet-supported", unless the
- "xxx" Job Template attribute is plural, such as "finishings" or
- "sides". In such cases the "xxx-supported" attribute names
- are: "finishings- supported" and "sides-supported".
-
- 4. The "xxx-default" default value attribute describes what will
- be done at job processing time when no other job processing
- information is supplied by the client (either explicitly as an
- IPP attribute in the create request or implicitly as an
- embedded instruction within the document data).
-
- If an application wishes to present an end user with a list of
- supported values from which to choose, the application SHOULD query
- the Printer object for its supported value attributes. The
- application SHOULD also query the default value attributes. If the
- application then limits selectable values to only those value that
- are supported, the application can guarantee that the values supplied
- by the client in the create request all fall within the set of
- supported values at the Printer. When querying the Printer, the
- client MAY enumerate each attribute by name in the Get-Printer-
- Attributes Request, or the client MAY just name the "job-template"
- group in order to get the complete set of supported attributes (both
- supported and default attributes).
-
- The "finishings" attribute is an example of a Job Template attribute.
- It can take on a set of values such as 'staple', 'punch', and/or
- 'cover'. A client can query the Printer object for the "finishings-
- supported" attribute and the "finishings-default" attribute. The
- supported attribute contains a set of supported values. The default
- value attribute contains the finishing value(s) that will be used for
- a new Job if the client does not supply a "finishings" attribute in
- the create request and the document data does not contain any
- corresponding finishing instructions. If the client does supply the
- "finishings" attribute in the create request, the IPP object
- validates the value or values to make sure that they are a subset of
- the supported values identified in the Printer object's "finishings-
- supported" attribute. See section 3.1.7.
-
- The table below summarizes the names and relationships for all Job
- Template attributes. The first column of the table (labeled "Job
- Attribute") shows the name and syntax for each Job Template attribute
- in the Job object. These are the attributes that can optionally be
- supplied by the client in a create request. The last two columns
- (labeled "Printer: Default Value Attribute" and "Printer: Supported
- Values Attribute") show the name and syntax for each Job Template
- attribute in the Printer object (the default value attribute and the
-
-
-
-Hastings, et al. Standards Track [Page 92]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- supported values attribute). A "No" in the table means the Printer
- MUST NOT support the attribute (that is, the attribute is simply not
- applicable). For brevity in the table, the 'text' and 'name' entries
- do not show the maximum length for each attribute.
-
- +===================+======================+======================+
- | Job Attribute |Printer: Default Value| Printer: Supported |
- | | Attribute | Values Attribute |
- +===================+======================+======================+
- | job-priority | job-priority-default |job-priority-supported|
- | (integer 1:100) | (integer 1:100) |(integer 1:100) |
- +-------------------+----------------------+----------------------+
- | job-hold-until | job-hold-until- |job-hold-until- |
- | (type3 keyword | | default | supported |
- | name) | (type3 keyword | |(1setOf ( |
- | | name) |type3 keyword | name))|
- +-------------------+----------------------+----------------------+
- | job-sheets | job-sheets-default |job-sheets-supported |
- | (type3 keyword | | (type3 keyword | |(1setOf ( |
- | name) | name) |type3 keyword | name))|
- +-------------------+----------------------+----------------------+
- |multiple-document- |multiple-document- |multiple-document- |
- | handling | handling-default |handling-supported |
- | (type2 keyword) | (type2 keyword) |(1setOf type2 keyword)|
- +-------------------+----------------------+----------------------+
- | copies | copies-default | copies-supported |
- | (integer (1:MAX)) | (integer (1:MAX)) | (rangeOfInteger |
- | | | (1:MAX)) |
- +-------------------+----------------------+----------------------+
- | finishings | finishings-default | finishings-supported |
- |(1setOf type2 enum)|(1setOf type2 enum) |(1setOf type2 enum) |
- +-------------------+----------------------+----------------------+
- | page-ranges | No | page-ranges- |
- | (1setOf | | supported (boolean) |
- | rangeOfInteger | | |
- | (1:MAX)) | | |
- +-------------------+----------------------+----------------------+
- | sides | sides-default | sides-supported |
- | (type2 keyword) | (type2 keyword) |(1setOf type2 keyword)|
- +-------------------+----------------------+----------------------+
- | number-up | number-up-default | number-up-supported |
- | (integer (1:MAX)) | (integer (1:MAX)) |(1setOf (integer |
- | | | (1:MAX) | |
- | | | rangeOfInteger |
- | | | (1:MAX))) |
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 93]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- +-------------------+----------------------+----------------------+
- | orientation- |orientation-requested-|orientation-requested-|
- | requested | default | supported |
- | (type2 enum) | (type2 enum) | (1setOf type2 enum) |
- +-------------------+----------------------+----------------------+
- | media | media-default | media-supported |
- | (type3 keyword | | (type3 keyword | |(1setOf ( |
- | name) | name) |type3 keyword | name))|
- | | | |
- | | | media-ready |
- | | |(1setOf ( |
- | | |type3 keyword | name))|
- +-------------------+----------------------+----------------------+
- | printer-resolution| printer-resolution- | printer-resolution- |
- | (resolution) | default | supported |
- | | (resolution) |(1setOf resolution) |
- +-------------------+----------------------+----------------------+
- | print-quality | print-quality-default| print-quality- |
- | (type2 enum) | (type2 enum) | supported |
- | | |(1setOf type2 enum) |
- +-------------------+----------------------+----------------------+
-
-4.2.1 job-priority (integer(1:100))
-
- This attribute specifies a priority for scheduling the Job. A higher
- value specifies a higher priority. The value 1 indicates the lowest
- possible priority. The value 100 indicates the highest possible
- priority. Among those jobs that are ready to print, a Printer MUST
- print all jobs with a priority value of n before printing those with
- a priority value of n-1 for all n.
-
- If the Printer object supports this attribute, it MUST always support
- the full range from 1 to 100. No administrative restrictions are
- permitted. This way an end-user can always make full use of the
- entire range with any Printer object. If privileged jobs are
- implemented outside IPP/1.1, they MUST have priorities higher than
- 100, rather than restricting the range available to end-users.
-
- If the client does not supply this attribute and this attribute is
- supported by the Printer object, the Printer object MUST use the
- value of the Printer object's "job-priority-default" at job
- submission time (unlike most Job Template attributes that are used if
- necessary at job processing time).
-
- The syntax for the "job-priority-supported" is also integer(1:100).
- This single integer value indicates the number of priority levels
- supported. The Printer object MUST take the value supplied by the
- client and map it to the closest integer in a sequence of n integers
-
-
-
-Hastings, et al. Standards Track [Page 94]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- values that are evenly distributed over the range from 1 to 100 using
- the formula:
-
- roundToNearestInt((100x+50)/n)
-
- where n is the value of "job-priority-supported" and x ranges from 0
- through n-1.
-
- For example, if n=1 the sequence of values is 50; if n=2, the
- sequence of values is: 25 and 75; if n = 3, the sequence of values
- is: 17, 50 and 83; if n = 10, the sequence of values is: 5, 15, 25,
- 35, 45, 55, 65, 75, 85, and 95; if n = 100, the sequence of values
- is: 1, 2, 3, ... 100.
-
- If the value of the Printer object's "job-priority-supported" is 10
- and the client supplies values in the range 1 to 10, the Printer
- object maps them to 5, in the range 11 to 20, the Printer object maps
- them to 15, etc.
-
-4.2.2 job-hold-until (type3 keyword | name (MAX))
-
- This attribute specifies the named time period during which the Job
- MUST become a candidate for printing.
-
- Standard keyword values for named time periods are:
-
- 'no-hold': immediately, if there are not other reasons to hold the
- job
- 'indefinite': - the job is held indefinitely, until a client
- performs a Release-Job (section 3.3.6)
- 'day-time': during the day
- 'evening': evening
- 'night': night
- 'weekend': weekend
- 'second-shift': second-shift (after close of business)
- 'third-shift': third-shift (after midnight)
-
- An administrator MUST associate allowable print times with a named
- time period (by means outside the scope of this IPP/1.1 document).
- An administrator is encouraged to pick names that suggest the type of
- time period. An administrator MAY define additional values using the
- 'name' or 'keyword' attribute syntax, depending on implementation.
-
- If the value of this attribute specifies a time period that is in the
- future, the Printer SHOULD add the 'job-hold-until-specified' value
- to the job's "job-state-reasons" attribute, MUST move the job to the
-
-
-
-
-
-Hastings, et al. Standards Track [Page 95]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'pending-held' state, and MUST NOT schedule the job for printing
- until the specified time-period arrives.
-
- When the specified time period arrives, the Printer MUST remove the
- 'job-hold-until-specified' value from the job's "job-state-reason"
- attribute, if present. If there are no other job state reasons that
- keep the job in the 'pending-held' state, the Printer MUST consider
- the job as a candidate for processing by moving the job to the
- 'pending' state.
-
- If this job attribute value is the named value 'no-hold', or the
- specified time period has already started, the job MUST be a
- candidate for processing immediately.
-
- If the client does not supply this attribute and this attribute is
- supported by the Printer object, the Printer object MUST use the
- value of the Printer object's "job-hold-until-default" at job
- submission time (unlike most Job Template attributes that are used if
- necessary at job processing time).
-
-4.2.3 job-sheets (type3 keyword | name(MAX))
-
- This attribute determines which job start/end sheet(s), if any, MUST
- be printed with a job.
-
- Standard keyword values are:
-
- 'none': no job sheet is printed
- 'standard': one or more site specific standard job sheets are
- printed, e.g. a single start sheet or both start and end sheet is
- printed
-
- An administrator MAY define additional values using the 'name' or
- 'keyword' attribute syntax, depending on implementation.
-
- The effect of this attribute on jobs with multiple documents MAY be
- affected by the "multiple-document-handling" job attribute (section
- 4.2.4), depending on the job sheet semantics.
-
-4.2.4 multiple-document-handling (type2 keyword)
-
- This attribute is relevant only if a job consists of two or more
- documents. This attribute MUST be supported with at least one value
- if the Printer supports multiple documents per job (see sections
- 3.2.4 and 3.3.1). The attribute controls finishing operations and
- the placement of one or more print-stream pages into impressions and
- onto media sheets. When the value of the "copies" attribute exceeds
- 1, it also controls the order in which the copies that result from
-
-
-
-Hastings, et al. Standards Track [Page 96]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- processing the documents are produced. For the purposes of this
- explanations, if "a" represents an instance of document data, then
- the result of processing the data in document "a" is a sequence of
- media sheets represented by "a(*)".
-
- Standard keyword values are:
-
- 'single-document': If a Job object has multiple documents, say,
- the document data is called a and b, then the result of
- processing all the document data (a and then b) MUST be treated
- as a single sequence of media sheets for finishing operations;
- that is, finishing would be performed on the concatenation of
- the sequences a(*),b(*). The Printer object MUST NOT force the
- data in each document instance to be formatted onto a new
- print-stream page, nor to start a new impression on a new media
- sheet. If more than one copy is made, the ordering of the sets
- of media sheets resulting from processing the document data
- MUST be a(*), b(*), a(*), b(*), start on a new media sheet.
- 'separate-documents-uncollated-copies': If a Job object has
- multiple documents, say, the document data is called a and b,
- then the result of processing the data in each document
- instance MUST be treated as a single sequence of media sheets
- for finishing operations; that is, the sets a(*) and b(*) would
- each be finished separately. The Printer object MUST force each
- copy of the result of processing the data in a single document
- to start on a new media sheet. If more than one copy is made,
- the ordering of the sets of media sheets resulting from
- processing the document data MUST be a(*), a(*), ..., b(*),
- b(*) ... .
- 'separate-documents-collated-copies': If a Job object has multiple
- documents, say, the document data is called a and b, then the
- result of processing the data in each document instance MUST be
- treated as a single sequence of media sheets for finishing
- operations; that is, the sets a(*) and b(*) would each be
- finished separately. The Printer object MUST force each copy of
- the result of processing the data in a single document to start
- on a new media sheet. If more than one copy is made, the
- ordering of the sets of media sheets resulting from processing
- the document data MUST be a(*), b(*), a(*), b(*), ... .
- 'single-document-new-sheet': Same as 'single-document', except
- that the Printer object MUST ensure that the first impression
- of each document instance in the job is placed on a new media
- sheet. This value allows multiple documents to be stapled
- together with a single staple where each document starts on a
- new sheet.
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 97]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- The 'single-document' value is the same as 'separate-documents-
- collated-copies' with respect to ordering of print-stream pages, but
- not media sheet generation, since 'single-document' will put the
- first page of the next document on the back side of a sheet if an odd
- number of pages have been produced so far for the job, while
- 'separate-documents-collated- copies' always forces the next document
- or document copy on to a new sheet. In addition, if the "finishings"
- attribute specifies 'staple', then with 'single-document', documents
- a and b are stapled together as a single document with no regard to
- new sheets, with 'single-document-new-sheet', documents a and b are
- stapled together as a single document, but document b starts on a new
- sheet, but with 'separate-documents-uncollated-copies' and
- 'separate-documents-collated-copies', documents a and b are stapled
- separately.
-
- Note: None of these values provide means to produce uncollated sheets
- within a document, i.e., where multiple copies of sheet n are
- produced before sheet n+1 of the same document.
-
- The relationship of this attribute and the other attributes that
- control document processing is described in section 15.3.
-
-4.2.5 copies (integer(1:MAX))
-
- This attribute specifies the number of copies to be printed.
-
- On many devices the supported number of collated copies will be
- limited by the number of physical output bins on the device, and may
- be different from the number of uncollated copies which can be
- supported.
-
- Note: The effect of this attribute on jobs with multiple documents is
- controlled by the "multiple-document-handling" job attribute (section
- 4.2.4) and the relationship of this attribute and the other
- attributes that control document processing is described in section
- 15.3.
-
-4.2.6 finishings (1setOf type2 enum)
-
- This attribute identifies the finishing operations that the Printer
- uses for each copy of each printed document in the Job. For Jobs with
- multiple documents, the "multiple-document-handling" attribute
- determines what constitutes a "copy" for purposes of finishing.
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 98]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Standard enum values are:
-
- Value Symbolic Name and Description
-
- '3' 'none': Perform no finishing
- '4' 'staple': Bind the document(s) with one or more staples. The
- exact number and placement of the staples is site-
- defined.
- '5' 'punch': This value indicates that holes are required in the
- finished document. The exact number and placement of the
- holes is site-defined The punch specification MAY be
- satisfied (in a site- and implementation-specific manner)
- either by drilling/punching, or by substituting pre-
- drilled media.
- '6' 'cover': This value is specified when it is desired to select
- a non-printed (or pre-printed) cover for the document.
- This does not supplant the specification of a printed
- cover (on cover stock medium) by the document itself.
- '7' 'bind': This value indicates that a binding is to be applied
- to the document; the type and placement of the binding is
- site-defined.
- '8' 'saddle-stitch': Bind the document(s) with one or more
- staples (wire stitches) along the middle fold. The exact
- number and placement of the staples and the middle fold
- is implementation and/or site-defined.
- '9' 'edge-stitch': Bind the document(s) with one or more staples
- (wire stitches) along one edge. The exact number and
- placement of the staples is implementation and/or site-
- defined.
- '10'-'19' reserved for future generic finishing enum values.
-
- The following values are more specific; they indicate a corner or an
- edge as if the document were a portrait document (see below):
-
- '20' 'staple-top-left': Bind the document(s) with one or more
- staples in the top left corner.
- '21' 'staple-bottom-left': Bind the document(s) with one or more
- staples in the bottom left corner.
- '22' 'staple-top-right': Bind the document(s) with one or more
- staples in the top right corner.
- '23' 'staple-bottom-right': Bind the document(s) with one or more
- staples in the bottom right corner.
- '24' 'edge-stitch-left': Bind the document(s) with one or more
- staples (wire stitches) along the left edge. The exact
- number and placement of the staples is implementation
- and/or site-defined.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 99]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- '25' 'edge-stitch-top': Bind the document(s) with one or more
- staples (wire stitches) along the top edge. The exact
- number and placement of the staples is implementation
- and/or site-defined.
- '26' 'edge-stitch-right': Bind the document(s) with one or more
- staples (wire stitches) along the right edge. The exact
- number and placement of the staples is implementation
- and/or site-defined.
- '27' 'edge-stitch-bottom': Bind the document(s) with one or more
- staples (wire stitches) along the bottom edge. The exact
- number and placement of the staples is implementation
- and/or site-defined.
- '28' 'staple-dual-left': Bind the document(s) with two staples
- (wire stitches) along the left edge assuming a portrait
- document (see above).
- '29' 'staple-dual-top': Bind the document(s) with two staples
- (wire stitches) along the top edge assuming a portrait
- document (see above).
- '30' 'staple-dual-right': Bind the document(s) with two staples
- (wire stitches) along the right edge assuming a portrait
- document (see above).
- '31' 'staple-dual-bottom': Bind the document(s) with two staples
- (wire stitches) along the bottom edge assuming a portrait
- document (see above).
-
- The 'staple-xxx' values are specified with respect to the document as
- if the document were a portrait document. If the document is
- actually a landscape or a reverse-landscape document, the client
- supplies the appropriate transformed value. For example, to position
- a staple in the upper left hand corner of a landscape document when
- held for reading, the client supplies the 'staple-bottom-left' value
- (since landscape is defined as a +90 degree rotation of the image
- with respect to the media from portrait, i.e., anti-clockwise). On
- the other hand, to position a staple in the upper left hand corner of
- a reverse-landscape document when held for reading, the client
- supplies the 'staple-top-right' value (since reverse-landscape is
- defined as a -90 degree rotation of the image with respect to the
- media from portrait, i.e., clockwise).
-
- The angle (vertical, horizontal, angled) of each staple with respect
- to the document depends on the implementation which may in turn
- depend on the value of the attribute.
-
- Note: The effect of this attribute on jobs with multiple documents is
- controlled by the "multiple-document-handling" job attribute (section
- 4.2.4) and the relationship of this attribute and the other
- attributes that control document processing is described in section
- 15.3.
-
-
-
-Hastings, et al. Standards Track [Page 100]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- If the client supplies a value of 'none' along with any other
- combination of values, it is the same as if only that other
- combination of values had been supplied (that is the 'none' value has
- no effect).
-
-4.2.7 page-ranges (1setOf rangeOfInteger (1:MAX))
-
- This attribute identifies the range(s) of print-stream pages that the
- Printer object uses for each copy of each document which are to be
- printed. Nothing is printed for any pages identified that do not
- exist in the document(s). Ranges MUST be in ascending order, for
- example: 1-3, 5-7, 15-19 and MUST NOT overlap, so that a non-spooling
- Printer object can process the job in a single pass. If the ranges
- are not ascending or are overlapping, the IPP object MUST reject the
- request and return the 'client-error-bad-request' status code. The
- attribute is associated with print-stream pages not application-
- numbered pages (for example, the page numbers found in the headers
- and or footers for certain word processing applications).
-
- For Jobs with multiple documents, the "multiple-document-handling"
- attribute determines what constitutes a "copy" for purposes of the
- specified page range(s). When "multiple-document-handling" is
- 'single-document', the Printer object MUST apply each supplied page
- range once to the concatenation of the print-stream pages. For
- example, if there are 8 documents of 10 pages each, the page-range
- '41:60' prints the pages in the 5th and 6th documents as a single
- document and none of the pages of the other documents are printed.
- When "multiple-document- handling" is 'separate-documents-
- uncollated-copies' or 'separate-documents-collated-copies', the
- Printer object MUST apply each supplied page range repeatedly to each
- document copy. For the same job, the page-range '1:3, 10:10' would
- print the first 3 pages and the 10th page of each of the 8 documents
- in the Job, as 8 separate documents.
-
- In most cases, the exact pages to be printed will be generated by a
- device driver and this attribute would not be required. However,
- when printing an archived document which has already been formatted,
- the end user may elect to print just a subset of the pages contained
- in the document. In this case, if page-range = n.m is specified, the
- first page to be printed will be page n. All subsequent pages of the
- document will be printed through and including page m.
-
- "page-ranges-supported" is a boolean value indicating whether or not
- the printer is capable of supporting the printing of page ranges.
- This capability may differ from one PDL to another. There is no
- "page-ranges-default" attribute. If the "page-ranges" attribute is
- not supplied by the client, all pages of the document will be
- printed.
-
-
-
-Hastings, et al. Standards Track [Page 101]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Note: The effect of this attribute on jobs with multiple documents is
- controlled by the "multiple-document-handling" job attribute (section
- 4.2.4) and the relationship of this attribute and the other
- attributes that control document processing is described in section
- 15.3.
-
-4.2.8 sides (type2 keyword)
-
- This attribute specifies how print-stream pages are to be imposed
- upon the sides of an instance of a selected medium, i.e., an
- impression.
-
- The standard keyword values are:
-
- 'one-sided': imposes each consecutive print-stream page upon the
- same side of consecutive media sheets.
- 'two-sided-long-edge': imposes each consecutive pair of print-
- stream pages upon front and back sides of consecutive media
- sheets, such that the orientation of each pair of print-stream
- pages on the medium would be correct for the reader as if for
- binding on the long edge. This imposition is sometimes called
- 'duplex' or 'head-to-head'.
- 'two-sided-short-edge': imposes each consecutive pair of print-
- stream pages upon front and back sides of consecutive media
- sheets, such that the orientation of each pair of print-stream
- pages on the medium would be correct for the reader as if for
- binding on the short edge. This imposition is sometimes called
- 'tumble' or 'head-to-toe'.
- 'two-sided-long-edge', 'two-sided-short-edge',
- 'tumble', and 'duplex' all work the same for portrait or
- landscape. However
- 'head-to-toe' is
- 'tumble' in portrait but 'duplex' in landscape. 'head-to-head'
- also switches between 'duplex' and 'tumble' when using portrait
- and landscape modes.
-
- Note: The effect of this attribute on jobs with multiple documents is
- controlled by the "multiple-document-handling" job attribute (section
- 4.2.4) and the relationship of this attribute and the other
- attributes that control document processing is described in section
- 15.3.
-
-4.2.9 number-up (integer(1:MAX))
-
- This attribute specifies the number of print-stream pages to impose
- upon a single side of an instance of a selected medium. For example,
- if the value is:
-
-
-
-
-Hastings, et al. Standards Track [Page 102]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Value Description
-
- '1' the Printer MUST place one print-stream page on a single side
- of an instance of the selected medium (MAY add some sort
- of translation, scaling, or rotation).
- '2' the Printer MUST place two print-stream pages on a single side
- of an instance of the selected medium (MAY add some sort
- of translation, scaling, or rotation).
- '4' the Printer MUST place four print-stream pages on a single
- side of an instance of the selected medium (MAY add some
- sort of translation, scaling, or rotation).
-
- This attribute primarily controls the translation, scaling and
- rotation of print-stream pages.
-
- Note: The effect of this attribute on jobs with multiple documents is
- controlled by the "multiple-document-handling" job attribute (section
- 4.2.4) and the relationship of this attribute and the other
- attributes that control document processing is described in section
- 15.3.
-
-4.2.10 orientation-requested (type2 enum)
-
- This attribute indicates the desired orientation for printed print-
- stream pages; it does not describe the orientation of the client-
- supplied print-stream pages.
-
- For some document formats (such as 'application/postscript'), the
- desired orientation of the print-stream pages is specified within the
- document data. This information is generated by a device driver
- prior to the submission of the print job. Other document formats
- (such as 'text/plain') do not include the notion of desired
- orientation within the document data. In the latter case it is
- possible for the Printer object to bind the desired orientation to
- the document data after it has been submitted. It is expected that a
- Printer object would only support "orientations-requested" for some
- document formats (e.g., 'text/plain' or 'text/html') but not others
- (e.g., 'application/postscript'). This is no different than any
- other Job Template attribute since section 4.2, item 1, points out
- that a Printer object may support or not support any Job Template
- attribute based on the document format supplied by the client.
- However, a special mention is made here since it is very likely that
- a Printer object will support "orientation-requested" for only a
- subset of the supported document formats.
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 103]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Standard enum values are:
-
- Value Symbolic Name and Description
-
- '3' 'portrait': The content will be imaged across the short edge
- of the medium.
- '4' 'landscape': The content will be imaged across the long edge
- of the medium. Landscape is defined to be a rotation of
- the print-stream page to be imaged by +90 degrees with
- respect to the medium (i.e. anti-clockwise) from the
- portrait orientation. Note: The +90 direction was
- chosen because simple finishing on the long edge is the
- same edge whether portrait or landscape
- '5' 'reverse-landscape': The content will be imaged across the
- long edge of the medium. Reverse-landscape is defined to
- be a rotation of the print-stream page to be imaged by -
- 90 degrees with respect to the medium (i.e. clockwise)
- from the portrait orientation. Note: The 'reverse-
- landscape' value was added because some applications
- rotate landscape -90 degrees from portrait, rather than
- +90 degrees.
- '6' 'reverse-portrait': The content will be imaged across the
- short edge of the medium. Reverse-portrait is defined to
- be a rotation of the print-stream page to be imaged by
- 180 degrees with respect to the medium from the portrait
- orientation. Note: The 'reverse-portrait' value was
- added for use with the "finishings" attribute in cases
- where the opposite edge is desired for finishing a
- portrait document on simple finishing devices that have
- only one finishing position. Thus a 'text'/plain'
- portrait document can be stapled "on the right" by a
- simple finishing device as is common use with some middle
- eastern languages such as Hebrew.
-
- Note: The effect of this attribute on jobs with multiple documents is
- controlled by the "multiple-document-handling" job attribute (section
- 4.2.4) and the relationship of this attribute and the other
- attributes that control document processing is described in section
- 15.3.
-
-4.2.11 media (type3 keyword | name(MAX))
-
- This attribute identifies the medium that the Printer uses for all
- impressions of the Job.
-
- The values for "media" include medium-names, medium-sizes, input-
- trays and electronic forms so that one attribute specifies the media.
- If a Printer object supports a medium name as a value of this
-
-
-
-Hastings, et al. Standards Track [Page 104]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- attribute, such a medium name implicitly selects an input-tray that
- contains the specified medium. If a Printer object supports a medium
- size as a value of this attribute, such a medium size implicitly
- selects a medium name that in turn implicitly selects an input-tray
- that contains the medium with the specified size. If a Printer
- object supports an input-tray as the value of this attribute, such an
- input-tray implicitly selects the medium that is in that input-tray
- at the time the job prints. This case includes manual-feed input-
- trays. If a Printer object supports an electronic form as the value
- of this attribute, such an electronic form implicitly selects a
- medium-name that in turn implicitly selects an input-tray that
- contains the medium specified by the electronic form. The electronic
- form also implicitly selects an image that the Printer MUST merge
- with the document data as its prints each page.
-
- Standard keyword values are taken from ISO DPA [ISO10175], the
- Printer MIB [RFC1759], and ASME-Y14.1M [ASME-Y14.1M] and are listed
- in section 14. An administrator MAY define additional values using
- the 'name' or 'keyword' attribute syntax, depending on
- implementation.
-
- There is also an additional Printer attribute named "media-ready"
- which differs from "media-supported" in that legal values only
- include the subset of "media-supported" values that are physically
- loaded and ready for printing with no operator intervention required.
- If an IPP object supports "media-supported", it NEED NOT support
- "media-ready".
-
- The relationship of this attribute and the other attributes that
- control document processing is described in section 15.3.
-
-4.2.12 printer-resolution (resolution)
-
- This attribute identifies the resolution that Printer uses for the
- Job.
-
-4.2.13 print-quality (type2 enum)
-
- This attribute specifies the print quality that the Printer uses for
- the Job.
-
- The standard enum values are:
-
- Value Symbolic Name and Description
-
- '3' 'draft': lowest quality available on the printer
- '4' 'normal': normal or intermediate quality on the printer
- '5' 'high': highest quality available on the printer
-
-
-
-Hastings, et al. Standards Track [Page 105]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-4.3 Job Description Attributes
-
- The attributes in this section form the attribute group called "job-
- description". The following table summarizes these attributes. The
- third column indicates whether the attribute is a REQUIRED attribute
- that MUST be supported by Printer objects. If it is not indicated as
- REQUIRED, then it is OPTIONAL. The maximum size in octets for 'text'
- and 'name' attributes is indicated in parenthesizes.
-
- +----------------------------+----------------------+--------------+
- | Attribute | Syntax | REQUIRED? |
- +----------------------------+----------------------+--------------+
- | job-uri | uri | REQUIRED |
- +----------------------------+----------------------+--------------+
- | job-id | integer(1:MAX) | REQUIRED |
- +----------------------------+----------------------+--------------+
- | job-printer-uri | uri | REQUIRED |
- +----------------------------+----------------------+--------------+
- | job-more-info | uri | |
- +----------------------------+----------------------+--------------+
- | job-name | name (MAX) | REQUIRED |
- +----------------------------+----------------------+--------------+
- | job-originating-user-name | name (MAX) | REQUIRED |
- +----------------------------+----------------------+--------------+
- | job-state | type1 enum | REQUIRED |
- +----------------------------+----------------------+--------------+
- | job-state-reasons | 1setOf type2 keyword | REQUIRED |
- +----------------------------+----------------------+--------------+
- | job-state-message | text (MAX) | |
- +----------------------------+----------------------+--------------+
- | job-detailed-status- | 1setOf text (MAX) | |
- | messages | | |
- +----------------------------+----------------------+--------------+
- | job-document-access-errors | 1setOf text (MAX) | |
- +----------------------------+----------------------+--------------+
- | number-of-documents | integer (0:MAX) | |
- +----------------------------+----------------------+--------------+
- | output-device-assigned | name (127) | |
- +----------------------------+----------------------+--------------+
- | time-at-creation | integer (MIN:MAX) | REQUIRED |
- +----------------------------+----------------------+--------------+
- | time-at-processing | integer (MIN:MAX) | REQUIRED |
- +----------------------------+----------------------+--------------+
- | time-at-completed | integer (MIN:MAX) | REQUIRED |
- +----------------------------+----------------------+--------------+
- | job-printer-up-time | integer (1:MAX) | REQUIRED |
- +----------------------------+----------------------+--------------+
- | date-time-at-creation | dateTime | |
-
-
-
-Hastings, et al. Standards Track [Page 106]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- +----------------------------+----------------------+--------------+
- | date-time-at-processing | dateTime | |
- +----------------------------+----------------------+--------------+
- | date-time-at-completed | dateTime | |
- +----------------------------+----------------------+--------------+
- | number-of-intervening-jobs | integer (0:MAX) | |
- +----------------------------+----------------------+--------------+
- | job-message-from-operator | text (127) | |
- +----------------------------+----------------------+--------------+
- | job-k-octets | integer (0:MAX) | |
- +----------------------------+----------------------+--------------+
- | job-impressions | integer (0:MAX) | |
- +----------------------------+----------------------+--------------+
- | job-media-sheets | integer (0:MAX) | |
- +----------------------------+----------------------+--------------+
- | job-k-octets-processed | integer (0:MAX) | |
- +----------------------------+----------------------+--------------+
- | job-impressions-completed | integer (0:MAX) | |
- +----------------------------+----------------------+--------------+
- | job-media-sheets-completed | integer (0:MAX) | |
- +----------------------------+----------------------+--------------+
- | attributes-charset | charset | REQUIRED |
- +----------------------------+----------------------+--------------+
- | attributes-natural-language| naturalLanguage | REQUIRED |
- +----------------------------+----------------------+--------------+
-
-4.3.1 job-uri (uri)
-
- This REQUIRED attribute contains the URI for the job. The Printer
- object, on receipt of a new job, generates a URI which identifies the
- new Job. The Printer object returns the value of the "job-uri"
- attribute as part of the response to a create request. The precise
- format of a Job URI is implementation dependent. If the Printer
- object supports more than one URI and there is some relationship
- between the newly formed Job URI and the Printer object's URI, the
- Printer object uses the Printer URI supplied by the client in the
- create request. For example, if the create request comes in over a
- secure channel, the new Job URI MUST use the same secure channel.
- This can be guaranteed because the Printer object is responsible for
- generating the Job URI and the Printer object is aware of its
- security configuration and policy as well as the Printer URI used in
- the create request.
-
- For a description of this attribute and its relationship to "job-id"
- and "job-printer-uri" attribute, see the discussion in section 2.4 on
- "Object Identity".
-
-
-
-
-
-Hastings, et al. Standards Track [Page 107]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-4.3.2 job-id (integer(1:MAX))
-
- This REQUIRED attribute contains the ID of the job. The Printer, on
- receipt of a new job, generates an ID which identifies the new Job on
- that Printer. The Printer returns the value of the "job-id"
- attribute as part of the response to a create request. The 0 value
- is not included to allow for compatibility with SNMP index values
- which also cannot be 0.
-
- For a description of this attribute and its relationship to "job-uri"
- and "job-printer-uri" attribute, see the discussion in section 2.4 on
- "Object Identity".
-
-4.3.3 job-printer-uri (uri)
-
- This REQUIRED attribute identifies the Printer object that created
- this Job object. When a Printer object creates a Job object, it
- populates this attribute with the Printer object URI that was used in
- the create request. This attribute permits a client to identify the
- Printer object that created this Job object when only the Job
- object's URI is available to the client. The client queries the
- creating Printer object to determine which languages, charsets,
- operations, are supported for this Job.
-
- For a description of this attribute and its relationship to "job-uri"
- and "job-id" attribute, see the discussion in section 2.4 on "Object
- Identity".
-
-4.3.4 job-more-info (uri)
-
- Similar to "printer-more-info", this attribute contains the URI
- referencing some resource with more information about this Job
- object, perhaps an HTML page containing information about the Job.
-
-4.3.5 job-name (name(MAX))
-
- This REQUIRED attribute is the name of the job. It is a name that is
- more user friendly than the "job-uri" attribute value. It does not
- need to be unique between Jobs. The Job's "job-name" attribute is
- set to the value supplied by the client in the "job-name" operation
- attribute in the create request (see Section 3.2.1.1). If, however,
- the "job-name" operation attribute is not supplied by the client in
- the create request, the Printer object, on creation of the Job, MUST
- generate a name. The printer SHOULD generate the value of the Job's
- "job-name" attribute from the first of the following sources that
- produces a value: 1) the "document-name" operation attribute of the
-
-
-
-
-
-Hastings, et al. Standards Track [Page 108]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- first (or only) document, 2) the "document-URI" attribute of the
- first (or only) document, or 3) any other piece of Job specific
- and/or Document Content information.
-
-4.3.6 job-originating-user-name (name(MAX))
-
- This REQUIRED attribute contains the name of the end user that
- submitted the print job. The Printer object sets this attribute to
- the most authenticated printable name that it can obtain from the
- authentication service over which the IPP operation was received.
- Only if such is not available, does the Printer object use the value
- supplied by the client in the "requesting-user-name" operation
- attribute of the create operation (see Sections 4.4.2, 4.4.3, and 8).
-
- Note: The Printer object needs to keep an internal originating user
- id of some form, typically as a credential of a principal, with the
- Job object. Since such an internal attribute is implementation-
- dependent and not of interest to clients, it is not specified as a
- Job Description attribute. This originating user id is used for
- authorization checks (if any) on all subsequent operations.
-
-4.3.7 job-state (type1 enum)
-
- This REQUIRED attribute identifies the current state of the job.
- Even though the IPP protocol defines seven values for job states
- (plus the out-of-band 'unknown' value - see Section 4.1),
- implementations only need to support those states which are
- appropriate for the particular implementation. In other words, a
- Printer supports only those job states implemented by the output
- device and available to the Printer object implementation.
-
- Standard enum values are:
-
- Values Symbolic Name and Description
-
- '3' 'pending': The job is a candidate to start processing, but is
- not yet processing.
-
- '4' 'pending-held': The job is not a candidate for processing for
- any number of reasons but will return to the 'pending'
- state as soon as the reasons are no longer present. The
- job's "job-state-reason" attribute MUST indicate why the
- job is no longer a candidate for processing.
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 109]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- '5' 'processing': One or more of:
-
- 1. the job is using, or is attempting to use, one or
- more purely software processes that are analyzing,
- creating, or interpreting a PDL, etc.,
- 2. the job is using, or is attempting to use, one or
- more hardware devices that are interpreting a PDL, making
- marks on a medium, and/or performing finishing, such as
- stapling, etc.,
- 3. the Printer object has made the job ready for
- printing, but the output device is not yet printing it,
- either because the job hasn't reached the output device
- or because the job is queued in the output device or some
- other spooler, awaiting the output device to print it.
-
- When the job is in the 'processing' state, the entire job
- state includes the detailed status represented in the
- Printer object's "printer-state", "printer-state-
- reasons", and "printer-state-message" attributes.
-
- Implementations MAY, though they NEED NOT, include
- additional values in the job's "job-state-reasons"
- attribute to indicate the progress of the job, such as
- adding the 'job-printing' value to indicate when the
- output device is actually making marks on paper and/or
- the 'processing-to-stop-point' value to indicate that the
- IPP object is in the process of canceling or aborting the
- job. Most implementations won't bother with this nuance.
-
- '6' 'processing-stopped': The job has stopped while processing
- for any number of reasons and will return to the
- 'processing' state as soon as the reasons are no longer
- present.
-
- The job's "job-state-reason" attribute MAY indicate why
- the job has stopped processing. For example, if the
- output device is stopped, the 'printer-stopped' value MAY
- be included in the job's "job-state-reasons" attribute.
-
- Note: When an output device is stopped, the device
- usually indicates its condition in human readable form
- locally at the device. A client can obtain more complete
- device status remotely by querying the Printer object's
- "printer-state", "printer-state-reasons" and "printer-
- state-message" attributes.
-
- '7' 'canceled': The job has been canceled by a Cancel-Job
- operation and the Printer object has completed canceling
-
-
-
-Hastings, et al. Standards Track [Page 110]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- the job and all job status attributes have reached their
- final values for the job. While the Printer object is
- canceling the job, the job remains in its current state,
- but the job's "job-state-reasons" attribute SHOULD
- contain the 'processing-to-stop-point' value and one of
- the 'canceled-by-user', 'canceled-by-operator', or
- 'canceled-at-device' value. When the job moves to the
- 'canceled' state, the 'processing-to-stop-point' value,
- if present, MUST be removed, but the 'canceled-by-xxx',
- if present, MUST remain.
-
- '8' 'aborted': The job has been aborted by the system, usually
- while the job was in the 'processing' or 'processing-
- stopped' state and the Printer has completed aborting the
- job and all job status attributes have reached their
- final values for the job. While the Printer object is
- aborting the job, the job remains in its current state,
- but the job's "job-state-reasons" attribute SHOULD
- contain the 'processing-to-stop-point' and 'aborted-by-
- system' values. When the job moves to the 'aborted'
- state, the 'processing-to-stop-point' value, if present,
- MUST be removed, but the 'aborted-by-system' value, if
- present, MUST remain.
-
- '9' 'completed': The job has completed successfully or with
- warnings or errors after processing and all of the job
- media sheets have been successfully stacked in the
- appropriate output bin(s) and all job status attributes
- have reached their final values for the job. The job's
- "job-state-reasons" attribute SHOULD contain one of:
- 'completed-successfully', 'completed-with-warnings', or
- 'completed-with-errors' values.
-
- The final value for this attribute MUST be one of: 'completed',
- 'canceled', or 'aborted' before the Printer removes the job
- altogether. The length of time that jobs remain in the 'canceled',
- 'aborted', and 'completed' states depends on implementation. See
- section 4.3.7.2.
-
- The following figure shows the normal job state transitions.
-
- +----> canceled
- /
- +----> pending --------> processing ---------+------> completed
- | ^ ^ \
- --->+ | | +----> aborted
- | v v /
- +----> pending-held processing-stopped ---+
-
-
-
-Hastings, et al. Standards Track [Page 111]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Normally a job progresses from left to right. Other state
- transitions are unlikely, but are not forbidden. Not shown are the
- transitions to the 'canceled' state from the 'pending', 'pending-
- held', and 'processing-stopped' states.
-
- Jobs reach one of the three terminal states: 'completed', 'canceled',
- or 'aborted', after the jobs have completed all activity, including
- stacking output media, after the jobs have completed all activity,
- and all job status attributes have reached their final values for the
- job.
-
-4.3.7.1 Forwarding Servers
-
- As with all other IPP attributes, if the implementation cannot
- determine the correct value for this attribute, it SHOULD respond
- with the out-of-band value 'unknown' (see section 4.1) rather than
- try to guess at some possibly incorrect value and give the end user
- the wrong impression about the state of the Job object. For example,
- if the implementation is just a gateway into some printing system
- from which it can normally get status, but temporarily is unable,
- then the implementation should return the 'unknown' value. However,
- if the implementation is a gateway to a printing system that never
- provides detailed status about the print job, the implementation MAY
- set the IPP Job object's state to 'completed', provided that it also
- sets the 'queued-in-device' value in the job's "job-state-reasons"
- attribute (see section 4.3.8).
-
-4.3.7.2 Partitioning of Job States
-
- This section partitions the 7 job states into phases: Job Not
- Completed, Job Retention, Job History, and Job Removal. This section
- also explains the 'job-restartable' value of the "job-state-reasons"
- Job Description attribute for use with the Restart-Job operation.
-
- Job Not Completed: When a job is in the 'pending', 'pending-held',
- 'processing', or 'processing-stopped' states, the job is not
- completed.
-
- Job Retention: When a job enters one of the three terminal job
- states: 'completed', 'canceled', or 'aborted', the IPP Printer
- object MAY "retain" the job in a restartable condition for an
- implementation-defined time period. This time period MAY be zero
- seconds and MAY depend on the terminal job state. This phase is
- called Job Retention. While in the Job Retention phase, the job's
- document data is retained and a client may restart the job using the
- Restart-Job operation. If the IPP object supports the Restart-Job
-
-
-
-
-
-Hastings, et al. Standards Track [Page 112]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- operation, then it SHOULD indicate that the job is restartable by
- adding the 'job-restartable' value to the job's "job-state-reasons"
- attribute (see Section 4.3.8) during the Job Retention phase.
-
- Job History: After the Job Retention phase expires for a job, the
- Printer object deletes the document data for the job and the job
- becomes part of the Job History. The Printer object MAY also delete
- any number of the job attributes. Since the job is no longer
- restartable, the Printer object MUST remove the 'job-restartable'
- value from the job's "job-state-reasons" attribute, if present.
-
- Job Removal: After the job has remained in the Job History for an
- implementation-defined time, such as when the number of jobs exceeds
- a fixed number or after a fixed time period (which MAY be zero
- seconds), the IPP Printer removes the job from the system.
-
- Using the Get-Jobs operation and supplying the 'not-completed' value
- for the "which-jobs" operation attribute, a client is requesting jobs
- in the Job Not Completed phase. Using the Get-Jobs operation and
- supplying the 'completed' value for the "which-jobs" operation
- attribute, a client is requesting jobs in the Job Retention and Job
- History phases. Using the Get-Job-Attributes operation, a client is
- requesting a job in any phase except Job Removal. After Job Removal,
- the Get-Job-Attributes and Get-Jobs operations no longer are capable
- of returning any information about a job.
-
-4.3.8 job-state-reasons (1setOf type2 keyword)
-
- This REQUIRED attribute provides additional information about the
- job's current state, i.e., information that augments the value of the
- job's "job-state" attribute.
-
- These values MAY be used with any job state or states for which the
- reason makes sense. Some of these value definitions indicate
- conformance requirements; the rest are OPTIONAL. Furthermore, when
- implemented, the Printer MUST return these values when the reason
- applies and MUST NOT return them when the reason no longer applies
- whether the value of the Job's "job-state" attribute changed or not.
- When the Job does not have any reasons for being in its current
- state, the value of the Job's "job-state-reasons" attribute MUST be
- 'none'.
-
- Note: While values cannot be added to the 'job-state' attribute
- without impacting deployed clients that take actions upon receiving
- "job-state" values, it is the intent that additional "job-state-
- reasons" values can be defined and registered without impacting such
- deployed clients. In other words, the "job-state-reasons" attribute
- is intended to be extensible.
-
-
-
-Hastings, et al. Standards Track [Page 113]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- The following standard keyword values are defined. For ease of
- understanding, the values are presented in the order in which the
- reasons are likely to occur (if implemented), starting with the
- 'job-incoming' value:
-
- 'none': There are no reasons for the job's current state. This
- state reason is semantically equivalent to "job-state-reasons"
- without any value and MUST be used when there is no other
- value, since the 1setOf attribute syntax requires at least one
- value.
- 'job-incoming': Either (1) the Printer has accepted the Create-
- Job operation and is expecting additional Send-Document and/or
- Send-URI operations, or (2) the Printer is retrieving/accepting
- document data as a result of a Print-Job, Print-URI, Send-
- Document or Send-URI operation.
- 'job-data-insufficient': The Create-Job operation has been
- accepted by the Printer, but the Printer is expecting
- additional document data before it can move the job into the
- 'processing' state. If a Printer starts processing before it
- has received all data, the Printer removes the 'job-data-
- insufficient' reason, but the 'job-incoming' remains. If a
- Printer starts processing after it has received all data, the
- Printer removes the 'job-data-insufficient' reason and the
- 'job-incoming' at the same time.
- 'document-access-error': After accepting a Print-URI or Send-URI
- request, the Printer could not access one or more documents
- passed by reference. This reason is intended to cover any file
- access problem, including file does not exist and access denied
- because of an access control problem. The Printer MAY also
- indicate the document access error using the "job-document-
- access-errors" Job Description attribute (see section 4.3.11).
- Whether the Printer aborts the job and moves the job to the
- 'aborted' job state or prints all documents that are accessible
- and moves the job to the 'completed' job state and adds the
- 'completed-with-errors' value in the job's "job-state-reasons"
- attribute depends on implementation and/or site policy. This
- value SHOULD be supported if the Print-URI or Send-URI
- operations are supported.
- 'submission-interrupted': The job was not completely submitted
- for some unforeseen reason, such as: (1) the Printer has
- crashed before the job was closed by the client, (2) the
- Printer or the document transfer method has crashed in some
- non-recoverable way before the document data was entirely
- transferred to the Printer, (3) the client crashed or failed to
- close the job before the time-out period. See section 4.4.31.
- 'job-outgoing': The Printer is transmitting the job to the output
- device.
-
-
-
-
-Hastings, et al. Standards Track [Page 114]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'job-hold-until-specified': The value of the job's "job-hold-
- until" attribute was specified with a time period that is still
- in the future. The job MUST NOT be a candidate for processing
- until this reason is removed and there are no other reasons to
- hold the job. This value SHOULD be supported if the "job-
- hold-until" Job Template attribute is supported.
- 'resources-are-not-ready': At least one of the resources needed
- by the job, such as media, fonts, resource objects, etc., is
- not ready on any of the physical printer's for which the job is
- a candidate. This condition MAY be detected when the job is
- accepted, or subsequently while the job is pending or
- processing, depending on implementation. The job may remain in
- its current state or be moved to the 'pending-held' state,
- depending on implementation and/or job scheduling policy.
- 'printer-stopped-partly': The value of the Printer's "printer-
- state-reasons" attribute contains the value 'stopped-partly'.
- 'printer-stopped': The value of the Printer's "printer-state"
- attribute is 'stopped'.
- 'job-interpreting': Job is in the 'processing' state, but more
- specifically, the Printer is interpreting the document data.
- 'job-queued': Job is in the 'processing' state, but more
- specifically, the Printer has queued the document data.
- 'job-transforming': Job is in the 'processing' state, but more
- specifically, the Printer is interpreting document data and
- producing another electronic representation.
- 'job-queued-for-marker': Job is in any of the 'pending-held',
- 'pending', or 'processing' states, but more specifically, the
- Printer has completed enough processing of the document to be
- able to start marking and the job is waiting for the marker.
- Systems that require human intervention to release jobs using
- the Release-Job operation, put the job into the 'pending-held'
- job state. Systems that automatically select a job to use the
- marker put the job into the 'pending' job state or keep the
- job in the 'processing' job state while waiting for the marker,
- depending on implementation. All implementations put the job
- into (or back into) the 'processing' state when marking does
- begin.
- 'job-printing': The output device is marking media. This value is
- useful for Printers which spend a great deal of time processing
- (1) when no marking is happening and then want to show that
- marking is now happening or (2) when the job is in the process
- of being canceled or aborted while the job remains in the
- 'processing' state, but the marking has not yet stopped so that
- impression or sheet counts are still increasing for the job.
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 115]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'job-canceled-by-user': The job was canceled by the owner of the
- job using the Cancel-Job request, i.e., by a user whose
- authenticated identity is the same as the value of the
- originating user that created the Job object, or by some other
- authorized end-user, such as a member of the job owner's
- security group. This value SHOULD be supported.
- 'job-canceled-by-operator': The job was canceled by the operator
- using the Cancel-Job request, i.e., by a user who has been
- authenticated as having operator privileges (whether local or
- remote). If the security policy is to allow anyone to cancel
- anyone's job, then this value may be used when the job is
- canceled by other than the owner of the job. For such a
- security policy, in effect, everyone is an operator as far as
- canceling jobs with IPP is concerned. This value SHOULD be
- supported if the implementation permits canceling by other than
- the owner of the job.
- 'job-canceled-at-device': The job was canceled by an unidentified
- local user, i.e., a user at a console at the device. This
- value SHOULD be supported if the implementation supports
- canceling jobs at the console.
- 'aborted-by-system': The job (1) is in the process of being
- aborted, (2) has been aborted by the system and placed in the
- 'aborted' state, or (3) has been aborted by the system and
- placed in the 'pending-held' state, so that a user or operator
- can manually try the job again. This value SHOULD be
- supported.
- 'unsupported-compression': The job was aborted by the system
- because the Printer determined while attempting to decompress
- the document-data's that the compression is actually not among
- those supported by the Printer. This value MUST be supported,
- since "compressions is a REQUIRED operation attribute.
- 'compression-error': The job was aborted by the system because the
- Printer encountered an error in the document-data while
- decompressing it. If the Printer posts this reason, the
- document-data has already passed any tests that would have led
- to the 'unsupported-compression' job-state-reason.
- 'unsupported-document-format': The job was aborted by the system
- because the document-data's document-format is not among those
- supported by the Printer. If the client specifies the
- document-format as 'application/octet-stream', the printer MAY
- abort the job and post this reason even though the format is a
- member of the "document-format-supported" printer attribute,
- but not among the auto-sensed document-formats. This value
- MUST be supported, since "document-format" is a REQUIRED
- operation attribute.
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 116]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'document-format-error': The job was aborted by the system because
- the Printer encountered an error in the document-data while
- processing it. If the Printer posts this reason, the
- document-data has already passed any tests that would have led
- to the 'unsupported-document-format' job-state-reason.
- 'processing-to-stop-point': The requester has issued a Cancel-Job
- operation or the Printer object has aborted the job, but is
- still performing some actions on the job until a specified stop
- point occurs or job termination/cleanup is completed.
-
- If the implementation requires some measurable time to cancel
- the job in the 'processing' or 'processing-stopped' job states,
- the IPP object MUST use this value to indicate that the Printer
- object is still performing some actions on the job while the
- job remains in the 'processing' or 'processing-stopped' state.
- After all the job's job description attributes have stopped
- incrementing, the Printer object moves the job from the
- 'processing' state to the 'canceled' or
- 'aborted' job states.
-
- 'service-off-line': The Printer is off-line and accepting no
- jobs. All 'pending' jobs are put into the 'pending-held'
- state. This situation could be true if the service's or
- document transform's input is impaired or broken.
- 'job-completed-successfully': The job completed successfully.
- This value SHOULD be supported.
- 'job-completed-with-warnings': The job completed with warnings.
- This value SHOULD be supported if the implementation detects
- warnings.
- 'job-completed-with-errors': The job completed with errors (and
- possibly warnings too). This value SHOULD be supported if the
- implementation detects errors.
- 'job-restartable' - This job is retained (see section 4.3.7.2) and
- is currently able to be restarted using the Restart-Job
- operation (see section 3.3.7). If 'job-restartable' is a value
- of the job's 'job-state-reasons' attribute, then the IPP object
- MUST accept a Restart-Job operation for that job. This value
- SHOULD be supported if the Restart-Job operation is supported.
- 'queued-in-device': The job has been forwarded to a device or
- print system that is unable to send back status. The Printer
- sets the job's "job-state " attribute to 'completed' and adds
- the 'queued-in-device' value to the job's "job-state-reasons"
- attribute to indicate that the Printer has no additional
- information about the job and never will have any better
- information. See section 4.3.7.1.
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 117]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-4.3.9 job-state-message (text(MAX))
-
- This attribute specifies information about the "job-state" and "job-
- state-reasons" attributes in human readable text. If the Printer
- object supports this attribute, the Printer object MUST be able to
- generate this message in any of the natural languages identified by
- the Printer's "generated-natural-language-supported" attribute (see
- the "attributes-natural-language" operation attribute specified in
- Section 3.1.4.1).
-
- The value SHOULD NOT contain additional information not contained in
- the values of the "job-state" and "job-states-reasons" attributes,
- such as interpreter error information. Otherwise, application
- programs might attempt to parse the (localized text). For such
- additional information such as interpreter errors for application
- program consumption or specific document access errors, new
- attributes with keyword values, needs to be developed and registered.
-
-4.3.10 job-detailed-status-messages (1setOf text(MAX))
-
- This attribute specifies additional detailed and technical
- information about the job. The Printer NEED NOT localize the
- message(s), since they are intended for use by the system
- administrator or other experienced technical persons. Localization
- might obscure the technical meaning of such messages. Clients MUST
- NOT attempt to parse the value of this attribute. See "job-
- document-access-errors" (section 4.3.11) for additional errors that a
- program can process.
-
-4.3.11 job-document-access-errors (1setOf text(MAX))
-
- This attribute provides additional information about each document
- access error for this job encountered by the Printer after it
- returned a response to the Print-URI or Send-URI operation and
- subsequently attempted to access document(s) supplied in the Print-
- URI or Send-URI operation. For errors in the protocol that is
- identified by the URI scheme in the "document-uri" operation
- attribute, such as 'http:' or 'ftp:', the error code is returned in
- parentheses, followed by the URI. For example:
-
- (404) http://ftp.pwg.org/pub/pwg/ipp/new_MOD/ipp-model-v11.pdf
-
- Most Internet protocols use decimal error codes (unlike IPP), so the
- ASCII error code representation is in decimal.
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 118]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-4.3.12 number-of-documents (integer(0:MAX))
-
- This attribute indicates the number of documents in the job, i.e.,
- the number of Send-Document, Send-URI, Print-Job, or Print-URI
- operations that the Printer has accepted for this job, regardless of
- whether the document data has reached the Printer object or not.
-
- Implementations supporting the OPTIONAL Create-Job/Send-
- Document/Send-URI operations SHOULD support this attribute so that
- clients can query the number of documents in each job.
-
-4.3.13 output-device-assigned (name(127))
-
- This attribute identifies the output device to which the Printer
- object has assigned this job. If an output device implements an
- embedded Printer object, the Printer object NEED NOT set this
- attribute. If a print server implements a Printer object, the value
- MAY be empty (zero- length string) or not returned until the Printer
- object assigns an output device to the job. This attribute is
- particularly useful when a single Printer object supports multiple
- devices (so called "fan-out" - see section 2.1).
-
-4.3.14 Event Time Job Description Attributes
-
- This section defines the Job Description attributes that indicate the
- time at which certain events occur for a job. If the job event has
- not yet occurred, then the IPP object MUST return the 'no-value'
- out-of-band value (see the beginning of Section 4.1). The "time-at-
- xxx(integer)" attributes represent time as an 'integer' representing
- the number of seconds since the device was powered up (informally
- called "time ticks"). The "date-time-at-xxx(dateTime)" attributes
- represent time as 'dateTime' representing date and time (including an
- offset from UTC).
-
- In order to populate these attributes, the Printer object copies the
- value(s) of the following Printer Description attributes at the time
- the event occurs:
-
- 1. the value in the Printer's "printer-up-time" attribute for the
- "time-at-xxx(integer)" attributes
-
- 2. the value in the Printer's "printer-current-time" attribute for
- the "date-time-at-xxx(dateTime)" attributes.
-
- If the Printer resets its "printer-up-time" attribute to 1 on power-
- up (see section 4.4.29) and has persistent jobs, then it MUST change
- all of jobs' "time-at-xxx(integer)" (time tick) job attributes whose
- events have occurred either to:
-
-
-
-Hastings, et al. Standards Track [Page 119]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 1. 0 to indicate that the event happened before the most recent
- power up OR
-
- 2. the negative of the number of seconds before the most recent
- power-up that the event took place, though the negative number
- NEED NOT reflect the exact number of seconds.
-
- If a client queries a "time-at-xxx(integer)" time tick Job attribute
- and finds the value to be 0 or negative, the client MUST assume that
- the event occurred in some life other than the Printer's current
- life.
-
- Note: A Printer does not change the values of any "date-time-at-
- xxx(dateTime)" job attributes on power-up.
-
-4.3.14.1 time-at-creation (integer(MIN:MAX))
-
- This REQUIRED attribute indicates the time at which the Job object
- was created.
-
-4.3.14.2 time-at-processing (integer(MIN:MAX))
-
- This REQUIRED attribute indicates the time at which the Job object
- first began processing after the create operation or the most recent
- Restart-Job operation. The out-of-band 'no-value' value is returned
- if the job has not yet been in the 'processing' state (see the
- beginning of Section 4.1).
-
-4.3.14.3 time-at-completed (integer(MIN:MAX))
-
- This REQUIRED attribute indicates the time at which the Job object
- completed (or was canceled or aborted). The out-of-band 'no-value'
- value is returned if the job has not yet completed, been canceled, or
- aborted (see the beginning of Section 4.1).
-
-4.3.14.4 job-printer-up-time (integer(1:MAX))
-
- This REQUIRED Job Description attribute indicates the amount of time
- (in seconds) that the Printer implementation has been up and running.
- This attribute is an alias for the "printer-up-time" Printer
- Description attribute (see Section 4.4.29).
-
- A client MAY request this attribute in a Get-Job-Attributes or Get-
- Jobs request and use the value returned in combination with other
- requested Event Time Job Description Attributes in order to display
- time attributes to a user. The difference between this attribute and
- the 'integer' value of a "time-at-xxx" attribute is the number of
-
-
-
-
-Hastings, et al. Standards Track [Page 120]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- seconds ago that the "time-at-xxx" event occurred. A client can
- compute the wall-clock time at which the "time-at-xxx" event occurred
- by subtracting this difference from the client's wall-clock time.
-
-4.3.14.5 date-time-at-creation (dateTime)
-
- This attribute indicates the date and time at which the Job object
- was created.
-
-4.3.14.6 date-time-at-processing (dateTime)
-
- This attribute indicates the date and time at which the Job object
- first began processing after the create operation or the most recent
- Restart-Job operation.
-
-4.3.14.7 date-time-at-completed (dateTime)
-
- This attribute indicates the date and time at which the Job object
- completed (or was canceled or aborted).
-
-4.3.15 number-of-intervening-jobs (integer(0:MAX))
-
- This attribute indicates the number of jobs that are "ahead" of this
- job in the relative chronological order of expected time to complete
- (i.e., the current scheduled order). For efficiency, it is only
- necessary to calculate this value when an operation is performed that
- requests this attribute.
-
-4.3.16 job-message-from-operator (text(127))
-
- This attribute provides a message from an operator, system
- administrator or "intelligent" process to indicate to the end user
- the reasons for modification or other management action taken on a
- job.
-
-4.3.17 Job Size Attributes
-
- This sub-section defines job attributes that describe the size of the
- job. These attributes are not intended to be counters; they are
- intended to be useful routing and scheduling information if known.
- For these attributes, the Printer object may try to compute the value
- if it is not supplied in the create request. Even if the client does
- supply a value for these three attributes in the create request, the
- Printer object MAY choose to change the value if the Printer object
- is able to compute a value which is more accurate than the client
- supplied value. The Printer object may be able to determine the
- correct value for these attributes either right at job submission
- time or at any later point in time.
-
-
-
-Hastings, et al. Standards Track [Page 121]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-4.3.17.1 job-k-octets (integer(0:MAX))
-
- This attribute specifies the total size of the document(s) in K
- octets, i.e., in units of 1024 octets requested to be processed in
- the job. The value MUST be rounded up, so that a job between 1 and
- 1024 octets MUST be indicated as being 1, 1025 to 2048 MUST be 2,
- etc.
-
- This value MUST NOT include the multiplicative factors contributed by
- the number of copies specified by the "copies" attribute, independent
- of whether the device can process multiple copies without making
- multiple passes over the job or document data and independent of
- whether the output is collated or not. Thus the value is independent
- of the implementation and indicates the size of the document(s)
- measured in K octets independent of the number of copies.
-
- This value MUST also not include the multiplicative factor due to a
- copies instruction embedded in the document data. If the document
- data actually includes replications of the document data, this value
- will include such replication. In other words, this value is always
- the size of the source document data, rather than a measure of the
- hardcopy output to be produced.
-
-4.3.17.2 job-impressions (integer(0:MAX))
-
- This attribute specifies the total size in number of impressions of
- the document(s) being submitted (see the definition of impression in
- section 12.2.5).
-
- As with "job-k-octets", this value MUST NOT include the
- multiplicative factors contributed by the number of copies specified
- by the "copies" attribute, independent of whether the device can
- process multiple copies without making multiple passes over the job
- or document data and independent of whether the output is collated or
- not. Thus the value is independent of the implementation and
- reflects the size of the document(s) measured in impressions
- independent of the number of copies.
-
- As with "job-k-octets", this value MUST also not include the
- multiplicative factor due to a copies instruction embedded in the
- document data. If the document data actually includes replications
- of the document data, this value will include such replication. In
- other words, this value is always the number of impressions in the
- source document data, rather than a measure of the number of
- impressions to be produced by the job.
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 122]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-4.3.17.3 job-media-sheets (integer(0:MAX))
-
- This attribute specifies the total number of media sheets to be
- produced for this job.
-
- Unlike the "job-k-octets" and the "job-impressions" attributes, this
- value MUST include the multiplicative factors contributed by the
- number of copies specified by the "copies" attribute and a 'number of
- copies' instruction embedded in the document data, if any. This
- difference allows the system administrator to control the lower and
- upper bounds of both (1) the size of the document(s) with "job-k-
- octets-supported" and "job-impressions-supported" and (2) the size of
- the job with "job-media-sheets-supported".
-
-4.3.18 Job Progress Attributes
-
- This sub-section defines job attributes that describe the progress of
- the job. These attributes are intended to be counters. That is, the
- value for a job that has not started processing MUST be 0. When the
- job's "job-state" is 'processing' or 'processing-stopped', this value
- is intended to contain the amount of the job that has been processed
- to the time at which the attributes are requested. When the job
- enters the 'completed', 'canceled', or 'aborted' states, these values
- are the final values for the job.
-
-4.3.18.1 job-k-octets-processed (integer(0:MAX))
-
- This attribute specifies the total number of octets processed in K
- octets, i.e., in units of 1024 octets so far. The value MUST be
- rounded up, so that a job between 1 and 1024 octets inclusive MUST be
- indicated as being 1, 1025 to 2048 inclusive MUST be 2, etc.
-
- For implementations where multiple copies are produced by the
- interpreter with only a single pass over the data, the final value
- MUST be equal to the value of the "job-k-octets" attribute. For
- implementations where multiple copies are produced by the interpreter
- by processing the data for each copy, the final value MUST be a
- multiple of the value of the "job-k-octets" attribute.
-
-4.3.18.2 job-impressions-completed (integer(0:MAX))
-
- This job attribute specifies the number of impressions completed for
- the job so far. For printing devices, the impressions completed
- includes interpreting, marking, and stacking the output.
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 123]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-4.3.18.3 job-media-sheets-completed (integer(0:MAX))
-
- This job attribute specifies the media-sheets completed marking and
- stacking for the entire job so far whether those sheets have been
- processed on one side or on both.
-
-4.3.19 attributes-charset (charset)
-
- This REQUIRED attribute is populated using the value in the client
- supplied "attributes-charset" attribute in the create request. It
- identifies the charset (coded character set and encoding method) used
- by any Job attributes with attribute syntax 'text' and 'name' that
- were supplied by the client in the create request. See Section 3.1.4
- for a complete description of the "attributes-charset" operation
- attribute.
-
- This attribute does not indicate the charset in which the 'text' and
- 'name' values are stored internally in the Job object. The internal
- charset is implementation-defined. The IPP object MUST convert from
- whatever the internal charset is to that being requested in an
- operation as specified in Section 3.1.4.
-
-4.3.20 attributes-natural-language (naturalLanguage)
-
- This REQUIRED attribute is populated using the value in the client
- supplied "attributes-natural-language" attribute in the create
- request. It identifies the natural language used for any Job
- attributes with attribute syntax 'text' and 'name' that were supplied
- by the client in the create request. See Section 3.1.4 for a
- complete description of the "attributes-natural-language" operation
- attribute. See Sections 4.1.1.2 and 4.1.2.2 for how a Natural
- Language Override may be supplied explicitly for each 'text' and
- 'name' attribute value that differs from the value identified by the
- "attributes-natural-language" attribute.
-
-4.4 Printer Description Attributes
-
- These attributes form the attribute group called "printer-
- description". The following table summarizes these attributes, their
- syntax, and whether or not they are REQUIRED for a Printer object to
- support. If they are not indicated as REQUIRED, they are OPTIONAL.
- The maximum size in octets for 'text' and 'name' attributes is
- indicated in parenthesizes.
-
- Note: How these attributes are set by an Administrator is outside the
- scope of this IPP/1.1 document.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 124]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- +----------------------------+---------------------------+-----------+
- | Attribute | Syntax | REQUIRED? |
- +----------------------------+---------------------------+-----------+
- | printer-uri-supported | 1setOf uri | REQUIRED |
- +----------------------------+---------------------------+-----------+
- | uri-security-supported | 1setOf type2 keyword | REQUIRED |
- +----------------------------+---------------------------+-----------+
- | uri-authentication- | 1setOf type2 keyword | REQUIRED |
- | supported | | |
- +----------------------------+---------------------------+-----------+
- | printer-name | name (127) | REQUIRED |
- +----------------------------+---------------------------+-----------+
- | printer-location | text (127) | |
- +----------------------------+---------------------------+-----------+
- | printer-info | text (127) | |
- +----------------------------+---------------------------+-----------+
- | printer-more-info | uri | |
- +----------------------------+---------------------------+-----------+
- | printer-driver-installer | uri | |
- +----------------------------+---------------------------+-----------+
- | printer-make-and-model | text (127) | |
- +----------------------------+---------------------------+-----------+
- | printer-more-info- | uri | |
- | manufacturer | | |
- +----------------------------+---------------------------+-----------+
- | printer-state | type1 enum | REQUIRED |
- +----------------------------+---------------------------+-----------+
- | printer-state-reasons | 1setOf type2 keyword | REQUIRED |
- +----------------------------+---------------------------+-----------+
- | printer-state-message | text (MAX) | |
- +----------------------------+---------------------------+-----------+
- | ipp-versions-supported | 1setOf type2 keyword | REQUIRED |
- +----------------------------+---------------------------+-----------+
- | operations-supported | 1setOf type2 enum | REQUIRED |
- +----------------------------+---------------------------+-----------+
- | multiple-document-jobs- | boolean | |
- | supported | | |
- +----------------------------+---------------------------+-----------+
- | charset-configured | charset | REQUIRED |
- +----------------------------+---------------------------+-----------+
- | charset-supported | 1setOf charset | REQUIRED |
- +----------------------------+---------------------------+-----------+
- | natural-language-configured| naturalLanguage | REQUIRED |
- +----------------------------+---------------------------+-----------+
- | generated-natural-language-| 1setOf naturalLanguage | REQUIRED |
- | supported | | |
- +----------------------------+---------------------------+-----------+
- | document-format-default | mimeMediaType | REQUIRED |
-
-
-
-Hastings, et al. Standards Track [Page 125]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- +----------------------------+---------------------------+-----------+
- | document-format-supported | 1setOf mimeMediaType | REQUIRED |
- +----------------------------+---------------------------+-----------+
- | printer-is-accepting-jobs | boolean | REQUIRED |
- +----------------------------+---------------------------+-----------+
- | queued-job-count | integer (0:MAX) | REQUIRED |
- +----------------------------+---------------------------+-----------+
- | printer-message-from- | text (127) | |
- | operator | | |
- +----------------------------+---------------------------+-----------+
- | color-supported | boolean | |
- +----------------------------+---------------------------+-----------+
- | reference-uri-schemes- | 1setOf uriScheme | |
- | supported | | |
- +----------------------------+---------------------------+-----------+
- | pdl-override-supported | type2 keyword | REQUIRED |
- +----------------------------+---------------------------+-----------+
- | printer-up-time | integer (1:MAX) | REQUIRED |
- +----------------------------+---------------------------+-----------+
- | printer-current-time | dateTime | |
- +----------------------------+---------------------------+-----------+
- | multiple-operation-time-out| integer (1:MAX) | |
- +----------------------------+---------------------------+-----------+
- | compression-supported | 1setOf type3 keyword | REQUIRED |
- +----------------------------+---------------------------+-----------+
- | job-k-octets-supported | rangeOfInteger (0:MAX) | |
- +----------------------------+---------------------------+-----------+
- | job-impressions-supported | rangeOfInteger (0:MAX) | |
- +----------------------------+---------------------------+-----------+
- | job-media-sheets-supported | rangeOfInteger (0:MAX) | |
- +----------------------------+---------------------------+-----------+
- | pages-per-minute | integer(0:MAX) | |
- +----------------------------+---------------------------+-----------+
- | pages-per-minute-color | integer(0:MAX) | |
- +----------------------------+---------------------------+-----------+
-
-4.4.1 printer-uri-supported (1setOf uri)
-
- This REQUIRED Printer attribute contains at least one URI for the
- Printer object. It OPTIONALLY contains more than one URI for the
- Printer object. An administrator determines a Printer object's
- URI(s) and configures this attribute to contain those URIs by some
- means outside the scope of this IPP/1.1 document. The precise format
- of this URI is implementation dependent and depends on the protocol.
- See the next two sections for a description of the "uri-security-
- supported" and "uri-authentication-supported" attributes, both of
-
-
-
-
-
-Hastings, et al. Standards Track [Page 126]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- which are the REQUIRED companion attributes to this "printer-uri-
- supported" attribute. See section 2.4 on Printer object identity and
- section 8.2 on security and URIs for more information.
-
-4.4.2 uri-authentication-supported (1setOf type2 keyword)
-
- This REQUIRED Printer attribute MUST have the same cardinality
- (contain the same number of values) as the "printer-uri-supported"
- attribute. This attribute identifies the Client Authentication
- mechanism associated with each URI listed in the "printer-uri-
- supported" attribute. The Printer object uses the specified mechanism
- to identify the authenticated user (see section 8.3). The "i th"
- value in "uri-authentication-supported" corresponds to the "i th"
- value in "printer-uri-supported" and it describes the authentication
- mechanisms used by the Printer when accessed via that URI. See
- [RFC2910] for more details on Client Authentication.
-
- The following standard keyword values are defined:
-
- 'none': There is no authentication mechanism associated with the
- URI. The Printer object assumes that the authenticated user is
- "anonymous".
- 'requesting-user-name': When a client performs an operation whose
- target is the associated URI, the Printer object assumes that
- the authenticated user is specified by the "requesting-user-
- name" Operation attribute (see section 8.3). If the
- "requesting-user-name" attribute is absent in a request, the
- Printer object assumes that the authenticated user is
- "anonymous".
- 'basic': When a client performs an operation whose target is the
- associated URI, the Printer object challenges the client with
- HTTP basic authentication [RFC2617]. The Printer object assumes
- that the authenticated user is the name received via the basic
- authentication mechanism.
- 'digest': When a client performs an operation whose target is the
- associated URI, the Printer object challenges the client with
- HTTP digest authentication [RFC2617]. The Printer object
- assumes that the authenticated user is the name received via
- the digest authentication mechanism.
- 'certificate': When a client performs an operation whose target is
- the associated URI, the Printer object expects the client to
- provide a certificate. The Printer object assumes that the
- authenticated user is the textual name contained within the
- certificate.
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 127]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-4.4.3 uri-security-supported (1setOf type2 keyword)
-
- This REQUIRED Printer attribute MUST have the same cardinality
- (contain the same number of values) as the "printer-uri-supported"
- attribute. This attribute identifies the security mechanisms used
- for each URI listed in the "printer-uri-supported" attribute. The "i
- th" value in "uri-security-supported" corresponds to the "i th" value
- in "printer-uri-supported" and it describes the security mechanisms
- used for accessing the Printer object via that URI. See [RFC2910]
- for more details on security mechanisms.
-
- The following standard keyword values are defined:
-
- 'none': There are no secure communication channel protocols in use
- for the given URI.
- 'ssl3': SSL3 [SSL] is the secure communications channel protocol
- in use for the given URI.
- 'tls': TLS [RFC2246] is the secure communications channel
- protocol in use for the given URI.
-
- This attribute is orthogonal to the definition of a Client
- Authentication mechanism. Specifically, 'none' does not exclude
- Client Authentication. See section 4.4.2.
-
- Consider the following example. For a single Printer object, an
- administrator configures the "printer-uri-supported", "uri-
- authentication-supported" and "uri-security-supported" attributes as
- follows:
-
- "printer-uri-supported": 'xxx://acme.com/open-use-printer',
- 'xxx://acme.com/restricted-use-printer',
- 'xxx://acme.com/private-printer'
- "uri-authentication-supported": 'none', 'digest', 'basic'
- "uri-security-supported": 'none', 'none', 'tls'
-
- Note: 'xxx' is not a valid scheme. See the IPP/1.1 "Transport and
- Encoding" document [RFC2910] for the actual URI schemes to be used in
- object target attributes.
-
- In this case, one Printer object has three URIs.
-
- - For the first URI, 'xxx://acme.com/open-use-printer', the value
- 'none' in "uri-security-supported" indicates that there is no
- secure channel protocol configured to run under HTTP. The value
- of 'none' in "uri-authentication-supported" indicates that all
- users are 'anonymous'. There will be no challenge and the
- Printer will ignore "requesting-user-name".
-
-
-
-
-Hastings, et al. Standards Track [Page 128]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- - For the second URI, 'xxx://acme.com/restricted-use-printer', the
- value 'none' in "uri-security-supported" indicates that there is
- no secure channel protocol configured to run under HTTP. The
- value of 'digest' in "uri-authentication-supported" indicates
- that the Printer will issue a challenge and that the Printer
- will use the name supplied by the digest mechanism to determine
- the authenticated user (see section 8.3).
- - For the third URI, 'xxx://acme.com/private-printer', the value
- 'tls' in "uri-security-supported" indicates that TLS is being
- used to secure the channel. The client SHOULD be prepared to
- use TLS framing to negotiate an acceptable ciphersuite to use
- while communicating with the Printer object. In this case, the
- name implies the use of a secure communications channel, but the
- fact is made explicit by the presence of the 'tls' value in
- "uri-security-supported". The client does not need to resort to
- understanding which security it must use by following naming
- conventions or by parsing the URI to determine which security
- mechanisms are implied. The value of 'basic' in "uri-
- authentication-supported" indicates that the Printer will issue
- a challenge and that the Printer will use the name supplied by
- the digest mechanism to determine the authenticated user (see
- section 8.3). Because this challenge occurs in a tls session,
- the channel is secure.
-
- It is expected that many IPP Printer objects will be configured to
- support only one channel (either configured to use TLS access or not)
- and only one authentication mechanism. Such Printer objects only have
- one URI listed in the "printer-uri-supported" attribute. No matter
- the configuration of the Printer object (whether it has only one URI
- or more than one URI), a client MUST supply only one URI in the
- target "printer-uri" operation attribute.
-
-4.4.4 printer-name (name(127))
-
- This REQUIRED Printer attribute contains the name of the Printer
- object. It is a name that is more end-user friendly than a URI. An
- administrator determines a printer's name and sets this attribute to
- that name. This name may be the last part of the printer's URI or it
- may be unrelated. In non-US-English locales, a name may contain
- characters that are not allowed in a URI.
-
-4.4.5 printer-location (text(127))
-
- This Printer attribute identifies the location of the device. This
- could include things like: "in Room 123A, second floor of building
- XYZ".
-
-
-
-
-
-Hastings, et al. Standards Track [Page 129]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-4.4.6 printer-info (text(127))
-
- This Printer attribute identifies the descriptive information about
- this Printer object. This could include things like: "This printer
- can be used for printing color transparencies for HR presentations",
- or "Out of courtesy for others, please print only small (1-5 page)
- jobs at this printer", or even "This printer is going away on July 1,
- 1997, please find a new printer".
-
-4.4.7 printer-more-info (uri)
-
- This Printer attribute contains a URI used to obtain more information
- about this specific Printer object. For example, this could be an
- HTTP type URI referencing an HTML page accessible to a Web Browser.
- The information obtained from this URI is intended for end user
- consumption. Features outside the scope of IPP can be accessed from
- this URI. The information is intended to be specific to this printer
- instance and site specific services (e.g. job pricing, services
- offered, end user assistance). The device manufacturer may initially
- populate this attribute.
-
-4.4.8 printer-driver-installer (uri)
-
- This Printer attribute contains a URI to use to locate the driver
- installer for this Printer object. This attribute is intended for
- consumption by automata. The mechanics of print driver installation
- is outside the scope of this IPP/1.1 document. The device
- manufacturer may initially populate this attribute.
-
-4.4.9 printer-make-and-model (text(127))
-
- This Printer attribute identifies the make and model of the device.
- The device manufacturer may initially populate this attribute.
-
-4.4.10 printer-more-info-manufacturer (uri)
-
- This Printer attribute contains a URI used to obtain more information
- about this type of device. The information obtained from this URI is
- intended for end user consumption. Features outside the scope of IPP
- can be accessed from this URI (e.g., latest firmware, upgrades, print
- drivers, optional features available, details on color support). The
- information is intended to be germane to this printer without regard
- to site specific modifications or services. The device manufacturer
- may initially populate this attribute.
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 130]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-4.4.11 printer-state (type1 enum)
-
- This REQUIRED Printer attribute identifies the current state of the
- device. The "printer-state reasons" attribute augments the
- "printer-state" attribute to give more detailed information about the
- Printer in the given printer state.
-
- A Printer object need only update this attribute before responding to
- an operation which requests the attribute; the Printer object NEED
- NOT update this attribute continually, since asynchronous event
- notification is not part of IPP/1.1. A Printer NEED NOT implement
- all values if they are not applicable to a given implementation.
-
- The following standard enum values are defined:
-
- Value Symbolic Name and Description
-
- '3' 'idle': Indicates that new jobs can start processing without
- waiting.
- '4' 'processing': Indicates that jobs are processing; new jobs
- will wait before processing.
- '5' 'stopped': Indicates that no jobs can be processed and
- intervention is required.
-
- Values of "printer-state-reasons", such as 'spool-area-full' and
- 'stopped-partly', MAY be used to provide further information.
-
-4.4.12 printer-state-reasons (1setOf type2 keyword)
-
- This REQUIRED Printer attribute supplies additional detail about the
- device's state. Some of the these value definitions indicate
- conformance requirements; the rest are OPTIONAL.
-
- Each keyword value MAY have a suffix to indicate its level of
- severity. The three levels are: report (least severe), warning, and
- error (most severe).
-
- - '-report': This suffix indicates that the reason is a "report".
- An implementation may choose to omit some or all reports. Some
- reports specify finer granularity about the printer state;
- others serve as a precursor to a warning. A report MUST contain
- nothing that could affect the printed output.
- - '-warning': This suffix indicates that the reason is a
- "warning". An implementation may choose to omit some or all
- warnings. Warnings serve as a precursor to an error. A warning
- MUST contain nothing that prevents a job from completing, though
- in some cases the output may be of lower quality.
-
-
-
-
-Hastings, et al. Standards Track [Page 131]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- - '-error': This suffix indicates that the reason is an "error".
- An implementation MUST include all errors. If this attribute
- contains one or more errors, printer MUST be in the stopped
- state.
-
- If the implementation does not add any one of the three suffixes, all
- parties MUST assume that the reason is an "error".
-
- If a Printer object controls more than one output device, each value
- of this attribute MAY apply to one or more of the output devices. An
- error on one output device that does not stop the Printer object as a
- whole MAY appear as a warning in the Printer's "printer-state-reasons
- attribute". If the "printer-state" for such a Printer has a value of
- 'stopped', then there MUST be an error reason among the values in the
- "printer-state-reasons" attribute.
-
- The following standard keyword values are defined:
-
- 'other': The device has detected an error other than one listed in
- this document.
- 'none': There are not reasons. This state reason is semantically
- equivalent to "printer-state-reasons" without any value and
- MUST be used, since the 1setOf attribute syntax requires at
- least one value.
- 'media-needed': A tray has run out of media.
- 'media-jam': The device has a media jam.
- 'moving-to-paused': Someone has paused the Printer object using
- the Pause-Printer operation (see section 3.2.7) or other means,
- but the device(s) are taking an appreciable time to stop.
- Later, when all output has stopped, the "printer-state" becomes
- 'stopped', and the 'paused' value replaces the 'moving-to-
- paused' value in the "printer-state-reasons" attribute. This
- value MUST be supported, if the Pause-Printer operation is
- supported and the implementation takes significant time to
- pause a device in certain circumstances.
- 'paused': Someone has paused the Printer object using the Pause-
- Printer operation (see section 3.2.7) or other means and the
- Printer object's "printer-state" is 'stopped'. In this state,
- a Printer MUST NOT produce printed output, but it MUST perform
- other operations requested by a client. If a Printer had been
- printing a job when the Printer was paused, the Printer MUST
- resume printing that job when the Printer is no longer paused
- and leave no evidence in the printed output of such a pause.
- This value MUST be supported, if the Pause-Printer operation is
- supported.
- 'shutdown': Someone has removed a Printer object from service, and
- the device may be powered down or physically removed. In this
- state, a Printer object MUST NOT produce printed output, and
-
-
-
-Hastings, et al. Standards Track [Page 132]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- unless the Printer object is realized by a print server that is
- still active, the Printer object MUST perform no other
- operations requested by a client, including returning this
- value. If a Printer object had been printing a job when it was
- shutdown, the Printer NEED NOT resume printing that job when
- the Printer is no longer shutdown. If the Printer resumes
- printing such a job, it may leave evidence in the printed
- output of such a shutdown, e.g. the part printed before the
- shutdown may be printed a second time after the shutdown.
- 'connecting-to-device': The Printer object has scheduled a job on
- the output device and is in the process of connecting to a
- shared network output device (and might not be able to actually
- start printing the job for an arbitrarily long time depending
- on the usage of the output device by other servers on the
- network).
- 'timed-out': The server was able to connect to the output device
- (or is always connected), but was unable to get a response from
- the output device.
- 'stopping': The Printer object is in the process of stopping the
- device and will be stopped in a while. When the device is
- stopped, the Printer object will change the Printer object's
- state to 'stopped'. The 'stopping-warning' reason is never an
- error, even for a Printer with a single output device. When an
- output-device ceases accepting jobs, the Printer will have this
- reason while the output device completes printing.
- 'stopped-partly': When a Printer object controls more than one
- output device, this reason indicates that one or more output
- devices are stopped. If the reason is a report, fewer than
- half of the output devices are stopped. If the reason is a
- warning, fewer than all of the output devices are stopped.
- 'toner-low': The device is low on toner.
- 'toner-empty': The device is out of toner.
- 'spool-area-full': The limit of persistent storage allocated for
- spooling has been reached. The Printer is temporarily unable
- to accept more jobs. The Printer will remove this value when
- it is able to accept more jobs. This value SHOULD be used by a
- non-spooling Printer that only accepts one or a small number
- jobs at a time or a spooling Printer that has filled the spool
- space.
- 'cover-open': One or more covers on the device are open.
- 'interlock-open': One or more interlock devices on the printer are
- unlocked.
- 'door-open': One or more doors on the device are open.
- 'input-tray-missing': One or more input trays are not in the
- device.
- 'media-low': At least one input tray is low on media.
- 'media-empty': At least one input tray is empty.
-
-
-
-
-Hastings, et al. Standards Track [Page 133]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'output-tray-missing': One or more output trays are not in the
- device
- 'output-area-almost-full': One or more output area is almost full
- (e.g. tray, stacker, collator).
- 'output-area-full': One or more output area is full. (e.g. tray,
- stacker, collator)
- 'marker-supply-low': The device is low on at least one marker
- supply. (e.g. toner, ink, ribbon)
- 'marker-supply-empty: The device is out of at least one marker
- supply. (e.g. toner, ink, ribbon)
- 'marker-waste-almost-full': The device marker supply waste
- receptacle is almost full.
- 'marker-waste-full': The device marker supply waste receptacle is
- full.
- 'fuser-over-temp': The fuser temperature is above normal.
- 'fuser-under-temp': The fuser temperature is below normal.
- 'opc-near-eol': The optical photo conductor is near end of life.
- 'opc-life-over': The optical photo conductor is no longer
- functioning.
- 'developer-low': The device is low on developer.
- 'developer-empty: The device is out of developer.
- 'interpreter-resource-unavailable': An interpreter resource is
- unavailable (i.e. font, form)
-
-4.4.13 printer-state-message (text(MAX))
-
- This Printer attribute specifies information about the "printer-
- state" and "printer-state-reasons" attributes in human readable text.
- If the Printer object supports this attribute, the Printer object
- MUST be able to generate this message in any of the natural languages
- identified by the Printer's "generated-natural-language-supported"
- attribute (see the "attributes-natural-language" operation attribute
- specified in Section 3.1.4.1).
-
-4.4.14 ipp-versions-supported (1setOf type2 keyword)
-
- This REQUIRED attribute identifies the IPP protocol version(s) that
- this Printer supports, including major and minor versions, i.e., the
- version numbers for which this Printer implementation meets the
- conformance requirements. For version number validation, the Printer
- matches the (two-octet binary) "version-number" parameter supplied by
- the client in each request (see sections 3.1.1 and 3.1.8) with the
- (US-ASCII) keyword values of this attribute.
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 134]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- The following standard keyword values are defined:
-
- '1.0': Meets the conformance requirement of IPP version 1.0 as
- specified in RFC 2566 [RFC2566] and RFC 2565 [RFC2565]
- including any extensions registered according to Section 6 and
- any extension defined in this version or any future version of
- the IPP "Model and Semantics" document or the IPP "Encoding and
- Transport" document following the rules, if any, when the
- "version-number" parameter is '1.0'.
- '1.1': Meets the conformance requirement of IPP version 1.1 as
- specified in this document and [RFC2910] including any
- extensions registered according to Section 6 and any extension
- defined in any future versions of the IPP "Model and Semantics"
- document or the IPP Encoding and Transport document following
- the rules, if any, when the "version-number" parameter is
- '1.1'.
-
-4.4.15 operations-supported (1setOf type2 enum)
-
- This REQUIRED Printer attribute specifies the set of supported
- operations for this Printer object and contained Job objects.
-
- This attribute is encoded as any other enum attribute syntax
- according to [RFC2910] as 32-bits. However, all 32-bit enum values
- for this attribute MUST NOT exceed 0x00008FFF, since these same
- values are also passed in two octets in the "operation-id" parameter
- (see section 3.1.1) in each Protocol request with the two high order
- octets omitted in order to indicate the operation being performed
- [RFC2910].
-
- The following standard enum and "operation-id" (see section 3.1.2)
- values are defined:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 135]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Value Operation Name
- ----------------- -------------------------------------
-
- 0x0000 reserved, not used
- 0x0001 reserved, not used
- 0x0002 Print-Job
- 0x0003 Print-URI
- 0x0004 Validate-Job
- 0x0005 Create-Job
- 0x0006 Send-Document
- 0x0007 Send-URI
- 0x0008 Cancel-Job
- 0x0009 Get-Job-Attributes
- 0x000A Get-Jobs
- 0x000B Get-Printer-Attributes
- 0x000C Hold-Job
- 0x000D Release-Job
- 0x000E Restart-Job
- 0x000F reserved for a future operation
- 0x0010 Pause-Printer
- 0x0011 Resume-Printer
- 0x0012 Purge-Jobs
- 0x0013-0x3FFF reserved for future IETF standards track
- operations (see section 6.4)
- 0x4000-0x8FFF reserved for vendor extensions (see section 6.4)
-
-4.4.16 multiple-document-jobs-supported (boolean)
-
- This Printer attribute indicates whether or not the Printer supports
- more than one document per job, i.e., more than one Send-Document or
- Send-Data operation with document data. If the Printer supports the
- Create-Job and Send-Document operations (see section 3.2.4 and
- 3.3.1), it MUST support this attribute.
-
-4.4.17 charset-configured (charset)
-
- This REQUIRED Printer attribute identifies the charset that the
- Printer object has been configured to represent 'text' and 'name'
- Printer attributes that are set by the operator, system
- administrator, or manufacturer, i.e., for "printer-name" (name),
- "printer-location" (text), "printer-info" (text), and "printer-make-
- and-model" (text). Therefore, the value of the Printer object's
- "charset-configured" attribute MUST also be among the values of the
- Printer object's "charset-supported" attribute.
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 136]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-4.4.18 charset-supported (1setOf charset)
-
- This REQUIRED Printer attribute identifies the set of charsets that
- the Printer and contained Job objects support in attributes with
- attribute syntax 'text' and 'name'. At least the value 'utf-8' MUST
- be present, since IPP objects MUST support the UTF-8 [RFC2279]
- charset. If a Printer object supports a charset, it means that for
- all attributes of syntax 'text' and 'name' the IPP object MUST (1)
- accept the charset in requests and return the charset in responses as
- needed.
-
- If more charsets than UTF-8 are supported, the IPP object MUST
- perform charset conversion between the charsets as described in
- Section 3.1.4.2.
-
-4.4.19 natural-language-configured (naturalLanguage)
-
- This REQUIRED Printer attribute identifies the natural language that
- the Printer object has been configured to represent 'text' and 'name'
- Printer attributes that are set by the operator, system
- administrator, or manufacturer, i.e., for "printer-name" (name),
- "printer-location" (text), "printer-info" (text), and "printer-make-
- and-model" (text). When returning these Printer attributes, the
- Printer object MAY return them in the configured natural language
- specified by this attribute, instead of the natural language
- requested by the client in the "attributes-natural-language"
- operation attribute. See Section 3.1.4.1 for the specification of
- the OPTIONAL multiple natural language support. Therefore, the value
- of the Printer object's "natural-language-configured" attribute MUST
- also be among the values of the Printer object's "generated-natural-
- language-supported" attribute.
-
-4.4.20 generated-natural-language-supported (1setOf naturalLanguage)
-
- This REQUIRED Printer attribute identifies the natural language(s)
- that the Printer object and contained Job objects support in
- attributes with attribute syntax 'text' and 'name'. The natural
- language(s) supported depends on implementation and/or configuration.
- Unlike charsets, IPP objects MUST accept requests with any natural
- language or any Natural Language Override whether the natural
- language is supported or not.
-
- If a Printer object supports a natural language, it means that for
- any of the attributes for which the Printer or Job object generates
- messages, i.e., for the "job-state-message" and "printer-state-
- message" attributes and Operation Messages (see Section 3.1.5) in
- operation responses, the Printer and Job objects MUST be able to
-
-
-
-
-Hastings, et al. Standards Track [Page 137]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- generate messages in any of the Printer's supported natural
- languages. See section 3.1.4 for the definition of 'text' and 'name'
- attributes in operation requests and responses.
-
- Note: A Printer object that supports multiple natural languages,
- often has separate catalogs of messages, one for each natural
- language supported.
-
-4.4.21 document-format-default (mimeMediaType)
-
- This REQUIRED Printer attribute identifies the document format that
- the Printer object has been configured to assume if the client does
- not supply a "document-format" operation attribute in any of the
- operation requests that supply document data. The standard values
- for this attribute are Internet Media types (sometimes called MIME
- types). For further details see the description of the
- 'mimeMediaType' attribute syntax in Section 4.1.9.
-
-4.4.22 document-format-supported (1setOf mimeMediaType)
-
- This REQUIRED Printer attribute identifies the set of document
- formats that the Printer object and contained Job objects can
- support. For further details see the description of the
- 'mimeMediaType' attribute syntax in Section 4.1.9.
-
-4.4.23 printer-is-accepting-jobs (boolean)
-
- This REQUIRED Printer attribute indicates whether the printer is
- currently able to accept jobs, i.e., is accepting Print-Job, Print-
- URI, and Create-Job requests. If the value is 'true', the printer is
- accepting jobs. If the value is 'false', the Printer object is
- currently rejecting any jobs submitted to it. In this case, the
- Printer object returns the 'server-error-not-accepting-jobs' status
- code.
-
- This value is independent of the "printer-state" and "printer-state-
- reasons" attributes because its value does not affect the current
- job; rather it affects future jobs. This attribute, when 'false',
- causes the Printer to reject jobs even when the "printer-state" is
- 'idle' or, when 'true', causes the Printer object to accepts jobs
- even when the "printer-state" is 'stopped'.
-
-4.4.24 queued-job-count (integer(0:MAX))
-
- This REQUIRED Printer attribute contains a count of the number of
- jobs that are either 'pending', 'processing', 'pending-held', or
- 'processing-stopped' and is set by the Printer object.
-
-
-
-
-Hastings, et al. Standards Track [Page 138]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-4.4.25 printer-message-from-operator (text(127))
-
- This Printer attribute provides a message from an operator, system
- administrator or "intelligent" process to indicate to the end user
- information or status of the printer, such as why it is unavailable
- or when it is expected to be available.
-
-4.4.26 color-supported (boolean)
-
- This Printer attribute identifies whether the device is capable of
- any type of color printing at all, including highlight color. All
- document instructions having to do with color are embedded within the
- document PDL (none are external IPP attributes in IPP/1.1).
-
- Note: end-users are able to determine the nature and details of the
- color support by querying the "printer-more-info-manufacturer"
- Printer attribute.
-
-4.4.27 reference-uri-schemes-supported (1setOf uriScheme)
-
- This Printer attribute specifies which URI schemes are supported for
- use in the "document-uri" operation attribute of the Print-URI or
- Send-URI operation. If a Printer object supports these optional
- operations, it MUST support the "reference-uri-schemes-supported"
- Printer attribute with at least the following schemed URI value:
-
- 'ftp': The Printer object will use an FTP 'get' operation as
- defined in RFC 2228 [RFC2228] using FTP URLs as defined by
- [RFC2396] and [RFC2316].
-
- The Printer object MAY OPTIONALLY support other URI schemes (see
- section 4.1.6).
-
-4.4.28 pdl-override-supported (type2 keyword)
-
- This REQUIRED Printer attribute expresses the ability for a
- particular Printer implementation to either attempt to override
- document data instructions with IPP attributes or not.
-
- This attribute takes on the following keyword values:
-
- - 'attempted': This value indicates that the Printer object
- attempts to make the IPP attribute values take precedence over
- embedded instructions in the document data, however there is no
- guarantee.
- - 'not-attempted': This value indicates that the Printer object
- makes no attempt to make the IPP attribute values take
- precedence over embedded instructions in the document data.
-
-
-
-Hastings, et al. Standards Track [Page 139]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Section 15 contains a full description of how this attribute
- interacts with and affects other IPP attributes, especially the
- "ipp-attribute-fidelity" attribute.
-
-4.4.29 printer-up-time (integer(1:MAX))
-
- This REQUIRED Printer attribute indicates the amount of time (in
- seconds) that this Printer instance has been up and running. The
- value is a monotonically increasing value starting from 1 when the
- Printer object is started-up (initialized, booted, etc.). This value
- is used to populate the Event Time Job Description Job attributes
- "time-at-creation", "time-at-processing", and "time-at-completed"
- (see section 4.3.14).
-
- If the Printer object goes down at some value 'n', and comes back up,
- the implementation MAY:
-
- 1. Know how long it has been down, and resume at some value
- greater than 'n', or
- 2. Restart from 1.
-
- In other words, if the device or devices that the Printer object is
- representing are restarted or power cycled, the Printer object MAY
- continue counting this value or MAY reset this value to 1 depending
- on implementation. However, if the Printer object software ceases
- running, and restarts without knowing the last value for "printer-
- up-time", the implementation MUST reset this value to 1. If this
- value is reset and the Printer has persistent jobs, the Printer MUST
- reset the "time-at-xxx(integer) Event Time Job Description attributes
- according to Section 4.3.14. An implementation MAY use both
- implementation alternatives, depending on warm versus cold start,
- respectively.
-
-4.4.30 printer-current-time (dateTime)
-
- This Printer attribute indicates the current date and time. This
- value is used to populate the Event Time Job Description attributes:
- "date-time-at-creation", "date-time-at-processing", and "date-time-
- at-completed" (see Section 4.3.14).
-
- The date and time is obtained on a "best efforts basis" and does not
- have to be that precise in order to work in practice. A Printer
- implementation sets the value of this attribute by obtaining the date
- and time via some implementation-dependent means, such as getting the
- value from a network time server, initialization at time of
- manufacture, or setting by an administrator. See [IPP-IIG] for
- examples. If an implementation supports this attribute and the
- implementation knows that it has not yet been set, then the
-
-
-
-Hastings, et al. Standards Track [Page 140]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- implementation MUST return the value of this attribute using the
- out-of-band 'no-value' meaning not configured. See the beginning of
- section 4.1.
-
- The time zone of this attribute NEED NOT be the time zone used by
- people located near the Printer object or device. The client MUST
- NOT expect that the time zone of any received 'dateTime' value to be
- in the time zone of the client or in the time zone of the people
- located near the printer.
-
- The client SHOULD display any dateTime attributes to the user in
- client local time by converting the 'dateTime' value returned by the
- server to the time zone of the client, rather than using the time
- zone returned by the Printer in attributes that use the 'dateTime'
- attribute syntax.
-
-4.4.31 multiple-operation-time-out (integer(1:MAX))
-
- This Printer attributes identifies the minimum time (in seconds) that
- the Printer object waits for additional Send-Document or Send-URI
- operations to follow a still-open Job object before taking any
- recovery actions, such as the ones indicated in section 3.3.1. If
- the Printer object supports the Create-Job and Send-Document
- operations (see section 3.2.4 and 3.3.1), it MUST support this
- attribute.
-
- It is RECOMMENDED that vendors supply a value for this attribute that
- is between 60 and 240 seconds. An implementation MAY allow a system
- administrator to set this attribute (by means outside this IPP/1.1
- document). If so, the system administrator MAY be able to set values
- outside this range.
-
-4.4.32 compression-supported (1setOf type3 keyword)
-
- This REQUIRED Printer attribute identifies the set of supported
- compression algorithms for document data. Compression only applies
- to the document data; compression does not apply to the encoding of
- the IPP operation itself. The supported values are used to validate
- the client supplied "compression" operation attributes in Print-Job,
- Send-Document, and Send-URI requests.
-
- Standard keyword values are :
-
- 'none': no compression is used.
- 'deflate': ZIP public domain inflate/deflate) compression technology
- in RFC 1951 [RFC1951]
- 'gzip' GNU zip compression technology described in RFC 1952
- [RFC1952].
-
-
-
-Hastings, et al. Standards Track [Page 141]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'compress': UNIX compression technology in RFC 1977 [RFC1977]
-
-4.4.33 job-k-octets-supported (rangeOfInteger(0:MAX))
-
- This Printer attribute specifies the upper and lower bounds of total
- sizes of jobs in K octets, i.e., in units of 1024 octets. The
- supported values are used to validate the client supplied "job-k-
- octets" operation attributes in create requests. The corresponding
- job description attribute "job-k-octets" is defined in section
- 4.3.17.1.
-
-4.4.34 job-impressions-supported (rangeOfInteger(0:MAX))
-
- This Printer attribute specifies the upper and lower bounds for the
- number of impressions per job. The supported values are used to
- validate the client supplied "job-impressions" operation attributes
- in create requests. The corresponding job description attribute
- "job-impressions" is defined in section 4.3.17.2.
-
-4.4.35 job-media-sheets-supported (rangeOfInteger(0:MAX))
-
- This Printer attribute specifies the upper and lower bounds for the
- number of media sheets per job. The supported values are used to
- validate the client supplied "job-media-sheets" operation attributes
- in create requests. The corresponding Job attribute "job-media-
- sheets" is defined in section 4.3.17.3.
-
-4.4.36 pages-per-minute (integer(0:MAX))
-
- This Printer attributes specifies the nominal number of pages per
- minute to the nearest whole number which may be generated by this
- printer (e.g., simplex, black-and-white). This attribute is
- informative, not a service guarantee. Generally, it is the value
- used in the marketing literature to describe the device.
-
- A value of 0 indicates a device that takes more than two minutes to
- process a page.
-
-4.4.37 pages-per-minute-color (integer(0:MAX))
-
- This Printer attributes specifies the nominal number of pages per
- minute to the nearest whole number which may be generated by this
- printer when printing color (e.g., simplex, color). For purposes of
- this attribute, "color" means the same as for the "color-supported"
- attribute, namely, the device is capable of any type of color
- printing at all, including highlight color. This attribute is
-
-
-
-
-
-Hastings, et al. Standards Track [Page 142]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- informative, not a service guarantee. Generally, it is the value
- used in the marketing literature to describe the color capabilities
- of this device.
-
- A value of 0 indicates a device that takes more than two minutes to
- process a page.
-
- If a color device has several color modes, it MAY use the pages-per-
- minute value for this attribute that corresponds to the mode that
- produces the highest number.
-
- Black and white only printers MUST NOT support this attribute. If
- this attribute is present, then the "color-supported" Printer
- description attribute MUST be present and have a 'true' value.
-
- The values of these two attributes returned by the Get-Printer-
- Attributes operation MAY be affected by the "document-format"
- attribute supplied by the client in the Get-Printer-Attributes
- request. In other words, the implementation MAY have different
- speeds depending on the document format being processed. See section
- 3.2.5.1 Get-Printer-Attributes.
-
-5. Conformance
-
- This section describes conformance issues and requirements. This
- document introduces model entities such as objects, operations,
- attributes, attribute syntaxes, and attribute values. These
- conformance sections describe the conformance requirements which
- apply to these model entities.
-
-5.1 Client Conformance Requirements
-
- This section describes the conformance requirements for a client (see
- section 2.1), whether it be:
-
- 1. contained within software controlled by an end user, e.g.
- activated by the "Print" menu item in an application that sends
- IPP requests or
-
- 2. the print server component that sends IPP requests to either an
- output device or another "downstream" print server.
-
- A conforming client MUST support all REQUIRED operations as defined
- in this document. For each attribute included in an operation
- request, a conforming client MUST supply a value whose type and value
- syntax conforms to the requirements of the Model document as
- specified in Sections 3 and 4. A conforming client MAY supply any
-
-
-
-
-Hastings, et al. Standards Track [Page 143]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- IETF standards track extensions and/or vendor extensions in an
- operation request, as long as the extensions meet the requirements in
- Section 6.
-
- Otherwise, there are no conformance requirements placed on the user
- interfaces provided by IPP clients or their applications. For
- example, one application might not allow an end user to submit
- multiple documents per job, while another does. One application
- might first query a Printer object in order to supply a graphical
- user interface (GUI) dialogue box with supported and default values
- whereas a different implementation might not.
-
- When sending a request, an IPP client NEED NOT supply any attributes
- that are indicated as OPTIONALLY supplied by the client.
-
- A client MUST be able to accept any of the attribute syntaxes defined
- in Section 4.1, including their full range, that may be returned to
- it in a response from a Printer object. In particular for each
- attribute that the client supports whose attribute syntax is 'text',
- the client MUST accept and process both the 'textWithoutLanguage' and
- 'textWithLanguage' forms. Similarly, for each attribute that the
- client supports whose attribute syntax is 'name', the client MUST
- accept and process both the 'nameWithoutLanguage' and
- 'nameWithLanguage' forms. For presentation purposes, truncation of
- long attribute values is not recommended. A recommended approach
- would be for the client implementation to allow the user to scroll
- through long attribute values.
-
- A response MAY contain attribute groups, attributes, attribute
- syntaxes, values, and status codes that the client does not expect.
- Therefore, a client implementation MUST gracefully handle such
- responses and not refuse to inter-operate with a conforming Printer
- that is returning IETF standards track extension or vendor
- extensions, including attribute groups, attributes, attribute
- syntaxes, attribute values, status codes, and out-of-band attribute
- values that conform to Section 6. Clients may choose to ignore any
- parameters, attribute groups, attributes, attribute syntaxes, or
- values that they do not understand.
-
- While a client is sending data to a printer, it SHOULD do its best to
- prevent a channel from being closed by a lower layer when the channel
- is blocked (i.e. flow-controlled off) for whatever reason, e.g. 'out
- of paper' or 'job ahead hasn't freed up enough memory'. However, the
- layer that launched the print submission (e.g. an end user) MAY close
- the channel in order to cancel the job. When a client closes a
- channel, a Printer MAY print all or part of the received portion of
- the document. See the "Encoding and Transport" document [RFC2910]
- for more details.
-
-
-
-Hastings, et al. Standards Track [Page 144]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- A client MUST support Client Authentication as defined in the IPP/1.1
- Encoding and Transport document [RFC2910]. A client SHOULD support
- Operation Privacy and Server Authentication as defined in the IPP/1.1
- Encoding and Transport document [RFC2910]. See also section 8 of
- this document.
-
-5.2 IPP Object Conformance Requirements
-
- This section specifies the conformance requirements for conforming
- implementations of IPP objects (see section 2). These requirements
- apply to an IPP object whether it is:
-
- (1) an (embedded) device component that accepts IPP requests and
- controls the device or
-
- (2) a component of a print server that accepts IPP requests (where
- the print server control one or more networked devices using IPP or
- other protocols).
-
-5.2.1 Objects
-
- Conforming implementations MUST implement all of the model objects as
- defined in this document in the indicated sections:
-
- Section 2.1 - Printer Object
- Section 2.2 - Job Object
-
-5.2.2 Operations
-
- Conforming IPP object implementations MUST implement all of the
- REQUIRED model operations, including REQUIRED responses, as defined
- in this document in the indicated sections:
-
- For a Printer object:
- Print-Job (section 3.2.1) REQUIRED
- Print-URI (section 3.2.2) OPTIONAL
- Validate-Job (section 3.2.3) REQUIRED
- Create-Job (section 3.2.4) OPTIONAL
- Get-Printer-Attributes (section 3.2.5) REQUIRED
- Get-Jobs (section 3.2.6) REQUIRED
- Pause-Printer (section 3.2.7) OPTIONAL
- Resume-Printer (section 3.2.8) OPTIONAL
- Purge-Jobs (section 3.2.9) OPTIONAL
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 145]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- For a Job object:
- Send-Document (section 3.3.1) OPTIONAL
- Send-URI (section 3.3.2) OPTIONAL
- Cancel-Job (section 3.3.3) REQUIRED
- Get-Job-Attributes (section 3.3.4) REQUIRED
- Hold-Job (section 3.3.5) OPTIONAL
- Release-Job (section 3.3.6) OPTIONAL
- Restart-Job (section 3.3.7) OPTIONAL
-
- Conforming IPP objects MUST support all REQUIRED operation attributes
- and all values of such attributes if so indicated in the description.
- Conforming IPP objects MUST ignore all unsupported or unknown
- operation attributes or operation attribute groups received in a
- request, but MUST reject a request that contains a supported
- operation attribute that contains an unsupported value.
-
- Conforming IPP objects MAY return operation responses that contain
- attributes groups, attributes names, attribute syntaxes, attribute
- values, and status codes that are extensions to this standard. The
- additional attribute groups MAY occur in any order.
-
- The following section on object attributes specifies the support
- required for object attributes.
-
-5.2.3 IPP Object Attributes
-
- Conforming IPP objects MUST support all of the REQUIRED object
- attributes, as defined in this document in the indicated sections.
-
- If an object supports an attribute, it MUST support only those values
- specified in this document or through the extension mechanism
- described in section 5.2.4. It MAY support any non-empty subset of
- these values. That is, it MUST support at least one of the specified
- values and at most all of them.
-
-5.2.4 Versions
-
- IPP/1.1 clients MUST meet the conformance requirements for clients
- specified in this document and [RFC2910]. IPP/1.1 clients MUST send
- requests containing a "version-number" parameter with a '1.1' value.
-
- IPP/1.1 Printer and Job objects MUST meet the conformance
- requirements for IPP objects specified in this document and
- [RFC2910]. IPP/1.1 objects MUST accept requests containing a
- "version-number" parameter with a '1.1' value (or reject the request
- if the operation is not supported).
-
-
-
-
-
-Hastings, et al. Standards Track [Page 146]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- It is beyond the scope of this specification to mandate conformance
- with previous versions. IPP/1.1 was deliberately designed, however,
- to make supporting previous versions easy. It is worth noting that,
- at the time of composing this specification (1999), we would expect
- IPP/1.1 Printer implementations to:
-
- understand any valid request in the format of IPP/1.0, or 1.1;
-
- respond appropriately with a response containing the same
- "version-number" parameter value used by the client in the request.
-
- And we would expect IPP/1.1 clients to:
-
- understand any valid response in the format of IPP/1.0, or 1.1.
-
- It is recommended that IPP/1.1 clients try supplying alternate
- version numbers if they receive a 'server-error-version-not-
- supported' error return in a response.
-
-5.2.5 Extensions
-
- A conforming IPP object MAY support IETF standards track extensions
- and vendor extensions, as long as the extensions meet the
- requirements specified in Section 6.
-
- For each attribute included in an operation response, a conforming
- IPP object MUST return a value whose type and value syntax conforms
- to the requirement of the Model document as specified in Sections 3
- and 4.
-
-5.2.6 Attribute Syntaxes
-
- An IPP object MUST be able to accept any of the attribute syntaxes
- defined in Section 4.1, including their full range, in any operation
- in which a client may supply attributes or the system administrator
- may configure attributes (by means outside the scope of this IPP/1.1
- document). In particular for each attribute that the IPP object
- supports whose attribute syntax is 'text', the IPP object MUST accept
- and process both the 'textWithoutLanguage' and 'textWithLanguage'
- forms. Similarly, for each attribute that the IPP object supports
- whose attribute syntax is 'name', the IPP object MUST accept and
- process both the 'nameWithoutLanguage' and 'nameWithLanguage' forms.
- Furthermore, an IPP object MUST return attributes to the client in
- operation responses that conform to the syntax specified in Section
- 4.1, including their full range if supplied previously by a client.
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 147]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-5.2.7 Security
-
- An IPP Printer implementation SHOULD contain support for Client
- Authentication as defined in the IPP/1.1 Encoding and Transport
- document [RFC2910]. A Printer implementation MAY allow an
- administrator to configure the Printer so that all, some, or none of
- the users are authenticated. See also section 8 of this document.
-
- An IPP Printer implementation SHOULD contain support for Operation
- Privacy and Server Authentication as defined in the IPP/1.1 Encoding
- and Transport document [RFC2910]. A Printer implementation MAY allow
- an administrator to configure the degree of support for Operation
- Privacy and Server Authentication. See also section 8 of this
- document.
-
- Security MUST NOT be compromised when a client supplies a lower
- "version-number" parameter in a request. For example, if an IPP/1.1
- conforming Printer object accepts version '1.0' requests and is
- configured to enforce Digest Authentication, it MUST do the same for
- a version '1.0' request.
-
-5.3 Charset and Natural Language Requirements
-
- All clients and IPP objects MUST support the 'utf-8' charset as
- defined in section 4.1.7.
-
- IPP objects MUST be able to accept any client request which correctly
- uses the "attributes-natural-language" operation attribute or the
- Natural Language Override mechanism on any individual attribute
- whether or not the natural language is supported by the IPP object.
- If an IPP object supports a natural language, then it MUST be able to
- translate (perhaps by table lookup) all generated 'text' or 'name'
- attribute values into one of the supported languages (see section
- 3.1.4). That is, the IPP object that supports a natural language
- NEED NOT be a general purpose translator of any arbitrary 'text' or
- 'name' value supplied by the client into that natural language.
- However, the object MUST be able to translate (automatically
- generate) any of its own attribute values and messages into that
- natural language.
-
-6. IANA Considerations
-
- This section describes the procedures for defining semantics for the
- following IETF standards track extensions and vendor extensions to
- the IPP/1.1 Model and Semantics document:
-
- 1. keyword attribute values
- 2. enum attribute values
-
-
-
-Hastings, et al. Standards Track [Page 148]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 3. attributes
- 4. attribute syntaxes
- 5. operations
- 6. attribute groups
- 7. status codes
- 8. out-of-band attribute values
-
- Extensions registered for use with IPP/1.1 are OPTIONAL for client
- and IPP object conformance to the IPP/1.1 "Model and Semantics"
- document (this document).
-
- These extension procedures are aligned with the guidelines as set
- forth by the IESG [IANA-CON]. Section 11 describes how to propose
- new registrations for consideration. IANA will reject registration
- proposals that leave out required information or do not follow the
- appropriate format described in Section 11. The IPP/1.1 Model and
- Semantics document may also be extended by an appropriate RFC that
- specifies any of the above extensions.
-
-6.1 Typed 'keyword' and 'enum' Extensions
-
- IPP allows for 'keyword' and 'enum' extensions (see sections 4.1.2.3
- and 4.1.4). This document uses prefixes to the 'keyword' and 'enum'
- basic attribute syntax type in order to communicate extra information
- to the reader through its name. This extra information is not
- represented in the protocol because it is unimportant to a client or
- Printer object. The list below describes the prefixes and their
- meaning.
-
- "type1": This IPP specification document must be revised (or
- another IETF standards track document which augments this
- document) to add a new keyword or a new enum. No vendor
- defined keywords or enums are allowed.
-
- "type2": Implementers can, at any time, add new keyword or enum
- values by proposing the complete specification to IANA:
-
- iana@iana.org
-
- IANA will forward the registration proposal to the IPP
- Designated Expert who will review the proposal with a mailing
- list that the Designated Expert keeps for this purpose.
- Initially, that list will be the mailing list used by the IPP
- WG:
-
- ipp@pwg.org
-
- even after the IPP WG is disbanded as permitted by [IANA-CON].
-
-
-
-Hastings, et al. Standards Track [Page 149]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- The IPP Designated Expert is appointed by the IESG Area
- Director responsible for IPP, according to [IANA-CON].
-
- When a type2 keyword or enum is approved, the IPP Designated
- Expert becomes the point of contact for any future maintenance
- that might be required for that registration.
-
- "type3": Implementers can, at any time, add new keyword and enum
- values by submitting the complete specification to IANA as for
- type2 who will forward the proposal to the IPP Designated
- Expert. While no additional technical review is required, the
- IPP Designated Expert may, at his/her discretion, forward the
- proposal to the same mailing list as for type2 registrations
- for advice and comment.
-
- When a type3 keyword or enum is approved by the IPP Designated
- Expert, the original proposer becomes the point of contact for
- any future maintenance that might be required for that
- registration.
-
- For type2 and type3 keywords, the proposer includes the name of the
- keyword in the registration proposal and the name is part of the
- technical review.
-
- After type2 and type3 enums specifications are approved, the IPP
- Designated Expert in consultation with IANA assigns the next
- available enum number for each enum value.
-
- IANA will publish approved type2 and type3 keyword and enum
- attributes value registration specifications in:
-
- ftp.isi.edu/iana/assignments/ipp/attribute-values/xxx/yyy.txt
-
- where xxx is the attribute name that specifies the initial values and
- yyy.txt is a descriptive file name that contains one or more enums or
- keywords approved at the same time. For example, if several
- additional enums for stapling are approved for use with the
- "finishings" attribute (and "finishings-default" and "finishings-
- supported" attributes), IANA will publish the additional values in
- the file:
-
- ftp.isi.edu/iana/assignments/ipp/attribute-
- values/finishings/stapling.txt
-
- Note: Some attributes are defined to be: 'type3 keywords' | 'name'
- which allows for attribute values to be extended by a site
- administrator with administrator defined names. Such names are not
- registered with IANA.
-
-
-
-Hastings, et al. Standards Track [Page 150]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- By definition, each of the three types above assert some sort of
- registry or review process in order for extensions to be considered
- valid. Each higher numbered level (1, 2, 3) tends to be decreasingly
- less stringent than the previous level. Therefore, any typeN value
- MAY be registered using a process for some typeM where M is less than
- N, however such registration is NOT REQUIRED. For example, a type3
- value MAY be registered in a type 1 manner (by being included in a
- future version of an IPP specification), however, it is NOT REQUIRED.
-
- This document defines keyword and enum values for all of the above
- types, including type3 keywords.
-
- For vendor keyword extensions, implementers SHOULD use keywords with
- a suitable distinguishing prefix, such as "xxx-" where xxx follows
- the syntax rules for keywords (see section 4.1.3) and is the
- (lowercase) fully qualified company name registered with IANA for use
- in domain names [RFC1035]. For example, if the company XYZ Corp. had
- obtained the domain name "XYZ.com", then a vendor keyword 'abc' would
- be: 'xyz.com-abc'.
-
- Note: RFC 1035 [RFC1035] indicates that while upper and lower case
- letters are allowed in domain names, no significance is attached to
- the case. That is, two names with the same spelling but different
- case are to be treated as if identical. Also, the labels in a domain
- name must follow the rules for ARPANET host names: They must start
- with a letter, end with a letter or digit, and have as interior
- characters only letters, digits, and hyphen. Labels must be 63
- characters or less. Labels are separated by the "." character.
-
- For vendor enum extensions, implementers MUST use values in the
- reserved integer range which is 2**30 to 2**31-1.
-
-6.2 Attribute Extensibility
-
- Attribute names (see section 4.1.3) are type2 keywords. Therefore,
- new attributes may be registered and have the same status as
- attributes in this document by following the type2 extension rules.
- For vendor attribute extensions, implementers SHOULD use keywords
- with a suitable distinguishing prefix as described in Section 6.1.
-
- IANA will publish approved attribute registration specifications as
- separate files:
-
- ftp.isi.edu/iana/assignments/ipp/attributes/xxx-yyy.txt
-
- where "xxx-yyy" is the new attribute name.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 151]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- If a new Printer object attribute is defined and its values can be
- affected by a specific document format, its specification needs to
- contain the following sentence:
-
- "The value of this attribute returned in a Get-Printer-
- Attributes response MAY depend on the "document-format"
- attribute supplied (see Section 3.2.5.1)."
-
- If the specification does not, then its value in the Get-Printer-
- Attributes response MUST NOT depend on the "document-format" supplied
- in the request. When a new Job Template attribute is registered, the
- value of the Printer attributes MAY vary with "document-format"
- supplied in the request without the specification having to indicate
- so.
-
-6.3 Attribute Syntax Extensibility
-
- Attribute syntaxes (see section 4.1) are like type2 enums.
- Therefore, new attribute syntaxes may be registered and have the same
- status as attribute syntaxes in this document by following the type2
- extension rules described in Section 6.1. The initial set of value
- codes that identify each of the attribute syntaxes have been assigned
- in the "Encoding and Transport" document [RFC2910], including a
- designated range for vendor extension.
-
- For attribute syntaxes, the IPP Designated Expert in consultation
- with IANA assigns the next attribute syntax code in the appropriate
- range as specified in [RFC2910]. IANA will publish approved
- attribute syntax registration specifications as separate files:
-
- ftp.isi.edu/iana/assignments/ipp/attribute-syntaxes/xxx-yyy.txt
-
- where 'xxx-yyy' is the new attribute syntax name.
-
-6.4 Operation Extensibility
-
- Operations (see section 3) may also be registered following the type2
- procedures described in Section 6.1, though major new operations will
- usually be done by a new standards track RFC that augments this
- document. For vendor operation extensions, implementers MUST use the
- range for the "operation-id" in requests specified in Section 4.4.15
- "operations-supported" Printer attribute.
-
- For operations, the IPP Designated Expert in consultation with IANA
- assigns the next operation-id code as specified in Section 4.4.15.
- IANA will publish approved operation registration specifications as
- separate files:
-
-
-
-
-Hastings, et al. Standards Track [Page 152]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- ftp.isi.edu/iana/assignments/ipp/operations/Xxx-Yyy.txt
-
- where "Xxx-Yyy" is the new operation name.
-
-6.5 Attribute Group Extensibility
-
- Attribute groups (see section 3.1.3) passed in requests and responses
- may be registered following the type2 procedures described in Section
- 6.1. The initial set of attribute group tags have been assigned in
- the "Encoding and Transport" document [RFC2910], including a
- designated range for vendor extension.
-
- For attribute groups, the IPP Designated Expert in consultation with
- IANA assigns the next attribute group tag code in the appropriate
- range as specified in [RFC2910]. IANA will publish approved
- attribute group registration specifications as separate files:
-
- ftp.isi.edu/iana/assignments/ipp/attribute-group-tags/xxx-yyy-
- tag.txt
-
- where 'xxx-yyy-tag' is the new attribute group tag name.
-
-6.6 Status Code Extensibility
-
- Operation status codes (see section 3.1.6.1) may also be registered
- following the type2 procedures described in Section 6.1. The values
- for status codes are allocated in ranges as specified in Section 14
- for each status code class:
-
- "informational" - Request received, continuing process
- "successful" - The action was successfully received, understood, and
- accepted
- "redirection" - Further action must be taken in order to complete the
- request
- "client-error" - The request contains bad syntax or cannot be
- fulfilled
- "server-error" - The IPP object failed to fulfill an apparently
- valid request
-
- For vendor operation status code extensions, implementers MUST use
- the top of each range as specified in Section 13.
-
- For operation status codes, the IPP Designated Expert in consultation
- with IANA assigns the next status code in the appropriate class range
- as specified in Section 13. IANA will publish approved status code
- registration specifications as separate files:
-
- ftp.isi.edu/iana/assignments/ipp/status-codes/xxx-yyy.txt
-
-
-
-Hastings, et al. Standards Track [Page 153]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- where "xxx-yyy" is the new operation status code keyword.
-
-6.7 Out-of-band Attribute Value Extensibility
-
- Out-of-band attribute values (see the beginning of section 4.1)
- passed in requests and responses may be registered following the
- type2 procedures described in Section 6.1. The initial set of out-
- of-band attribute value tags have been assigned in the "Encoding and
- Transport" document [RFC2910].
-
- For out-of-band attribute value tags, the IPP Designated Expert in
- consultation with IANA assigns the next out-of-band attribute value
- tag code in the appropriate range as specified in [RFC2910]. IANA
- will publish approved out-of-band attribute value tags registration
- specifications as separate files:
-
- ftp.isi.edu/iana/assignments/ipp/out-of-band-attribute-value-
- tags/xxx-yyy-tag.txt
-
- where 'xxx-yyy-tag' is the new out-of-band attribute value tag name.
-
-6.8 Registration of MIME types/sub-types for document-formats
-
- The "document-format" attribute's syntax is 'mimeMediaType'. This
- means that valid values are Internet Media Types (see Section 4.1.9).
- RFC 2045 [RFC2045] defines the syntax for valid Internet media types.
- IANA is the registry for all Internet media types.
-
-6.9 Registration of charsets for use in 'charset' attribute values
-
- The "attributes-charset" attribute's syntax is 'charset'. This means
- that valid values are charsets names. When a charset in the IANA
- registry has more than one name (alias), the name labeled as
- "(preferred MIME name)", if present, MUST be used (see Section
- 4.1.7). IANA is the registry for charsets following the procedures
- of [RFC2278].
-
-7. Internationalization Considerations
-
- Some of the attributes have values that are text strings and names
- which are intended for human understanding rather than machine
- understanding (see the 'text' and 'name' attribute syntaxes in
- Sections 4.1.1 and 4.1.2).
-
- In each operation request, the client
-
- - identifies the charset and natural language of the request which
- affects each supplied 'text' and 'name' attribute value, and
-
-
-
-Hastings, et al. Standards Track [Page 154]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- - requests the charset and natural language for attributes
- returned by the IPP object in operation responses (as described
- in Section 3.1.4.1).
-
- In addition, the client MAY separately and individually identify the
- Natural Language Override of a supplied 'text' or 'name' attribute
- using the 'textWithLanguage' and 'nameWithLanguage' technique
- described section 4.1.1.2 and 4.1.2.2 respectively.
-
- All IPP objects MUST support the UTF-8 [RFC2279] charset in all
- 'text' and 'name' attributes supported. If an IPP object supports
- more than the UTF-8 charset, the object MUST convert between them in
- order to return the requested charset to the client according to
- Section 3.1.4.2. If an IPP object supports more than one natural
- language, the object SHOULD return 'text' and 'name' values in the
- natural language requested where those values are generated by the
- Printer (see Section 3.1.4.1).
-
- For Printers that support multiple charsets and/or multiple natural
- languages in 'text' and 'name' attributes, different jobs may have
- been submitted in differing charsets and/or natural languages. All
- responses MUST be returned in the charset requested by the client.
- However, the Get-Jobs operation uses the 'textWithLanguage' and
- 'nameWithLanguage' mechanism to identify the differing natural
- languages with each job attribute returned.
-
- The Printer object also has configured charset and natural language
- attributes. The client can query the Printer object to determine
- the list of charsets and natural languages supported by the Printer
- object and what the Printer object's configured values are. See the
- "charset-configured", "charset-supported", "natural-language-
- configured", and "generated-natural-language-supported" Printer
- description attributes for more details.
-
- The "charset-supported" attributed identifies the supported charsets.
- If a charset is supported, the IPP object MUST be capable of
- converting to and from that charset into any other supported charset.
- In many cases, an IPP object will support only one charset and it
- MUST be the UTF-8 charset.
-
- The "charset-configured" attribute identifies the one supported
- charset which is the native charset given the current configuration
- of the IPP object (administrator defined).
-
- The "generated-natural-language-supported" attribute identifies the
- set of supported natural languages for generated messages; it is not
- related to the set of natural languages that must be accepted for
- client supplied 'text' and 'name' attributes. For client supplied
-
-
-
-Hastings, et al. Standards Track [Page 155]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'text' and 'name' attributes, an IPP object MUST accept ALL supplied
- natural languages. Just because a Printer object is currently
- configured to support 'en-us' natural language does not mean that the
- Printer object should reject a job if the client supplies a job name
- that is in 'fr-ca'.
-
- The "natural-language-configured" attribute identifies the one
- supported natural language for generated messages which is the native
- natural language given the current configuration of the IPP object
- (administrator defined).
-
- Attributes of type 'text' and 'name' are populated from different
- sources. These attributes can be categorized into following groups
- (depending on the source of the attribute):
-
- 1. Some attributes are supplied by the client (e.g., the client
- supplied "job-name", "document-name", and "requesting-user-
- name" operation attributes along with the corresponding Job
- object's "job-name" and "job-originating-user-name"
- attributes). The IPP object MUST accept these attributes in
- any natural language no matter what the set of supported
- languages for generated messages
- 2. Some attributes are supplied by the system administrator (e.g.,
- the Printer object's "printer-name" and "printer-location"
- attributes). These too can be in any natural language. If the
- natural language for these attributes is different than what a
- client requests, then they must be reported using the Natural
- Language Override mechanism.
- 3. Some attributes are supplied by the device manufacturer (e.g.,
- the Printer object's "printer-make-and-model" attribute).
- These too can be in any natural language. If the natural
- language for these attributes is different than what a client
- requests, then they must be reported using the Natural Language
- Override mechanism.
- 4. Some attributes are supplied by the operator (e.g., the Job
- object's "job-message-from-operator" attribute). These too can
- be in any natural language. If the natural language for these
- attributes is different than what a client requests, then they
- must be reported using the Natural Language Override mechanism.
- 5. Some attributes are generated by the IPP object (e.g., the Job
- object's "job-state-message" attribute, the Printer object's
- "printer-state-message" attribute, and the "status-message"
- operation attribute). These attributes can only be in one of
- the "generated-natural-language-supported" natural languages.
- If a client requests some natural language for these attributes
- other than one of the supported values, the IPP object SHOULD
-
-
-
-
-
-Hastings, et al. Standards Track [Page 156]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- respond using the value of the "natural-language-configured"
- attribute (using the Natural Language Override mechanism if
- needed).
-
- The 'text' and 'name' attributes specified in this version of this
- document (additional ones will be registered according to the
- procedures in Section 6) are:
-
- Attributes Source
-
- Operation Attributes:
- job-name (name) client
- document-name (name) client
- requesting-user-name (name) client
- status-message (text) Job or Printer object
- detailed-status-message (text) Job or Printer object -
- see rule 1
- document-access-error (text) Job or Printer object -
- see rule 1
-
- Job Template Attributes:
- job-hold-until (keyword | name) client matches
- administrator-configured
- job-hold-until-default (keyword | name) client matches
- administrator-configured
- job-hold-until-supported (keyword | client matches
- name) administrator-configured
- job-sheets (keyword | name) client matches
- administrator-configured
- job-sheets-default (keyword | name) client matches
- administrator-configured
- job-sheets-supported (keyword | name) client matches
- administrator-configured
- media (keyword | name) client matches
- administrator-configured
- media-default (keyword | name) client matches
- administrator-configured
- media-supported (keyword | name) client matches
- administrator-configured
- media-ready (keyword | name) client matches
- administrator-configured
-
- Job Description Attributes:
- job-name (name) client or Printer object
- job-originating-user-name (name) Printer object
- job-state-message (text) Job or Printer object
- output-device-assigned (name(127)) administrator
- job-message-from-operator (text(127)) operator
-
-
-
-Hastings, et al. Standards Track [Page 157]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- job-detailed-status-messages (1setOf Job or Printer object -
- text) see rule 1
- job-document-access-errors (1setOf Job or Printer object -
- text) see rule 1
-
- Printer Description Attributes:
- printer-name (name(127)) administrator
- printer-location (text(127)) administrator
- printer-info (text(127)) administrator
- printer-make-and-model (text(127)) administrator or
- manufacturer
- printer-state-message (text) Printer object
- printer-message-from-operator operator
- (text(127))
-
- Rule 1 - Neither the Printer nor the client localizes these message
- attributes, since they are intended for use by the system
- administrator or other experienced technical persons.
-
-8. Security Considerations
-
- It is difficult to anticipate the security risks that might exist in
- any given IPP environment. For example, if IPP is used within a given
- corporation over a private network, the risks of exposing document
- data may be low enough that the corporation will choose not to use
- encryption on that data. However, if the connection between the
- client and the IPP object is over a public network, the client may
- wish to protect the content of the information during transmission
- through the network with encryption.
-
- Furthermore, the value of the information being printed may vary from
- one IPP environment to the next. Printing payroll checks, for
- example, would have a different value than printing public
- information from a file. There is also the possibly of denial-of-
- service attacks, but denial-of-service attacks against printing
- resources are not well understood and there is no published
- precedents regarding this scenario.
-
- Once the authenticated identity of the requester has been supplied to
- the IPP object, the object uses that identity to enforce any
- authorization policy that might be in place. For example, one site's
- policy might be that only the job owner is allowed to cancel a job.
- The details and mechanisms to set up a particular access control
- policy are not part of IPP/1.1, and must be established via some
- other type of administrative or access control framework. However,
- there are operation status codes that allow an IPP server to return
- information back to a client about any potential access control
- violations for an IPP object.
-
-
-
-Hastings, et al. Standards Track [Page 158]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- During a create operation, the client's identity is recorded in the
- Job object in an implementation-defined attribute. This information
- can be used to verify a client's identity for subsequent operations
- on that Job object in order to enforce any access control policy that
- might be in effect. See section 8.3 below for more details.
-
- Since the security levels or the specific threats that an IPP system
- administrator may be concerned with cannot be anticipated, IPP MUST
- be capable of operating with different security mechanisms and
- security policies as required by the individual installation.
- Security policies might vary from very strong, to very weak, to none
- at all, and corresponding security mechanisms will be required.
-
-8.1 Security Scenarios
-
- The following sections describe specific security attacks for IPP
- environments. Where examples are provided they should be considered
- illustrative of the environment and not an exhaustive set. Not all of
- these environments will necessarily be addressed in initial
- implementations of IPP.
-
-8.1.1 Client and Server in the Same Security Domain
-
- This environment is typical of internal networks where traditional
- office workers print the output of personal productivity applications
- on shared work-group printers, or where batch applications print
- their output on large production printers. Although the identity of
- the user may be trusted in this environment, a user might want to
- protect the content of a document against such attacks as
- eavesdropping, replaying or tampering.
-
-8.1.2 Client and Server in Different Security Domains
-
- Examples of this environment include printing a document created by
- the client on a publicly available printer, such as at a commercial
- print shop; or printing a document remotely on a business associate's
- printer. This latter operation is functionally equivalent to sending
- the document to the business associate as a facsimile. Printing
- sensitive information on a Printer in a different security domain
- requires strong security measures. In this environment authentication
- of the printer is required as well as protection against unauthorized
- use of print resources. Since the document crosses security domains,
- protection against eavesdropping and document tampering are also
- required. It will also be important in this environment to protect
- Printers against "spamming" and malicious document content.
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 159]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-8.1.3 Print by Reference
-
- When the document is not stored on the client, printing can be done
- by reference. That is, the print request can contain a reference, or
- pointer, to the document instead of the actual document itself (see
- sections 3.2.2 and 3.3.2). Standard methods currently do not exist
- for remote entities to "assume" the credentials of a client for
- forwarding requests to a 3rd party. It is anticipated that Print-By-
- Reference will be used to access "public" documents and that
- sophisticated methods for authenticating "proxies" is not specified
- in this document.
-
-8.2 URIs in Operation, Job, and Printer attributes
-
- The "printer-uri-supported" attribute contains the Printer object's
- URI(s). Its companion attribute, "uri-security-supported",
- identifies the security mechanism used for each URI listed in the
- "printer-uri-supported" attribute. For each Printer operation
- request, a client MUST supply only one URI in the "printer-uri"
- operation attribute. In other words, even though the Printer
- supports more than one URI, the client only interacts with the
- Printer object using one if its URIs. This duality is not needed for
- Job objects, since the Printer objects is the factory for Job
- objects, and the Printer object will generate the correct URI for new
- Job objects depending on the Printer object's security configuration.
-
-8.3 URIs for each authentication mechanisms
-
- Each URI has an authentication mechanism associated with it. If the
- URI is the i'th element of "printer-uri-supported", then
- authentication mechanism is the "i th" element of "uri-
- authentication-supported". For a list of possible authentication
- mechanisms, see section 4.4.2.
-
- The Printer object uses an authentication mechanism to determine the
- name of the user performing an operation. This user is called the
- "authenticated user". The credibility of authentication depends on
- the mechanism that the Printer uses to obtain the user's name. When
- the authentication mechanism is 'none', all authenticated users are
- "anonymous".
-
- During job creation operations, the Printer initializes the value of
- the "job-originating-user-name" attribute (see section 4.3.6) to be
- the authenticated user. The authenticated user is this case is called
- the "job owner".
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 160]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- If an implementation can be configured to support more than one
- authentication mechanism (see section 4.4.2), then it MUST implement
- rules for determining equality of authenticated user names which have
- been authenticated via different authentication mechanisms. One
- possible policy is that identical names that are authenticated via
- different mechanisms are different. For example, a user can cancel
- his job only if he uses the same authentication mechanism for both
- Cancel-Job and Print-Job. Another policy is that identical names
- that are authenticated via different mechanism are the same if the
- authentication mechanism for the later operation is not less strong
- than the authentication mechanism for the earlier job creation
- operation. For example, a user can cancel his job only if he uses
- the same or stronger authentication mechanism for Cancel-Job and
- Print-Job. With this second policy a job submitted via 'requesting-
- user-name' authentication could be canceled via 'digest'
- authentication. With the first policy, the job could not be canceled
- in this way.
-
- A client is able to determine the authentication mechanism used to
- create a job. It is the i'th value of the Printer's "uri-
- authentication-supported" attribute (see section 4.4.2), where i is
- the index of the element of the Printer's "printer-uri-supported"
- attribute (see section 4.4.1) equal to the job's "job-printer-uri"
- attribute (see section 4.3.3).
-
-8.4 Restricted Queries
-
- In many IPP operations, a client supplies a list of attributes to be
- returned in the response. For security reasons, an IPP object may be
- configured not to return all attributes (or all values) that a client
- requests. The job attributes returned MAY depend on whether the
- requesting user is the same as the user that submitted the job. The
- IPP object MAY even return none of the requested attributes. In such
- cases, the status returned is the same as if the object had returned
- all requested attributes. The client cannot tell by such a response
- whether the requested attribute was present or absent on the object.
-
-8.5 Operations performed by operators and system administrators
-
- For the three printer operations Pause-Printer, Resume-Printer, and
- Purge-Jobs (see sections 3.2.7, 3.2.8 and 3.2.9), the requesting user
- is intended to be an operator or administrator of the Printer object
- (see section 1). Otherwise, the IPP Printer MUST reject the
- operation and return: 'client-error-forbidden', 'client-error-not-
- authenticated', or 'client-error-not-authorized' as appropriate. For
- operations on jobs, the requesting user is intended to be the job
-
-
-
-
-
-Hastings, et al. Standards Track [Page 161]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- owner or may be an operator or administrator of the Printer object.
- The means for authorizing an operator or administrator of the Printer
- object are not specified in this document.
-
-8.6 Queries on jobs submitted using non-IPP protocols
-
- If the device that an IPP Printer is representing is able to accept
- jobs using other job submission protocols in addition to IPP, it is
- RECOMMENDED that such an implementation at least allow such "foreign"
- jobs to be queried using Get-Jobs returning "job-id" and "job-uri" as
- 'unknown'. Such an implementation NEED NOT support all of the same
- IPP job attributes as for IPP jobs. The IPP object returns the
- 'unknown' out-of-band value for any requested attribute of a foreign
- job that is supported for IPP jobs, but not for foreign jobs.
-
- It is further RECOMMENDED, that the IPP Printer generate "job-id" and
- "job-uri" values for such "foreign jobs", if possible, so that they
- may be targets of other IPP operations, such as Get-Job-Attributes
- and Cancel-Job. Such an implementation also needs to deal with the
- problem of authentication of such foreign jobs. One approach would
- be to treat all such foreign jobs as belonging to users other than
- the user of the IPP client. Another approach would be for the
- foreign job to belong to 'anonymous'. Only if the IPP client has
- been authenticated as an operator or administrator of the IPP Printer
- object, could the foreign jobs be queried by an IPP request.
- Alternatively, if the security policy is to allow users to query
- other users' jobs, then the foreign jobs would also be visible to an
- end-user IPP client using Get-Jobs and Get-Job-Attributes.
-
-9. References
-
- [ASME-Y14.1M] Metric Drawing Sheet Size and Format, ASME Y14.1M-1995.
- This standard defines metric sheet sizes and formats
- for engineering drawings.
-
- [ASCII] Coded Character Set - 7-bit American Standard Code for
- Information Interchange (ASCII), ANSI X3.4-1986. This
- standard is the specification of the US-ASCII charset.
-
- [BCP-11] Bradner S. and R. Hovey, "The Organizations Involved in
- the IETF Standards Process", BCP 11, RFC 2028, October
- 1996.
-
- [HTPP] J. Barnett, K. Carter, R. DeBry, "Initial Draft -
- Hypertext Printing Protocol - HTPP/1.0", October 1996,
- ftp://ftp.pwg.org/pub/pwg/ipp/historic/htpp/overview.ps.gz
-
-
-
-
-
-Hastings, et al. Standards Track [Page 162]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- [IANA-CON] Narten, T. and H. Alvestrand, "Guidelines for Writing
- an IANA Considerations Section in RFCs", BCP 26, RFC
- 2434, October 1998.
-
- [IANA-CS] IANA Registry of Coded Character Sets:
- ftp://ftp.isi.edu/in-notes/iana/assignments/character-
- sets
-
- [IANA-MT] IANA Registry of Media Types: ftp://ftp.isi.edu/in-
- notes/iana/assignments/media-types/
-
- [IPP-IIG] Hastings, T., Manros, C., Kugler, C., Holst, H., and P.
- Zehler, "Internet Printing Protocol/1.1: draft-ietf-
- ipp-implementers-guide-v11-01.txt, work in progress,
- May 30, 2000.
-
- [ISO10646-1] ISO/IEC 10646-1:1993, "Information technology --
- Universal Multiple-Octet Coded Character Set (UCS) -
- Part 1: Architecture and Basic Multilingual Plane,
- JTC1/SC2."
-
- [ISO8859-1] ISO/IEC 8859-1:1987, "Information technology -- 8-bit
- One-Byte Coded Character Set - Part 1: Latin Alphabet
- Nr 1", 1987, JTC1/SC2.
-
- [ISO10175] ISO/IEC 10175 Document Printing Application (DPA), June
- 1996.
-
- [LDPA] T. Hastings, S. Isaacson, M. MacKay, C. Manros, D.
- Taylor, P. Zehler, "LDPA - Lightweight Document
- Printing Application", October 1996,
- ftp://ftp.pwg.org/pub/pwg/ipp/historic/ldpa/ldpa8.pdf.gz
-
- [P1387.4] Kirk, M. (editor), POSIX System Administration - Part
- 4: Printing Interfaces, POSIX 1387.4 D8, 1994.
-
- [PSIS] Herriot, R. (editor), X/Open A Printing System
- Interoperability Specification (PSIS), August 1995.
-
- [PWG] Printer Working Group, http://www.pwg.org.
-
- [RFC1035] Mockapetris, P., "Domain Names - Implementation and
- Specification", STD 13, RFC 1035, November 1987.
-
- [RFC1179] McLaughlin, L., "Line Printer Daemon Protocol", RFC
- 1179, August 1990.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 163]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- [RFC1759] Smith, R., Wright, F., Hastings, T., Zilles, S. and J.
- Gyllenskog, "Printer MIB", RFC 1759, March 1995.
-
- [RFC1766] Alvestrand, H., "Tags for the Identification of
- Languages", RFC 1766, March 1995.
-
- [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format
- Specification version 1.3 ", RFC 1951, May 1996.
-
- [RFC1952] Deutsch, P., "GZIP file format specification version
- 4.3", RFC 1952, May 1996.
-
- [RFC1977] Schryver, V., "PPP BSD Compression Protocol", RFC 1977,
- August 1996.
-
- [RFC2026] Bradner, S., "The Internet Standards Process --
- Revision 3", BCP 9, RFC 2026, October 1996.
-
- [RFC2045] Freed, N. and N. Borenstein, ", Multipurpose Internet
- Mail Extensions (MIME) Part One: Format of Internet
- Message Bodies", RFC 2045, November 1996.
-
- [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet
- Mail Extensions (MIME) Part Two: Media Types", RFC
- 2046, November 1996.
-
- [RFC2048] Freed, N., Klensin, J. and J. Postel, "Multipurpose
- Internet Mail Extension (MIME) Part Four: Registration
- Procedures", RFC 2048, November 1996.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2228] Horowitz, M. and S. Lunt, "FTP Security Extensions",
- RFC 2228, October 1997.
-
- [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version
- 1.0", RFC 2246, January 1999.
-
- [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
- Languages" BCP 18, RFC 2277, January 1998.
-
- [RFC2278] Freed, N. and J. Postel: "IANA CharSet Registration
- Procedures", BCP 19, RFC 2278, January 1998.
-
- [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO
- 10646", RFC 2279, January 1998.
-
-
-
-
-Hastings, et al. Standards Track [Page 164]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- [RFC2316] Bellovin, S., "Report of the IAB Security Architecture
- Workshop", RFC 2316, April 1998.
-
- [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
- Resource Identifiers (URI): Generic Syntax", RFC 2396,
- August 1998.
-
- [RFC2565] Herriot, R., Butler, S., Moore, P. and R. Turner,
- "Internet Printing Protocol/1.0: Encoding and
- Transport", RFC 2565, April 1999.
-
- [RFC2566] deBry, R., Hastings, T., Herriot, R., Isaacson, S. and
- P. Powell, "Internet Printing Protocol/1.0: Model and
- Semantics", RFC 2566, April 1999.
-
- [RFC2567] Wright, D., "Design Goals for an Internet Printing
- Protocol", RFC 2567, April 1999.
-
- [RFC2568] Zilles, S., "Rationale for the Structure and Model and
- Protocol for the Internet Printing Protocol", RFC 2568,
- April 1999.
-
- [RFC2569] Herriot, R., Hastings, T., Jacobs, N. and J. Martin,
- "Mapping between LPD and IPP Protocols", RFC 2569,
- April 1999.
-
- [RFC2579] McCloghrie, K., Perkins, D. and J. Schoenwaelder,
- "Textual Conventions for SMIv2", STD 58, RFC 2579,
- April 1999.
-
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
- Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext
- Transfer Protocol - HTTP/1.1", RFC 2616, June 1999.
-
- [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence,
- S., Leach, P., Luotonen, A. and L. Stewart, "HTTP
- Authentication: Basic and Digest Access
- Authentication", RFC 2617, June 1999.
-
- [RFC2639] Hastings, T. and C. Manros, "Internet Printing
- Protocol/1.0: Encoding and Transport", RFC 2639, July
- 1999.
-
- [RFC2910] Herriot, R., Butler, S., Moore, P., Turner, R. and J.
- Wenn, "Internet Printing Protocol/1.1: Encoding and
- Transport", RFC 2910, September 2000.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 165]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- [SSL] Netscape, The SSL Protocol, Version 3, (Text version
- 3.02), November 1996.
-
- [SWP] P. Moore, B. Jahromi, S. Butler, "Simple Web Printing
- SWP/1.0", May 7, 1997,
- ftp://ftp.pwg.org/pub/pwg/ipp/new_PRO/swp9705.pdf
-
-10. Authors' Addresses
-
- Scott A. Isaacson, Editor
- Novell, Inc.
- 122 E 1700 S
- Provo, UT 84606
-
- Phone: 801-861-7366
- Fax: 801-861-2517
- EMail: sisaacson@novell.com
-
-
- Tom Hastings
- Xerox Corporation
- 737 Hawaii St. ESAE 231
- El Segundo, CA 90245
-
- Phone: 310-333-6413
- Fax: 310-333-5514
- EMail: hastings@cp10.es.xerox.com
-
-
- Robert Herriot
- Xerox Corp.
- 3400 Hill View Ave, Building 1
- Palo Alto, CA 94304
-
- Phone: 650-813-7696
- Fax: 650-813-6860
- EMail: robert.herriot@pahv.xerox.com
-
-
- Roger deBry
- Utah Valley State College
- Orem, UT 84058
-
- Phone: (801) 222-8000
- EMail: debryro@uvsc.edu
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 166]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Patrick Powell
- Astart Technologies
- 9475 Chesapeake Dr., Suite D
- San Diego, CA 95123
-
- Phone: (619) 874-6543
- Fax: (619) 279-8424
- EMail: papowell@astart.com
-
- IPP Web Page: http://www.pwg.org/ipp/
- IPP Mailing List: ipp@pwg.org
-
- To subscribe to the ipp mailing list, send the following email:
- 1) send it to majordomo@pwg.org
- 2) leave the subject line blank
- 3) put the following two lines in the message body:
- subscribe ipp
- end
-
- Implementers of this specification document are encouraged to join
- IPP Mailing List in order to participate in any discussions of
- clarification issues and review of registration proposals for
- additional attributes and values.
-
- Other Participants:
-
- Chuck Adams - Tektronix Shivaun Albright - HP
- Stefan Andersson - Axis Jeff Barnett - IBM
- Ron Bergman - Hitachi Koki Imaging Dennis Carney - IBM
- Systems
- Keith Carter - IBM Angelo Caruso - Xerox
- Rajesh Chawla - TR Computing Nancy Chen - Okidata
- Solutions
- Josh Cohen - Microsoft Jeff Copeland - QMS
- Andy Davidson - Tektronix Roger deBry - IBM
- Maulik Desai - Auco Mabry Dozier - QMS
- Lee Farrell - Canon Information Satoshi Fujitami - Ricoh
- Systems
- Steve Gebert - IBM Sue Gleeson - Digital
- Charles Gordon - Osicom Brian Grimshaw - Apple
- Jerry Hadsell - IBM Richard Hart - Digital
- Tom Hastings - Xerox Henrik Holst - I-data
- Stephen Holmstead Zhi-Hong Huang - Zenographics
- Scott Isaacson - Novell Babek Jahromi - Microsoft
- Swen Johnson - Xerox David Kellerman - Northlake
- Software
- Robert Kline - TrueSpectra Charles Kong - Panasonic
- Carl Kugler - IBM Dave Kuntz - Hewlett-Packard
-
-
-
-Hastings, et al. Standards Track [Page 167]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Takami Kurono - Brother Rick Landau - Digital
- Scott Lawrence - Agranot Systems Greg LeClair - Epson
- Dwight Lewis - Lexmark Harry Lewis - IBM
- Tony Liao - Vivid Image Roy Lomicka - Digital
- Pete Loya - HP Ray Lutz - Cognisys
- Mike MacKay - Novell, Inc. David Manchala - Xerox
- Carl-Uno Manros - Xerox Jay Martin - Underscore
- Stan McConnell - Xerox Larry Masinter - Xerox
- Sandra Matts - Hewlett Packard Peter Michalek - Shinesoft
- Ira McDonald - High North Inc. Mike Moldovan - G3 Nova
- Tetsuya Morita - Ricoh Yuichi Niwa - Ricoh
- Pat Nogay - IBM Ron Norton - Printronics
- Hugo Parra, Novell Bob Pentecost - Hewlett-Packard
- Patrick Powell - Astart Jeff Rackowitz - Intermec
- Technologies
- Eric Random - Peerless Rob Rhoads - Intel
- Xavier Riley - Xerox Gary Roberts - Ricoh
- David Roach - Unisys Stuart Rowley - Kyocera
- Yuji Sasaki - Japan Computer Richard Schneider - Epson
- Industry
- Kris Schoff - HP Katsuaki Sekiguchi - Canon
- Bob Setterbo - Adobe Gail Songer - Peerless
- Hideki Tanaka - Cannon Devon Taylor - Novell
- Mike Timperman - Lexmark Atsushi Uchino - Epson
- Shigeru Ueda - Canon Bob Von Andel - Allegro Software
- William Wagner - NetSilicon/DPI Jim Walker - DAZEL
- Chris Wellens - Interworking Labs Trevor Wells - Hewlett Packard
- Craig Whittle - Sharp Labs Rob Whittle - Novell, Inc.
- Jasper Wong - Xionics Don Wright - Lexmark
- Michael Wu - Heidelberg Digital Rick Yardumian - Xerox
- Michael Yeung - Toshiba Lloyd Young - Lexmark
- Atsushi Yuki - Kyocera Peter Zehler - Xerox
- William Zhang- Canon Information Frank Zhao - Panasonic
- Systems
- Steve Zilles - Adobe Rob Zirnstein - Canon Information
- Systems
-
-11. Formats for IPP Registration Proposals
-
- In order to propose an IPP extension for registration, the proposer
- must submit an application to IANA by email to "iana@iana.org" or by
- filling out the appropriate form on the IANA web pages
- (http://www.iana.org). This section specifies the required
- information and the formats for proposing registrations of extensions
- to IPP as provided in Section 6 for:
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 168]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 1. type2 'keyword' attribute values
- 2. type3 'keyword' attribute values
- 3. type2 'enum' attribute values
- 4. type3 'enum' attribute values
- 5. attributes
- 6. attribute syntaxes
- 7. operations
- 8. status codes
- 9. out-of-band attribute values
-
-11.1 Type2 keyword attribute values registration,
-
- Type of registration: type2 keyword attribute value
- Name of attribute to which this keyword specification is to be added:
- Proposed keyword name of this keyword value:
- Specification of this keyword value (follow the style of IPP Model
- Section 4.1.2.3):
- Name of proposer:
- Address of proposer:
- Email address of proposer:
-
- Note: For type2 keywords, the Designated Expert will be the point of
- contact for the approved registration specification, if any
- maintenance of the registration specification is needed.
-
-11.2 Type3 keyword attribute values registration
-
- Type of registration: type3 keyword attribute value
- Name of attribute to which this keyword specification is to be added:
- Proposed keyword name of this keyword value:
- Specification of this keyword value (follow the style of IPP Model
- Section 4.1.2.3):
- Name of proposer:
- Address of proposer:
- Email address of proposer:
-
- Note: For type3 keywords, the proposer will be the point of contact
- for the approved registration specification, if any maintenance of
- the registration specification is needed.
-
-11.3 Type2 enum attribute values registration
-
- Type of registration: type2 enum attribute value
- Name of attribute to which this enum specification is to be added:
- Keyword symbolic name of this enum value:
- Numeric value (to be assigned by the IPP Designated Expert in
- consultation with IANA):
-
-
-
-
-Hastings, et al. Standards Track [Page 169]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Specification of this enum value (follow the style of IPP Model
- Section 4.1.4):
- Name of proposer:
- Address of proposer:
- Email address of proposer:
-
- Note: For type2 enums, the Designated Expert will be the point of
- contact for the approved registration specification, if any
- maintenance of the registration specification is needed.
-
-11.4 Type3 enum attribute values registration
-
- Type of registration: type3 enum attribute value
- Name of attribute to which this enum specification is to be added:
- Keyword symbolic name of this enum value:
- Numeric value (to be assigned by the IPP Designated Expert in
- consultation with IANA):
- Specification of this enum value (follow the style of IPP Model
- Section 4.1.4):
- Name of proposer:
- Address of proposer:
- Email address of proposer:
-
- Note: For type3 enums, the proposer will be the point of contact for
- the approved registration specification, if any maintenance of the
- registration specification is needed.
-
-11.5 Attribute registration
-
- Type of registration: attribute
- Proposed keyword name of this attribute:
- Types of attribute (Operation, Job Template, Job Description, Printer
- Description):
- Operations to be used with if the attribute is an operation attribute:
- Object (Job, Printer, etc. if bound to an object):
- Attribute syntax(es) (include 1setOf and range as in Section 4.2):
- If attribute syntax is 'keyword' or 'enum', is it type2 or type3:
- If this is a Printer attribute, MAY the value returned depend on
- "document-format" (See Section 6.2):
- If this is a Job Template attribute, how does its specification depend
- on the value of the "multiple-document-handling" attribute:
- Specification of this attribute (follow the style of IPP Model Section
- 4.2):
- Name of proposer:
- Address of proposer:
- Email address of proposer:
-
-
-
-
-
-Hastings, et al. Standards Track [Page 170]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Note: For attributes, the IPP Designated Expert will be the point of
- contact for the approved registration specification, if any
- maintenance of the registration specification is needed.
-
-11.6 Attribute Syntax registration
-
- Type of registration: attribute syntax
- Proposed name of this attribute syntax:
- Type of attribute syntax (integer, octetString, character-string, see
- [RFC2910]):
- Numeric tag according to [RFC2910] (to be assigned by the IPP
- Designated Expert in consultation with IANA):
- Specification of this attribute (follow the style of IPP Model Section
- 4.1):
- Name of proposer:
- Address of proposer:
- Email address of proposer:
-
- Note: For attribute syntaxes, the IPP Designated Expert will be the
- point of contact for the approved registration specification, if any
- maintenance of the registration specification is needed.
-
-11.7 Operation registration
-
- Type of registration: operation
- Proposed name of this operation:
- Numeric operation-id value according to section 4.4.15 (to be assigned
- by the IPP Designated Expert in consultation with IANA):
- Object Target (Job, Printer, etc. that operation is upon):
- Specification of this operation (follow the style of IPP Model Section
- 3):
- Name of proposer:
- Address of proposer:
- Email address of proposer:
-
- Note: For operations, the IPP Designated Expert will be the point of
- contact for the approved registration specification, if any
- maintenance of the registration specification is needed.
-
-11.8 Attribute Group registration
-
- Type of registration: attribute group
- Proposed name of this attribute group:
- Numeric tag according to [RFC2910] (to be assigned by the IPP
- Designated Expert in consultation with IANA):
- Operation requests and group number for each operation in which the
- attribute group occurs:
-
-
-
-
-Hastings, et al. Standards Track [Page 171]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Operation responses and group number for each operation in which the
- attribute group occurs:
- Specification of this attribute group (follow the style of IPP Model
- Section 3):
- Name of proposer:
- Address of proposer:
- Email address of proposer:
-
- Note: For attribute groups, the IPP Designated Expert will be the
- point of contact for the approved registration specification, if any
- maintenance of the registration specification is needed.
-
-11.9 Status code registration
-
- Type of registration: status code
- Keyword symbolic name of this status code value:
- Numeric value (to be assigned by the IPP Designated Expert in
- consultation with IANA):
- Operations that this status code may be used with:
- Specification of this status code (follow the style of IPP Model
- Section 13 APPENDIX B: Status Codes and Suggested Status Code
- Messages):
- Name of proposer:
- Address of proposer:
- Email address of proposer:
-
- Note: For status codes, the Designated Expert will be the point of
- contact for the approved registration specification, if any
- maintenance of the registration specification is needed.
-
-11.10 Out-of-band Attribute Value registration
-
- Type of registration: out-of-band attribute value
- Proposed name of this out-of-band attribute value:
- Numeric tag according to [RFC2910] (to be assigned by the IPP Designated
- Expert in consultation with IANA):
- Operations that this out-of-band attribute value may be used with:
- Attributes that this out-of-band attribute value may be used with:
- Specification of this out-of-band attribute value (follow the style of
- the beginning of IPP Model Section 4.1):
- Name of proposer:
- Address of proposer:
- Email address of proposer:
-
- Note: For out-of-band attribute values, the IPP Designated Expert
- will be the point of contact for the approved registration
- specification, if any maintenance of the registration specification
- is needed.
-
-
-
-Hastings, et al. Standards Track [Page 172]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-12. APPENDIX A: Terminology
-
- This specification document uses the terminology defined in this
- section.
-
-12.1 Conformance Terminology
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT",
- "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
- interpreted as described in RFC 2119 [RFC2119].
-
-12.1.1 NEED NOT
-
- This term is not included in RFC 2119. The verb "NEED NOT" indicates
- an action that the subject of the sentence does not have to implement
- in order to claim conformance to the standard. The verb "NEED NOT"
- is used instead of "MAY NOT" since "MAY NOT" sounds like a
- prohibition.
-
-12.2 Model Terminology
-
-12.2.1 Keyword
-
- Keywords are used within this document as identifiers of semantic
- entities within the abstract model (see section 4.1.2.3). Attribute
- names, some attribute values, attribute syntaxes, and attribute group
- names are represented as keywords.
-
-12.2.2 Attributes
-
- An attribute is an item of information that is associated with an
- instance of an IPP object. An attribute consists of an attribute
- name and one or more attribute values. Each attribute has a specific
- attribute syntax. All object attributes are defined in section 4 and
- all operation attributes are defined in section 3.
-
- Job Template Attributes are described in section 4.2. The client
- optionally supplies Job Template attributes in a create request
- (operation requests that create Job objects). The Printer object has
- associated attributes which define supported and default values for
- the Printer.
-
-12.2.2.1 Attribute Name
-
- Each attribute is uniquely identified in this document by its
- attribute name. An attribute name is a keyword. The keyword
- attribute name is given in the section header describing that
-
-
-
-
-Hastings, et al. Standards Track [Page 173]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- attribute. In running text in this document, attribute names are
- indicated inside double quotation marks (") where the quotation marks
- are not part of the keyword itself.
-
-12.2.2.2 Attribute Group Name
-
- Related attributes are grouped into named groups. The name of the
- group is a keyword. The group name may be used in place of naming
- all the attributes in the group explicitly. Attribute groups are
- defined in section 3.
-
-12.2.2.3 Attribute Value
-
- Each attribute has one or more values. Attribute values are
- represented in the syntax type specified for that attribute. In
- running text in this document, attribute values are indicated inside
- single quotation marks ('), whether their attribute syntax is
- keyword, integer, text, etc. where the quotation marks are not part
- of the value itself.
-
-12.2.2.4 Attribute Syntax
-
- Each attribute is defined using an explicit syntax type. In this
- document, each syntax type is defined as a keyword with specific
- meaning. The "Encoding and Transport" document [RFC2910] indicates
- the actual "on-the-wire" encoding rules for each syntax type.
- Attribute syntax types are defined in section 4.1.
-
-12.2.3 Supports
-
- By definition, a Printer object supports an attribute only if that
- Printer object responds with the corresponding attribute populated
- with some value(s) in a response to a query for that attribute. A
- Printer object supports an attribute value if the value is one of the
- Printer object's "supported values" attributes. The device behind a
- Printer object may exhibit a behavior that corresponds to some IPP
- attribute, but if the Printer object, when queried for that
- attribute, doesn't respond with the attribute, then as far as IPP is
- concerned, that implementation does not support that feature. If the
- Printer object's "xxx-supported" attribute is not populated with a
- particular value (even if that value is a legal value for that
- attribute), then that Printer object does not support that particular
- value.
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 174]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- A conforming implementation MUST support all REQUIRED attributes.
- However, even for REQUIRED attributes, conformance to IPP does not
- mandate that all implementations support all possible values
- representing all possible job processing behaviors and features. For
- example, if a given instance of a Printer supports only certain
- document formats, then that Printer responds with the "document-
- format-supported" attribute populated with a set of values, possibly
- only one, taken from the entire set of possible values defined for
- that attribute. This limited set of values represents the Printer's
- set of supported document formats. Supporting an attribute and some
- set of values for that attribute enables IPP end users to be aware of
- and make use of those features associated with that attribute and
- those values. If an implementation chooses to not support an
- attribute or some specific value, then IPP end users would have no
- ability to make use of that feature within the context of IPP itself.
- However, due to existing practice and legacy systems which are not
- IPP aware, there might be some other mechanism outside the scope of
- IPP to control or request the "unsupported" feature (such as embedded
- instructions within the document data itself).
-
- For example, consider the "finishings-supported" attribute.
-
- 1) If a Printer object is not physically capable of stapling, the
- "finishings-supported" attribute MUST NOT be populated with the
- value of 'staple'.
- 2) A Printer object is physically capable of stapling, however an
- implementation chooses not to support stapling in the IPP
- "finishings" attribute. In this case, 'staple' MUST NOT be a
- value in the "finishings-supported" Printer object attribute.
- Without support for the value 'staple', an IPP end user would
- have no means within the protocol itself to request that a Job
- be stapled. However, an existing document data formatter might
- be able to request that the document be stapled directly with
- an embedded instruction within the document data. In this
- case, the IPP implementation does not "support" stapling,
- however the end user is still able to have some control over
- the stapling of the completed job.
- 3) A Printer object is physically capable of stapling, and an
- implementation chooses to support stapling in the IPP
- "finishings" attribute. In this case, 'staple' MUST be a value
- in the "finishings-supported" Printer object attribute. Doing
- so, would enable end users to be aware of and make use of the
- stapling feature using IPP attributes.
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 175]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Even though support for Job Template attributes by a Printer object
- is OPTIONAL, it is RECOMMENDED that if the device behind a Printer
- object is capable of realizing any feature or function that
- corresponds to an IPP attribute and some associated value, then that
- implementation SHOULD support that IPP attribute and value.
-
- The set of values in any of the supported value attributes is set
- (populated) by some administrative process or automatic sensing
- mechanism that is outside the scope of this IPP/1.1 document. For
- administrative policy and control reasons, an administrator may
- choose to make only a subset of possible values visible to the end
- user. In this case, the real output device behind the IPP Printer
- abstraction may be capable of a certain feature, however an
- administrator is specifying that access to that feature not be
- exposed to the end user through the IPP protocol. Also, since a
- Printer object may represent a logical print device (not just a
- physical device) the actual process for supporting a value is
- undefined and left up to the implementation. However, if a Printer
- object supports a value, some manual human action may be needed to
- realize the semantic action associated with the value, but no end
- user action is required.
-
- For example, if one of the values in the "finishings-supported"
- attribute is 'staple', the actual process might be an automatic
- staple action by a physical device controlled by some command sent to
- the device. Or, the actual process of stapling might be a manual
- action by an operator at an operator attended Printer object.
-
- For another example of how supported attributes function, consider a
- system administrator who desires to control all print jobs so that no
- job sheets are printed in order to conserve paper. To force no job
- sheets, the system administrator sets the only supported value for
- the "job-sheets-supported" attribute to 'none'. In this case, if a
- client requests anything except 'none', the create request is
- rejected or the "job-sheets" value is ignored (depending on the value
- of "ipp-attribute-fidelity"). To force the use of job start/end
- sheets on all jobs, the administrator does not include the value
- 'none' in the "job-sheets- supported" attribute. In this case, if a
- client requests 'none', the create request is rejected or the "job-
- sheets" value is ignored (again depending on the value of "ipp-
- attribute-fidelity").
-
-12.2.4 print-stream page
-
- A "print-stream page" is a page according to the definition of pages
- in the language used to express the document data.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 176]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-12.2.5 impression
-
- An "impression" is the image (possibly many print-stream pages in
- different configurations) imposed onto a single media page.
-
-13. APPENDIX B: Status Codes and Suggested Status Code Messages
-
- This section defines status code enum keywords and values that are
- used to provide semantic information on the results of an operation
- request. Each operation response MUST include a status code. The
- response MAY also contain a status message that provides a short
- textual description of the status. The status code is intended for
- use by automata, and the status message is intended for the human end
- user. Since the status message is an OPTIONAL component of the
- operation response, an IPP application (i.e., a browser, GUI, print
- driver or gateway) is NOT REQUIRED to examine or display the status
- message, since it MAY not be returned to the application.
-
- The prefix of the status keyword defines the class of response as
- follows:
-
- "informational" - Request received, continuing process
- "successful" - The action was successfully received, understood,
- and accepted
- "redirection" - Further action must be taken in order to complete
- the request
- "client-error" - The request contains bad syntax or cannot be
- fulfilled
- "server-error" - The IPP object failed to fulfill an apparently
- valid request
-
- As with type2 enums, IPP status codes are extensible. IPP clients
- are NOT REQUIRED to understand the meaning of all registered status
- codes, though such understanding is obviously desirable. However,
- IPP clients MUST understand the class of any status code, as
- indicated by the prefix, and treat any unrecognized response as being
- equivalent to the first status code of that class, with the exception
- that an unrecognized response MUST NOT be cached. For example, if an
- unrecognized status code of "client-error-xxx-yyy" is received by the
- client, it can safely assume that there was something wrong with its
- request and treat the response as if it had received a "client-
- error-bad-request" status code. In such cases, IPP applications
- SHOULD present the OPTIONAL message (if present) to the end user
- since the message is likely to contain human readable information
- which will help to explain the unusual status. The name of the enum
- is the suggested status message for US English.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 177]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- The status code values range from 0x0000 to 0x7FFF. The value ranges
- for each status code class are as follows:
-
- "successful" - 0x0000 to 0x00FF
- "informational" - 0x0100 to 0x01FF
- "redirection" - 0x0200 to 0x02FF
- "client-error" - 0x0400 to 0x04FF
- "server-error" - 0x0500 to 0x05FF
-
- The top half (128 values) of each range (0x0n40 to 0x0nFF, for n = 0
- to 5) is reserved for vendor use within each status code class.
- Values 0x0600 to 0x7FFF are reserved for future assignment by IETF
- standards track documents and MUST NOT be used.
-
-13.1 Status Codes
-
- Each status code is described below. Section 13.1.5.9 contains a
- table that indicates which status codes apply to which operations.
- The Implementer's Guide [IPP-IIG] describe the suggested steps for
- processing IPP attributes for all operations, including returning
- status codes.
-
-13.1.1 Informational
-
- This class of status code indicates a provisional response and is to
- be used for informational purposes only.
-
- There are no status codes defined in IPP/1.1 for this class of status
- code.
-
-13.1.2 Successful Status Codes
-
- This class of status code indicates that the client's request was
- successfully received, understood, and accepted.
-
-13.1.2.1 successful-ok (0x0000)
-
- The request has succeeded and no request attributes were substituted
- or ignored. In the case of a response to a create request, the
- 'successful-ok' status code indicates that the request was
- successfully received and validated, and that the Job object has been
- created; it does not indicate that the job has been processed. The
- transition of the Job object into the 'completed' state is the only
- indicator that the job has been printed.
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 178]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-13.1.2.2 successful-ok-ignored-or-substituted-attributes (0x0001)
-
- The request has succeeded, but some supplied (1) attributes were
- ignored or (2) unsupported values were substituted with supported
- values or were ignored in order to perform the operation without
- rejecting it. Unsupported attributes, attribute syntaxes, or values
- MUST be returned in the Unsupported Attributes group of the response
- for all operations. There is an exception to this rule for the query
- operations: Get-Printer-Attributes, Get-Jobs, and Get-Job-Attributes
- for the "requested-attributes" operation attribute only. When the
- supplied values of the "requested-attributes" operation attribute are
- requesting attributes that are not supported, the IPP object MAY, but
- is NOT REQUIRED to, return the "requested-attributes" attribute in
- the Unsupported Attribute response group (with the unsupported values
- only). See sections 3.1.7 and 3.2.1.2.
-
-13.1.2.3 successful-ok-conflicting-attributes (0x0002)
-
- The request has succeeded, but some supplied attribute values
- conflicted with the values of other supplied attributes. These
- conflicting values were either (1) substituted with (supported)
- values or (2) the attributes were removed in order to process the job
- without rejecting it. Attributes or values which conflict with other
- attributes and have been substituted or ignored MUST be returned in
- the Unsupported Attributes group of the response for all operations
- as supplied by the client. See sections 3.1.7 and 3.2.1.2.
-
-13.1.3 Redirection Status Codes
-
- This class of status code indicates that further action needs to be
- taken to fulfill the request.
-
- There are no status codes defined in IPP/1.1 for this class of status
- code.
-
-13.1.4 Client Error Status Codes
-
- This class of status code is intended for cases in which the client
- seems to have erred. The IPP object SHOULD return a message
- containing an explanation of the error situation and whether it is a
- temporary or permanent condition.
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 179]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-13.1.4.1 client-error-bad-request (0x0400)
-
- The request could not be understood by the IPP object due to
- malformed syntax (such as the value of a fixed length attribute whose
- length does not match the prescribed length for that attribute - see
- the Implementer's Guide [IPP-IIG] ). The IPP application SHOULD NOT
- repeat the request without modifications.
-
-13.1.4.2 client-error-forbidden (0x0401)
-
- The IPP object understood the request, but is refusing to fulfill it.
- Additional authentication information or authorization credentials
- will not help and the request SHOULD NOT be repeated. This status
- code is commonly used when the IPP object does not wish to reveal
- exactly why the request has been refused or when no other response is
- applicable.
-
-13.1.4.3 client-error-not-authenticated (0x0402)
-
- The request requires user authentication. The IPP client may repeat
- the request with suitable authentication information. If the request
- already included authentication information, then this status code
- indicates that authorization has been refused for those credentials.
- If this response contains the same challenge as the prior response,
- and the user agent has already attempted authentication at least
- once, then the response message may contain relevant diagnostic
- information. This status codes reveals more information than
- "client-error-forbidden".
-
-13.1.4.4 client-error-not-authorized (0x0403)
-
- The requester is not authorized to perform the request. Additional
- authentication information or authorization credentials will not help
- and the request SHOULD NOT be repeated. This status code is used
- when the IPP object wishes to reveal that the authentication
- information is understandable, however, the requester is explicitly
- not authorized to perform the request. This status codes reveals
- more information than "client-error-forbidden" and "client-error-
- not-authenticated".
-
-13.1.4.5 client-error-not-possible (0x0404)
-
- This status code is used when the request is for something that can
- not happen. For example, there might be a request to cancel a job
- that has already been canceled or aborted by the system. The IPP
- client SHOULD NOT repeat the request.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 180]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-13.1.4.6 client-error-timeout (0x0405)
-
- The client did not produce a request within the time that the IPP
- object was prepared to wait. For example, a client issued a Create-
- Job operation and then, after a long period of time, issued a Send-
- Document operation and this error status code was returned in
- response to the Send-Document request (see section 3.3.1). The IPP
- object might have been forced to clean up resources that had been
- held for the waiting additional Documents. The IPP object was forced
- to close the Job since the client took too long. The client SHOULD
- NOT repeat the request without modifications.
-
-13.1.4.7 client-error-not-found (0x0406)
-
- The IPP object has not found anything matching the request URI. No
- indication is given of whether the condition is temporary or
- permanent. For example, a client with an old reference to a Job (a
- URI) tries to cancel the Job, however in the mean time the Job might
- have been completed and all record of it at the Printer has been
- deleted. This status code, 'client-error-not-found' is returned
- indicating that the referenced Job can not be found. This error
- status code is also used when a client supplies a URI as a reference
- to the document data in either a Print-URI or Send-URI operation, but
- the document can not be found.
-
- In practice, an IPP application should avoid a not found situation by
- first querying and presenting a list of valid Printer URIs and Job
- URIs to the end-user.
-
-13.1.4.8 client-error-gone (0x0407)
-
- The requested object is no longer available and no forwarding address
- is known. This condition should be considered permanent. Clients
- with link editing capabilities should delete references to the
- request URI after user approval. If the IPP object does not know or
- has no facility to determine, whether or not the condition is
- permanent, the status code "client-error-not-found" should be used
- instead.
-
- This response is primarily intended to assist the task of maintenance
- by notifying the recipient that the resource is intentionally
- unavailable and that the IPP object administrator desires that remote
- links to that resource be removed. It is not necessary to mark all
- permanently unavailable resources as "gone" or to keep the mark for
- any length of time -- that is left to the discretion of the IPP
- object administrator and/or Printer implementation.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 181]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-13.1.4.9 client-error-request-entity-too-large (0x0408)
-
- The IPP object is refusing to process a request because the request
- entity is larger than the IPP object is willing or able to process.
- An IPP Printer returns this status code when it limits the size of
- print jobs and it receives a print job that exceeds that limit or
- when the attributes are so many that their encoding causes the
- request entity to exceed IPP object capacity.
-
-13.1.4.10 client-error-request-value-too-long (0x0409)
-
- The IPP object is refusing to service the request because one or more
- of the client-supplied attributes has a variable length value that is
- longer than the maximum length specified for that attribute. The IPP
- object might not have sufficient resources (memory, buffers, etc.) to
- process (even temporarily), interpret, and/or ignore a value larger
- than the maximum length. Another use of this error code is when the
- IPP object supports the processing of a large value that is less than
- the maximum length, but during the processing of the request as a
- whole, the object may pass the value onto some other system component
- which is not able to accept the large value. For more details, see
- the Implementer's Guide [IPP-IIG] .
-
- Note: For attribute values that are URIs, this rare condition is
- only likely to occur when a client has improperly submitted a request
- with long query information (e.g. an IPP application allows an end-
- user to enter an invalid URI), when the client has descended into a
- URI "black hole" of redirection (e.g., a redirected URI prefix that
- points to a suffix of itself), or when the IPP object is under attack
- by a client attempting to exploit security holes present in some IPP
- objects using fixed-length buffers for reading or manipulating the
- Request-URI.
-
-13.1.4.11 client-error-document-format-not-supported (0x040A)
-
- The IPP object is refusing to service the request because the
- document data is in a format, as specified in the "document-format"
- operation attribute, that is not supported by the Printer object.
- This error is returned independent of the client-supplied "ipp-
- attribute-fidelity". The Printer object MUST return this status
- code, even if there are other Job Template attributes that are not
- supported as well, since this error is a bigger problem than with Job
- Template attributes. See sections 3.1.6.1, 3.1.7, and 3.2.1.1.
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 182]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-13.1.4.12 client-error-attributes-or-values-not-supported (0x040B)
-
- In a create request, if the Printer object does not support one or
- more attributes, attribute syntaxes, or attribute values supplied in
- the request and the client supplied the "ipp-attribute-fidelity"
- operation attribute with the 'true' value, the Printer object MUST
- return this status code. The Printer object MUST also return in the
- Unsupported Attributes Group all the attributes and/or values
- supplied by the client that are not supported. See section 3.1.7.
- For example, if the request indicates 'iso-a4' media, but that media
- type is not supported by the Printer object. Or, if the client
- supplies a Job Template attribute and the attribute itself is not
- even supported by the Printer. If the "ipp-attribute-fidelity"
- attribute is 'false', the Printer MUST ignore or substitute values
- for unsupported Job Template attributes and values rather than reject
- the request and return this status code.
-
- For any operation where a client requests attributes (such as a Get-
- Jobs, Get-Printer-Attributes, or Get-Job-Attributes operation), if
- the IPP object does not support one or more of the requested
- attributes, the IPP object simply ignores the unsupported requested
- attributes and processes the request as if they had not been
- supplied, rather than returning this status code. In this case, the
- IPP object MUST return the 'successful-ok-ignored-or-substituted-
- attributes' status code and MAY return the unsupported attributes as
- values of the "requested-attributes" in the Unsupported Attributes
- Group (see section 13.1.2.2).
-
-13.1.4.13 client-error-uri-scheme-not-supported (0x040C)
-
- The scheme of the client-supplied URI in a Print-URI or a Send-URI
- operation is not supported. See sections 3.1.6.1 and 3.1.7.
-
-13.1.4.14 client-error-charset-not-supported (0x040D)
-
- For any operation, if the IPP Printer does not support the charset
- supplied by the client in the "attributes-charset" operation
- attribute, the Printer MUST reject the operation and return this
- status and any 'text' or 'name' attributes using the 'utf-8' charset
- (see Section 3.1.4.1). See sections 3.1.6.1 and 3.1.7.
-
-13.1.4.15 client-error-conflicting-attributes (0x040E)
-
- The request is rejected because some attribute values conflicted with
- the values of other attributes which this document does not permit to
- be substituted or ignored. The Printer object MUST also return in
- the Unsupported Attributes Group the conflicting attributes supplied
- by the client. See sections 3.1.7 and 3.2.1.2.
-
-
-
-Hastings, et al. Standards Track [Page 183]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-13.1.4.16 client-error-compression-not-supported (0x040F)
-
- The IPP object is refusing to service the request because the
- document data, as specified in the "compression" operation attribute,
- is compressed in a way that is not supported by the Printer object.
- This error is returned independent of the client-supplied "ipp-
- attribute-fidelity". The Printer object MUST return this status
- code, even if there are other Job Template attributes that are not
- supported as well, since this error is a bigger problem than with Job
- Template attributes. See sections 3.1.6.1, 3.1.7, and 3.2.1.1.
-
-13.1.4.17 client-error-compression-error (0x0410)
-
- The IPP object is refusing to service the request because the
- document data cannot be decompressed when using the algorithm
- specified by the "compression" operation attribute. This error is
- returned independent of the client-supplied "ipp-attribute-fidelity".
- The Printer object MUST return this status code, even if there are
- Job Template attributes that are not supported as well, since this
- error is a bigger problem than with Job Template attributes. See
- sections 3.1.7 and 3.2.1.1.
-
-13.1.4.18 client-error-document-format-error (0x0411)
-
- The IPP object is refusing to service the request because Printer
- encountered an error in the document data while interpreting it.
- This error is returned independent of the client-supplied "ipp-
- attribute-fidelity". The Printer object MUST return this status
- code, even if there are Job Template attributes that are not
- supported as well, since this error is a bigger problem than with Job
- Template attributes. See sections 3.1.7 and 3.2.1.1.
-
-13.1.4.19 client-error-document-access-error (0x0412)
-
- The IPP object is refusing to service the Print-URI or Send-URI
- request because Printer encountered an access error while attempting
- to validate the accessibility or access the document data specified
- in the "document-uri" operation attribute. The Printer MAY also
- return a specific document access error code using the "document-
- access-error" operation attribute (see section 3.1.6.4). This error
- is returned independent of the client-supplied "ipp-attribute-
- fidelity". The Printer object MUST return this status code, even if
- there are Job Template attributes that are not supported as well,
- since this error is a bigger problem than with Job Template
- attributes. See sections 3.1.6.1 and 3.1.7.
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 184]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-13.1.5 Server Error Status Codes
-
- This class of status codes indicates cases in which the IPP object is
- aware that it has erred or is incapable of performing the request.
- The IPP object SHOULD include a message containing an explanation of
- the error situation, and whether it is a temporary or permanent
- condition.
-
-13.1.5.1 server-error-internal-error (0x0500)
-
- The IPP object encountered an unexpected condition that prevented it
- from fulfilling the request. This error status code differs from
- "server-error-temporary-error" in that it implies a more permanent
- type of internal error. It also differs from "server-error-device-
- error" in that it implies an unexpected condition (unlike a paper-jam
- or out-of-toner problem which is undesirable but expected). This
- error status code indicates that probably some knowledgeable human
- intervention is required.
-
-13.1.5.2 server-error-operation-not-supported (0x0501)
-
- The IPP object does not support the functionality required to fulfill
- the request. This is the appropriate response when the IPP object
- does not recognize an operation or is not capable of supporting it.
- See sections 3.1.6.1 and 3.1.7.
-
-13.1.5.3 server-error-service-unavailable (0x0502)
-
- The IPP object is currently unable to handle the request due to a
- temporary overloading or maintenance of the IPP object. The
- implication is that this is a temporary condition which will be
- alleviated after some delay. If known, the length of the delay may be
- indicated in the message. If no delay is given, the IPP application
- should handle the response as it would for a "server-error-
- temporary-error" response. If the condition is more permanent, the
- error status codes "client-error-gone" or "client-error-not-found"
- could be used.
-
-13.1.5.4 server-error-version-not-supported (0x0503)
-
- The IPP object does not support, or refuses to support, the IPP
- protocol version that was supplied as the value of the "version-
- number" operation parameter in the request. The IPP object is
- indicating that it is unable or unwilling to complete the request
- using the same major and minor version number as supplied in the
- request other than with this error message. The error response SHOULD
- contain a "status-message" attribute (see section 3.1.6.2) describing
-
-
-
-
-Hastings, et al. Standards Track [Page 185]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- why that version is not supported and what other versions are
- supported by that IPP object. See sections 3.1.6.1, 3.1.7, and
- 3.1.8.
-
- The error response MUST identify in the "version-number" operation
- parameter the closest version number that the IPP object does
- support. For example, if a client supplies version '1.0' and an
- IPP/1.1 object supports version '1.0', then it responds with version
- '1.0' in all responses to such a request. If the IPP/1.1 object does
- not support version '1.0', then it should accept the request and
- respond with version '1.1' or may reject the request and respond with
- this error code and version
- '1.1'. If a client supplies a version '1.2', the IPP/1.1 object
- should accept the request and return version '1.1' or may reject the
- request and respond with this error code and version '1.1'. See
- sections 3.1.8 and 4.4.14.
-
-13.1.5.5 server-error-device-error (0x0504)
-
- A printer error, such as a paper jam, occurs while the IPP object
- processes a Print or Send operation. The response contains the true
- Job Status (the values of the "job-state" and "job-state-reasons"
- attributes). Additional information can be returned in the OPTIONAL
- "job-state-message" attribute value or in the OPTIONAL status message
- that describes the error in more detail. This error status code is
- only returned in situations where the Printer is unable to accept the
- create request because of such a device error. For example, if the
- Printer is unable to spool, and can only accept one job at a time,
- the reason it might reject a create request is that the printer
- currently has a paper jam. In many cases however, where the Printer
- object can accept the request even though the Printer has some error
- condition, the 'successful-ok' status code will be returned. In such
- a case, the client would look at the returned Job Object Attributes
- or later query the Printer to determine its state and state reasons.
-
-13.1.5.6 server-error-temporary-error (0x0505)
-
- A temporary error such as a buffer full write error, a memory
- overflow (i.e. the document data exceeds the memory of the Printer),
- or a disk full condition, occurs while the IPP Printer processes an
- operation. The client MAY try the unmodified request again at some
- later point in time with an expectation that the temporary internal
- error condition may have been cleared. Alternatively, as an
- implementation option, a Printer object MAY delay the response until
- the temporary condition is cleared so that no error is returned.
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 186]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-13.1.5.7 server-error-not-accepting-jobs (0x0506)
-
- A temporary error indicating that the Printer is not currently
- accepting jobs, because the administrator has set the value of the
- Printer's "printer-is-accepting-jobs" attribute to 'false' (by means
- outside the scope of this IPP/1.1 document).
-
-13.1.5.8 server-error-busy (0x0507)
-
- A temporary error indicating that the Printer is too busy processing
- jobs and/or other requests. The client SHOULD try the unmodified
- request again at some later point in time with an expectation that
- the temporary busy condition will have been cleared.
-
-13.1.5.9 server-error-job-canceled (0x0508)
-
- An error indicating that the job has been canceled by an operator or
- the system while the client was transmitting the data to the IPP
- Printer. If a job-id and job-uri had been created, then they are
- returned in the Print-Job, Send-Document, or Send-URI response as
- usual; otherwise, no job-id and job-uri are returned in the response.
-
-13.1.5.10 server-error-multiple-document-jobs-not-supported (0x0509)
-
- The IPP object does not support multiple documents per job and a
- client attempted to supply document data with a second Send-Document
- or Send-URI operation.
-
-13.2 Status Codes for IPP Operations
-
- PJ = Print-Job, PU = Print-URI, CJ = Create-Job, SD = Send-Document
- SU = Send-URI, V = Validate-Job, GA = Get-Job-Attributes and
- Get-Printer-Attributes, GJ = Get-Jobs, C = Cancel-Job
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 187]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- IPP Operations
- IPP Status Keyword PJ PU CJ SD SU V GA GJ C
- ------------------ -- -- -- -- -- - -- -- -
- successful-ok x x x x x x x x x
- successful-ok-ignored-or-substituted- x x x x x x x x x
- attributes
- successful-ok-conflicting-attributes x x x x x x x x x
- client-error-bad-request x x x x x x x x x
- client-error-forbidden x x x x x x x x x
- client-error-not-authenticated x x x x x x x x x
- client-error-not-authorized x x x x x x x x x
- client-error-not-possible x x x x x x x x x
- client-error-timeout x x
- client-error-not-found x x x x x x x x x
- client-error-gone x x x x x x x x x
- client-error-request-entity-too-large x x x x x x x x x
- client-error-request-value-too-long x x x x x x x x x
- client-error-document-format-not- x x x x x x
- supported
- client-error-attributes-or-values-not- x x x x x x x x x
- supported
- client-error-uri-scheme-not-supported x x
- client-error-charset-not-supported x x x x x x x x x
- client-error-conflicting-attributes x x x x x x x x x
- client-error-compression-not-supported x x x x x
- client-error-compression-error x x x x
- client-error-document-format-error x x x x
- client-error-document-access-error x x
- server-error-internal-error x x x x x x x x x
- server-error-operation-not-supported x x x x
- server-error-service-unavailable x x x x x x x x x
- server-error-version-not-supported x x x x x x x x x
- server-error-device-error x x x x x
- server-error-temporary-error x x x x x
- server-error-not-accepting-jobs x x x x
- server-error-busy x x x x x x x x x
- server-error-job-canceled x x x
- server-error-multiple-document-jobs- x x
- not-supported
-
- HJ = Hold-Job, RJ = Release-Job, RS = Restart-Job
- PP = Pause-Printer, RP = Resume-Printer, PJ = Purge-Jobs
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 188]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- IPP Operations (cont.)
- IPP Status Keyword HJ RJ RS PP RP PJ
- ------------------ -- -- -- -- -- --
- successful-ok x x x x x x
- successful-ok-ignored-or-substituted- x x x x x x
- attributes
- successful-ok-conflicting-attributes x x x x x x
- client-error-bad-request x x x x x x
- client-error-forbidden x x x x x x
- client-error-not-authenticated x x x x x x
- client-error-not-authorized x x x x x x
- client-error-not-possible x x x x x x
- client-error-timeout
- client-error-not-found x x x x x x
- client-error-gone x x x x x x
- client-error-request-entity-too-large x x x x x x
- client-error-request-value-too-long x x x x x x
- client-error-document-format-not-
- supported
- client-error-attributes-or-values-not- x x x x x x
- supported
- client-error-uri-scheme-not-supported
- client-error-charset-not-supported x x x x x x
- client-error-conflicting-attributes x x x x x x
- client-error-compression-not-supported
- client-error-compression-error
- client-error-document-format-error
- client-error-document-access-error
- server-error-internal-error x x x x x x
- server-error-operation-not-supported x x x x x x
- server-error-service-unavailable x x x x x x
- server-error-version-not-supported x x x x x x
- server-error-device-error
- server-error-temporary-error x x x x x x
- server-error-not-accepting-jobs
- server-error-busy x x x x x x
- server-error-job-canceled
- server-error-multiple-document-jobs-
- not-supported
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 189]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-14. APPENDIX C: "media" keyword values
-
- Standard keyword values are taken from several sources.
-
- Standard values are defined (taken from DPA[ISO10175] and the Printer
- MIB[RFC1759]):
-
- 'default': The default medium for the output device
- 'iso-a4-white': Specifies the ISO A4 white medium: 210 mm x 297 mm
- 'iso-a4-colored': Specifies the ISO A4 colored medium: 210 mm x 297
- mm
- 'iso-a4-transparent' Specifies the ISO A4 transparent medium: 210 mm
- x 297 mm
- 'iso-a3-white': Specifies the ISO A3 white medium: 297 mm x 420 mm
- 'iso-a3-colored': Specifies the ISO A3 colored medium: 297 mm x 420
- mm
- 'iso-a5-white': Specifies the ISO A5 white medium: 148 mm x 210 mm
- 'iso-a5-colored': Specifies the ISO A5 colored medium: 148 mm x 210
- mm
- 'iso-b4-white': Specifies the ISO B4 white medium: 250 mm x 353 mm
- 'iso-b4-colored': Specifies the ISO B4 colored medium: 250 mm x 353
- mm
- 'iso-b5-white': Specifies the ISO B5 white medium: 176 mm x 250 mm
- 'iso-b5-colored': Specifies the ISO B5 colored medium: 176 mm x 250
- mm
- 'jis-b4-white': Specifies the JIS B4 white medium: 257 mm x 364 mm
- 'jis-b4-colored': Specifies the JIS B4 colored medium: 257 mm x 364
- mm
- 'jis-b5-white': Specifies the JIS B5 white medium: 182 mm x 257 mm
- 'jis-b5-colored': Specifies the JIS B5 colored medium: 182 mm x 257
- mm
-
- The following standard values are defined for North American media:
-
- 'na-letter-white': Specifies the North American letter white medium
- 'na-letter-colored': Specifies the North American letter colored
- medium
- 'na-letter-transparent': Specifies the North American letter
- transparent medium
- 'na-legal-white': Specifies the North American legal white medium
- 'na-legal-colored': Specifies the North American legal colored
- medium
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 190]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- The following standard values are defined for envelopes:
-
- 'iso-b4-envelope': Specifies the ISO B4 envelope medium
- 'iso-b5-envelope': Specifies the ISO B5 envelope medium
- 'iso-c3-envelope': Specifies the ISO C3 envelope medium
- 'iso-c4-envelope': Specifies the ISO C4 envelope medium
- 'iso-c5-envelope': Specifies the ISO C5 envelope medium
- 'iso-c6-envelope': Specifies the ISO C6 envelope medium
- 'iso-designated-long-envelope': Specifies the ISO Designated Long
- envelope medium
- 'na-10x13-envelope': Specifies the North American 10x13 envelope
- medium
- 'na-9x12-envelope': Specifies the North American 9x12 envelope
- medium
- 'monarch-envelope': Specifies the Monarch envelope
- 'na-number-10-envelope': Specifies the North American number 10
- business envelope medium
- 'na-7x9-envelope': Specifies the North American 7x9 inch envelope
- 'na-9x11-envelope': Specifies the North American 9x11 inch
- envelope
- 'na-10x14-envelope': Specifies the North American 10x14 inch
- envelope
- 'na-number-9-envelope': Specifies the North American number 9
- business envelope
- 'na-6x9-envelope': Specifies the North American 6x9 inch envelope
- 'na-10x15-envelope': Specifies the North American 10x15 inch
- envelope
-
- The following standard values are defined for the less commonly used
- media:
-
- 'executive-white': Specifies the white executive medium
- 'folio-white': Specifies the folio white medium
- 'invoice-white': Specifies the white invoice medium
- 'ledger-white': Specifies the white ledger medium
- 'quarto-white': Specified the white quarto medium
- 'iso-a0-white': Specifies the ISO A0 white medium: 841 mm x 1189 mm
- 'iso-a0-transparent': Specifies the ISO A0 transparent medium: 841 mm
- x 1189 mm
- 'iso-a0-translucent': Specifies the ISO A0 translucent medium: 841 mm
- x 1189 mm
- 'iso-a1-white': Specifies the ISO A1 white medium: 594 mm x 841 mm
- 'iso-a1-transparent': Specifies the ISO A1 transparent medium: 594 mm
- x 841 mm
- 'iso-a1-translucent': Specifies the ISO A1 translucent medium: 594 mm
- x 841 mm
- 'iso-a2-white': Specifies the ISO A2 white medium: 420 mm x 594 mm
-
-
-
-
-Hastings, et al. Standards Track [Page 191]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'iso-a2-transparent': Specifies the ISO A2 transparent medium: 420 mm
- x 594 mm
- 'iso-a2-translucent': Specifies the ISO A2 translucent medium: 420 mm
- x 594 mm
- 'iso-a3-transparent': Specifies the ISO A3 transparent medium: 297 mm
- x 420 mm
- 'iso-a3-translucent': Specifies the ISO A3 translucent medium: 297 mm
- x 420 mm
- 'iso-a4-translucent': Specifies the ISO A4 translucent medium: 210 mm
- x 297 mm
- 'iso-a5-transparent': Specifies the ISO A5 transparent medium: 148 mm
- x 210 mm
- 'iso-a5-translucent': Specifies the ISO A5 translucent medium: 148 mm
- x 210 mm
- 'iso-a6-white': Specifies the ISO A6 white medium: 105 mm x 148 mm
- 'iso-a7-white': Specifies the ISO A7 white medium: 74 mm x 105 mm
- 'iso-a8-white': Specifies the ISO A8 white medium: 52 mm x 74 mm
- 'iso-a9-white': Specifies the ISO A9 white medium: 37 mm x 52 mm
- 'iso-a10-white': Specifies the ISO A10 white medium: 26 mm x 37 mm
- 'iso-b0-white': Specifies the ISO B0 white medium: 1000 mm x 1414 mm
- 'iso-b1-white': Specifies the ISO B1 white medium: 707 mm x 1000 mm
- 'iso-b2-white': Specifies the ISO B2 white medium: 500 mm x 707 mm
- 'iso-b3-white': Specifies the ISO B3 white medium: 353 mm x 500 mm
- 'iso-b6-white': Specifies the ISO B6 white medium: 125 mm x 176 mm
- 'iso-b7-white': Specifies the ISO B7 white medium: 88 mm x 125 mm
- 'iso-b8-white': Specifies the ISO B8 white medium: 62 mm x 88 mm
- 'iso-b9-white': Specifies the ISO B9 white medium: 44 mm x 62 mm
- 'iso-b10-white': Specifies the ISO B10 white medium: 31 mm x 44 mm
- 'jis-b0-white': Specifies the JIS B0 white medium: 1030 mm x 1456 mm
- 'jis-b0-transparent': Specifies the JIS B0 transparent medium: 1030
- mm x 1456 mm
- 'jis-b0-translucent': Specifies the JIS B0 translucent medium: 1030
- mm x 1456 mm
- 'jis-b1-white': Specifies the JIS B1 white medium: 728 mm x 1030 mm
- 'jis-b1-transparent': Specifies the JIS B1 transparent medium: 728 mm
- x 1030 mm
- 'jis-b1-translucent': Specifies the JIS B1 translucent medium: 728 mm
- x 1030 mm
- 'jis-b2-white': Specifies the JIS B2 white medium: 515 mm x 728 mm
- 'jis-b2-transparent': Specifies the JIS B2 transparent medium: 515 mm
- x 728 mm
- 'jis-b2-translucent': Specifies the JIS B2 translucent medium: 515 mm
- x 728 mm
- 'jis-b3-white': Specifies the JIS B3 white medium: 364 mm x 515 mm
- 'jis-b3-transparent': Specifies the JIS B3 transparent medium: 364 mm
- x 515 mm
- 'jis-b3-translucent': Specifies the JIS B3 translucent medium: 364 mm
- x 515 mm
-
-
-
-Hastings, et al. Standards Track [Page 192]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'jis-b4-transparent': Specifies the JIS B4 transparent medium: 257 mm
- x 364 mm
- 'jis-b4-translucent': Specifies the JIS B4 translucent medium: 257 mm
- x 364 mm
- 'jis-b5-transparent': Specifies the JIS B5 transparent medium: 182 mm
- x 257 mm
- 'jis-b5-translucent': Specifies the JIS B5 translucent medium: 182 mm
- x 257 mm
- 'jis-b6-white': Specifies the JIS B6 white medium: 128 mm x 182 mm
- 'jis-b7-white': Specifies the JIS B7 white medium: 91 mm x 128 mm
- 'jis-b8-white': Specifies the JIS B8 white medium: 64 mm x 91 mm
- 'jis-b9-white': Specifies the JIS B9 white medium: 45 mm x 64 mm
- 'jis-b10-white': Specifies the JIS B10 white medium: 32 mm x 45 mm
-
- The following standard values are defined for American Standard (i.e.
- ANSI) engineering media:
-
- 'a-white': Specifies the engineering ANSI A size white medium: 8.5
- inches x 11 inches
- 'a-transparent': Specifies the engineering ANSI A size transparent
- medium: 8.5 inches x 11 inches
- 'a-translucent': Specifies the engineering ANSI A size translucent
- medium: 8.5 inches x 11 inches
- 'b-white': Specifies the engineering ANSI B size white medium: 11
- inches x 17 inches
- 'b-transparent': Specifies the engineering ANSI B size transparent
- medium: 11 inches x 17 inches)
- 'b-translucent': Specifies the engineering ANSI B size translucent
- medium: 11 inches x 17 inches
- 'c-white': Specifies the engineering ANSI C size white medium: 17
- inches x 22 inches
- 'c-transparent': Specifies the engineering ANSI C size transparent
- medium: 17 inches x 22 inches
- 'c-translucent': Specifies the engineering ANSI C size translucent
- medium: 17 inches x 22 inches
- 'd-white': Specifies the engineering ANSI D size white medium: 22
- inches x 34 inches
- 'd-transparent': Specifies the engineering ANSI D size transparent
- medium: 22 inches x 34 inches
- 'd-translucent': Specifies the engineering ANSI D size translucent
- medium: 22 inches x 34 inches
- 'e-white': Specifies the engineering ANSI E size white medium: 34
- inches x 44 inches
- 'e-transparent': Specifies the engineering ANSI E size transparent
- medium: 34 inches x 44 inches
- 'e-translucent': Specifies the engineering ANSI E size translucent
- medium: 34 inches x 44 inches
-
-
-
-
-Hastings, et al. Standards Track [Page 193]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- The following standard values are defined for American Standard (i.e.
- ANSI) engineering media for devices that provide the "synchro-cut"
- feature (see section 14.1):
-
- 'axsynchro-white': Specifies the roll paper having the width of the
- longer edge (11 inches) of the engineering ANSI A size white medium
- and cuts synchronizing with data.
- 'axsynchro-transparent': Specifies the roll paper having the width of
- the longer edge (11 inches) of the engineering ANSI A size
- transparent medium and cuts synchronizing with data.
- 'axsynchro-translucent': Specifies the roll paper having the width of
- the longer edge (11 inches) of the engineering ANSI A size
- translucent medium and cuts synchronizing with data.
- 'bxsynchro-white': Specifies the roll paper having the width of the
- longer edge (17 inches) of the engineering ANSI B size white medium
- and cuts synchronizing with data.
- 'bxsynchro-transparent': Specifies the roll paper having the width of
- the longer edge (17 inches) of the engineering ANSI B size
- transparent medium and cuts synchronizing with data.
- 'bxsynchro-translucent': Specifies the roll paper having the width of
- the longer edge (17 inches) of the engineering ANSI B size
- translucent medium and cuts synchronizing with data.
- 'cxsynchro-white': Specifies the roll paper having the width of the
- longer edge (22 inches) of the engineering ANSI C size white medium
- and cuts synchronizing with data.
- 'cxsynchro-transparent': Specifies the roll paper having the width of
- the longer edge (22 inches) of the engineering ANSI C size
- transparent medium and cuts synchronizing with data.
- 'cxsynchro-translucent': Specifies the roll paper having the width of
- the longer edge (22 inches) of the engineering ANSI C size
- translucent medium and cuts synchronizing with data.
- 'dxsynchro-white': Specifies the roll paper having the width of the
- longer edge (34 inches) of the engineering ANSI D size white medium
- and cuts synchronizing with data.
- 'dxsynchro-transparent': Specifies the roll paper having the width of
- the longer edge (34 inches) of the engineering ANSI D size
- transparent medium and cuts synchronizing with data.
- 'dxsynchro-translucent': Specifies the roll paper having the width of
- the longer edge (34 inches) of the engineering ANSI D size
- translucent medium and cuts synchronizing with data.
- 'exsynchro-white': Specifies the roll paper having the width of the
- longer edge (44 inches) of the engineering ANSI E size white medium
- and cuts synchronizing with data.
- 'exsynchro-transparent': Specifies the roll paper having the width of
- the longer edge (44 inches) of the engineering ANSI E size
- transparent medium and cuts synchronizing with data.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 194]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'exsynchro-translucent': Specifies the roll paper having the width of
- the longer edge (44 inches) of the engineering ANSI E size
- translucent medium and cuts synchronizing with data.
-
- The following standard values are defined for American Architectural
- engineering media:
-
- 'arch-a-white': Specifies the Architectural A size white medium: 9
- inches x 12 inches
- 'arch-a-transparent': Specifies the Architectural A size transparent
- medium: 9 inches x 12 inches
- 'arch-a-translucent': Specifies the Architectural A size translucent
- medium: 9 inches x 12 inches
- 'arch-b-white': Specifies the Architectural B size white medium: 12
- inches x 18 inches
- 'arch-b-transparent': Specifies the Architectural B size transparent
- medium: 12 inches x 18 inches
- 'arch-b-translucent': Specifies the Architectural B size translucent
- medium: 12 inches x 18 inches
- 'arch-c-white': Specifies the Architectural C size white medium: 18
- inches x 24 inches
- 'arch-c-transparent': Specifies the Architectural C size transparent
- medium: 18 inches x 24 inches
- 'arch-c-translucent': Specifies the Architectural C size translucent
- medium: 18 inches x 24 inches
- 'arch-d-white': Specifies the Architectural D size white medium: 24
- inches x 36 inches
- 'arch-d-transparent': Specifies the Architectural D size transparent
- medium: 24 inches x 36 inches
- 'arch-d-translucent': Specifies the Architectural D size translucent
- medium: 24 inches x 36 inches
- 'arch-e-white': Specifies the Architectural E size white medium: 36
- inches x 48 inches
- 'arch-e-transparent': Specifies the Architectural E size transparent
- medium: 36 inches x 48 inches
- 'arch-e-translucent': Specifies the Architectural E size translucent
- medium: 36 inches x 48 inches
-
- The following standard values are defined for American Architectural
- engineering media for devices that provide the "synchro-cut" feature
- (see section 14.1):
-
- 'arch-axsynchro-white': Specifies the roll paper having the width of
- the longer edge (12 inches) of the Architectural A size white
- medium and cuts synchronizing with data.
- 'arch-axsynchro-transparent': Specifies the roll paper having the
- width of the longer edge (12 inches) of the Architectural A size
- transparent medium and cuts synchronizing with data.
-
-
-
-Hastings, et al. Standards Track [Page 195]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'arch-axsynchro-translucent': Specifies the roll paper having the
- width of the longer edge (12 inches) of the Architectural A size
- translucent medium and cuts synchronizing with data.
- 'arch-bxsynchro-white': Specifies the roll paper having the width of
- the longer edge (18 inches) of the Architectural B size white
- medium and cuts synchronizing with data.
- 'arch-bxsynchro-transparent': Specifies the roll paper having the
- width of the longer edge (18 inches) of the Architectural B size
- transparent medium and cuts synchronizing with data.
- 'arch-bxsynchro-translucent': Specifies the roll paper having the
- width of the longer edge (18 inches) of the Architectural B size
- translucent medium and cuts synchronizing with data.
- 'arch-cxsynchro-white': Specifies the roll paper having the width of
- the longer edge (24 inches) of the Architectural C size white
- medium and cuts synchronizing with data.
- 'arch-cxsynchro-transparent': Specifies the roll paper having the
- width of the longer edge (24 inches) of the Architectural C size
- transparent medium and cuts synchronizing with data.
- 'arch-cxsynchro-translucent': Specifies the roll paper having the
- width of the longer edge (24 inches) of the Architectural C size
- translucent medium and cuts synchronizing with data.
- 'arch-dxsynchro-white': Specifies the roll paper having the width of
- the longer edge (36 inches) of the Architectural D size white
- medium and cuts synchronizing with data.
- 'arch-dxsynchro-transparent': Specifies the roll paper having the
- width of the longer edge (36 inches) of the Architectural D size
- transparent medium and cuts synchronizing with data.
- 'arch-dxsynchro-translucent': Specifies the roll paper having the
- width of the longer edge (36 inches) of the Architectural D size
- translucent medium and cuts synchronizing with data.
- 'arch-exsynchro-white': Specifies the roll paper having the width of
- the longer edge (48 inches) of the Architectural E size white
- medium and cuts synchronizing with data.
- 'arch-exsynchro-transparent': Specifies the roll paper having the
- width of the longer edge (48 inches) of the Architectural E size
- transparent medium and cuts synchronizing with data.
- 'arch-exsynchro-translucent': Specifies the roll paper having the
- width of the longer edge (48 inches) of the Architectural E size
- translucent medium and cuts synchronizing with data.
-
- The following standard values are defined for Japanese and European
- Standard (i.e. ISO) engineering media, which are of a long fixed size
- [ASME-Y14.1M]:
-
- 'iso-a1x3-white': Specifies the ISO A1X3 white medium having the
- width of the longer edge (841 mm) of the ISO A1 medium
-
-
-
-
-
-Hastings, et al. Standards Track [Page 196]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'iso-a1x3-transparent': Specifies the ISO A1X3 transparent medium
- having the width of the longer edge (841 mm) of the ISO A1
- medium
- 'iso-a1x3-translucent': Specifies the ISO A1X3 translucent medium
- having the width of the longer edge (841 mm) of the ISO A1
- medium
- 'iso-a1x4-white': Specifies the ISO A1X4 white medium having the
- width of the longer edge (841 mm) of the ISO A1 medium
- 'iso-a1x4-transparent': Specifies the ISO A1X4 transparent medium
- having the width of the longer edge (841 mm) of the ISO A1
- medium
- 'iso-a1x4- translucent': Specifies the ISO A1X4 translucent medium
- having the width of the longer edge (841 mm) of the ISO A1
- medium
- 'iso-a2x3-white': Specifies the ISO A2X3 white medium having the
- width of the longer edge (594 mm) of the ISO A2 medium
- 'iso-a2x3-transparent': Specifies the ISO A2X3 transparent medium
- having the width of the longer edge (594 mm) of the ISO A2
- medium
- 'iso-a2x3-translucent': Specifies the ISO A2X3 translucent medium
- having the width of the longer edge (594 mm) of the ISO A2
- medium
- 'iso-a2x4-white': Specifies the ISO A2X4 white medium having the
- width of the longer edge (594 mm) of the ISO A2 medium
- 'iso-a2x4-transparent': Specifies the ISO A2X4 transparent medium
- having the width of the longer edge (594 mm) of the ISO A2
- medium
- 'iso-a2x4-translucent': Specifies the ISO A2X4 translucent medium
- having the width of the longer edge (594 mm) of the ISO A2
- medium
- 'iso-a2x5-white': Specifies the ISO A2X5 white medium having the
- width of the longer edge (594 mm) of the ISO A2 medium
- 'iso-a2x5-transparent': Specifies the ISO A2X5 transparent medium
- having the width of the longer edge (594 mm) of the ISO A2
- medium
- 'iso-a2x5-translucent': Specifies the ISO A2X5 translucent medium
- having the width of the longer edge (594 mm) of the ISO A2
- medium
- 'iso-a3x3-white': Specifies the ISO A3X3 white medium having the
- width of the longer edge (420 mm) of the ISO A3 medium
- 'iso-a3x3-transparent': Specifies the ISO A3X3 transparent medium
- having the width of the longer edge (420 mm) of the ISO A3
- medium
- 'iso-a3x3-translucent': Specifies the ISO A3X3 translucent medium
- having the width of the longer edge (420 mm) of the ISO A3
- medium
- 'iso-a3x4-white': Specifies the ISO A3X4 white medium having the
- width of the longer edge (420 mm) of the ISO A3 medium
-
-
-
-Hastings, et al. Standards Track [Page 197]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'iso-a3x4-transparent': Specifies the ISO A3X4 transparent medium
- having the width of the longer edge (420 mm) of the ISO A3
- medium
- 'iso-a3x4-translucent': Specifies the ISO A3X4 translucent medium
- having the width of the longer edge (420 mm) of the ISO A3
- medium
- 'iso-a3x5-white': Specifies the ISO A3X5 white medium having the
- width of the longer edge (420 mm) of the ISO A3 medium
- 'iso-a3x5-transparent': Specifies the ISO A3X5 transparent medium
- having the width of the longer edge (420 mm) of the ISO A3
- medium
- 'iso-a3x5-translucent': Specifies the ISO A3X5 translucent medium
- having the width of the longer edge (420 mm) of the ISO A3
- medium
- 'iso-a3x6-white': Specifies the ISO A3X6 white medium having the
- width of the longer edge (420 mm) of the ISO A3 medium
- 'iso-a3x6-transparent': Specifies the ISO A3X6 transparent medium
- having the width of the longer edge (420 mm) of the ISO A3
- medium
- 'iso-a3x6-translucent': Specifies the ISO A3X6 translucent medium
- having the width of the longer edge (420 mm) of the ISO A3
- medium
- 'iso-a3x7-white': Specifies the ISO A3X7 white medium having the
- width of the longer edge (420 mm) of the ISO A3 medium
- 'iso-a3x7-transparent': Specifies the ISO A3X7 transparent medium
- having the width of the longer edge (420 mm) of the ISO A3
- medium
- 'iso-a3x7-translucent'': Specifies the ISO A3X7 translucent' medium
- having the width of the longer edge (420 mm) of the ISO A3
- medium
- 'iso-a4x3-white': Specifies the ISO A4X3 white medium having the
- width of the longer edge (297 mm) of the ISO A4 medium
- 'iso-a4x3-transparent': Specifies the ISO A4X3 transparent medium
- having the width of the longer edge (297 mm) of the ISO A4
- medium
- 'iso-a4x3-translucent'': Specifies the ISO A4X3 translucent' medium
- having the width of the longer edge (297 mm) of the ISO A4
- medium
- 'iso-a4x4-white': Specifies the ISO A4X4 white medium having the
- width of the longer edge (297 mm) of the ISO A4 medium
- 'iso-a4x4-transparent': Specifies the ISO A4X4 transparent medium
- having the width of the longer edge (297 mm) of the ISO A4
- medium
- 'iso-a4x4-translucent': Specifies the ISO A4X4 translucent medium
- having the width of the longer edge (297 mm) of the ISO A4
- medium
- 'iso-a4x5-white': Specifies the ISO A4X5 white medium having the
- width of the longer edge (297 mm) of the ISO A4 medium
-
-
-
-Hastings, et al. Standards Track [Page 198]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'iso-a4x5-transparent': Specifies the ISO A4X5 transparent medium
- having the width of the longer edge (297 mm) of the ISO A4
- medium
- 'iso-a4x5-translucent': Specifies the ISO A4X5 translucent medium
- having the width of the longer edge (297 mm) of the ISO A4
- medium
- 'iso-a4x6-white': Specifies the ISO A4X6 white medium having the
- width of the longer edge (297 mm) of the ISO A4 medium
- 'iso-a4x6-transparent': Specifies the ISO A4X6 transparent medium
- having the width of the longer edge (297 mm) of the ISO A4
- medium
- 'iso-a4x6-translucent': Specifies the ISO A4X6 translucent medium
- having the width of the longer edge (297 mm) of the ISO A4
- medium
- 'iso-a4x7-white': Specifies the ISO A4X7 white medium having the
- width of the longer edge (297 mm) of the ISO A4 medium
- 'iso-a4x7-transparent': Specifies the ISO A4X7 transparent medium
- having the width of the longer edge (297 mm) of the ISO A4
- medium
- 'iso-a4x7-translucent': Specifies the ISO A4X7 translucent medium
- having the width of the longer edge (297 mm) of the ISO A4
- medium
- 'iso-a4x8-white': Specifies the ISO A4X8 white medium having the
- width of the longer edge (297 mm) of the ISO A4 medium
- 'iso-a4x8-transparent': Specifies the ISO A4X8 transparent medium
- having the width of the longer edge (297 mm) of the ISO A4
- medium
- 'iso-a4x8-translucent': Specifies the ISO A4X8 translucent medium
- having the width of the longer edge (297 mm) of the ISO A4
- medium
- 'iso-a4x9-white': Specifies the ISO A4X9 white medium having the
- width of the longer edge (297 mm) of the ISO A4 medium
- 'iso-a4x9-transparent': Specifies the ISO A4X9 transparent medium
- having the width of the longer edge (297 mm) of the ISO A4
- medium
- 'iso-a4x9-translucent': Specifies the ISO A4X9 translucent medium
- having the width of the longer edge (297 mm) of the ISO A4
- medium
-
- The following standard values are defined for Japanese and European
- Standard (i.e. ISO) engineering media, which are either a long fixed
- size [ASME-Y14.1M] or roll feed, for devices that provide the
- "synchro-cut" feature (see section 14.1):
-
- 'iso-a0xsynchro-white': Specifies the paper having the width of the
- longer edge (1189 mm) of the ISO A0 white medium and cuts
- synchronizing with data.
-
-
-
-
-Hastings, et al. Standards Track [Page 199]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'iso-a0xsynchro-transparent': Specifies the paper having the width of
- the longer edge (1189 mm) of the ISO A0 transparent medium and
- cuts synchronizing with data.
- 'iso-a0xsynchro-translucent': Specifies the paper having the width of
- the longer edge (1189 mm) of the ISO A0 translucent medium and
- cuts synchronizing with data.
- 'iso-a1xsynchro-white': Specifies the paper having the width of the
- longer edge (841 mm) of the ISO A1 white medium and cuts
- synchronizing with data.
- 'iso-a1xsynchro-transparent': Specifies the paper having the width of
- the longer edge (841 mm) of the ISO A1 transparent medium and
- cuts synchronizing with data.
- 'iso-a1xsynchro-translucent': Specifies the paper having the width of
- the longer edge (841 mm) of the ISO A1 translucent medium and
- cuts synchronizing with data.
- 'iso-a2xsynchro-white': Specifies the paper having the width of the
- longer edge (594 mm) of the ISO A2 white medium and cuts
- synchronizing with data.
- 'iso-a2xsynchro-transparent': Specifies the paper having the width of
- the longer edge (594 mm) of the ISO A2 transparent medium and
- cuts synchronizing with data.
- 'iso-a2xsynchro-translucent': Specifies the paper having the width of
- the longer edge (594 mm) of the ISO A2 translucent medium and
- cuts synchronizing with data.
- 'iso-a3xsynchro-white': Specifies the paper having the width of the
- longer edge (420 mm) of the ISO A3 white medium and cuts
- synchronizing with data.
- 'iso-a3xsynchro-transparent': Specifies the paper having the width of
- the longer edge (420 mm) of the ISO A3 transparent medium and
- cuts synchronizing with data.
- 'iso-a3xsynchro-translucent': Specifies the paper having the width of
- the longer edge (420 mm) of the ISO A3 translucent medium and
- cuts synchronizing with data.
- 'iso-a4xsynchro-white': Specifies the paper having the width of the
- longer edge (297 mm) of the ISO A4 white medium and cuts
- synchronizing with data.
- 'iso-a4xsynchro-transparent': Specifies the paper having the width of
- the longer edge (297 mm) of the ISO A4 transparent medium and
- cuts synchronizing with data.
- 'iso-a4xsynchro-translucent': Specifies the paper having the width of
- the longer edge (297 mm) of the ISO A4 transparent medium and
- cuts synchronizing with data.
-
- The following standard values are defined for American Standard (i.e.
- ANSI) engineering media, American Architectural engineering media,
- and Japanese and European Standard (i.e. ISO) engineering media,
-
-
-
-
-
-Hastings, et al. Standards Track [Page 200]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- which are either a long fixed size [ASME-Y14.1M] or roll feed, for
- devices that provide the "synchro-cut" feature and/or the "auto-
- select" feature (see section 14.1):
-
- 'auto-white': Specifies that the printer selects the white medium
- with the appropriate fixed size (e.g. a1, a2, etc.) or data-
- synchro size, and the selection is implementation-defined.
- 'auto-transparent': Specifies that the printer selects the
- transparent medium with the appropriate fixed size (e.g. a1, a2,
- etc.) or data-synchro size, and the selection is implementation-
- defined.
- 'auto-translucent': Specifies that the printer selects the
- translucent medium with the appropriate fixed size (e.g. a1, a2,
- etc.) or data-synchro size, and the selection is implementation-
- defined.
- 'auto-fixed-size-white': Specifies that the printer selects the white
- medium with the appropriate fixed size (e.g. a1, a2, etc.) or
- the appropriate long fixed size listed above.
- 'auto-fixed-size-transparent': Specifies that the printer selects the
- transparent medium with the appropriate fixed size (e.g. a1, a2,
- etc.) or the appropriate long fixed size listed above.
- 'auto-fixed-size-translucent': Specifies that the printer selects the
- translucent medium with the appropriate fixed size (e.g. a1, a2,
- etc.) or the appropriate long fixed size listed above.
- 'auto-synchro-white': Specifies that the printer selects the white
- paper with the appropriate width and cuts it synchronizing with
- data.
- 'auto-synchro-transparent': Specifies that the printer selects the
- transparent paper with the appropriate width and cuts it
- synchronizing with data.
- 'auto-synchro-translucent': Specifies that the printer selects the
- translucent paper with the appropriate width and cuts it
- synchronizing with data.
-
- The following standard values are defined for input-trays (from ISO
- DPA and the Printer MIB):
-
- 'top': The top input tray in the printer.
- 'middle': The middle input tray in the printer.
- 'bottom': The bottom input tray in the printer.
- 'envelope': The envelope input tray in the printer.
- 'manual': The manual feed input tray in the printer.
- 'large-capacity': The large capacity input tray in the printer.
- 'main': The main input tray
- 'side': The side input tray
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 201]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- The following standard values are defined for media sizes (from ISO
- DPA):
-
- 'iso-a0': Specifies the ISO A0 size: 841 mm by 1189 mm as defined in
- ISO 216
- 'iso-a1': Specifies the ISO A1 size: 594 mm by 841 mm as defined in
- ISO 216
- 'iso-a2': Specifies the ISO A2 size: 420 mm by 594 mm as defined in
- ISO 216
- 'iso-a3': Specifies the ISO A3 size: 297 mm by 420 mm as defined in
- ISO 216
- 'iso-a4': Specifies the ISO A4 size: 210 mm by 297 mm as defined in
- ISO 216
- 'iso-a5': Specifies the ISO A5 size: 148 mm by 210 mm as defined in
- ISO 216
- 'iso-a6': Specifies the ISO A6 size: 105 mm by 148 mm as defined in
- ISO 216
- 'iso-a7': Specifies the ISO A7 size: 74 mm by 105 mm as defined in
- ISO 216
- 'iso-a8': Specifies the ISO A8 size: 52 mm by 74 mm as defined in ISO
- 216
- 'iso-a9': Specifies the ISO A9 size: 37 mm by 52 mm as defined in ISO
- 216
- 'iso-a10': Specifies the ISO A10 size: 26 mm by 37 mm as defined in
- ISO 216
- 'iso-b0': Specifies the ISO B0 size: 1000 mm by 1414 mm as defined in
- ISO 216
- 'iso-b1': Specifies the ISO B1 size: 707 mm by 1000 mm as defined in
- ISO 216
- 'iso-b2': Specifies the ISO B2 size: 500 mm by 707 mm as defined in
- ISO 216
- 'iso-b3': Specifies the ISO B3 size: 353 mm by 500 mm as defined in
- ISO 216
- 'iso-b4': Specifies the ISO B4 size: 250 mm by 353 mm as defined in
- ISO 216
- 'iso-b5': Specifies the ISO B5 size: 176 mm by 250 mm as defined in
- ISO 216
- 'iso-b6': Specifies the ISO B6 size: 125 mm by 176 mm as defined in
- ISO 216
- 'iso-b7': Specifies the ISO B7 size: 88 mm by 125 mm as defined in
- ISO 216
- 'iso-b8': Specifies the ISO B8 size: 62 mm by 88 mm as defined in ISO
- 216
- 'iso-b9': Specifies the ISO B9 size: 44 mm by 62 mm as defined in ISO
- 216
- 'iso-b10': Specifies the ISO B10 size: 31 mm by 44 mm as defined in
- ISO 216
-
-
-
-
-Hastings, et al. Standards Track [Page 202]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'na-letter': Specifies the North American letter size: 8.5 inches by
- 11 inches
- 'na-legal': Specifies the North American legal size: 8.5 inches by 14
- inches
- 'na-8x10': Specifies the North American 8 inches by 10 inches
- 'na-5x7': Specifies the North American 5 inches by 7 inches
- 'executive': Specifies the executive size (7.25 X 10.5 in)
- 'folio': Specifies the folio size (8.5 X 13 in)
- 'invoice': Specifies the invoice size (5.5 X 8.5 in)
- 'ledger': Specifies the ledger size (11 X 17 in)
- 'quarto': Specifies the quarto size (8.5 X 10.83 in)
- 'iso-c3': Specifies the ISO C3 size: 324 mm by 458 mm as defined in
- ISO 269
- 'iso-c4': Specifies the ISO C4 size: 229 mm by 324 mm as defined in
- ISO 269
- 'iso-c5': Specifies the ISO C5 size: 162 mm by 229 mm as defined in
- ISO 269
- 'iso-c6': Specifies the ISO C6 size: 114 mm by 162 mm as defined in
- ISO 269
- 'iso-designated-long': Specifies the ISO Designated Long size: 110 mm
- by 220 mm as defined in ISO 269
- 'na-10x13-envelope': Specifies the North American 10x13 size: 10
- inches by 13 inches
- 'na-9x12-envelope': Specifies the North American 9x12 size: 9 inches
- by 12 inches
- 'na-number-10-envelope': Specifies the North American number 10
- business envelope size: 4.125 inches by 9.5 inches
- 'na-7x9-envelope': Specifies the North American 7x9 inch envelope
- size
- 'na-9x11-envelope': Specifies the North American 9x11 inch envelope
- size
- 'na-10x14-envelope': Specifies the North American 10x14 inch envelope
- size
- 'na-number-9-envelope': Specifies the North American number 9
- business envelope size
- 'na-6x9-envelope': Specifies the North American 6x9 envelope size
- 'na-10x15-envelope': Specifies the North American 10x15 envelope size
- 'monarch-envelope': Specifies the Monarch envelope size (3.87 x 7.5
- in)
- 'jis-b0': Specifies the JIS B0 size: 1030mm x 1456mm
- 'jis-b1': Specifies the JIS B1 size: 728mm x 1030mm
- 'jis-b2': Specifies the JIS B2 size: 515mm x 728mm
- 'jis-b3': Specifies the JIS B3 size: 364mm x 515mm
- 'jis-b4': Specifies the JIS B4 size: 257mm x 364mm
- 'jis-b5': Specifies the JIS B5 size: 182mm x 257mm
- 'jis-b6': Specifies the JIS B6 size: 128mm x 182mm
- 'jis-b7': Specifies the JIS B7 size: 91mm x 128mm
- 'jis-b8': Specifies the JIS B8 size: 64mm x 91mm
-
-
-
-Hastings, et al. Standards Track [Page 203]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 'jis-b9': Specifies the JIS B9 size: 45mm x 64mm
- 'jis-b10': Specifies the JIS B10 size: 32mm x 45mm
-
- The following standard values are defined for American Standard (i.e.
- ANSI) engineering media sizes:
-
- 'a': Specifies the engineering ANSI A size medium: 8.5 inches x 11
- inches
- 'b': Specifies the engineering ANSI B size medium: 11 inches x 17
- inches
- 'c': Specifies the engineering ANSI C size medium: 17 inches x 22
- inches
- 'd': Specifies the engineering ANSI D size medium: 22 inches x 34
- inches
- 'e': Specifies the engineering ANSI E size medium: 34 inches x 44
- inches
-
- The following standard values are defined for American Architectural
- engineering media sizes:
-
- 'arch-a': Specifies the Architectural A size medium: 9 inches x 12
- inches
- 'arch-b': Specifies the Architectural B size medium: 12 inches x 18
- inches
- 'arch-c': Specifies the Architectural C size medium: 18 inches x 24
- inches
- 'arch-d': Specifies the Architectural D size medium: 24 inches x 36
- inches
- 'arch-e': Specifies the Architectural E size medium: 36 inches x 48
- inches
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 204]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-14.1. Examples
-
- Below are examples to supplement the engineering media value
- definitions.
-
- Example 1: "Synchro-Cut", a device cutting the roll paper in
- synchronization with the data
-
- data height: A1 height
- data width (shaded): A1 width < data width < (A1 width) x 2
- specified value: 'iso-a1xsynchro-white'
-
- | |
- |<--- data width --->|
- | |
- | | | |
- |<- A1 width ->|<- A1 width ->|
- | | | |
- cross ^ | | | |
- feed | +--------------------------------------------/
- direction | |//////////////|/////| | ^ /
- | |//////////////|/////| | | /
- | |//////////////|/////| | | /
- | |//////////////|/////| | | \
-<-----------+- |//////////////|/////| | A1 \ roll
-feed | |//////////////|/////| | height \ paper
-direction |//////////////|/////| | | \
- |//////////////|/////| | | /
- |//////////////|/////| | v /
- +------------------------------------------/
- |
- |
- |<------ CUT HERE (to synchronize
- | with data width)
- |
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 205]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Example 2: "Auto-Cut", a device cutting the roll paper at multiples
- of fixed-size media width
-
- data height: A1 height
- data width (shaded): A1 width < data width < (A1 width) x 2
- specified value: 'auto-fixed-size-white'
-
- | |
- |<--- data width --->|
- | |
- | | | |
- |<- A1 width ->|<- A1 width ->|
- | | | |
- cross ^ | | | |
- feed | +--------------------------------------------/
- direction | |//////////////|/////| | ^ /
- | |//////////////|/////| | | /
- | |//////////////|/////| | | /
- | |//////////////|/////| | | \
-<-----------+- |//////////////|/////| | A1 \ roll
-feed | |//////////////|/////| | height \ paper
-direction |//////////////|/////| | | \
- |//////////////|/////| | | /
- |//////////////|/////| | v /
- +------------------------------------------/
- |
- |
- |<--- CUT HERE
- | (to synchronize
- | with data width)
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 206]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Example 3: the 'iso-a4x4-white' fixed size paper
-
- paper height: A4 height
- paper width: (A4 width) x 4
- specified value: 'iso-a4x4-white'
-
- | | | | |
- |<- A4 width ->|<- A4 width ->|<- A4 width ->|<- A4 width ->|
- | | | | |
- | | | | |
- +-----------------------------------------------------------+
- | ^ | | | |
- | | | | | |
- | | | | | |
- | A4 | | | |
- | height | | | |
- | | | | | |
- | | | | | |
- | | | | | |
- | v | | | |
- +-----------------------------------------------------------+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 207]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Example 4: "Synchro-Cut", a device cutting the fixed size paper in
- synchronization with the data
-
- data height: A4 height
- data width (shaded): (A4 width) x 2 < data width < (A4 width) x 3
- specified value: 'iso-a4xsynchro-white'
-
- | |
- |<---------- data width ----------->|
- | |
- | | | | |
- |<- A4 width ->|<- A4 width ->|<- A4 width ->|
- | | | | |
- cross ^ | | | | |
- feed | +--------------------------------------------+
- direction | |//////////////|//////////////|/////| ^ |
- | |//////////////|//////////////|/////| | |
- | |//////////////|//////////////|/////| | |
- | |//////////////|//////////////|/////| | |
- <-----------+- |//////////////|//////////////|/////| A4 |
- feed | |//////////////|//////////////|/////| height |
- direction |//////////////|//////////////|/////| | |
- |//////////////|//////////////|/////| | |
- |//////////////|//////////////|/////| v |
- +--------------------------------------------+
- |
- CUT HERE ---->|
- (to synchronize |
- with data width) |
-
-15. APPENDIX D: Processing IPP Attributes
-
- When submitting a print job to a Printer object, the IPP model allows
- a client to supply operation and Job Template attributes along with
- the document data. These Job Template attributes in the create
- request affect the rendering, production and finishing of the
- documents in the job. Similar types of instructions may also be
- contained in the document to be printed, that is, embedded within the
- print data itself. In addition, the Printer has a set of attributes
- that describe what rendering and finishing options which are
- supported by that Printer. This model, which allows for flexibility
- and power, also introduces the potential that at job submission time,
- these client-supplied attributes may conflict with either:
-
- - what the implementation is capable of realizing (i.e., what the
- Printer supports), as well as
- - the instructions embedded within the print data itself.
-
-
-
-
-Hastings, et al. Standards Track [Page 208]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- The following sections describe how these two types of conflicts are
- handled in the IPP model.
-
-15.1 Fidelity
-
- If there is a conflict between what the client requests and what a
- Printer object supports, the client may request one of two possible
- conflict handling mechanisms:
-
- 1) either reject the job since the job can not be processed
- exactly as specified, or
- 2) allow the Printer to make any changes necessary to proceed with
- processing the Job the best it can.
-
- In the first case the client is indicating to the Printer object:
- "Print the job exactly as specified with no exceptions, and if that
- can't be done, don't even bother printing the job at all." In the
- second case, the client is indicating to the Printer object: "It is
- more important to make sure the job is printed rather than be
- processed exactly as specified; just make sure the job is printed
- even if some client-supplied attributes need to be changed or
- ignored."
-
- The IPP model accounts for this situation by introducing an "ipp-
- attribute-fidelity" attribute.
-
- In a create request, "ipp-attribute-fidelity" is a boolean operation
- attribute that is OPTIONALLY supplied by the client. The value
- 'true' indicates that total fidelity to client supplied Job Template
- attributes and values is required. The client is requesting that the
- Job be printed exactly as specified, and if that is not possible then
- the job MUST be rejected rather than processed incorrectly. The
- value 'false' indicates that a reasonable attempt to print the Job is
- acceptable. If a Printer does not support some of the client
- supplied Job Template attributes or values, the Printer MUST ignore
- them or substitute any supported value for unsupported values,
- respectively. The Printer may choose to substitute the default value
- associated with that attribute, or use some other supported value
- that is similar to the unsupported requested value. For example, if
- a client supplies a "media" value of 'na-letter', the Printer may
- choose to substitute 'iso-a4' rather than a default value of
- 'envelope'. If the client does not supply the "ipp-attribute-
- fidelity" attribute, the Printer assumes a value of 'false'.
-
- Each Printer implementation MUST support both types of "fidelity"
- printing (that is whether the client supplies a value of 'true' or
- 'false'):
-
-
-
-
-Hastings, et al. Standards Track [Page 209]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- - If the client supplies 'false' or does not supply the attribute,
- the Printer object MUST always accept the request by ignoring
- unsupported Job Template attributes and by substituting
- unsupported values of supported Job Template attributes with
- supported values.
- - If the client supplies 'true', the Printer object MUST reject
- the request if the client supplies unsupported Job Template
- attributes.
-
- Since a client can always query a Printer to find out exactly what is
- and is not supported, "ipp-attribute-fidelity" set to 'false' is
- useful when:
-
- 1) The End-User uses a command line interface to request
- attributes that might not be supported.
- 2) In a GUI context, if the End User expects the job might be
- moved to another printer and prefers a sub-optimal result to
- nothing at all.
- 3) The End User just wants something reasonable in lieu of nothing
- at all.
-
-15.2 Page Description Language (PDL) Override
-
- If there is a conflict between the value of an IPP Job Template
- attribute and a corresponding instruction in the document data, the
- value of the IPP attribute SHOULD take precedence over the document
- instruction. Consider the case where a previously formatted file of
- document data is sent to an IPP Printer. In this case, if the client
- supplies any attributes at job submission time, the client desires
- that those attributes override the embedded instructions. Consider
- the case were a previously formatted document has embedded in it
- commands to load 'iso-a4' media. However, the document is passed to
- an end user that only has access to a printer with 'na-letter' media
- loaded. That end user most likely wants to submit that document to
- an IPP Printer with the "media" Job Template attribute set to 'na-
- letter'. The job submission attribute should take precedence over
- the embedded PDL instruction. However, until companies that supply
- document data interpreters allow a way for external IPP attributes to
- take precedence over embedded job production instructions, a Printer
- might not be able to support the semantics that IPP attributes
- override the embedded instructions.
-
- The IPP model accounts for this situation by introducing a "pdl-
- override-supported" attribute that describes the Printer objects
- capabilities to override instructions embedded in the PDL data
- stream. The value of the "pdl-override-supported" attribute is
- configured by means outside the scope of this IPP/1.1 document.
-
-
-
-
-Hastings, et al. Standards Track [Page 210]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- This REQUIRED Printer attribute takes on the following values:
-
- - 'attempted': This value indicates that the Printer object
- attempts to make the IPP attribute values take precedence over
- embedded instructions in the document data, however there is no
- guarantee.
- - 'not-attempted': This value indicates that the Printer object
- makes no attempt to make the IPP attribute values take
- precedence over embedded instructions in the document data.
-
- At job processing time, an implementation that supports the value of
- 'attempted' might do one of several different actions:
-
- 1) Generate an output device specific command sequence to realize
- the feature represented by the IPP attribute value.
- 2) Parse the document data itself and replace the conflicting
- embedded instruction with a new embedded instruction that
- matches the intent of the IPP attribute value.
- 3) Indicate to the Printer that external supplied attributes take
- precedence over embedded instructions and then pass the
- external IPP attribute values to the document data interpreter.
- 4) Anything else that allows for the semantics that IPP attributes
- override embedded document data instructions.
-
- Since 'attempted' does not offer any type of guarantee, even though a
- given Printer object might not do a very "good" job of attempting to
- ensure that IPP attributes take a higher precedence over instructions
- embedded in the document data, it would still be a conforming
- implementation.
-
- At job processing time, an implementation that supports the value of
- 'not-attempted' might do one of the following actions:
-
- 1) Simply pre-pend the document data with the PDL instruction that
- corresponds to the client-supplied PDL attribute, such that if
- the document data also has the same PDL instruction, it will
- override what the Printer object pre-pended. In other words,
- this implementation is using the same implementation semantics
- for the client-supplied IPP attributes as for the Printer
- object defaults.
-
- 2) Parse the document data and replace the conflicting embedded
- instruction with a new embedded instruction that approximates,
- but does not match, the semantic intent of the IPP attribute
- value.
-
- Note: The "ipp-attribute-fidelity" attribute applies to the
- Printer's ability to either accept or reject other unsupported Job
-
-
-
-Hastings, et al. Standards Track [Page 211]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- Template attributes. In other words, if "ipp-attribute-fidelity" is
- set to 'true', a Job is accepted if and only if the client supplied
- Job Template attributes and values are supported by the Printer.
- Whether these attributes actually affect the processing of the Job
- when the document data contains embedded instructions depends on the
- ability of the Printer to override the instructions embedded in the
- document data with the semantics of the IPP attributes. If the
- document data attributes can be overridden ("pdl-override-supported"
- set to 'attempted'), the Printer makes an attempt to use the IPP
- attributes when processing the Job. If the document data attributes
- can not be overridden ("pdl-override-supported" set to 'not-
- attempted'), the Printer makes no attempt to override the embedded
- document data instructions with the IPP attributes when processing
- the Job, and hence, the IPP attributes may fail to affect the Job
- processing and output when the corresponding instruction is embedded
- in the document data.
-
-15.3 Using Job Template Attributes During Document Processing.
-
- The Printer object uses some of the Job object's Job Template
- attributes during the processing of the document data associated with
- that job. These include, but are not limited to, "orientation-
- requested", "number-up", "sides", "media", and "copies". The
- processing of each document in a Job Object MUST follow the steps
- below. These steps are intended only to identify when and how
- attributes are to be used in processing document data and any
- alternative steps that accomplishes the same effect can be used to
- implement this specification document.
-
- 1. Using the client supplied "document-format" attribute or some
- form of document format detection algorithm (if the value of
- "document-format" is not specific enough), determine whether or
- not the document data has already been formatted for printing.
- If the document data has been formatted, then go to step 2.
- Otherwise, the document data MUST be formatted. The formatting
- detection algorithm is implementation defined and is not
- specified by this document. The formatting of the document
- data uses the "orientation-requested" attribute to determine
- how the formatted print data should be placed on a print-stream
- page, see section 4.2.10 for the details.
-
- 2. The document data is in the form of a print-stream in a known
- media type. The "page-ranges" attribute is used to select, as
- specified in section 4.2.7, a sub-sequence of the pages in the
- print-stream that are to be processed and images.
-
- 3. The input to this step is a sequence of print-stream pages.
- This step is controlled by the "number-up" attribute. If the
-
-
-
-Hastings, et al. Standards Track [Page 212]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- value of "number-up" is N, then during the processing of the
- print-stream pages, each N print-stream pages are positioned,
- as specified in section 4.2.9, to create a single impression.
- If a given document does not have N more print-stream pages,
- then the completion of the impression is controlled by the
- "multiple-document-handling" attribute as described in section
- 4.2.4; when the value of this attribute is 'single-document' or
- 'single-document-new-sheet', the print-stream pages of document
- data from subsequent documents is used to complete the
- impression.
-
- The size(scaling), position(translation) and rotation of the
- print-stream pages on the impression is implementation defined.
- Note that during this process the print-stream pages may be
- rendered to a form suitable for placing on the impression; this
- rendering is controlled by the values of the "printer-
- resolution" and "print-quality" attributes as described in
- sections 4.2.12 and 4.2.13. In the case N=1, the impression is
- nearly the same as the print-stream page; the differences would
- only be in the size, position and rotation of the print-stream
- page and/or any decoration, such as a frame to the page, that
- is added by the implementation.
-
- 4. The collection of impressions is placed, in sequence, onto
- sides of the media sheets. This placement is controlled by the
- "sides" attribute and the orientation of the print-stream page,
- as described in section 4.2.8. The orientation of the print-
- stream pages affects the orientation of the impression; for
- example, if "number-up" equals 2, then, typically, two portrait
- print-stream pages become one landscape impression. Note that
- the placement of impressions onto media sheets is also
- controlled by the "multiple-document-handling" attribute as
- described in section 4.2.4.
-
- 5. The "copies" and "multiple-document-handling" attributes are
- used to determine how many copies of each media instance are
- created and in what order. See sections 4.2.5 and 4.2.4 for the
- details.
-
- 6. When the correct number of copies are created, the media
- instances are finished according to the values of the
- "finishings" attribute as described in 4.2.6. Note that
- sometimes finishing operations may require manual intervention
- to perform the finishing operations on the copies, especially
- uncollated copies. This document allows any or all of the
- processing steps to be performed automatically or manually at
- the discretion of the Printer object.
-
-
-
-
-Hastings, et al. Standards Track [Page 213]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-16. APPENDIX E: Generic Directory Schema
-
- This section defines a generic schema for an entry in a directory
- service. A directory service is a means by which service users can
- locate service providers. In IPP environments, this means that IPP
- Printers can be registered (either automatically or with the help of
- an administrator) as entries of type printer in the directory using
- an implementation specific mechanism such as entry attributes, entry
- type fields, specific branches, etc. Directory clients can search or
- browse for entries of type printer. Clients use the directory
- service to find entries based on naming, organizational contexts, or
- filtered searches on attribute values of entries. For example, a
- client can find all printers in the "Local Department" context.
- Authentication and authorization are also often part of a directory
- service so that an administrator can place limits on end users so
- that they are only allowed to find entries to which they have certain
- access rights. IPP itself does not require any specific directory
- service protocol or provider.
-
- Note: Some directory implementations allow for the notion of
- "aliasing". That is, one directory entry object can appear as
- multiple directory entry object with different names for each object.
- In each case, each alias refers to the same directory entry object
- which refers to a single IPP Printer object.
-
- The generic schema is a subset of IPP Printer Job Template and
- Printer Description attributes (sections 4.2 and 4.4). These
- attributes are identified as either RECOMMENDED or OPTIONAL for the
- directory entry itself. This conformance labeling is NOT the same
- conformance labeling applied to the attributes of IPP Printers
- objects. The conformance labeling in this Appendix is intended to
- apply to directory templates and to IPP Printer implementations that
- subscribe by adding one or more entries to a directory. RECOMMENDED
- attributes SHOULD be associated with each directory entry. OPTIONAL
- attributes MAY be associated with the directory entry (if known or
- supported). In addition, all directory entry attributes SHOULD
- reflect the current attribute values for the corresponding Printer
- object.
-
- The names of attributes in directory schema and entries SHOULD be the
- same as the IPP Printer attribute names as shown, as much as
- possible.
-
- In order to bridge between the directory service and the IPP Printer
- object, one of the RECOMMENDED directory entry attributes is the
- Printer object's "printer-uri-supported" attribute. The directory
- client queries the "printer-uri-supported" attribute (or its
- equivalent) in the directory entry and then the IPP client addresses
-
-
-
-Hastings, et al. Standards Track [Page 214]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- the IPP Printer object using one of its URIs. The "uri-security-
- supported" attribute identifies the protocol (if any) used to secure
- a channel.
-
- The following attributes define the generic schema for directory
- entries of type PRINTER:
-
- printer-uri-supported RECOMMENDED Section 4.4.1
- uri-authentication-supported RECOMMENDED Section 4.4.2
- uri-security-supported RECOMMENDED Section 4.4.3
- printer-name RECOMMENDED Section 4.4.4
- printer-location RECOMMENDED Section 4.4.5
- printer-info OPTIONAL Section 4.4.6
- printer-more-info OPTIONAL Section 4.4.7
- printer-make-and-model RECOMMENDED Section 4.4.9
- ipp-versions-supported RECOMMENDED Section 4.4.14
- multiple-document-jobs-supported OPTIONAL Section 4.4.16
- charset-supported OPTIONAL Section 4.4.18
-
- generated-natural-language-
- supported OPTIONAL Section 4.4.20
- document-format-supported RECOMMENDED Section 4.4.22
- color-supported RECOMMENDED Section 4.4.26
- compression-supported RECOMMENDED Section 4.4.32
- pages-per-minute OPTIONAL Section 4.4.36
- pages-per-minute-color OPTIONAL Section 4.4.37
-
- finishings-supported OPTIONAL Section 4.2.6
- number-up-supported OPTIONAL Section 4.2.7
- sides-supported RECOMMENDED Section 4.2.8
- media-supported RECOMMENDED Section 4.2.11
- printer-resolution-supported OPTIONAL Section 4.2.12
- print-quality-supported OPTIONAL Section 4.2.13
-
-17. APPENDIX F: Differences between the IPP/1.0 and IPP/1.1 "Model and
- Semantics" Documents
-
- This Appendix is divided into two lists that summarize the
- differences between IPP/1.1 (this document) and IPP/1.0 [RFC2566].
- The section numbers refer to the numbers in this document which in
- some cases have changed from RFC 2566. When a change affects
- multiple sections, the item is listed once in the order of the first
- section affected and the remaining affected section numbers are
- indicated.
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 215]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- The first list contains extensions and clarifications and the second
- list contains changes in semantics or conformance. However, client
- and IPP object implementations of IPP/1.0 MAY implement any of the
- extensions and clarifications in this document.
-
- The following extensions and clarifications have been incorporated
- into this document:
-
- 1. Section 2.1 - clarified that the term "client" can be either
- contained in software controlled by an end user or a part of a
- print server that controls devices.
- 2. Section 2 - clarified that the term "IPP object" and "Printer
- object" can either be embedded in a device object or part of a
- print server that accepts IPP requests.
- 3. Section 2.4 - added the description of the new "uri-
- authentication-supported" Printer Description attribute.
- 4. Section 3.1.3, 3.1.6, 3.2.5.2, and 3.2.6.2 - clarified the
- error handling for operation attributes that have their own
- status code.
- 5. Section 3.1.3 - clarified that multiple occurrences of the
- same attribute in an attribute group is mal-formed. An IPP
- Printer MAY reject the request or choose one of the
- attributes.
- 6. Section 3.1.6 - reorganized this section into sub-sections to
- separately describe "status-code", "status-message",
- "detailed-status-message", and "document-access-error"
- attributes.
- 7. Section 3.1.6.1 - clarified the error status codes and their
- relationship to operation attributes.
- 8. Section 3.1.6.3 - Added the OPTIONAL "detailed-status-message
- (text(MAX))" operation attribute to provide additional more
- detailed information about a response.
- 9. Section 3.1.6.4 and 3.2.2 - Added the OPTIONAL "document-
- access-error (text(MAX))" operation attribute for use with
- Print-URI and Send-URI responses.
- 10. Sections 3.1.7 - Added this new section to clarify returning
- Unsupported Attributes for all operations, including only
- returning attributes that were in the request. Moved the text
- from section 3.2.1.2 Unsupported Attributes to this section.
- 11. Sections 3.1.7 and 4.1 - clarified the encoding of the "out-
- of-band" 'unsupported' and 'unknown' values.
- 12. Section 3.1.8 - clarified that only the version number
- parameter will be carried forward into future major or minor
- versions of the protocol.
- 13. Section 3.1.8 - relaxed the requirements to increment the
- major version number in future versions of the Model and
- Semantics document.
-
-
-
-
-Hastings, et al. Standards Track [Page 216]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 14. Section 3.1.9, and 3.2.5 - added the 'processing' state to the
- list of job states that a job can be in after a Create-Job
- operation.
- 15. Section 3.1.9 - clarified that a non-spooling Printer MAY
- accept zero or more subsequent jobs while processing a job and
- flow control them down. Subsequent create requests are
- rejected with the 'server-error-busy' error status.
- 16. Section 3.2.1.1 - clarified the validation of the
- "compression" operation attribute and its relationship to the
- validation of the "document-format" attribute and returning
- Unsupported Attributes.
- 17. Sections 3.2.1.1, 4.3.8, 13.1.4.16, and 13.1.4.17 - added the
- 'client-error-compression-not-supported', 'client-error-
- compression-error' status codes and the 'unsupported-
- compression' and 'compression-error' job-state-reasons.
- 18. Sections 3.2.1.1 and 4.3.8 - added 'unsupported-document-
- format' and 'document-format-error' job-state-reasons.
- 19. Sections 3.2.2, 4.3.8 and 13.1.4.19 - added 'client-error-
- document-access-error' status code and 'document-access-error'
- job state reason.
- 20. Section 3.2.5.2 and 3.2.6.2 - clarified that the Unsupported
- Attributes group MUST NOT include attributes not requested in
- the Get-Printer-Attributes request.
- 21. Section 3.2.6 - clarified that "limit" takes precedence over
- "which-jobs" and "my-jobs'.
- 22. Section 3.2.6.2 - clarified that Get-Jobs returns
- 'successful-ok' when no jobs to return.
- 23. Sections 3.2.7, 3.2.8, and 3.2.9 - added the OPTIONAL Pause-
- Printer, Resume-Printer, and Purge-Jobs operations
- 24. Section 3.3.1 - clarified that the authorization required for
- a Send-Document request MUST be the same user as the Create-
- Job or an operator.
- 25. Section 3.3.1.1 - clarified that a Create-Job Send-Document
- with "last-document" = 'true' and no data is not an error; its
- a job with no documents.
- 26. Sections 3.3.5, 3.3.6, and 3.3.7 - added the OPTIONAL Hold-
- Job, Release-Job, and Restart-Job operations. Clarified the
- Restart-Job operation so that the Printer MUST re-fetch any
- documents passed by-reference (Print-URI or Send-URI).
- 27. Section 4.1 - clarified that the encoding of the out-of-band
- values are specified in the Encoding and Transport" document.
- 28. Section 4.1 - Clarified that the requirement that clients MUST
- NOT send "out-of-band" values in requests applies only to
- operations defined in this document. Other operations are
- allowed to define "out-of-band" values that clients can
- supply.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 217]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 29. Sections 4.1.1 and 4.1.2 - clarified that the maximum 'text'
- and 'name' values of 1023 and 255 are for the
- 'textWithoutLanguage' portion of the 'textWithLanguage' form,
- so that the maximum number of octets for the actual text and
- name data is the same for the without and with language forms;
- the 'naturalLanguage' part is in addition.
- 30. Section 4.1.9 - clarified that 'mimeMediaType' values can
- include any parameters from the IANA Registry, not just
- charset parameters.
- 31. Section 4.1.9.1 - clarified that 'application/octet-stream'
- auto-sensing can happen at create request time and/or
- job/document processing time.
- 32. Section 4.1.9.1 - clarified that auto-sensing involves the
- Printer examining some number of octets of document data using
- an implementation-dependent method.
- 33. Section 4.1.14 - clarified that the localization of dateTime
- by the client includes the time zone.
- 34. Section 4.2 - clarified that xxx-supported have multiple
- keywords and/or names by adding parentheses to the table to
- give: (1setOf (type3 keyword | name))
- 35. Section 4.2.2 - added the 'indefinite' keyword value to the
- "job-hold-until" attribute for use with the create operations
- and Hold-Job and Restart-Job operations.
- 36. Section 4.2.6 - added more enum values to the "finishings" Job
- Template attribute.
- 37. Section 4.2.6 - clarified that the landscape definition is a
- rotation of the image with respect to the medium.
- 38. Section 4.3.7 - added that a forwarding server that cannot get
- any job state MAY return the job's state as 'completed',
- provided that it also return the new 'queued-in-device' job
- state reason.
- 39. Section 4.3.7.2 - added the Partitioning of Job States section
- to clarify the concepts of Job Retention, Job History, and Job
- Removal.
- 40. Section 4.3.8 - added 'job-data-insufficient' job state reason
- to indicate whether sufficient data has arrived for the
- document to start to be processed.
- 41. Section 4.3.8 - added 'document-access-error' job state reason
- to indicate an access error of any kind.
- 42. Section 4.3.8 - added 'job-queued-for-marker' job state reason
- to indicate whether the job has completed some processing and
- is waiting for the marker.
- 43. Section 4.3.8 - added 'unsupported-compression' and
- 'compression-error' job state reasons to indicate compression
- not supported or compression processing error after the create
- has been accepted.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 218]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 44. Section 4.3.8 - added 'unsupported-document-format' and
- 'document-format-error' job state reasons to indicate document
- not supported or document format processing error after the
- create has been accepted.
- 45. Section 4.3.8 - added 'queued-in-device' job state reason to
- indicate that a job as been forwarded to a print system or
- device that does not provide any job status.
- 46. Section 4.3.10 - added "job-detailed-status-messages (1setOf
- text(MAX)) for returning detailed error messages.
- 47. Section 4.3.11 - added the "job-document-access-errors (1setOf
- text(MAX))
- 48. Section 4.3.14.2 - clarified that the time recorded is the
- first time processing since the create operation or the
- Restart-Job operation.
- 49. Section 4.3.14.2 and 4.3.14.3 - clarified that the out-of-band
- value 'no-value' is returned if the job has not started
- processing or has not completed, respectively.
- 50. Section 4.3.14 - Added the OPTIONAL "date-time-at-creation",
- "date-time-at-processing", and "date-time-at-completed" Event
- Time Job Description attributes
- 51. Section 4.4.3 - added the 'tls' value to "uri-security-
- supported" attribute.
- 52. Section 4.4.3 - clarified "uri-security-supported" is
- orthogonal to Client Authentication so that 'none' does not
- exclude Client Authentication.
- 53. Section 4.4.11 - simplified the "printer-state" descriptions
- while generalizing to allow high end devices that interpret
- one or more jobs while marking another. Indicated that
- 'spool-area-full' and 'stopped-partly' "printer-state-reasons"
- may be used to provide further state information.
- 54. Section 4.4.12 - added the 'moving-to-paused' keyword value to
- the "printer-state-reasons" attribute for use with the Pause-
- Printer operation.
- 55. Section 4.4.12 - replaced the duplicate 'marker-supply-low'
- keyword with the missing 'toner-empty' keyword for the
- "printer-state-reasons" attribute. (This correction was also
- made before RFC 2566 was published).
- 56. Section 4.4.12 - clarified 'spool-area-full' "printer-state-
- reasons" to include non-spooling printers to indicate when it
- can and cannot accept another job.
- 57. Section 4.4.15 - added the enum values to the "operations-
- supported" attribute for the new operations. Clarified that
- the values of this attribute are encoded as any enum, namely
- 32-bit values.
- 58. Section 4.4.30 - clarified that the dateTime value of
- "printer-current-time" is on a "best efforts basis". If a
- proper date-time cannot be obtained, the implementation
- returns the 'no-value' out-of-band value. Also clarified that
-
-
-
-Hastings, et al. Standards Track [Page 219]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- the time zone NEED NOT be the time zone that the people near
- the device use and that the client SHOULD display the dateTime
- attributes in the user's local time.
- 59. Sections 4.4.36 and 4.4.37 - added the OPTIONAL "pages-per-
- minute" and "pages-per-minute-color" Printer Description
- attributes.
- 60. Section 5.1 - clarified that the client conformance
- requirements apply to clients controlled by an end user and
- clients in servers.
- 61. Section 5.1 - clarified that any response MAY contain
- additional attribute groups, attributes, attribute syntaxes,
- or attribute values.
- 62. Section 5.1 - clarified that a client SHOULD do its best to
- prevent a channel from being closed by a lower layer when the
- channel is flow controlled off by the IPP Printer.
- 63. Section 5.2 - clarified that the IPP object requirements apply
- to objects embedded in devices or that are parts of servers.
- 64. Section 5.2.2 - clarified that IPP objects MAY return
- operation responses that contain attribute groups, attribute
- names, attribute syntaxes, attribute values, and status codes
- that are extensions to this standard.
- 65. Section 6 - changed the terminology of "private extensions" to
- "vendor extensions" and indicated that they are registered
- with IANA along with IETF standards track extensions.
- 66. Section 6.7 - inserted this section on registering out-of-band
- attribute values with IANA as extensions.
- 67. Section 8.3 - clarified the use of URIs for each Client
- Authentication mechanism.
- 68. Section 8.5 - added the security discussion around the new
- operator/administrator operations.
- 69. Section 13.1.4.16 - added client-error-compression-not-
- supported (0x040F)
- 70. Section 13.1.4.17 - added client-error-compression-error
- (0x0410)
- 71. Section 13.1.4.18 - added client-error-document-format-error
- (0x0411)
- 72. Section 13.1.4.19 - added client-error-document-access-error
- (0x0412)
- 73. Section 13.1.5.10 - added server-error-multiple-document-
- jobs-not-supported (0x0509)
- 74. Section 14 - added 'a-white', 'b-white', 'c-white', 'd-white',
- and 'e-white' and clarified that the existing 'a', 'b', 'c',
- 'd', and 'e' values are size values. Added American,
- Japanese, and European Engineering sizes, filled out
- -transparent and - translucent media names and drawings for
- the synchro cut sizes.
-
-
-
-
-
-Hastings, et al. Standards Track [Page 220]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 75. Section 16 - softened the RECOMMENDATION for IPP Printer
- attributes in a Directory schema so that they can have
- equivalents.
- 76. Section 16 - added the OPTIONAL "pages-per-minute" and
- "pages-per-minute-color" Printer attributes to the Directory
- schema.
- 77. Section 16 - added OPTIONAL "multiple-document-jobs-supported"
- to the Directory schema.
- 78. Section 16 - added RECOMMENDED "uri-authentication-supported",
- "ipp-versions-supported", and "compression-supported" to the
- Directory schema.
-
- The following changes in semantics and/or conformance have been
- incorporated into this document:
-
- 1. Section 3.1.6.3 - allowed a Printer to localize the
- "detailed-status-message" operation response attribute, but
- indicated that such localization might obscure the technical
- meaning of such messages.
- 2. Section 3.1.8, 5.2.4, and 13.1.5.4 - Clients and IPP objects
- MUST support version 1.1 conformance requirements. It is
- recommended that they interoperate with 1.0. Also clarified
- that IPP Printers MUST accept '1.1' requests. It is
- recommended that they also accept '1.x' requests.
-
- 3. Section 3.2.1.1 and section 4.4.32 - changed the "compression"
- operation and the "compression-supported" Printer Description
- attribute from OPTIONAL to REQUIRED.
- 4. Sections 3.2.1.2 and 4.3.8 - changed "job-state-reasons" from
- RECOMMENDED to REQUIRED, so that "job-state-reasons" MUST be
- returned in create operation responses.
- 5. Sections 3.2.4, 3.3.1, 4.4.16, and 16 - changed Create-
- Job/Send-Document so that they MAY be implemented while only
- supporting one document jobs. Added the "multiple-document-
- jobs-supported" boolean Printer Description attribute to
- indicate whether Create-Job/Send-Document support multiple
- document jobs or not. Added to the Directory schema.
- 6. Section 4.1.9 - deleted 'text/plain; charset=iso-10646-ucs-2',
- since binary is not legal with the 'text' type.
- 7. Section 4.1.9.1 - added the RECOMMENDATION that a Printer
- indicate by printing on the job's job-start-sheet that auto-
- sensing has occurred and what document format was auto-sensed.
- 8. Section 4.2.4 - indicated that the "multiple-document-
- handling" Job Template attribute MUST be supported with at
- least one value if the Printer supports multiple documents per
- job
-
-
-
-
-
-Hastings, et al. Standards Track [Page 221]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 9. Section 4.3.7.2 - indicated that the 'job-restartable' job
- state reason SHOULD be supported if the Restart-Job operation
- is supported.
- 10. Section 4.3.8 - changed "job-state-reasons" from RECOMMENDED
- to REQUIRED.
- 11. Section 4.3.8 - clarified the conformance of the values of the
- "job-state-reasons" attribute by copying conformance
- requirements from other sections of the document so that it is
- clear from reading the definition of "job-state-reasons" which
- values MUST or SHOULD be supported. The 'none',
- 'unsupported-compression', and 'unsupported-document-format'
- values MUST be supported. The 'job-hold-until-specified'
- SHOULD be specified if the "job-hold-until" Job Template is
- supported. The following values SHOULD be supported: 'job-
- canceled-by-user', 'aborted-by-system', and 'job-completed-
- successfully'. The
- 'job-canceled-by-operator' SHOULD be supported if the
- implementation permits canceling by other than the job owner.
- The 'job-canceled-at-device' SHOULD be supported if the device
- supports canceling jobs at the console. The 'job-completed-
- with-warnings' SHOULD be supported, if the implementation
- detects warnings. The 'job-completed-with-errors' SHOULD be
- supported if the implementation detects errors. The 'job-
- restartable' SHOULD be supported if the Restart-Job operation
- is supported.
- 12. Section 4.3.10 - allowed a Printer to localize the "job-
- detailed-status-message" Job Description attribute, but
- indicated that such localization might obscure the technical
- meaning of such messages.
- 13. Section 4.3.14 - changed the "time-at-creation", "time-at-
- processing", and "time-at-completed" Event Time Job
- Description attributes from OPTIONAL to REQUIRED.
- 14. Section 4.3.14.4 - added the REQUIRED "job-printer-up-time
- (integer(1:MAX))" Job Description attribute as an alias for
- "printer-up-time" to reduce number of operations to get job
- times.
- 15. Section 4.4.2 - added the REQUIRED "uri-authentication-
- supported (1setOf type2 keyword)" Printer Description
- attribute to describe the Client Authentication used by each
- Printer URI.
- 16. Section 4.4.12 - changed "printer-state-reasons" Printer
- Description attribute from OPTIONAL to REQUIRED.
- 17. Section 4.4.12 - changed 'paused' value of "printer-state-
- reasons" to MUST if Pause-Printer operation is supported.
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 222]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
- 18. Section 4.4.14 - added the REQUIRED "ipp-versions-supported
- (1setOf keyword)" Printer Description attribute, since IPP/1.1
- Printers do not have to support version '1.0' conformance
- requirements. Section 4.4.16 - added the "multiple-document-
- jobs-supported (boolean)" Printer Description attribute so
- that a client can tell whether a Printer that supports
- Create-Job/Send-Document supports multiple document jobs or
- not. This attribute is REQUIRED if the Create-Job operation
- is supported.
- 19. Section 4.4.24 - changed the "queued-job-count" Printer
- Description attribute from RECOMMENDED to REQUIRED.
- 20. Section 4.4.32 - changed "compression-supported (1setOf type3
- keyword)" Printer Description attribute from OPTIONAL to
- REQUIRED.
- 21. Section 5.1 - changed the client security requirements from
- RECOMMENDED non-standards track SSL3 to MUST support Client
- Authentication as defined in the IPP/1.1 Encoding and
- Transport document [RFC2910]. A client SHOULD support
- Operation Privacy and Server Authentication as defined in the
- IPP/1.1 Encoding and Transport document [RFC2910].
- 22. Section 5.2.7 - changed the IPP object security requirements
- from OPTIONAL non-standards track SSL3 to SHOULD contain
- support for Client Authentication as defined in the IPP/1.1
- Encoding and Transport document [RFC2910]. A Printer
- implementation MAY allow an administrator to configure the
- Printer so that all, some, or none of the users are
- authenticated. An IPP Printer implementation SHOULD contain
- support for Operation Privacy and Server Authentication as
- defined in the IPP/1.1 Encoding and Transport document
- [RFC2910]. A Printer implementation MAY allow an
- administrator to configure the degree of support for Operation
- Privacy and Server Authentication. Security MUST NOT be
- compromised when the client supplies a lower version-number in
- a request.
- 23. Section 14 (Appendix C): Corrected typo, changing the keyword
- 'iso-10-white' to 'iso-a10-white'.
-
- See also the "IPP/1.1 Encoding and Transport" [RFC2910] document for
- differences between IPP/1.0 [RFC2565] and IPP/1.1 [RFC2910].
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 223]
-\f
-RFC 2911 IPP/1.1: Model and Semantics September 2000
-
-
-18. Full Copyright Statement
-
- Copyright (C) The Internet Society (2000). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Standards Track [Page 224]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group D. Kristol
-Request for Comments: 2965 Bell Laboratories, Lucent Technologies
-Obsoletes: 2109 L. Montulli
-Category: Standards Track Epinions.com, Inc.
- October 2000
-
-
- HTTP State Management Mechanism
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2000). All Rights Reserved.
-
-IESG Note
-
- The IESG notes that this mechanism makes use of the .local top-level
- domain (TLD) internally when handling host names that don't contain
- any dots, and that this mechanism might not work in the expected way
- should an actual .local TLD ever be registered.
-
-Abstract
-
- This document specifies a way to create a stateful session with
- Hypertext Transfer Protocol (HTTP) requests and responses. It
- describes three new headers, Cookie, Cookie2, and Set-Cookie2, which
- carry state information between participating origin servers and user
- agents. The method described here differs from Netscape's Cookie
- proposal [Netscape], but it can interoperate with HTTP/1.0 user
- agents that use Netscape's method. (See the HISTORICAL section.)
-
- This document reflects implementation experience with RFC 2109 and
- obsoletes it.
-
-1. TERMINOLOGY
-
- The terms user agent, client, server, proxy, origin server, and
- http_URL have the same meaning as in the HTTP/1.1 specification
- [RFC2616]. The terms abs_path and absoluteURI have the same meaning
- as in the URI Syntax specification [RFC2396].
-
-
-
-
-Kristol & Montulli Standards Track [Page 1]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- Host name (HN) means either the host domain name (HDN) or the numeric
- Internet Protocol (IP) address of a host. The fully qualified domain
- name is preferred; use of numeric IP addresses is strongly
- discouraged.
-
- The terms request-host and request-URI refer to the values the client
- would send to the server as, respectively, the host (but not port)
- and abs_path portions of the absoluteURI (http_URL) of the HTTP
- request line. Note that request-host is a HN.
-
- The term effective host name is related to host name. If a host name
- contains no dots, the effective host name is that name with the
- string .local appended to it. Otherwise the effective host name is
- the same as the host name. Note that all effective host names
- contain at least one dot.
-
- The term request-port refers to the port portion of the absoluteURI
- (http_URL) of the HTTP request line. If the absoluteURI has no
- explicit port, the request-port is the HTTP default, 80. The
- request-port of a cookie is the request-port of the request in which
- a Set-Cookie2 response header was returned to the user agent.
-
- Host names can be specified either as an IP address or a HDN string.
- Sometimes we compare one host name with another. (Such comparisons
- SHALL be case-insensitive.) Host A's name domain-matches host B's if
-
- * their host name strings string-compare equal; or
-
- * A is a HDN string and has the form NB, where N is a non-empty
- name string, B has the form .B', and B' is a HDN string. (So,
- x.y.com domain-matches .Y.com but not Y.com.)
-
- Note that domain-match is not a commutative operation: a.b.c.com
- domain-matches .c.com, but not the reverse.
-
- The reach R of a host name H is defined as follows:
-
- * If
-
- - H is the host domain name of a host; and,
-
- - H has the form A.B; and
-
- - A has no embedded (that is, interior) dots; and
-
- - B has at least one embedded dot, or B is the string "local".
- then the reach of H is .B.
-
-
-
-
-Kristol & Montulli Standards Track [Page 2]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- * Otherwise, the reach of H is H.
-
- For two strings that represent paths, P1 and P2, P1 path-matches P2
- if P2 is a prefix of P1 (including the case where P1 and P2 string-
- compare equal). Thus, the string /tec/waldo path-matches /tec.
-
- Because it was used in Netscape's original implementation of state
- management, we will use the term cookie to refer to the state
- information that passes between an origin server and user agent, and
- that gets stored by the user agent.
-
-1.1 Requirements
-
- The key words "MAY", "MUST", "MUST NOT", "OPTIONAL", "RECOMMENDED",
- "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT" in this
- document are to be interpreted as described in RFC 2119 [RFC2119].
-
-2. STATE AND SESSIONS
-
- This document describes a way to create stateful sessions with HTTP
- requests and responses. Currently, HTTP servers respond to each
- client request without relating that request to previous or
- subsequent requests; the state management mechanism allows clients
- and servers that wish to exchange state information to place HTTP
- requests and responses within a larger context, which we term a
- "session". This context might be used to create, for example, a
- "shopping cart", in which user selections can be aggregated before
- purchase, or a magazine browsing system, in which a user's previous
- reading affects which offerings are presented.
-
- Neither clients nor servers are required to support cookies. A
- server MAY refuse to provide content to a client that does not return
- the cookies it sends.
-
-3. DESCRIPTION
-
- We describe here a way for an origin server to send state information
- to the user agent, and for the user agent to return the state
- information to the origin server. The goal is to have a minimal
- impact on HTTP and user agents.
-
-3.1 Syntax: General
-
- The two state management headers, Set-Cookie2 and Cookie, have common
- syntactic properties involving attribute-value pairs. The following
- grammar uses the notation, and tokens DIGIT (decimal digits), token
-
-
-
-
-
-Kristol & Montulli Standards Track [Page 3]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- (informally, a sequence of non-special, non-white space characters),
- and http_URL from the HTTP/1.1 specification [RFC2616] to describe
- their syntax.
-
- av-pairs = av-pair *(";" av-pair)
- av-pair = attr ["=" value] ; optional value
- attr = token
- value = token | quoted-string
-
- Attributes (names) (attr) are case-insensitive. White space is
- permitted between tokens. Note that while the above syntax
- description shows value as optional, most attrs require them.
-
- NOTE: The syntax above allows whitespace between the attribute and
- the = sign.
-
-3.2 Origin Server Role
-
- 3.2.1 General The origin server initiates a session, if it so
- desires. To do so, it returns an extra response header to the
- client, Set-Cookie2. (The details follow later.)
-
- A user agent returns a Cookie request header (see below) to the
- origin server if it chooses to continue a session. The origin server
- MAY ignore it or use it to determine the current state of the
- session. It MAY send back to the client a Set-Cookie2 response
- header with the same or different information, or it MAY send no
- Set-Cookie2 header at all. The origin server effectively ends a
- session by sending the client a Set-Cookie2 header with Max-Age=0.
-
- Servers MAY return Set-Cookie2 response headers with any response.
- User agents SHOULD send Cookie request headers, subject to other
- rules detailed below, with every request.
-
- An origin server MAY include multiple Set-Cookie2 headers in a
- response. Note that an intervening gateway could fold multiple such
- headers into a single header.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Kristol & Montulli Standards Track [Page 4]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- 3.2.2 Set-Cookie2 Syntax The syntax for the Set-Cookie2 response
- header is
-
- set-cookie = "Set-Cookie2:" cookies
- cookies = 1#cookie
- cookie = NAME "=" VALUE *(";" set-cookie-av)
- NAME = attr
- VALUE = value
- set-cookie-av = "Comment" "=" value
- | "CommentURL" "=" <"> http_URL <">
- | "Discard"
- | "Domain" "=" value
- | "Max-Age" "=" value
- | "Path" "=" value
- | "Port" [ "=" <"> portlist <"> ]
- | "Secure"
- | "Version" "=" 1*DIGIT
- portlist = 1#portnum
- portnum = 1*DIGIT
-
- Informally, the Set-Cookie2 response header comprises the token Set-
- Cookie2:, followed by a comma-separated list of one or more cookies.
- Each cookie begins with a NAME=VALUE pair, followed by zero or more
- semi-colon-separated attribute-value pairs. The syntax for
- attribute-value pairs was shown earlier. The specific attributes and
- the semantics of their values follows. The NAME=VALUE attribute-
- value pair MUST come first in each cookie. The others, if present,
- can occur in any order. If an attribute appears more than once in a
- cookie, the client SHALL use only the value associated with the first
- appearance of the attribute; a client MUST ignore values after the
- first.
-
- The NAME of a cookie MAY be the same as one of the attributes in this
- specification. However, because the cookie's NAME must come first in
- a Set-Cookie2 response header, the NAME and its VALUE cannot be
- confused with an attribute-value pair.
-
- NAME=VALUE
- REQUIRED. The name of the state information ("cookie") is NAME,
- and its value is VALUE. NAMEs that begin with $ are reserved and
- MUST NOT be used by applications.
-
- The VALUE is opaque to the user agent and may be anything the
- origin server chooses to send, possibly in a server-selected
- printable ASCII encoding. "Opaque" implies that the content is of
- interest and relevance only to the origin server. The content
- may, in fact, be readable by anyone that examines the Set-Cookie2
- header.
-
-
-
-Kristol & Montulli Standards Track [Page 5]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- Comment=value
- OPTIONAL. Because cookies can be used to derive or store private
- information about a user, the value of the Comment attribute
- allows an origin server to document how it intends to use the
- cookie. The user can inspect the information to decide whether to
- initiate or continue a session with this cookie. Characters in
- value MUST be in UTF-8 encoding. [RFC2279]
-
- CommentURL="http_URL"
- OPTIONAL. Because cookies can be used to derive or store private
- information about a user, the CommentURL attribute allows an
- origin server to document how it intends to use the cookie. The
- user can inspect the information identified by the URL to decide
- whether to initiate or continue a session with this cookie.
-
- Discard
- OPTIONAL. The Discard attribute instructs the user agent to
- discard the cookie unconditionally when the user agent terminates.
-
- Domain=value
- OPTIONAL. The value of the Domain attribute specifies the domain
- for which the cookie is valid. If an explicitly specified value
- does not start with a dot, the user agent supplies a leading dot.
-
- Max-Age=value
- OPTIONAL. The value of the Max-Age attribute is delta-seconds,
- the lifetime of the cookie in seconds, a decimal non-negative
- integer. To handle cached cookies correctly, a client SHOULD
- calculate the age of the cookie according to the age calculation
- rules in the HTTP/1.1 specification [RFC2616]. When the age is
- greater than delta-seconds seconds, the client SHOULD discard the
- cookie. A value of zero means the cookie SHOULD be discarded
- immediately.
-
- Path=value
- OPTIONAL. The value of the Path attribute specifies the subset of
- URLs on the origin server to which this cookie applies.
-
- Port[="portlist"]
- OPTIONAL. The Port attribute restricts the port to which a cookie
- may be returned in a Cookie request header. Note that the syntax
- REQUIREs quotes around the OPTIONAL portlist even if there is only
- one portnum in portlist.
-
-
-
-
-
-
-
-
-Kristol & Montulli Standards Track [Page 6]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- Secure
- OPTIONAL. The Secure attribute (with no value) directs the user
- agent to use only (unspecified) secure means to contact the origin
- server whenever it sends back this cookie, to protect the
- confidentially and authenticity of the information in the cookie.
-
- The user agent (possibly with user interaction) MAY determine what
- level of security it considers appropriate for "secure" cookies.
- The Secure attribute should be considered security advice from the
- server to the user agent, indicating that it is in the session's
- interest to protect the cookie contents. When it sends a "secure"
- cookie back to a server, the user agent SHOULD use no less than
- the same level of security as was used when it received the cookie
- from the server.
-
- Version=value
- REQUIRED. The value of the Version attribute, a decimal integer,
- identifies the version of the state management specification to
- which the cookie conforms. For this specification, Version=1
- applies.
-
- 3.2.3 Controlling Caching An origin server must be cognizant of the
- effect of possible caching of both the returned resource and the
- Set-Cookie2 header. Caching "public" documents is desirable. For
- example, if the origin server wants to use a public document such as
- a "front door" page as a sentinel to indicate the beginning of a
- session for which a Set-Cookie2 response header must be generated,
- the page SHOULD be stored in caches "pre-expired" so that the origin
- server will see further requests. "Private documents", for example
- those that contain information strictly private to a session, SHOULD
- NOT be cached in shared caches.
-
- If the cookie is intended for use by a single user, the Set-Cookie2
- header SHOULD NOT be cached. A Set-Cookie2 header that is intended
- to be shared by multiple users MAY be cached.
-
- The origin server SHOULD send the following additional HTTP/1.1
- response headers, depending on circumstances:
-
- * To suppress caching of the Set-Cookie2 header:
-
- Cache-control: no-cache="set-cookie2"
-
- and one of the following:
-
- * To suppress caching of a private document in shared caches:
-
- Cache-control: private
-
-
-
-Kristol & Montulli Standards Track [Page 7]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- * To allow caching of a document and require that it be validated
- before returning it to the client:
-
- Cache-Control: must-revalidate, max-age=0
-
- * To allow caching of a document, but to require that proxy
- caches (not user agent caches) validate it before returning it
- to the client:
-
- Cache-Control: proxy-revalidate, max-age=0
-
- * To allow caching of a document and request that it be validated
- before returning it to the client (by "pre-expiring" it):
-
- Cache-control: max-age=0
-
- Not all caches will revalidate the document in every case.
-
- HTTP/1.1 servers MUST send Expires: old-date (where old-date is a
- date long in the past) on responses containing Set-Cookie2 response
- headers unless they know for certain (by out of band means) that
- there are no HTTP/1.0 proxies in the response chain. HTTP/1.1
- servers MAY send other Cache-Control directives that permit caching
- by HTTP/1.1 proxies in addition to the Expires: old-date directive;
- the Cache-Control directive will override the Expires: old-date for
- HTTP/1.1 proxies.
-
-3.3 User Agent Role
-
- 3.3.1 Interpreting Set-Cookie2 The user agent keeps separate track
- of state information that arrives via Set-Cookie2 response headers
- from each origin server (as distinguished by name or IP address and
- port). The user agent MUST ignore attribute-value pairs whose
- attribute it does not recognize. The user agent applies these
- defaults for optional attributes that are missing:
-
- Discard The default behavior is dictated by the presence or absence
- of a Max-Age attribute.
-
- Domain Defaults to the effective request-host. (Note that because
- there is no dot at the beginning of effective request-host,
- the default Domain can only domain-match itself.)
-
- Max-Age The default behavior is to discard the cookie when the user
- agent exits.
-
- Path Defaults to the path of the request URL that generated the
- Set-Cookie2 response, up to and including the right-most /.
-
-
-
-Kristol & Montulli Standards Track [Page 8]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- Port The default behavior is that a cookie MAY be returned to any
- request-port.
-
- Secure If absent, the user agent MAY send the cookie over an
- insecure channel.
-
- 3.3.2 Rejecting Cookies To prevent possible security or privacy
- violations, a user agent rejects a cookie according to rules below.
- The goal of the rules is to try to limit the set of servers for which
- a cookie is valid, based on the values of the Path, Domain, and Port
- attributes and the request-URI, request-host and request-port.
-
- A user agent rejects (SHALL NOT store its information) if the Version
- attribute is missing. Moreover, a user agent rejects (SHALL NOT
- store its information) if any of the following is true of the
- attributes explicitly present in the Set-Cookie2 response header:
-
- * The value for the Path attribute is not a prefix of the
- request-URI.
-
- * The value for the Domain attribute contains no embedded dots,
- and the value is not .local.
-
- * The effective host name that derives from the request-host does
- not domain-match the Domain attribute.
-
- * The request-host is a HDN (not IP address) and has the form HD,
- where D is the value of the Domain attribute, and H is a string
- that contains one or more dots.
-
- * The Port attribute has a "port-list", and the request-port was
- not in the list.
-
- Examples:
-
- * A Set-Cookie2 from request-host y.x.foo.com for Domain=.foo.com
- would be rejected, because H is y.x and contains a dot.
-
- * A Set-Cookie2 from request-host x.foo.com for Domain=.foo.com
- would be accepted.
-
- * A Set-Cookie2 with Domain=.com or Domain=.com., will always be
- rejected, because there is no embedded dot.
-
- * A Set-Cookie2 with Domain=ajax.com will be accepted, and the
- value for Domain will be taken to be .ajax.com, because a dot
- gets prepended to the value.
-
-
-
-
-Kristol & Montulli Standards Track [Page 9]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- * A Set-Cookie2 with Port="80,8000" will be accepted if the
- request was made to port 80 or 8000 and will be rejected
- otherwise.
-
- * A Set-Cookie2 from request-host example for Domain=.local will
- be accepted, because the effective host name for the request-
- host is example.local, and example.local domain-matches .local.
-
- 3.3.3 Cookie Management If a user agent receives a Set-Cookie2
- response header whose NAME is the same as that of a cookie it has
- previously stored, the new cookie supersedes the old when: the old
- and new Domain attribute values compare equal, using a case-
- insensitive string-compare; and, the old and new Path attribute
- values string-compare equal (case-sensitive). However, if the Set-
- Cookie2 has a value for Max-Age of zero, the (old and new) cookie is
- discarded. Otherwise a cookie persists (resources permitting) until
- whichever happens first, then gets discarded: its Max-Age lifetime is
- exceeded; or, if the Discard attribute is set, the user agent
- terminates the session.
-
- Because user agents have finite space in which to store cookies, they
- MAY also discard older cookies to make space for newer ones, using,
- for example, a least-recently-used algorithm, along with constraints
- on the maximum number of cookies that each origin server may set.
-
- If a Set-Cookie2 response header includes a Comment attribute, the
- user agent SHOULD store that information in a human-readable form
- with the cookie and SHOULD display the comment text as part of a
- cookie inspection user interface.
-
- If a Set-Cookie2 response header includes a CommentURL attribute, the
- user agent SHOULD store that information in a human-readable form
- with the cookie, or, preferably, SHOULD allow the user to follow the
- http_URL link as part of a cookie inspection user interface.
-
- The cookie inspection user interface may include a facility whereby a
- user can decide, at the time the user agent receives the Set-Cookie2
- response header, whether or not to accept the cookie. A potentially
- confusing situation could arise if the following sequence occurs:
-
- * the user agent receives a cookie that contains a CommentURL
- attribute;
-
- * the user agent's cookie inspection interface is configured so
- that it presents a dialog to the user before the user agent
- accepts the cookie;
-
-
-
-
-
-Kristol & Montulli Standards Track [Page 10]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- * the dialog allows the user to follow the CommentURL link when
- the user agent receives the cookie; and,
-
- * when the user follows the CommentURL link, the origin server
- (or another server, via other links in the returned content)
- returns another cookie.
-
- The user agent SHOULD NOT send any cookies in this context. The user
- agent MAY discard any cookie it receives in this context that the
- user has not, through some user agent mechanism, deemed acceptable.
-
- User agents SHOULD allow the user to control cookie destruction, but
- they MUST NOT extend the cookie's lifetime beyond that controlled by
- the Discard and Max-Age attributes. An infrequently-used cookie may
- function as a "preferences file" for network applications, and a user
- may wish to keep it even if it is the least-recently-used cookie. One
- possible implementation would be an interface that allows the
- permanent storage of a cookie through a checkbox (or, conversely, its
- immediate destruction).
-
- Privacy considerations dictate that the user have considerable
- control over cookie management. The PRIVACY section contains more
- information.
-
- 3.3.4 Sending Cookies to the Origin Server When it sends a request
- to an origin server, the user agent includes a Cookie request header
- if it has stored cookies that are applicable to the request, based on
-
- * the request-host and request-port;
-
- * the request-URI;
-
- * the cookie's age.
-
- The syntax for the header is:
-
-cookie = "Cookie:" cookie-version 1*((";" | ",") cookie-value)
-cookie-value = NAME "=" VALUE [";" path] [";" domain] [";" port]
-cookie-version = "$Version" "=" value
-NAME = attr
-VALUE = value
-path = "$Path" "=" value
-domain = "$Domain" "=" value
-port = "$Port" [ "=" <"> value <"> ]
-
- The value of the cookie-version attribute MUST be the value from the
- Version attribute of the corresponding Set-Cookie2 response header.
- Otherwise the value for cookie-version is 0. The value for the path
-
-
-
-Kristol & Montulli Standards Track [Page 11]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- attribute MUST be the value from the Path attribute, if one was
- present, of the corresponding Set-Cookie2 response header. Otherwise
- the attribute SHOULD be omitted from the Cookie request header. The
- value for the domain attribute MUST be the value from the Domain
- attribute, if one was present, of the corresponding Set-Cookie2
- response header. Otherwise the attribute SHOULD be omitted from the
- Cookie request header.
-
- The port attribute of the Cookie request header MUST mirror the Port
- attribute, if one was present, in the corresponding Set-Cookie2
- response header. That is, the port attribute MUST be present if the
- Port attribute was present in the Set-Cookie2 header, and it MUST
- have the same value, if any. Otherwise, if the Port attribute was
- absent from the Set-Cookie2 header, the attribute likewise MUST be
- omitted from the Cookie request header.
-
- Note that there is neither a Comment nor a CommentURL attribute in
- the Cookie request header corresponding to the ones in the Set-
- Cookie2 response header. The user agent does not return the comment
- information to the origin server.
-
- The user agent applies the following rules to choose applicable
- cookie-values to send in Cookie request headers from among all the
- cookies it has received.
-
- Domain Selection
- The origin server's effective host name MUST domain-match the
- Domain attribute of the cookie.
-
- Port Selection
- There are three possible behaviors, depending on the Port
- attribute in the Set-Cookie2 response header:
-
- 1. By default (no Port attribute), the cookie MAY be sent to any
- port.
-
- 2. If the attribute is present but has no value (e.g., Port), the
- cookie MUST only be sent to the request-port it was received
- from.
-
- 3. If the attribute has a port-list, the cookie MUST only be
- returned if the new request-port is one of those listed in
- port-list.
-
- Path Selection
- The request-URI MUST path-match the Path attribute of the cookie.
-
-
-
-
-
-Kristol & Montulli Standards Track [Page 12]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- Max-Age Selection
- Cookies that have expired should have been discarded and thus are
- not forwarded to an origin server.
-
- If multiple cookies satisfy the criteria above, they are ordered in
- the Cookie header such that those with more specific Path attributes
- precede those with less specific. Ordering with respect to other
- attributes (e.g., Domain) is unspecified.
-
- Note: For backward compatibility, the separator in the Cookie header
- is semi-colon (;) everywhere. A server SHOULD also accept comma (,)
- as the separator between cookie-values for future compatibility.
-
- 3.3.5 Identifying What Version is Understood: Cookie2 The Cookie2
- request header facilitates interoperation between clients and servers
- that understand different versions of the cookie specification. When
- the client sends one or more cookies to an origin server, if at least
- one of those cookies contains a $Version attribute whose value is
- different from the version that the client understands, then the
- client MUST also send a Cookie2 request header, the syntax for which
- is
-
- cookie2 = "Cookie2:" cookie-version
-
- Here the value for cookie-version is the highest version of cookie
- specification (currently 1) that the client understands. The client
- needs to send at most one such request header per request.
-
- 3.3.6 Sending Cookies in Unverifiable Transactions Users MUST have
- control over sessions in order to ensure privacy. (See PRIVACY
- section below.) To simplify implementation and to prevent an
- additional layer of complexity where adequate safeguards exist,
- however, this document distinguishes between transactions that are
- verifiable and those that are unverifiable. A transaction is
- verifiable if the user, or a user-designated agent, has the option to
- review the request-URI prior to its use in the transaction. A
- transaction is unverifiable if the user does not have that option.
- Unverifiable transactions typically arise when a user agent
- automatically requests inlined or embedded entities or when it
- resolves redirection (3xx) responses from an origin server.
- Typically the origin transaction, the transaction that the user
- initiates, is verifiable, and that transaction may directly or
- indirectly induce the user agent to make unverifiable transactions.
-
- An unverifiable transaction is to a third-party host if its request-
- host U does not domain-match the reach R of the request-host O in the
- origin transaction.
-
-
-
-
-Kristol & Montulli Standards Track [Page 13]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- When it makes an unverifiable transaction, a user agent MUST disable
- all cookie processing (i.e., MUST NOT send cookies, and MUST NOT
- accept any received cookies) if the transaction is to a third-party
- host.
-
- This restriction prevents a malicious service author from using
- unverifiable transactions to induce a user agent to start or continue
- a session with a server in a different domain. The starting or
- continuation of such sessions could be contrary to the privacy
- expectations of the user, and could also be a security problem.
-
- User agents MAY offer configurable options that allow the user agent,
- or any autonomous programs that the user agent executes, to ignore
- the above rule, so long as these override options default to "off".
-
- (N.B. Mechanisms may be proposed that will automate overriding the
- third-party restrictions under controlled conditions.)
-
- Many current user agents already provide a review option that would
- render many links verifiable. For instance, some user agents display
- the URL that would be referenced for a particular link when the mouse
- pointer is placed over that link. The user can therefore determine
- whether to visit that site before causing the browser to do so.
- (Though not implemented on current user agents, a similar technique
- could be used for a button used to submit a form -- the user agent
- could display the action to be taken if the user were to select that
- button.) However, even this would not make all links verifiable; for
- example, links to automatically loaded images would not normally be
- subject to "mouse pointer" verification.
-
- Many user agents also provide the option for a user to view the HTML
- source of a document, or to save the source to an external file where
- it can be viewed by another application. While such an option does
- provide a crude review mechanism, some users might not consider it
- acceptable for this purpose.
-
-3.4 How an Origin Server Interprets the Cookie Header
-
- A user agent returns much of the information in the Set-Cookie2
- header to the origin server when the request-URI path-matches the
- Path attribute of the cookie. When it receives a Cookie header, the
- origin server SHOULD treat cookies with NAMEs whose prefix is $
- specially, as an attribute for the cookie.
-
-
-
-
-
-
-
-
-Kristol & Montulli Standards Track [Page 14]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
-3.5 Caching Proxy Role
-
- One reason for separating state information from both a URL and
- document content is to facilitate the scaling that caching permits.
- To support cookies, a caching proxy MUST obey these rules already in
- the HTTP specification:
-
- * Honor requests from the cache, if possible, based on cache
- validity rules.
-
- * Pass along a Cookie request header in any request that the
- proxy must make of another server.
-
- * Return the response to the client. Include any Set-Cookie2
- response header.
-
- * Cache the received response subject to the control of the usual
- headers, such as Expires,
-
- Cache-control: no-cache
-
- and
-
- Cache-control: private
-
- * Cache the Set-Cookie2 subject to the control of the usual
- header,
-
- Cache-control: no-cache="set-cookie2"
-
- (The Set-Cookie2 header should usually not be cached.)
-
- Proxies MUST NOT introduce Set-Cookie2 (Cookie) headers of their own
- in proxy responses (requests).
-
-4. EXAMPLES
-
-4.1 Example 1
-
- Most detail of request and response headers has been omitted. Assume
- the user agent has no stored cookies.
-
- 1. User Agent -> Server
-
- POST /acme/login HTTP/1.1
- [form data]
-
- User identifies self via a form.
-
-
-
-Kristol & Montulli Standards Track [Page 15]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- 2. Server -> User Agent
-
- HTTP/1.1 200 OK
- Set-Cookie2: Customer="WILE_E_COYOTE"; Version="1"; Path="/acme"
-
- Cookie reflects user's identity.
-
- 3. User Agent -> Server
-
- POST /acme/pickitem HTTP/1.1
- Cookie: $Version="1"; Customer="WILE_E_COYOTE"; $Path="/acme"
- [form data]
-
- User selects an item for "shopping basket".
-
- 4. Server -> User Agent
-
- HTTP/1.1 200 OK
- Set-Cookie2: Part_Number="Rocket_Launcher_0001"; Version="1";
- Path="/acme"
-
- Shopping basket contains an item.
-
- 5. User Agent -> Server
-
- POST /acme/shipping HTTP/1.1
- Cookie: $Version="1";
- Customer="WILE_E_COYOTE"; $Path="/acme";
- Part_Number="Rocket_Launcher_0001"; $Path="/acme"
- [form data]
-
- User selects shipping method from form.
-
- 6. Server -> User Agent
-
- HTTP/1.1 200 OK
- Set-Cookie2: Shipping="FedEx"; Version="1"; Path="/acme"
-
- New cookie reflects shipping method.
-
- 7. User Agent -> Server
-
- POST /acme/process HTTP/1.1
- Cookie: $Version="1";
- Customer="WILE_E_COYOTE"; $Path="/acme";
- Part_Number="Rocket_Launcher_0001"; $Path="/acme";
- Shipping="FedEx"; $Path="/acme"
- [form data]
-
-
-
-Kristol & Montulli Standards Track [Page 16]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- User chooses to process order.
-
- 8. Server -> User Agent
-
- HTTP/1.1 200 OK
-
- Transaction is complete.
-
- The user agent makes a series of requests on the origin server, after
- each of which it receives a new cookie. All the cookies have the
- same Path attribute and (default) domain. Because the request-URIs
- all path-match /acme, the Path attribute of each cookie, each request
- contains all the cookies received so far.
-
-4.2 Example 2
-
- This example illustrates the effect of the Path attribute. All
- detail of request and response headers has been omitted. Assume the
- user agent has no stored cookies.
-
- Imagine the user agent has received, in response to earlier requests,
- the response headers
-
- Set-Cookie2: Part_Number="Rocket_Launcher_0001"; Version="1";
- Path="/acme"
-
- and
-
- Set-Cookie2: Part_Number="Riding_Rocket_0023"; Version="1";
- Path="/acme/ammo"
-
- A subsequent request by the user agent to the (same) server for URLs
- of the form /acme/ammo/... would include the following request
- header:
-
- Cookie: $Version="1";
- Part_Number="Riding_Rocket_0023"; $Path="/acme/ammo";
- Part_Number="Rocket_Launcher_0001"; $Path="/acme"
-
- Note that the NAME=VALUE pair for the cookie with the more specific
- Path attribute, /acme/ammo, comes before the one with the less
- specific Path attribute, /acme. Further note that the same cookie
- name appears more than once.
-
- A subsequent request by the user agent to the (same) server for a URL
- of the form /acme/parts/ would include the following request header:
-
-
-
-
-
-Kristol & Montulli Standards Track [Page 17]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- Cookie: $Version="1"; Part_Number="Rocket_Launcher_0001";
- $Path="/acme"
-
- Here, the second cookie's Path attribute /acme/ammo is not a prefix
- of the request URL, /acme/parts/, so the cookie does not get
- forwarded to the server.
-
-5. IMPLEMENTATION CONSIDERATIONS
-
- Here we provide guidance on likely or desirable details for an origin
- server that implements state management.
-
-5.1 Set-Cookie2 Content
-
- An origin server's content should probably be divided into disjoint
- application areas, some of which require the use of state
- information. The application areas can be distinguished by their
- request URLs. The Set-Cookie2 header can incorporate information
- about the application areas by setting the Path attribute for each
- one.
-
- The session information can obviously be clear or encoded text that
- describes state. However, if it grows too large, it can become
- unwieldy. Therefore, an implementor might choose for the session
- information to be a key to a server-side resource. Of course, using
- a database creates some problems that this state management
- specification was meant to avoid, namely:
-
- 1. keeping real state on the server side;
-
- 2. how and when to garbage-collect the database entry, in case the
- user agent terminates the session by, for example, exiting.
-
-5.2 Stateless Pages
-
- Caching benefits the scalability of WWW. Therefore it is important
- to reduce the number of documents that have state embedded in them
- inherently. For example, if a shopping-basket-style application
- always displays a user's current basket contents on each page, those
- pages cannot be cached, because each user's basket's contents would
- be different. On the other hand, if each page contains just a link
- that allows the user to "Look at My Shopping Basket", the page can be
- cached.
-
-
-
-
-
-
-
-
-Kristol & Montulli Standards Track [Page 18]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
-5.3 Implementation Limits
-
- Practical user agent implementations have limits on the number and
- size of cookies that they can store. In general, user agents' cookie
- support should have no fixed limits. They should strive to store as
- many frequently-used cookies as possible. Furthermore, general-use
- user agents SHOULD provide each of the following minimum capabilities
- individually, although not necessarily simultaneously:
-
- * at least 300 cookies
-
- * at least 4096 bytes per cookie (as measured by the characters
- that comprise the cookie non-terminal in the syntax description
- of the Set-Cookie2 header, and as received in the Set-Cookie2
- header)
-
- * at least 20 cookies per unique host or domain name
-
- User agents created for specific purposes or for limited-capacity
- devices SHOULD provide at least 20 cookies of 4096 bytes, to ensure
- that the user can interact with a session-based origin server.
-
- The information in a Set-Cookie2 response header MUST be retained in
- its entirety. If for some reason there is inadequate space to store
- the cookie, it MUST be discarded, not truncated.
-
- Applications should use as few and as small cookies as possible, and
- they should cope gracefully with the loss of a cookie.
-
- 5.3.1 Denial of Service Attacks User agents MAY choose to set an
- upper bound on the number of cookies to be stored from a given host
- or domain name or on the size of the cookie information. Otherwise a
- malicious server could attempt to flood a user agent with many
- cookies, or large cookies, on successive responses, which would force
- out cookies the user agent had received from other servers. However,
- the minima specified above SHOULD still be supported.
-
-6. PRIVACY
-
- Informed consent should guide the design of systems that use cookies.
- A user should be able to find out how a web site plans to use
- information in a cookie and should be able to choose whether or not
- those policies are acceptable. Both the user agent and the origin
- server must assist informed consent.
-
-
-
-
-
-
-
-Kristol & Montulli Standards Track [Page 19]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
-6.1 User Agent Control
-
- An origin server could create a Set-Cookie2 header to track the path
- of a user through the server. Users may object to this behavior as
- an intrusive accumulation of information, even if their identity is
- not evident. (Identity might become evident, for example, if a user
- subsequently fills out a form that contains identifying information.)
- This state management specification therefore requires that a user
- agent give the user control over such a possible intrusion, although
- the interface through which the user is given this control is left
- unspecified. However, the control mechanisms provided SHALL at least
- allow the user
-
- * to completely disable the sending and saving of cookies.
-
- * to determine whether a stateful session is in progress.
-
- * to control the saving of a cookie on the basis of the cookie's
- Domain attribute.
-
- Such control could be provided, for example, by mechanisms
-
- * to notify the user when the user agent is about to send a
- cookie to the origin server, to offer the option not to begin a
- session.
-
- * to display a visual indication that a stateful session is in
- progress.
-
- * to let the user decide which cookies, if any, should be saved
- when the user concludes a window or user agent session.
-
- * to let the user examine and delete the contents of a cookie at
- any time.
-
- A user agent usually begins execution with no remembered state
- information. It SHOULD be possible to configure a user agent never
- to send Cookie headers, in which case it can never sustain state with
- an origin server. (The user agent would then behave like one that is
- unaware of how to handle Set-Cookie2 response headers.)
-
- When the user agent terminates execution, it SHOULD let the user
- discard all state information. Alternatively, the user agent MAY ask
- the user whether state information should be retained; the default
- should be "no". If the user chooses to retain state information, it
- would be restored the next time the user agent runs.
-
-
-
-
-
-Kristol & Montulli Standards Track [Page 20]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- NOTE: User agents should probably be cautious about using files to
- store cookies long-term. If a user runs more than one instance of
- the user agent, the cookies could be commingled or otherwise
- corrupted.
-
-6.2 Origin Server Role
-
- An origin server SHOULD promote informed consent by adding CommentURL
- or Comment information to the cookies it sends. CommentURL is
- preferred because of the opportunity to provide richer information in
- a multiplicity of languages.
-
-6.3 Clear Text
-
- The information in the Set-Cookie2 and Cookie headers is unprotected.
- As a consequence:
-
- 1. Any sensitive information that is conveyed in them is exposed
- to intruders.
-
- 2. A malicious intermediary could alter the headers as they travel
- in either direction, with unpredictable results.
-
- These facts imply that information of a personal and/or financial
- nature should only be sent over a secure channel. For less sensitive
- information, or when the content of the header is a database key, an
- origin server should be vigilant to prevent a bad Cookie value from
- causing failures.
-
- A user agent in a shared user environment poses a further risk.
- Using a cookie inspection interface, User B could examine the
- contents of cookies that were saved when User A used the machine.
-
-7. SECURITY CONSIDERATIONS
-
-7.1 Protocol Design
-
- The restrictions on the value of the Domain attribute, and the rules
- concerning unverifiable transactions, are meant to reduce the ways
- that cookies can "leak" to the "wrong" site. The intent is to
- restrict cookies to one host, or a closely related set of hosts.
- Therefore a request-host is limited as to what values it can set for
- Domain. We consider it acceptable for hosts host1.foo.com and
- host2.foo.com to share cookies, but not a.com and b.com.
-
- Similarly, a server can set a Path only for cookies that are related
- to the request-URI.
-
-
-
-
-Kristol & Montulli Standards Track [Page 21]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
-7.2 Cookie Spoofing
-
- Proper application design can avoid spoofing attacks from related
- domains. Consider:
-
- 1. User agent makes request to victim.cracker.edu, gets back
- cookie session_id="1234" and sets the default domain
- victim.cracker.edu.
-
- 2. User agent makes request to spoof.cracker.edu, gets back cookie
- session-id="1111", with Domain=".cracker.edu".
-
- 3. User agent makes request to victim.cracker.edu again, and
- passes
-
- Cookie: $Version="1"; session_id="1234",
- $Version="1"; session_id="1111"; $Domain=".cracker.edu"
-
- The server at victim.cracker.edu should detect that the second
- cookie was not one it originated by noticing that the Domain
- attribute is not for itself and ignore it.
-
-7.3 Unexpected Cookie Sharing
-
- A user agent SHOULD make every attempt to prevent the sharing of
- session information between hosts that are in different domains.
- Embedded or inlined objects may cause particularly severe privacy
- problems if they can be used to share cookies between disparate
- hosts. For example, a malicious server could embed cookie
- information for host a.com in a URI for a CGI on host b.com. User
- agent implementors are strongly encouraged to prevent this sort of
- exchange whenever possible.
-
-7.4 Cookies For Account Information
-
- While it is common practice to use them this way, cookies are not
- designed or intended to be used to hold authentication information,
- such as account names and passwords. Unless such cookies are
- exchanged over an encrypted path, the account information they
- contain is highly vulnerable to perusal and theft.
-
-8. OTHER, SIMILAR, PROPOSALS
-
- Apart from RFC 2109, three other proposals have been made to
- accomplish similar goals. This specification began as an amalgam of
- Kristol's State-Info proposal [DMK95] and Netscape's Cookie proposal
- [Netscape].
-
-
-
-
-Kristol & Montulli Standards Track [Page 22]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- Brian Behlendorf proposed a Session-ID header that would be user-
- agent-initiated and could be used by an origin server to track
- "clicktrails". It would not carry any origin-server-defined state,
- however. Phillip Hallam-Baker has proposed another client-defined
- session ID mechanism for similar purposes.
-
- While both session IDs and cookies can provide a way to sustain
- stateful sessions, their intended purpose is different, and,
- consequently, the privacy requirements for them are different. A
- user initiates session IDs to allow servers to track progress through
- them, or to distinguish multiple users on a shared machine. Cookies
- are server-initiated, so the cookie mechanism described here gives
- users control over something that would otherwise take place without
- the users' awareness. Furthermore, cookies convey rich, server-
- selected information, whereas session IDs comprise user-selected,
- simple information.
-
-9. HISTORICAL
-
-9.1 Compatibility with Existing Implementations
-
- Existing cookie implementations, based on the Netscape specification,
- use the Set-Cookie (not Set-Cookie2) header. User agents that
- receive in the same response both a Set-Cookie and Set-Cookie2
- response header for the same cookie MUST discard the Set-Cookie
- information and use only the Set-Cookie2 information. Furthermore, a
- user agent MUST assume, if it received a Set-Cookie2 response header,
- that the sending server complies with this document and will
- understand Cookie request headers that also follow this
- specification.
-
- New cookies MUST replace both equivalent old- and new-style cookies.
- That is, if a user agent that follows both this specification and
- Netscape's original specification receives a Set-Cookie2 response
- header, and the NAME and the Domain and Path attributes match (per
- the Cookie Management section) a Netscape-style cookie, the
- Netscape-style cookie MUST be discarded, and the user agent MUST
- retain only the cookie adhering to this specification.
-
- Older user agents that do not understand this specification, but that
- do understand Netscape's original specification, will not recognize
- the Set-Cookie2 response header and will receive and send cookies
- according to the older specification.
-
-
-
-
-
-
-
-
-Kristol & Montulli Standards Track [Page 23]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
- A user agent that supports both this specification and Netscape-style
- cookies SHOULD send a Cookie request header that follows the older
- Netscape specification if it received the cookie in a Set-Cookie
- response header and not in a Set-Cookie2 response header. However,
- it SHOULD send the following request header as well:
-
- Cookie2: $Version="1"
-
- The Cookie2 header advises the server that the user agent understands
- new-style cookies. If the server understands new-style cookies, as
- well, it SHOULD continue the stateful session by sending a Set-
- Cookie2 response header, rather than Set-Cookie. A server that does
- not understand new-style cookies will simply ignore the Cookie2
- request header.
-
-9.2 Caching and HTTP/1.0
-
- Some caches, such as those conforming to HTTP/1.0, will inevitably
- cache the Set-Cookie2 and Set-Cookie headers, because there was no
- mechanism to suppress caching of headers prior to HTTP/1.1. This
- caching can lead to security problems. Documents transmitted by an
- origin server along with Set-Cookie2 and Set-Cookie headers usually
- either will be uncachable, or will be "pre-expired". As long as
- caches obey instructions not to cache documents (following Expires:
- <a date in the past> or Pragma: no-cache (HTTP/1.0), or Cache-
- control: no-cache (HTTP/1.1)) uncachable documents present no
- problem. However, pre-expired documents may be stored in caches.
- They require validation (a conditional GET) on each new request, but
- some cache operators loosen the rules for their caches, and sometimes
- serve expired documents without first validating them. This
- combination of factors can lead to cookies meant for one user later
- being sent to another user. The Set-Cookie2 and Set-Cookie headers
- are stored in the cache, and, although the document is stale
- (expired), the cache returns the document in response to later
- requests, including cached headers.
-
-10. ACKNOWLEDGEMENTS
-
- This document really represents the collective efforts of the HTTP
- Working Group of the IETF and, particularly, the following people, in
- addition to the authors: Roy Fielding, Yaron Goland, Marc Hedlund,
- Ted Hardie, Koen Holtman, Shel Kaphan, Rohit Khare, Foteos Macrides,
- David W. Morris.
-
-
-
-
-
-
-
-
-Kristol & Montulli Standards Track [Page 24]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
-11. AUTHORS' ADDRESSES
-
- David M. Kristol
- Bell Laboratories, Lucent Technologies
- 600 Mountain Ave. Room 2A-333
- Murray Hill, NJ 07974
-
- Phone: (908) 582-2250
- Fax: (908) 582-1239
- EMail: dmk@bell-labs.com
-
-
- Lou Montulli
- Epinions.com, Inc.
- 2037 Landings Dr.
- Mountain View, CA 94301
-
- EMail: lou@montulli.org
-
-12. REFERENCES
-
- [DMK95] Kristol, D.M., "Proposed HTTP State-Info Mechanism",
- available at <http://portal.research.bell-
- labs.com/~dmk/state-info.html>, September, 1995.
-
- [Netscape] "Persistent Client State -- HTTP Cookies", available at
- <http://www.netscape.com/newsref/std/cookie_spec.html>,
- undated.
-
- [RFC2109] Kristol, D. and L. Montulli, "HTTP State Management
- Mechanism", RFC 2109, February 1997.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2279] Yergeau, F., "UTF-8, a transformation format of Unicode
- and ISO-10646", RFC 2279, January 1998.
-
- [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
- Resource Identifiers (URI): Generic Syntax", RFC 2396,
- August 1998.
-
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H. and T.
- Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1",
- RFC 2616, June 1999.
-
-
-
-
-
-
-Kristol & Montulli Standards Track [Page 25]
-\f
-RFC 2965 HTTP State Management Mechanism October 2000
-
-
-13. Full Copyright Statement
-
- Copyright (C) The Internet Society (2000). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Kristol & Montulli Standards Track [Page 26]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group T. Hastings
-Request for Comments: 3196 C. Manros
-Obsoletes: 2639 P. Zehler
-Category: Informational Xerox Corporation
- C. Kugler
- IBM Printing Systems Co
- H. Holst
- i-data Printing Systems
- November 2001
-
-
- Internet Printing Protocol/1.1: Implementor's Guide
-
-Status of this Memo
-
- This memo provides information for the Internet community. It does
- not specify an Internet standard of any kind. Distribution of this
- memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2001). All Rights Reserved.
-
-Abstract
-
- This document is one of a set of documents, which together describe
- all aspects of a new Internet Printing Protocol (IPP).
-
-Table of Contents
-
- 1 Introduction................................................... 4
- 1.1 Conformance language........................................ 5
- 1.2 Other terminology........................................... 6
- 1.3 Issues Raised from Interoperability Testing Events.......... 6
- 2 IPP Objects.................................................... 6
- 3 IPP Operations................................................. 7
- 3.1 Common Semantics............................................ 7
- 3.1.1 Summary of Operation Attributes............................ 8
- 3.1.2 Suggested Operation Processing Steps for IPP Objects....... 16
- 3.1.2.1 Suggested Operation Processing Steps for all Operations. 17
- 3.1.2.1.1 Validate version number............................... 18
- 3.1.2.1.2 Validate operation identifier......................... 20
- 3.1.2.1.3 Validate the request identifier....................... 20
- 3.1.2.1.4 Validate attribute group and attribute presence and
- order................................................. 20
- 3.1.2.1.4.1 Validate the presence and order of attribute groups. 20
- 3.1.2.1.4.2 Ignore unknown attribute groups in the expected
- position............................................ 21
-
-
-
-Hastings, et al. Informational [Page 1]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- 3.1.2.1.4.3 Validate the presence of a single occurrence of
- required Operation attributes....................... 21
- 3.1.2.1.5 Validate the values of the REQUIRED Operation
- attributes............................................ 29
- 3.1.2.1.6 Validate the values of the OPTIONAL Operation
- attributes............................................ 33
- 3.1.2.2 Suggested Additional Processing Steps for Operations
- that Create/Validate Jobs and Add Documents............. 37
- 3.1.2.2.1 Default "ipp-attribute-fidelity" if not supplied...... 37
- 3.1.2.2.2 Check that the Printer object is accepting jobs....... 38
- 3.1.2.2.3 Validate the values of the Job Template attributes.... 38
- 3.1.2.3 Algorithm for job validation............................ 39
- 3.1.2.3.1 Check for conflicting Job Template attributes values.. 45
- 3.1.2.3.2 Decide whether to REJECT the request.................. 46
- 3.1.2.3.3 For the Validate-Job operation, RETURN one of the
- success status codes.................................. 48
- 3.1.2.3.4 Create the Job object with attributes to support...... 48
- 3.1.2.3.5 Return one of the success status codes................ 50
- 3.1.2.3.6 Accept appended Document Content...................... 50
- 3.1.2.3.7 Scheduling and Starting to Process the Job............ 50
- 3.1.2.3.8 Completing the Job.................................... 50
- 3.1.2.3.9 Destroying the Job after completion................... 51
- 3.1.2.3.10 Interaction with "ipp-attribute-fidelity"............. 51
- 3.1.2.3.11 Character set code conversion support................. 51
- 3.1.2.3.12 What charset to return when an unsupported charset is
- requested (Issue 1.19)?....... ....................... 52
- 3.1.2.3.13 Natural Language Override (NLO)....................... 53
- 3.1.3 Status codes returned by operation......................... 55
- 3.1.3.1 Printer Operations...................................... 55
- 3.1.3.1.1 Print-Job............................................. 55
- 3.1.3.1.2 Print-URI............................................. 58
- 3.1.3.1.3 Validate-Job.......................................... 58
- 3.1.3.1.4 Create-Job............................................ 58
- 3.1.3.1.5 Get-Printer-Attributes................................ 59
- 3.1.3.1.6 Get-Jobs.............................................. 60
- 3.1.3.1.7 Pause-Printer......................................... 61
- 3.1.3.1.8 Resume-Printer........................................ 62
- 3.1.3.1.8.1 What about Printers unable to change state due to
- an error condition?................................. 63
- 3.1.3.1.8.2 How is "printer-state" handled on Resume-Printer?... 63
- 3.1.3.1.9 Purge-Printer......................................... 63
- 3.1.3.2 Job Operations.......................................... 64
- 3.1.3.2.1 Send-Document......................................... 64
- 3.1.3.2.2 Send-URI.............................................. 65
- 3.1.3.2.3 Cancel-Job............................................ 65
- 3.1.3.2.4 Get-Job-Attributes.................................... 67
- 3.1.3.2.5 Hold-Job.............................................. 68
- 3.1.3.2.6 Release-Job........................................... 69
-
-
-
-Hastings, et al. Informational [Page 2]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- 3.1.3.2.7 Restart-Job........................................... 69
- 3.1.3.2.7.1 Can documents be added to a restarted job?.......... 69
- 3.1.4 Returning unsupported attributes in Get-Xxxx responses
- (Issue 1.18)............................................... 70
- 3.1.5 Sending empty attribute groups............................. 70
- 3.2 Printer Operations.......................................... 71
- 3.2.1 Print-Job operation........................................ 71
- 3.2.1.1 Flow controlling the data portion of a Print-Job
- request (Issue 1.22).................................... 71
- 3.2.1.2 Returning job-state in Print-Job response (Issue 1.30).. 71
- 3.2.2 Get-Printer-Attributes operation........................... 72
- 3.2.3 Get-Jobs operation......................................... 72
- 3.2.3.1 Get-Jobs, my-jobs='true', and 'requesting-user-name'
- (Issue 1.39)?.......................................... 72
- 3.2.3.2 Why is there a "limit" attribute in the Get-Jobs
- operation?.............................................. 73
- 3.2.4 Create-Job operation....................................... 73
- 3.3 Job Operations.............................................. 74
- 3.3.1 Validate-Job............................................... 74
- 3.3.2 Restart-Job................................................ 74
- 4 Object Attributes.............................................. 74
- 4.1 Attribute Syntax's.......................................... 74
- 4.1.1 The 'none' value for empty sets (Issue 1.37)............... 74
- 4.1.2 Multi-valued attributes (Issue 1.31)....................... 75
- 4.1.3 Case Sensitivity in URIs (issue 1.6)....................... 75
- 4.1.4 Maximum length for xxxWithLanguage and xxxWithoutLanguage.. 76
- 4.2 Job Template Attributes..................................... 76
- 4.2.1 multiple-document-handling(type2 keyword).................. 76
- 4.2.1.1 Support of multiple document jobs....................... 76
- 4.3 Job Description Attributes.................................. 76
- 4.3.1 Getting the date and time of day........................... 76
- 4.4 Printer Description Attributes.............................. 77
- 4.4.1 queued-job-count (integer(0:MAX)).......................... 77
- 4.4.1.1 Why is "queued-job-count" RECOMMENDED (Issue 1.14)?..... 77
- 4.4.1.2 Is "queued-job-count" a good measure of how busy a
- printer is (Issue 1.15)?................................ 77
- 4.4.2 printer-current-time (dateTime)............................ 78
- 4.4.3 Printer-uri................................................ 78
- 4.5 Empty Jobs.................................................. 79
- 5 Directory Considerations....................................... 79
- 5.1 General Directory Schema Considerations..................... 79
- 5.2 IPP Printer with a DNS name................................. 79
- 6 Security Considerations........................................ 80
- 6.1 Querying jobs with IPP that were submitted using other job
- submission protocols (Issue 1.32)........................... 80
- 7 Encoding and Transport......................................... 81
- 7.1 General Headers............................................. 83
- 7.2 Request Headers............................................ 84
-
-
-
-Hastings, et al. Informational [Page 3]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- 7.3 Response Headers............................................ 86
- 7.4 Entity Headers............................................. 87
- 7.5 Optional support for HTTP/1.0............................... 88
- 7.6 HTTP/1.1 Chunking........................................... 88
- 7.6.1 Disabling IPP Server Response Chunking..................... 88
- 7.6.2 Warning About the Support of Chunked Requests.............. 88
- 8 References..................................................... 89
- 9 Authors' Addresses............................................. 91
- 10 Description of the Base IPP Documents.......................... 94
- 11 Full Copyright Statement....................................... 96
-
-Tables
-
- Table 1 - Summary of Printer operation attributes that sender MUST
- supply ................................................. 8
- Table 2 - Summary of Printer operation attributes that sender MAY
- supply ................................................. 10
- Table 3 - Summary of Job operation attributes that sender MUST
- supply.................................................. 12
- Table 4 - Summary of Job operation attributes that sender MAY
- supply.................................................. 14
- Table 5 - Printer operation response attributes................... 16
- Table 6 - Examples of validating IPP version...................... 19
- Table 7 - Rules for validating single values X against Z.......... 40
-
-1. Introduction
-
- IPP is an application level protocol that can be used for distributed
- printing using Internet tools and technologies. This document
- contains information that supplements the IPP Model and Semantics
- [RFC2911] and the IPP Transport and Encoding [RFC2910] documents. It
- is intended to help implementers understand IPP/1.1, as well as
- IPP/1.0 [RFC2565, RFC2566], and some of the considerations that may
- assist them in the design of their client and/or IPP object
- implementation. For example, a typical order of processing requests
- is given, including error checking. Motivation for some of the
- specification decisions is also included.
-
- This document obsoletes RFC 2639 which was the Implementor's Guide
- for IPP/1.0. The IPP Implementor's Guide (IIG) (this document)
- contains information that supplements the IPP Model and Semantics
- [RFC2911] and the IPP Transport and Encoding [RFC2910] documents.
- This document is just one of a suite of documents that fully define
- IPP. The base set of IPP documents includes:
-
- Design Goals for an Internet Printing Protocol [RFC2567]
- Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol [RFC2568]
-
-
-
-Hastings, et al. Informational [Page 4]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Internet Printing Protocol/1.1: Model and Semantics [RFC2911]
- Internet Printing Protocol/1.1: Encoding and Transport [RFC2910]
- Internet Printing Protocol/1.1: Implementor's Guide (this
- document)
- Mapping between LPD and IPP Protocols [RFC2569]
-
- See section 10 for a description of these base IPP documents. Anyone
- reading these documents for the first time is strongly encouraged to
- read the IPP documents in the above order.
-
- As such the information in this document is not part of the formal
- specification of IPP/1.1. Instead information is presented to help
- implementers understand IPP/1.1, as well as IPP/1.0 [RFC2565,
- RFC2566], including some of the motivation for decisions taken by the
- committee in developing the specification. Some of the
- implementation considerations are intended to help implementers
- design their client and/or IPP object implementations. If there are
- any contradictions between this document and [RFC2911] or [RFC2910],
- those documents take precedence over this document.
-
- Platform-specific implementation considerations will be included in
- this guide as they become known.
-
- Note: In order to help the reader of the IIG and the IPP Model and
- Semantics document, the sections in this document parallel the
- corresponding sections in the Model document and are numbered the
- same for ease of cross reference. The sections that correspond to
- the IPP Transport and Encoding are correspondingly offset.
-
-1.1 Conformance language
-
- Usually, this document does not contain the terminology MUST, MUST
- NOT, MAY, NEED NOT, SHOULD, SHOULD NOT, REQUIRED, and OPTIONAL.
- However, when those terms do appear in this document, their intent is
- to repeat what the [RFC2911] and [RFC2910] documents require and
- allow, rather than specifying additional conformance requirements.
- These terms are defined in section 12 on conformance terminology in
- [RFC2911], most of which is taken from RFC 2119 [RFC2119].
-
- Implementers should read section 12 (APPENDIX A) in [RFC2911] in
- order to understand these capitalized words. The words MUST, MUST
- NOT, and REQUIRED indicate what implementations are required to
- support in a client or IPP object in order to be conformant to
- [RFC2911] and [RFC2910]. MAY, NEED NOT, and OPTIONAL indicate was is
- merely allowed as an implementer option. The verbs SHOULD and SHOULD
- NOT indicate suggested behavior, but which is not required or
- disallowed, respectively, in order to conform to the specification.
-
-
-
-
-Hastings, et al. Informational [Page 5]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-1.2 Other terminology
-
- This document uses other terms, such as "attributes", "operation",
- and "Printer" as defined in [RFC2911] section 12. In addition, the
- term "sender" refers to the client that sends a request or an IPP
- object that returns a response. The term "receiver" refers to the
- IPP object that receives a request and to a client that receives a
- response.
-
-1.3 Issues Raised from Interoperability Testing Events
-
- The IPP WG has conducted three open Interoperability Testing Events.
- The first one was held in September 1998, the second one was held in
- March 1999, and the third one was held in October 2000. See the
- summary reports in:
-
- ftp://ftp.pwg.org/pub/pwg/ipp/new_TES/
-
- The issues raised from the first Interoperability Testing Event are
- numbered 1.n in this document and have been incorporated into
- "IPP/1.0 Model and Semantics" [RFC2566] and the "IPP/1.0 Encoding and
- Transport" [RFC2565] documents. However, some of the discussion is
- left here in the Implementor's Guide to help understanding.
-
- The issues raised from the second Interoperability Testing Event are
- numbered 2.n in this document have been incorporated into "IPP/1.1
- Model and Semantics" [RFC2911] and the "IPP/1.1 Encoding and
- Transport" [RFC2910] documents. However, some of the discussion is
- left here in the Implementor's Guide to help understanding.
-
- The issues raised from the third Interoperability Testing Event are
- numbered 3.n in this document and are described in:
-
- ftp://ftp.pwg.org/pub/pwg/ipp/Issues/Issues-raised-at-Bake-
- Off3.pdf
-
- ftp://ftp.pwg.org/pub/pwg/ipp/Issues/Issues-raised-at-Bake-
- Off3.doc
-
- ftp://ftp.pwg.org/pub/pwg/ipp/Issues/Issues-raised-at-Bake-
- Off3.txt
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 6]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-2. IPP Objects
-
- The term "client" in IPP is intended to mean any client that issues
- IPP operation requests and accepts IPP operation responses, whether
- it be a desktop or a server. In other words, the term "client" does
- not just mean end-user clients, such as those associated with
- desktops.
-
- The term "IPP Printer" in IPP is intended to mean an object that
- accepts IPP operation requests and returns IPP operation responses,
- whether implemented in a server or a device. An IPP Printer object
- MAY, if implemented in a server, turn around and forward received
- jobs (and other requests) to other devices and print
- servers/services, either using IPP or some other protocol.
-
-3 IPP Operations
-
- This section corresponds to Section 3 "IPP Operations" in the
- IPP/1.1 Model and Semantics document [RFC2911].
-
-3.1 Common Semantics
-
- This section discusses semantics common to all operations.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 7]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-3.1.1 Summary of Operation Attributes
-
- Table 1 - Summary of Printer operation attributes that sender MUST
- supply
-
-Printer Operations
-
- Requests Responses
- Operation PJ, PU CJ GPA GJ PP, All
- Attributes VJ (O) (O) (R) (R) RP, Operations
- (R) PP
- (O+)
-
- Operation parameters--REQUIRED to be supplied by the sender:
-
- operation-id R R R R R R
-
- status-code R
-
- request-id R R R R R R R
-
- version-number R R R R R R R
-
- Operation attributes--REQUIRED to be supplied by the sender:
-
- attributes- R R R R R R R
- charset
-
- attributes- R R R R R R R
- natural-
- language
-
- document-uri R
-
- job-id*
-
- job-uri*
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 8]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-Printer Operations
-
- Requests Responses
-
- Operation PJ, PU CJ GPA GJ PP, All
- Attributes VJ (O) (O) (R) (R) RP, Operations
- (R) PP
- (O+)
- last-document
-
- printer-uri R R R R R R
-
- Operation attributes--RECOMMENDED to be supplied by the
- sender:
-
- job-name R R R
-
- requesting-user- R R R R R R
- name
-
- Legend:
-
- PJ, VJ: Print-Job, Validate-Job
- PU: Print-URI
- CJ: Create-Job
- GPA: Get-Printer-Attributes
- GJ: Get-Jobs
- PP, RP, PP: Pause-Printer, Resume-Printer, Purge-Printer
- R indicates a REQUIRED operation that MUST be supported by the IPP
- object (Printer or Job). For attributes, R indicates that the
- attribute MUST be supported by the IPP object that supports the
- associated operation.
- O indicates an OPTIONAL operation or attribute that MAY be supported
- by the IPP object (Printer or Job).
- + indicates that this is not an IPP/1.0 feature, but is only a part
- of IPP/1.1 and future versions of IPP.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 9]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Table 2 - Summary of Printer operation attributes that sender MAY
- supply
-
-Printer Operations
-
- Requests Respon-
- ses
- Operation Attributes PJ, PU CJ GPA GJ PP, All
- VJ (O) (O) (R) (R) RP, Opera
- (R) PP tions
- (O+)
-
- Operation attributes--OPTIONAL to be supplied by the sender:
-
- status-message O
-
- detailed-status- O
- message
-
- document-access- O**
- error
-
- compression R R
-
- document-format R R R
-
- document-name O O
-
- document-natural- O O
- language
-
- ipp-attribute- R R R
- fidelity
-
- job-impressions O O O
-
- job-k-octets O O O
-
- job-media-sheets O O O
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 10]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-Printer Operations
-
- Requests Respon-
- ses
- Operation Attributes PJ, PU CJ GPA GJ PP, All
- VJ (O) (O) (R) (R) RP, Opera
- (R) PP tions
- (O+)
-
- limit R
-
- message
-
- my-jobs R
-
- requested-attributes R R
-
- which-jobs R
-
- Legend:
-
- PJ, VJ: Print-Job, Validate-Job
- PU: Print-URI
- CJ: Create-Job
- GPA: Get-Printer-Attributes
- GJ: Get-Jobs
- PP, RP, PP: Pause-Printer, Resume-Printer, Purge-Printer
- R indicates a REQUIRED operation that MUST be supported by the IPP
- object (Printer or Job). For attributes, R indicates that the
- attribute MUST be supported by the IPP object that supports the
- associated operation.
- O indicates an OPTIONAL operation or attribute that MAY be supported
- by the IPP object (Printer or Job).
- + indicates that this is not an IPP/1.0 feature, but is only a part
- of IPP/1.1 and future versions of IPP.
- * "job-id" is REQUIRED only if used together with "printer-uri" to
- identify the target job; otherwise, "job-uri" is REQUIRED.
- ** "document-access-error" applies to the Print-URI response only.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 11]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Table 3 - Summary of Job operation attributes that sender MUST supply
-
-Job Operations
-
- Requests Responses
- Operation SD SU CJ GJA HJ All
- Attributes (O) (O) (R) (R) RJ, RJ Opera-
- (O+) tions
-
- Operation parameters--REQUIRED to be supplied by the sender:
-
- operation-id R R R R R
-
- status-code R
-
- request-id R R R R R R
-
- version-number R R R R R R
-
- Operation attributes--REQUIRED to be supplied by the sender:
-
- attributes-charset R R R R R R
-
- attributes-natural- R R R R R R
- language
-
- document-uri R
-
- job-id* R R R R R
-
- job-uri* R R R R R
-
- last-document R R
-
- printer-uri R R R R R
-
- Operation attributes--RECOMMENDED to be supplied by the sender:
-
- job-name
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 12]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-Job Operations
-
- Requests Responses
-
- Operation SD SU CJ GJA HJ All
- Attributes (O) (O) (R) (R) RJ, RJ Opera-
- (O+) tions
-
- requesting-user- R R R R R
- name
-
- Legend:
-
- SD: Send-Document
- SU: Send-URI
- CJ: Cancel-Job
- GJA: Get-Job-Attributes
- HJ, RJ, RJ: Hold-Job, Release-Job, Restart-Job
- R indicates a REQUIRED operation that MUST be supported by the IPP
- object (Printer or Job). For attributes, R indicates that the
- attribute MUST be supported by the IPP object that supports the
- associated operation.
- O indicates an OPTIONAL operation or attribute that MAY be supported
- by the IPP object (Printer or Job).
- + indicates that this is not an IPP/1.0 feature, but is only a part
- of IPP/1.1 and future versions of IPP.
- * "job-id" is REQUIRED only if used together with "printer-uri" to
- identify the target job; otherwise, "job-uri" is REQUIRED.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 13]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Table 4 - Summary of Job operation attributes that sender MAY supply
-
-Job Operations
-
- Requests Responses
-
- Operation SD SU CJ GJA HJ, SD All
- Attributes (O) (O) (R) (R) RJ, (O) Opera-
- RJ tions
- (O+)
-
- Operation attributes--OPTIONAL to be supplied by the sender:
-
- status-message O
-
- detailed-status- O
- message
-
- document-access- O**
- error
-
- compression R R
-
- document-format R R
-
- document-name O O
-
- document-natural- O O
- language
-
- ipp-attribute-
- fidelity
-
- job-impressions
-
- job-k-octets
-
- job-media-sheets
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 14]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-Job Operations
-
- Requests Responses
-
- Operation SD SU CJ GJA HJ, SD All
- Attributes (O) (O) (R) (R) RJ, (O) Opera-
- RJ tions
- (O+)
-
- limit
-
- message O O O
-
- job-hold-until R
-
- my-jobs
-
- requested- R
- attributes
-
- which-jobs
-
- Legend:
-
- SD: Send-Document
- SU: Send-URI
- CJ: Cancel-Job
- GJA: Get-Job-Attributes
- HJ, RJ, RJ: Hold-Job, Release-Job, Restart-Job
- R indicates a REQUIRED operation that MUST be supported by the IPP
- object (Printer or Job). For attributes, R indicates that the
- attribute MUST be supported by the IPP object that supports the
- associated operation.
- O indicates an OPTIONAL operation or attribute that MAY be supported
- by the IPP object (Printer or Job).
- + indicates that this is not an IPP/1.0 feature, but is only a part
- of IPP/1.1 and future versions of IPP.
- * "job-id" is REQUIRED only if used together with "printer-uri" to
- identify the target job; otherwise, "job-uri" is REQUIRED.
- ** "document-access-error" applies to the Send-URI operation only
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 15]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Table 5 - Printer operation response attributes
-
-Printer Operations
-
- Response
-
- Operation PJ (R) VJ (R) PU (O) CJ (O) GPA GJ (R) PP,
- Attributes SD (O) SU (O) (R) RP, PP
- (O+)
-
- job-uri R R R
-
- job-id R R R
-
- job-state R R R
-
- job-state- R+ R+ R+
- reasons
-
- number-of- O O O
- intervening-
- jobs
-
- document- O
- access-
- error+
-
- Legend:
-
- PJ, SJ: Print-Job, Send-Document
- VJ: Validate-Job
- PU, SU: Print-URI, Send-URI
- CJ: Create-Job
- GPA: Get-Printer-Attributes
- GJ: Get-Jobs
- PP, RP, PP: Pause-Printer, Resume-Printer, Purge-Printer
- R indicates a REQUIRED operation that MUST be supported by the IPP
- object (Printer or Job). For attributes, R indicates that the
- attribute MUST be supported by the IPP object that supports the
- associated operation.
- O indicates an OPTIONAL operation or attribute that MAY be supported
- by the IPP object (Printer or Job).
-
-3.1.2 Suggested Operation Processing Steps for IPP Objects
-
- This section suggests the steps and error checks that an IPP object
- MAY perform when processing requests and returning responses. An IPP
- object MAY perform some or all of the error checks. However, some
-
-
-
-Hastings, et al. Informational [Page 16]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- implementations MAY choose to be more forgiving than the error checks
- shown here, in order to be able to accept requests from non-
- conforming clients. Not performing all of these error checks is a
- so-called "forgiving" implementation. On the other hand, clients
- that successfully submit requests to IPP objects that do perform all
- the error checks will be more likely to be able to interoperate with
- other IPP object implementations. Thus an implementer of an IPP
- object needs to decide whether to be a "forgiving" or a "strict"
- implementation. Therefore, the error status codes returned may
- differ between implementations. Consequentially, client SHOULD NOT
- expect exactly the error code processing described in this section.
-
- When an IPP object receives a request, the IPP object either accepts
- or rejects the request. In order to determine whether or not to
- accept or reject the request, the IPP object SHOULD execute the
- following steps. The order of the steps may be rearranged and/or
- combined, including making one or multiple passes over the request.
-
- A client MUST supply requests that would pass all of the error checks
- indicated here in order to be a conforming client. Therefore, a
- client SHOULD supply requests that are conforming, in order to avoid
- being rejected by some IPP object implementations and/or risking
- different semantics by different implementations of forgiving
- implementations. For example, a forgiving implementation that
- accepts multiple occurrences of the same attribute, rather than
- rejecting the request might use the first occurrences, while another
- might use the last occurrence. Thus such a non-conforming client
- would get different results from the two forgiving implementations.
-
- In the following, processing continues step by step until a "RETURNS
- the xxx status code ..." statement is encountered. Error returns are
- indicated by the verb: "REJECTS". Since clients have difficulty
- getting the status code before sending all of the document data in a
- Print-Job request, clients SHOULD use the Validate-Job operation
- before sending large documents to be printed, in order to validate
- whether the IPP Printer will accept the job or not.
-
- It is assumed that security authentication and authorization has
- already taken place at a lower layer.
-
-3.1.2.1 Suggested Operation Processing Steps for all Operations
-
- This section is intended to apply to all operations. The next
- section contains the additional steps for the Print-Job, Validate-
- Job, Print-URI, Create-Job, Send-Document, and Send-URI operations
- that create jobs, adds documents, and validates jobs.
-
-
-
-
-
-Hastings, et al. Informational [Page 17]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- IIG Sect # Flow IPP error status codes
- ---------- ---- ----------------------
- |
- v err
- 3.1.2.1.1 <Validate version> --> server-error-version-not-
- supported
- ok|
- v err
- 3.1.2.1.2 <Validate operation> --> server-error-operation-not-
- supported
- ok|
- v err
- 3.1.2.1.4.1- <Validate presence> --> client-error-bad-request
- 3.1.2.1.4.2 <of attributes>
- ok|
- v err
- 3.1.2.1.4.3 <Validate presence> --> client-error-bad-request
- <of operation attr>
- ok|
- v err
- 3.1.2.1.5 <Validate values of> --> client-error-bad-request
- <operation attrs> client-error-request-value-
- too-long
- <(length, tag, range,>
- <multi-value)>
- ok|
- v err
- 3.1.2.1.5 <Validate values> --> client-error-bad-request
- <with supported values> client-error-charset-not-
- supported
- ok| client-error-attributes-or-
- values-
- | not-supported
- v err
- 3.1.2.1.6 <Validate optionally> --> client-error-bad-request
- <operation attr> client-error-natural-language-
- not-supported
- | client-error-request-value-
- too-long
- | client-error-attributes-or-
- values-not-supported
-
-3.1.2.1.1 Validate version number
-
- Every request and every response contains the "version-number"
- attribute. The value of this attribute is the major and minor
- version number of the syntax and semantics that the client and IPP
- object is using, respectively. The "version-number" attribute
-
-
-
-Hastings, et al. Informational [Page 18]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- remains in a fixed position across all future versions so that all
- clients and IPP object that support future versions can determine
- which version is being used. The IPP object checks to see if the
- major version number supplied in the request is supported. If not,
- the Printer object REJECTS the request and RETURNS the 'server-
- error-version-not-supported' status code in the response. The IPP
- object returns in the "version-number" response attribute the major
- and minor version for the error response. Thus the client can learn
- at least one major and minor version that the IPP object supports.
- The IPP object is encouraged to return the closest version number to
- the one supplied by the client.
-
- The checking of the minor version number is implementation dependent,
- however if the client-supplied minor version is explicitly supported,
- the IPP object MUST respond using that identical minor version
- number. If the major version number matches, but the minor version
- number does not, the Printer SHOULD accept and attempt to process the
- request, or MAY reject the request and return the 'server-error-
- version-not-supported' status code. In all cases, the Printer MUST
- return the nearest version number that it supports. For example,
- suppose that an IPP/1.2 Printer supports versions '1.1' and '1.2'.
- The following responses are conforming:
-
- Table 6 - Examples of validating IPP version
-
- Client supplies Printer Accept Request? Printer returns
-
-
- 1.0 yes (SHOULD) 1.1
-
- 1.0 no (SHOULD NOT) 1.1
-
- 1.1 yes (MUST) 1.1
-
- 1.2 yes (MUST) 1.2
-
- 1.3 yes (SHOULD) 1.2
-
- 1.3 no (SHOULD NOT) 1.2
-
- It is advantageous for Printers to support both IPP/1.1 and IPP/1.0,
- so that they can interoperate with either client implementations.
- Some implementations may allow an Administrator to explicitly disable
- support for one or the other by setting the "ipp-versions-supported"
- Printer description attribute.
-
-
-
-
-
-
-Hastings, et al. Informational [Page 19]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Likewise, it is advantageous for clients to support both versions to
- allow interoperability with new and legacy Printers.
-
-3.1.2.1.2 Validate operation identifier
-
- The Printer object checks to see if the "operation-id" attribute
- supplied by the client is supported as indicated in the Printer
- object's "operations-supported" attribute. If not, the Printer
- REJECTS the request and returns the 'server-error-operation-not-
- supported' status code in the response.
-
-3.1.2.1.3 Validate the request identifier
-
- The Printer object SHOULD NOT check to see if the "request-id"
- attribute supplied by the client is in range: between 1 and 2**31 - 1
- (inclusive), but copies all 32 bits.
-
- Note: The "version-number", "operation-id", and the "request-id"
- parameters are in fixed octet positions in the IPP/1.1 encoding. The
- "version-number" parameter will be the same fixed octet position in
- all versions of the protocol. These fields are validated before
- proceeding with the rest of the validation.
-
-3.1.2.1.4 Validate attribute group and attribute presence and order
-
- The order of the following validation steps depends on
- implementation.
-
-3.1.2.1.4.1 Validate the presence and order of attribute groups
-
- Client requests and IPP object responses contain attribute groups
- that Section 3 requires to be present and in a specified order. An
- IPP object verifies that the attribute groups are present and in the
- correct order in requests supplied by clients (attribute groups
- without an * in the following tables).
-
- If an IPP object receives a request with (1) required attribute
- groups missing, or (2) the attributes groups are out of order, or (3)
- the groups are repeated, the IPP object REJECTS the request and
- RETURNS the 'client-error-bad-request' status code. For example, it
- is an error for the Job Template Attributes group to occur before the
- Operation Attributes group, for the Operation Attributes group to be
- omitted, or for an attribute group to occur more than once, except in
- the Get-Jobs response.
-
- Since this kind of attribute group error is most likely to be an
- error detected by a client developer rather than by a customer, the
- IPP object NEED NOT return an indication of which attribute group was
-
-
-
-Hastings, et al. Informational [Page 20]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- in error in either the Unsupported Attributes group or the Status
- Message. Also, the IPP object NEED NOT find all attribute group
- errors before returning this error.
-
-3.1.2.1.4.2 Ignore unknown attribute groups in the expected position
-
- Future attribute groups may be added to the specification at the end
- of requests just before the Document Content and at the end of
- response, except for the Get-Jobs response, where it maybe there or
- before the first job attributes returned. If an IPP object receives
- an unknown attribute group in these positions, it ignores the entire
- group, rather than returning an error, since that group may be a new
- group in a later minor version of the protocol that can be ignored.
- (If the new attribute group cannot be ignored without confusing the
- client, the major version number would have been increased in the
- protocol document and in the request). If the unknown group occurs
- in a different position, the IPP object REJECTS the request and
- RETURNS the 'client-error-bad-request' status code.
-
- Clients also ignore unknown attribute groups returned in a response.
-
- Note: By validating that requests are in the proper form, IPP
- objects force clients to use the proper form which, in turn,
- increases the chances that customers will be able to use such clients
- from multiple vendors with IPP objects from other vendors.
-
-3.1.2.1.4.3 Validate the presence of a single occurrence of required
- Operation attributes
-
- Client requests and IPP object responses contain Operation attributes
- that [RFC2911] Section 3 requires to be present. Attributes within a
- group may be in any order, except for the ordering of target,
- charset, and natural languages attributes. These attributes MUST be
- first, and MUST be supplied in the following order: charset, natural
- language, and then target. An IPP object verifies that the
- attributes that Section 4 requires to be supplied by the client have
- been supplied in the request (attributes without an * in the
- following tables). An asterisk (*) indicates groups and Operation
- attributes that the client may omit in a request or an IPP object may
- omit in a response.
-
- If an IPP object receives a request with required attributes missing
- or repeated from a group or in the wrong position, the behavior of
- the IPP object is IMPLEMENTATION DEPENDENT. Some of the possible
- implementations are:
-
- REJECTS the request and RETURNS the 'client-error-bad-request'
- status code
-
-
-
-Hastings, et al. Informational [Page 21]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- accepts the request and uses the first occurrence of the attribute
- no matter where it is
-
- accepts the request and uses the last occurrence of the attribute
- no matter where it is
-
- accept the request and assume some default value for the missing
- attribute
-
- Therefore, client MUST send conforming requests, if they want to
- receive the same behavior from all IPP object implementations. For
- example, it is an error for the "attributes-charset" or "attributes-
- natural-language" attribute to be omitted in any operation request,
- or for an Operation attribute to be supplied in a Job Template group
- or a Job Template attribute to be supplied in an Operation Attribute
- group in a create request. It is also an error to supply the
- "attributes-charset" attribute twice.
-
- Since these kinds of attribute errors are most likely to be detected
- by a client developer rather than by a customer, the IPP object NEED
- NOT return an indication of which attribute was in error in either
- the Unsupported Attributes group or the Status Message. Also, the
- IPP object NEED NOT find all attribute errors before returning this
- error.
-
- The following tables list all the attributes for all the operations
- by attribute group in each request and each response. The order of
- the groups is the order that the client supplies the groups as
- specified in [RFC2911] Section 3. The order of the attributes within
- a group is arbitrary, except as noted for some of the special
- operation attributes (charset, natural language, and target). The
- tables below use the following notation:
-
- R indicates a REQUIRED attribute or operation that an IPP
- object MUST support
- O indicates an OPTIONAL attribute or operation that an IPP
- object NEED NOT support
- * indicates that a client MAY omit the attribute in a request
- and that an IPP object MAY omit the attribute in a response.
- The absence of an * means that a client MUST supply the
- attribute in a request and an IPP object MUST supply the
- attribute in a response.
- + indicates that this is not a IPP/1.0 operation, but is only
- a part of IPP/1.1 and future versions of IPP.
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 22]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Operation Requests
-
- The tables below show the attributes in their proper attribute groups
- for operation requests:
-
- Note: All operation requests contain "version-number", "operation-
- id", and "request-id" parameters.
-
- Print-Job Request (R):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- printer-uri (R)
- requesting-user-name (R*)
- job-name (R*)
- ipp-attribute-fidelity (R*)
- document-name (R*)
- document-format (R*)
- document-natural-language (O*)
- compression (R*)
- job-k-octets (O*)
- job-impressions (O*)
- job-media-sheets (O*)
- Group 2: Job Template Attributes (R*)
- <Job Template attributes> (O*)
- (see [RFC2911] Section 4.2)
- Group 3: Document Content (R)
- <document content>
-
- Validate-Job Request (R):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- printer-uri (R)
- requesting-user-name (R*)
- job-name (R*)
- ipp-attribute-fidelity (R*)
- document-name (R*)
- document-format (R*)
- document-natural-language (O*)
- compression (R*)
- job-k-octets (O*)
- job-impressions (O*)
- job-media-sheets (O*)
- Group 2: Job Template Attributes (R*)
- <Job Template attributes> (O*)
- (see [RFC2911] Section 4.2)
-
-
-
-
-Hastings, et al. Informational [Page 23]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Print-URI Request (O):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- printer-uri (R)
- document-uri (R)
- requesting-user-name (R*)
- job-name (R*)
- ipp-attribute-fidelity (R*)
- document-name (R*)
- document-format (R*)
- document-natural-language (O*)
- compression (R*)
- job-k-octets (O*)
- job-impressions (O*)
- job-media-sheets (O*)
- Group 2: Job Template Attributes (R*)
- <Job Template attributes> (O*) (see
- (see [RFC2911] Section 4.2)
-
- Create-Job Request (O):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- printer-uri (R)
- requesting-user-name (R*)
- job-name (R*)
- ipp-attribute-fidelity (R*)
- job-k-octets (O*)
- job-impressions (O*)
- job-media-sheets (O*)
- Group 2: Job Template Attributes (R*)
- <Job Template attributes> (O*) (see
- (see [RFC2911] Section 4.2)
-
- Get-Printer-Attributes Request (R):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- printer-uri (R)
- requesting-user-name (R*)
- requested-attributes (R*)
- document-format (R*)
-
- Get-Jobs Request (R):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
-
-
-
-Hastings, et al. Informational [Page 24]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- printer-uri (R)
- requesting-user-name (R*)
- limit (R*)
- requested-attributes (R*)
- which-jobs (R*)
- my-jobs (R*)
-
- Send-Document Request (O):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- (printer-uri & job-id) | job-uri (R)
- last-document (R)
- requesting-user-name (R*)
- document-name (R*)
- document-format (R*)
- document-natural-language (O*)
- compression (R*)
- Group 2: Document Content (R*)
- <document content>
-
- Send-URI Request (O):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- (printer-uri & job-id) | job-uri (R)
- last-document (R)
- document-uri (R)
- requesting-user-name (R*)
- document-name (R*)
- document-format (R*)
- document-natural-language (O*)
- compression (R*)
-
- Cancel-Job Request (R):
- Release-Job Request (O+):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- (printer-uri & job-id) | job-uri (R)
- requesting-user-name (R*)
- message (O*)
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 25]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Get-Job-Attributes Request (R):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- (printer-uri & job-id) | job-uri (R)
- requesting-user-name (R*)
- requested-attributes (R*)
-
- Pause-Printer Request (O+):
- Resume-Printer Request (O+):
- Purge-Printer Request (O+):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- printer-uri (R)
- requesting-user-name (R*)
-
- Hold-Job Request (O+):
- Restart-Job Request (O+):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- (printer-uri & job-id) | job-uri (R)
- requesting-user-name (R*)
- job-hold-until (R*)
- message (O*)
-
- Operation Responses
-
- The tables below show the response attributes in their proper
- attribute groups for responses.
-
- Note: All operation responses contain "version-number", "status-
- code", and "request-id" parameters.
-
- Print-Job Response (R):
- Create-Job Response (O):
- Send-Document Response (O):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- status-message (O*)
- detailed-status-message (O*)
- Group 2: Unsupported Attributes (R*) (see Note 3)
- n <unsupported attributes> (R*)
- Group 3: Job Object Attributes(R*) (see Note 2)
- job-uri (R)
- job-id (R)
-
-
-
-Hastings, et al. Informational [Page 26]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- job-state (R)
- job-state-reasons (O* | R+)
- job-state-message (O*)
- number-of-intervening-jobs (O*)
-
- Validate-Job Response (R):
- Cancel-Job Response (R):
- Hold-Job Response (O+):
- Release-Job Response (O+):
- Restart-Job Response (O+):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- status-message (O*)
- detailed-status-message (O*)
- Group 2: Unsupported Attributes (R*) (see Note 3)
- <unsupported attributes> (R*)
-
- Print-URI Response (O):
- Send-URI Response (O):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- status-message (O*)
- detailed-status-message (O*)
- document-access-error (O*)
- Group 2: Unsupported Attributes (R*) (see Note 3)
- <unsupported attributes> (R*)
- Group 3: Job Object Attributes(R*) (see Note 2)
- job-uri (R)
- job-id (R)
- job-state (R)
- job-state-reasons (O* | R+)
- job-state-message (O*)
- number-of-intervening-jobs (O*)
-
- Get-Printer-Attributes Response (R):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- status-message (O*)
- detailed-status-message (O*)
- Group 2: Unsupported Attributes (R*) (see Note 4)
- <unsupported attributes> (R*)
- Group 3: Printer Object Attributes(R*) (see Note 2)
- <requested attributes> (R*)
-
-
-
-
-
-Hastings, et al. Informational [Page 27]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Get-Jobs Response (R):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- status-message (O*)
- detailed-status-message (O*)
- Group 2: Unsupported Attributes (R*) (see Note 4)
- <unsupported attributes> (R*)
- Group 3: Job Object Attributes(R*) (see Note 2, 5)
- <requested attributes> (R*)
-
- Get-Job-Attributes Response (R):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- status-message (O*)
- detailed-status-message (O*)
- Group 2: Unsupported Attributes (R*) (see Note 4)
- <unsupported attributes> (R*)
- Group 3: Job Object Attributes(R*) (see Note 2)
- <requested attributes> (R*)
-
- Pause-Printer Response (O+):
- Resume-Printer Response (O+):
- Purge-Printer Response (O+):
- Group 1: Operation Attributes (R)
- attributes-charset (R)
- attributes-natural-language (R)
- status-message (O*)
- detailed-status-message (O*)
- Group 2: Unsupported Attributes (R*) (see Note 4)
- <unsupported attributes> (R*)
-
- Note 2 - the Job Object Attributes and Printer Object Attributes are
- returned only if the IPP object returns one of the success status
- codes.
-
- Note 3 - the Unsupported Attributes Group is present only if the
- client included some Operation and/or Job Template attributes or
- values that the Printer doesn't support whether a success or an error
- return.
-
- Note 4 - the Unsupported Attributes Group is present only if the
- client included some Operation attributes that the Printer doesn't
- support whether a success or an error return.
-
-
-
-
-
-
-Hastings, et al. Informational [Page 28]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Note 5: for the Get-Jobs operation the response contains a separate
- Job Object Attributes group 3 to N containing requested-attributes
- for each job object in the response.
-
-3.1.2.1.5 Validate the values of the REQUIRED Operation attributes
-
- An IPP object validates the values supplied by the client of the
- REQUIRED Operation attribute that the IPP object MUST support. The
- next section specifies the validation of the values of the OPTIONAL
- Operation attributes that IPP objects MAY support.
-
- The IPP object performs the following syntactic validation checks of
- each Operation attribute value:
-
- a) that the length of each Operation attribute value is correct
- for the attribute syntax tag supplied by the client according
- to [RFC2911] Section 4.1,
-
- b) that the attribute syntax tag is correct for that Operation
- attribute according to [RFC2911] Section 3,
-
- c) that the value is in the range specified for that Operation
- attribute according to [RFC2911] Section 3,
-
- d) that multiple values are supplied by the client only for
- operation attributes that are multi-valued, i.e., that are
- 1setOf X according to [RFC2911] Section 3.
-
- If any of these checks fail, the IPP object REJECTS the request and
- RETURNS the 'client-error-bad-request' or the 'client-error-request-
- value-too-long' status code. Since such an error is most likely to
- be an error detected by a client developer, rather than by an end-
- user, the IPP object NEED NOT return an indication of which attribute
- had the error in either the Unsupported Attributes Group or the
- Status Message. The description for each of these syntactic checks
- is explicitly expressed in the first IF statement in the following
- table.
-
- In addition, the IPP object checks each Operation attribute value
- against some Printer object attribute or some hard-coded value if
- there is no "xxx-supported" Printer object attribute defined. If its
- value is not among those supported or is not in the range supported,
- then the IPP object REJECTS the request and RETURNS the error status
- code indicated in the table by the second IF statement. If the value
- of the Printer object's "xxx-supported" attribute is 'no-value'
- (because the system administrator hasn't configured a value), the
- check always fails.
-
-
-
-
-Hastings, et al. Informational [Page 29]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- -----------------------------------------------
-
- attributes-charset (charset)
-
- IF NOT a single non-empty 'charset' value, REJECT/RETURN 'client-
- error-bad-request'.
-
- IF the value length is greater than 63 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- IF NOT in the Printer object's "charset-supported" attribute,
- REJECT/RETURN "client-error-charset-not-supported".
-
- attributes-natural-language(naturalLanguage)
-
- IF NOT a single non-empty 'naturalLanguage' value, REJECT/RETURN
- 'client-error-bad-request'.
-
- IF the value length is greater than 63 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- ACCEPT the request even if not a member of the set in the Printer
- object's "generated-natural-language-supported" attribute. If the
- supplied value is not a member of the Printer object's
- "generated-natural-language-supported" attribute, use the Printer
- object's "natural-language- configured" value.
-
- requesting-user-name
-
- IF NOT a single 'name' value, REJECT/RETURN 'client-error-bad-
- request'.
-
- IF the value length is greater than 255 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- IF the IPP object can obtain a better-authenticated name, use it
- instead.
-
- job-name(name)
-
- IF NOT a single 'name' value, REJECT/RETURN 'client-error-bad-
- request'.
-
- IF the value length is greater than 255 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- IF NOT supplied by the client, the Printer object creates a name
- from the document-name or document-uri.
-
-
-
-Hastings, et al. Informational [Page 30]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- document-name (name)
-
- IF NOT a single 'name' value, REJECT/RETURN 'client-error-bad-
- request'.
-
- IF the value length is greater than 255 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- ipp-attribute-fidelity (boolean)
-
- IF NEITHER a single 'true' NOR a single 'false' 'boolean' value,
- REJECT/RETURN 'client-error-bad-request'.
-
- IF the value length is NOT equal to 1 octet, REJECT/RETURN
- 'client-error-request-value-too-long'
-
- IF NOT supplied by the client, the IPP object assumes the value
- 'false'.
-
- document-format (mimeMediaType)
-
- IF NOT a single non-empty 'mimeMediaType' value, REJECT/RETURN
- 'client-error-bad-request'.
-
- IF the value length is greater than 255 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- IF NOT in the Printer object's "document-format-supported"
- attribute, REJECT/RETURN 'client-error-document-format-not-
- supported'
-
- IF NOT supplied by the client, the IPP object assumes the value of
- the Printer object's "document-format-default" attribute.
-
- document-uri (uri)
-
- IF NOT a single non-empty 'uri' value, REJECT/RETURN 'client-
- error-bad-request'.
-
- IF the value length is greater than 1023 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- IF the URI syntax is not valid, REJECT/RETURN 'client-error-bad-
- request'.
-
- If the client-supplied URI scheme is not supported, i.e., the
- value is not in the Printer object's referenced-uri-scheme-
- supported" attribute, the Printer object MUST reject the request
-
-
-
-Hastings, et al. Informational [Page 31]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- and return the 'client-error-uri-scheme-not-supported' status
- code. The Printer object MAY check to see if the document exists
- and is accessible. If the document is not found or is not
- accessible, REJECT/RETURN 'client-error-not found'.
-
- last-document (boolean)
-
- IF NEITHER a single 'true' NOR a single 'false' 'boolean' value,
- REJECT/RETURN 'client-error-bad-request'.
-
- IF the value length is NOT equal to 1 octet, REJECT/RETURN
- 'client-error-request-value-too-long'
-
- job-id (integer(1:MAX))
-
- IF NOT an single 'integer' value equal to 4 octets AND in the
- range 1 to MAX, REJECT/RETURN 'client-error-bad-request'.
-
- IF NOT a job-id of an existing Job object, REJECT/RETURN 'client-
- error-not-found' or 'client-error-gone' status code, if keep track
- of recently deleted jobs.
-
- requested-attributes (1setOf keyword)
-
- IF NOT one or more 'keyword' values, REJECT/RETURN 'client-
- error-bad-request'.
-
- IF the value length is greater than 255 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- Ignore unsupported values, which are the keyword names of
- unsupported attributes. Don't bother to copy such requested
- (unsupported) attributes to the Unsupported Attribute response
- group since the response will not return them.
-
- which-jobs (type2 keyword)
-
- IF NOT a single 'keyword' value, REJECT/RETURN 'client-error-bad-
- request'.
-
- IF the value length is greater than 255 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- IF NEITHER 'completed' NOR 'not-completed', copy the attribute and
- the unsupported value to the Unsupported Attributes response group
- and REJECT/RETURN 'client-error-attributes-or-values-not-
- supported'.
-
-
-
-
-Hastings, et al. Informational [Page 32]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Note: a Printer still supports the 'completed' value even if it
- keeps no completed/canceled/aborted jobs: by returning no jobs
- when so queried.
-
- IF NOT supplied by the client, the IPP object assumes the 'not-
- completed' value.
-
- my-jobs (boolean)
-
- IF NEITHER a single 'true' NOR a single 'false' 'boolean' value,
- REJECT/RETURN 'client-error-bad-request'.
-
- IF the value length is NOT equal to 1 octet, REJECT/RETURN
- 'client-error-request-value-too-long'
-
- IF NOT supplied by the client, the IPP object assumes the 'false'
- value.
-
- limit (integer(1:MAX))
-
- IF NOT a single 'integer' value equal to 4 octets AND in the range
- 1 to MAX, REJECT/RETURN 'client-error-bad-request'.
-
- IF NOT supplied by the client, the IPP object returns all jobs, no
- matter how many.
-
- -----------------------------------------------
-
-3.1.2.1.6 Validate the values of the OPTIONAL Operation attributes
-
- OPTIONAL Operation attributes are those that an IPP object MAY
- support. An IPP object validates the values of the OPTIONAL
- attributes supplied by the client. The IPP object performs the same
- syntactic validation checks for each OPTIONAL attribute value as in
- Section 3.1.2.1.5. As in Section 3.1.2.1.5, if any fail, the IPP
- object REJECTS the request and RETURNS the 'client-error-bad-request'
- or the 'client-error-request-value-too-long' status code.
-
- In addition, the IPP object checks each Operation attribute value
- against some Printer attribute or some hard-coded value if there is
- no "xxx-supported" Printer attribute defined. If its value is not
- among those supported or is not in the range supported, then the IPP
- object REJECTS the request and RETURNS the error status code
- indicated in the table. If the value of the Printer object's "xxx-
- supported" attribute is 'no-value' (because the system administrator
- hasn't configured a value), the check always fails.
-
-
-
-
-
-Hastings, et al. Informational [Page 33]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- If the IPP object doesn't recognize/support an attribute, the IPP
- object treats the attribute as an unknown or unsupported attribute
- (see the last row in the table below).
-
- -----------------------------------------------
-
- document-natural-language (naturalLanguage)
-
- IF NOT a single non-empty 'naturalLanguage' value, REJECT/RETURN
- 'client-error-bad-request'.
-
- IF the value length is greater than 63 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- IF NOT a value that the Printer object supports in document
- formats, (no corresponding "xxx-supported" Printer attribute),
- REJECT/RETURN 'client-error-natural-language-not-supported'.
-
- compression (type3 keyword)
-
- IF NOT a single 'keyword' value, REJECT/RETURN 'client-error-bad-
- request'.
-
- IF the value length is greater than 255 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- IF NOT in the Printer object's "compression-supported" attribute,
- REJECT/RETURN 'client-error-compression-not-supported'.
-
- Note to IPP/1.0 implementers: Support for the "compression"
- attribute was optional in IPP/1.0 and was changed to REQUIRED in
- IPP/1.1. However, an IPP/1.0 object SHOULD at least check for the
- "compression" attribute being present and reject the create
- request, if they don't support "compression". Not checking is a
- bug, since the data will be unintelligible.
-
- job-k-octets (integer(0:MAX))
-
- IF NOT a single 'integer' value equal to 4 octets, REJECT/RETURN
- 'client-error-bad-request'.
-
- IF NOT in the range of the Printer object's "job-k-octets-
- supported" attribute, copy the attribute and the unsupported value
- to the Unsupported Attributes response group and REJECT/RETURN
- 'client-error-attributes-or-values-not-supported'.
-
-
-
-
-
-
-Hastings, et al. Informational [Page 34]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- job-impressions (integer(0:MAX))
-
- IF NOT a single 'integer' value equal to 4 octets, REJECT/RETURN
- 'client-error-bad-request'.
-
- IF NOT in the range of the Printer object's "job-impressions-
- supported" attribute, copy the attribute and the unsupported value
- to the Unsupported Attributes response group and REJECT/RETURN
- 'client-error-attributes-or-values-not-supported'.
-
- job-media-sheets (integer(0:MAX))
-
- IF NOT a single 'integer' value equal to 4 octets, REJECT/RETURN
- 'client-error-bad-request'.
-
- IF NOT in the range of the Printer object's "job-media-sheets-
- supported" attribute, copy the attribute and the unsupported value
- to the Unsupported Attributes response group and REJECT/RETURN
- 'client-error-attributes-or-values-not-supported'.
-
- message (text(127))
-
- IF NOT a single 'text' value, REJECT/RETURN 'client-error-bad-
- request'.
-
- IF the value length is greater than 127 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- unknown or unsupported attribute
-
- IF the attribute syntax supplied by the client is supported but
- the length is not legal for that attribute syntax, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- ELSE copy the attribute and value to the Unsupported Attributes
- response group and change the attribute value to the "out-of-band"
- 'unsupported' value, but otherwise ignore the attribute.
-
- Note: Future Operation attributes may be added to the protocol
- specification that may occur anywhere in the specified group. When
- the operation is otherwise successful, the IPP object returns the
- 'successful-ok-ignored-or-substituted-attributes' status code.
- Ignoring unsupported Operation attributes in all operations is
- analogous to the handling of unsupported Job Template attributes in
- the create and Validate-Job operations when the client supplies the
- "ipp-attribute-fidelity" Operation attribute with the 'false' value.
- This last rule is so that we can add OPTIONAL Operation attributes to
- future versions of IPP so that older clients can inter-work with new
-
-
-
-Hastings, et al. Informational [Page 35]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- IPP objects and newer clients can inter-work with older IPP objects.
- (If the new attribute cannot be ignored without performing
- unexpectedly, the major version number would have been increased in
- the protocol document and in the request). This rule for Operation
- attributes is independent of the value of the "ipp-attribute-
- fidelity" attribute. For example, if an IPP object doesn't support
- the OPTIONAL "job-k-octets" attribute', the IPP object treats "job-
- k-octets" as an unknown attribute and only checks the length for the
- 'integer' attribute syntax supplied by the client. If it is not four
- octets, the IPP object REJECTS the request and RETURNS the 'client-
- error-bad-request' status code, else the IPP object copies the
- attribute to the Unsupported Attribute response group, setting the
- value to the "out-of-band" 'unsupported' value, but otherwise ignores
- the attribute.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 36]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-3.1.2.2 Suggested Additional Processing Steps for Operations that
- Create/Validate Jobs and Add Documents
-
- This section in combination with the previous section recommends the
- processing steps for the Print-Job, Validate-Job, Print-URI, Create-
- Job, Send-Document, and Send-URI operations that IPP objects SHOULD
- use. These are the operations that create jobs, validate a Print-Job
- request, and add documents to a job.
-
- IIG Sect # Flow IPP error status codes
- ---------- ---- ----------------------
- |
- v No
- 3.1.2.2.1 <ipp-attribute-fidelity> ------------------+
- <supplied?> |
- Yes| |
- | ipp-attribute-fidelity = no |
- |<------------------------------+
- v No
- 3.1.2.2.2 <Printer is> --> server-error-not-accepting-jobs
- <accepting jobs?>
- Yes|
- v err
- 3.1.2.3 <Validate values of> --> client-error-bad-request
- <Job template attributes> client-error-request-value-too-
- long
- <(length, tag, range,>
- <multi-value)>
- ok|
- v err
- 3.1.2.3 <Validate values with> --> client-error-bad-request
- <supported values> client-error-attributes-or-
- | values-not-supported
- v err
- 3.1.2.3.1 <Any conflicting> --> client-error-conflicting-
- attributes
- <Job Template attr values> client-error-attributes-or-
- values-not-supported
- v
-
-3.1.2.2.1 Default "ipp-attribute-fidelity" if not supplied
-
- The Printer object checks to see if the client supplied an "ipp-
- attribute-fidelity" Operation attribute. If the attribute is not
- supplied by the client, the IPP object assumes that the value is
- 'false'.
-
-
-
-
-
-Hastings, et al. Informational [Page 37]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-3.1.2.2.2 Check that the Printer object is accepting jobs
-
- If the value of the Printer objects "printer-is-accepting-jobs" is
- 'false', the Printer object REJECTS the request and RETURNS the
- 'server-error-not-accepting-jobs' status code.
-
-3.1.2.2.3 Validate the values of the Job Template attributes
-
- An IPP object validates the values of all Job Template attribute
- supplied by the client. The IPP object performs the analogous
- syntactic validation checks of each Job Template attribute value that
- it performs for Operation attributes (see Section 3.1.2.1.5.):
-
- a) that the length of each value is correct for the attribute
- syntax tag supplied by the client according to [RFC2911]
- Section 4.1.
-
- b) that the attribute syntax tag is correct for that attribute
- according to [RFC2911] Sections 4.2 to 4.4.
-
- c) that multiple values are supplied only for multi-valued
- attributes, i.e., that are 1setOf X according to [RFC2911]
- Sections 4.2 to 4.4.
-
- As in Section 3.1.2.1.5, if any of these syntactic checks fail, the
- IPP object REJECTS the request and RETURNS the 'client-error-bad-
- request' or 'client-error-request-value-too-long' status code as
- appropriate, independent of the value of the "ipp-attribute-
- fidelity". Since such an error is most likely to be an error
- detected by a client developer, rather than by an end-user, the IPP
- object NEED NOT return an indication of which attribute had the error
- in either the Unsupported Attributes Group or the Status Message.
- The description for each of these syntactic checks is explicitly
- expressed in the first IF statement in the following table.
-
- Each Job Template attribute MUST occur no more than once. If an IPP
- Printer receives a create request with multiple occurrences of a Job
- Template attribute, it MAY:
-
- 1. reject the operation and return the 'client-error-bad-request'
- error status code
-
- 2. accept the operation and use the first occurrence of the
- attribute
-
- 3. accept the operation and use the last occurrence of the
- attribute
-
-
-
-
-Hastings, et al. Informational [Page 38]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- depending on implementation. Therefore, clients MUST NOT supply
- multiple occurrences of the same Job Template attribute in the Job
- Attributes group in the request.
-
-3.1.2.3 Algorithm for job validation
-
- The process of validating a Job-Template attribute "xxx" against a
- Printer attribute "xxx-supported" can use the following validation
- algorithm (see section 3.2.1.2 in [RFC2911]).
-
- To validate the value U of Job-Template attribute "xxx" against the
- value V of Printer "xxx-supported", perform the following algorithm:
-
- 1. If U is multi-valued, validate each value X of U by performing the
- algorithm in Table 7 with each value X. Each validation is
- separate from the standpoint of returning unsupported values.
- Example: If U is "finishings" that the client supplies with
- 'staple', 'bind' values, then X takes on the successive values:
- 'staple', then 'bind'
-
- 2. If V is multi-valued, validate X against each Z of V by performing
- the algorithm in Table 7 with each value Z. If a value Z
- validates, the validation for the attribute value X succeeds. If
- it fails, the algorithm is applied to the next value Z of V. If
- there are no more values Z of V, validation fails. Example" If V
- is "sides-supported" with values: 'one- sided', 'two-sided-long',
- and 'two-sided-short', then Z takes on the successive values:
- 'one-sided', 'two-sided-long', and 'two-sided-short'. If the
- client supplies "sides" with 'two-sided- long', the first
- comparison fails ('one-sided' is not equal to 'two-sided-long'),
- the second comparison succeeds ('two-sided-long' is equal to
- 'two-sided-long"), and the third comparison ('two-sided-short'
- with 'two-sided-long') is not even performed.
-
- 3. If both U and V are single-valued, let X be U and Z be V and use
- the validation rules in Table 7.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 39]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Table 7 - Rules for validating single values X against Z
-
- Attribute syntax attribute syntax validated if:
- of X of Z
-
- integer rangeOfInteger X is within the range of Z
-
- uri uriScheme the uri scheme in X is equal to
- Z
-
- any boolean the value of Z is TRUE
-
- any any X and Z are of the same type
- and are equal.
-
- If the value of the Printer object's "xxx-supported" attribute is
- 'no-value' (because the system administrator hasn't configured a
- value), the check always fails. If the check fails, the IPP object
- copies the attribute to the Unsupported Attributes response group
- with its unsupported value. If the attribute contains more than one
- value, each value is checked and each unsupported value is separately
- copied, while supported values are not copied. If an IPP object
- doesn't recognize/support a Job Template attribute, i.e., there is no
- corresponding Printer object "xxx-supported" attribute, the IPP
- object treats the attribute as an unknown or unsupported attribute
- (see the last row in the table below).
-
- If some Job Template attributes are supported for some document
- formats and not for others or the values are different for different
- document formats, the IPP object SHOULD take that into account in
- this validation using the value of the "document-format" supplied by
- the client (or defaulted to the value of the Printer's "document-
- format-default" attribute, if not supplied by the client). For
- example, if "number-up" is supported for the 'text/plain' document
- format, but not for the 'application/postscript' document format, the
- check SHOULD (though it NEED NOT) depend on the value of the
- "document-format" operation attribute. See "document-format" in
- [RFC2911] section 3.2.1.1 and 3.2.5.1.
-
- Note: whether the request is accepted or rejected is determined by
- the value of the "ipp-attribute-fidelity" attribute in a subsequent
- step, so that all Job Template attribute supplied are examined and
- all unsupported attributes and/or values are copied to the
- Unsupported Attributes response group.
-
- -----------------------------------------------
-
-
-
-
-
-Hastings, et al. Informational [Page 40]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- job-priority (integer(1:100))
-
- IF NOT a single 'integer' value with a length equal to 4 octets,
- REJECT/RETURN 'client-error-bad-request'.
-
- IF NOT supplied by the client, use the value of the Printer
- object's "job-priority-default" attribute at job submission time.
-
- IF NOT in the range 1 to 100, inclusive, copy the attribute and
- the unsupported value to the Unsupported Attributes response
- group.
-
- Map the value to the nearest supported value in the range 1:100 as
- specified by the number of discrete values indicated by the value
- of the Printer's "job-priority-supported" attribute. See the
- formula in [RFC2911] Section 4.2.1.
-
- job-hold-until (type3 keyword | name)
-
- IF NOT a single 'keyword' or 'name' value, REJECT/RETURN 'client-
- error-bad-request'.
-
- IF the value length is greater than 255 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- IF NOT supplied by the client, use the value of the Printer
- object's "job-hold-until" attribute at job submission time.
-
- IF NOT in the Printer object's "job-hold-until-supported"
- attribute, copy the attribute and the unsupported value to the
- Unsupported Attributes response group.
-
- job-sheets (type3 keyword | name)
-
- IF NOT a single 'keyword' or 'name' value, REJECT/RETURN 'client-
- error-bad-request'.
-
- IF the value length is greater than 255 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- IF NOT in the Printer object's "job-sheets-supported" attribute,
- copy the attribute and the unsupported value to the Unsupported
- Attributes response group.
-
- multiple-document-handling (type2 keyword)
-
- IF NOT a single 'keyword' value, REJECT/RETURN 'client-error-bad-
- request'.
-
-
-
-Hastings, et al. Informational [Page 41]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- IF the value length is greater than 255 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- IF NOT in the Printer object's "multiple-document-handling-
- supported" attribute, copy the attribute and the unsupported value
- to the Unsupported Attributes response group.
-
- copies (integer(1:MAX))
-
- IF NOT a single 'integer' value with a length equal to 4 octets,
- REJECT/RETURN 'client-error-bad-request'.
-
- IF NOT in range of the Printer object's "copies-supported"
- attribute
-
- copy the attribute and the unsupported value to the Unsupported
- Attributes response group.
-
- finishings (1setOf type2 enum)
-
- IF NOT an 'enum' value(s) each with a length equal to 4 octets,
- REJECT/RETURN 'client-error-bad-request'.
-
- IF NOT in the Printer object's "finishings-supported" attribute,
- copy the attribute and the unsupported value(s), but not any
- supported values, to the Unsupported Attributes response group.
-
- page-ranges (1setOf rangeOfInteger(1:MAX))
-
- IF NOT a 'rangeOfInteger' value(s) each with a length equal to 8
- octets, REJECT/RETURN 'client-error-bad-request'.
-
- IF first value is greater than second value in any range, the
- ranges are not in ascending order, or ranges overlap,
- REJECT/RETURN 'client-error-bad-request'.
-
- IF the value of the Printer object's "page-ranges-supported"
- attribute is 'false', copy the attribute to the Unsupported
- Attributes response group and set the value to the "out-of-band"
- 'unsupported' value.
-
- sides (type2 keyword)
-
- IF NOT a single 'keyword' value, REJECT/RETURN 'client-error-bad-
- request'.
-
- IF the value length is greater than 255 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
-
-
-Hastings, et al. Informational [Page 42]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- IF NOT in the Printer object's "sides-supported" attribute, copy
- the attribute and the unsupported value to the Unsupported
- Attributes response group.
-
- number-up (integer(1:MAX))
-
- IF NOT a single 'integer' value with a length equal to 4 octets,
- REJECT/RETURN 'client-error-bad-request'.
-
- IF NOT a value or in the range of one of the values of the Printer
- object's "number-up-supported" attribute, copy the attribute and
- value to the Unsupported Attribute response group.
-
- orientation-requested (type2 enum)
-
- IF NOT a single 'enum' value with a length equal to 4 octets,
- REJECT/RETURN 'client-error-bad-request'.
-
- IF NOT in the Printer object's "orientation-requested-supported"
- attribute, copy the attribute and the unsupported value to the
- Unsupported Attributes response group.
-
- media (type3 keyword | name)
-
- IF NOT a single 'keyword' or 'name' value, REJECT/RETURN 'client-
- error-bad-request'.
-
- IF the value length is greater than 255 octets, REJECT/RETURN
- 'client-error-request-value-too-long'.
-
- IF NOT in the Printer object's "media-supported" attribute, copy
- the attribute and the unsupported value to the Unsupported
- Attributes response group.
-
- printer-resolution (resolution)
-
- IF NOT a single 'resolution' value with a length equal to 9
- octets, REJECT/RETURN 'client-error-bad-request'.
-
- IF NOT in the Printer object's "printer-resolution-supported"
- attribute, copy the attribute and the unsupported value to the
- Unsupported Attributes response group.
-
- print-quality (type2 enum)
-
- IF NOT a single 'enum' value with a length equal to 4 octets,
- REJECT/RETURN 'client-error-bad-request'.
-
-
-
-
-Hastings, et al. Informational [Page 43]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- IF NOT in the Printer object's "print-quality-supported"
- attribute, copy the attribute and the unsupported value to the
- Unsupported Attributes response group.
-
- unknown or unsupported attribute (i.e., there is no corresponding
- Printer object "xxx-supported" attribute)
-
- IF the attribute syntax supplied by the client is supported but
- the length is not legal for that attribute syntax,
-
- REJECT/RETURN 'client-error-bad-request' if the length of the
- attribute syntax is fixed or 'client-error-request-value-too-long'
- if the length of the attribute syntax is variable.
-
- ELSE copy the attribute and value to the Unsupported Attributes
- response group and change the attribute value to the "out-of-band"
- 'unsupported' value. Any remaining Job Template Attributes are
- either unknown or unsupported Job Template attributes and are
- validated algorithmically according to their attribute syntax for
- proper length (see below).
-
- -----------------------------------------------
-
- If the attribute syntax is supported AND the length check fails,
- the IPP object REJECTS the request and RETURNS the 'client-error-
- bad-request' if the length of the attribute syntax is fixed or the
- 'client-error-request-value-too-long' status code if the length of
- the attribute syntax is variable. Otherwise, the IPP object copies
- the unsupported Job Template attribute to the Unsupported
- Attributes response group and changes the attribute value to the
- "out-of-band" 'unsupported' value. The following table shows the
- length checks for all attribute syntaxes. In the following table:
- "<=" means less than or equal, "=" means equal to:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 44]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Name Octet length check for read-write attributes
- ---------- ---------------------------------------------
-
- 'textWithLanguage <= 1023 AND 'naturalLanguage' <= 63
- 'textWithoutLanguage' <= 1023
- 'nameWithLanguage' <= 255 AND 'naturalLanguage' <= 63
- 'nameWithoutLanguage' <= 255
- 'keyword' <= 255
- 'enum' = 4
- 'uri' <= 1023
- 'uriScheme' <= 63
- 'charset' <= 63
- 'naturalLanguage' <= 63
- 'mimeMediaType' <= 255
- 'octetString' <= 1023
- 'boolean' = 1
- 'integer' = 4
- 'rangeOfInteger' = 8
- 'dateTime' = 11
- 'resolution' = 9
- '1setOf X'
-
- Note: It's possible for a Printer to receive a zero length keyword
- in a request. Since this is a keyword, its value needs to be
- compared with the supported values. Assuming that the printer
- doesn't have any values in its corresponding "xxx-supported"
- attribute that are keywords of zero length, the comparison will fail.
- Then the request will be accepted or rejected depending on the value
- of "ipp-attributes-fidelity" being 'false' or 'true', respectively.
- No special handling is required for
-
-3.1.2.3.1 Check for conflicting Job Template attributes values
-
- Once all the Operation and Job Template attributes have been checked
- individually, the Printer object SHOULD check for any conflicting
- values among all the supported values supplied by the client. For
- example, a Printer object might be able to staple and to print on
- transparencies, however due to physical stapling constraints, the
- Printer object might not be able to staple transparencies. The IPP
- object copies the supported attributes and their conflicting
- attribute values to the Unsupported Attributes response group. The
- Printer object only copies over those attributes that the Printer
- object either ignores or substitutes in order to resolve the
- conflict, and it returns the original values which were supplied by
- the client. For example suppose the client supplies "finishings"
- equals 'staple' and "media" equals 'transparency', but the Printer
- object does not support stapling transparencies. If the Printer
- chooses to ignore the stapling request in order to resolve the
-
-
-
-Hastings, et al. Informational [Page 45]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- conflict, the Printer objects returns "finishings" equal to 'staple'
- in the Unsupported Attributes response group. If any attributes are
- multi-valued, only the conflicting values of the attributes are
- copied.
-
- Note: The decisions made to resolve the conflict (if there is a
- choice) is implementation dependent.
-
-3.1.2.3.2 Decide whether to REJECT the request
-
- If there were any unsupported Job Template attributes or
- unsupported/conflicting Job Template attribute values and the client
- supplied the "ipp-attribute-fidelity" attribute with the 'true'
- value, the Printer object REJECTS the request and return the status
- code:
-
- 1.'client-error-conflicting-attributes' status code, if there were
- any conflicts between attributes supplied by the client.
-
- 2.'client-error-attributes-or-values-not-supported' status code,
- otherwise.
-
- Note: Unsupported Operation attributes or values that are returned
- do not affect the status returned in this step. If the unsupported
- Operation attribute was a serious error, the above already rejected
- the request in a previous step. If control gets to this step with
- unsupported Operation attributes being returned, they are not serious
- errors.
-
- In general, the final results of Job processing are unknown at Job
- submission time. The client has to rely on notifications or polling
- to find out what happens at Job processing time. However, there are
- cases in which some Printers can determine at Job submission time
- that Job processing is going to fail. As an optimization, we'd like
- to have the Printer reject the Job in these cases.
-
- There are three types of "processing" errors that might be detectable
- at Job submission time:
-
- 1. 'client-error-document-format-not-supported' : For the Print-
- Job, Send-Document, Print-URI, and Send-URI operations, if all these
- conditions are true:
-
- - the Printer supports auto-sensing,
- - the request "document-format" operation attribute is
- 'application/octet-stream',
- - the Printer receives document data before responding,
- - the Printer auto-senses the document format before responding,
-
-
-
-Hastings, et al. Informational [Page 46]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- - the sensed document format is not supported by the Printer
-
- then the Printer should respond with 'client-error-document-format-
- not-supported' status.
-
- 2. 'client-error-compression-error': For the Print-Job, Send-
- Document, Print-URI, and Send-URI operations, if all these
- conditions are true:
-
- - the client supplies a supported value for the "compression"
- operation attribute in the request
- - the Printer receives document data before responding,
- - the Printer attempts to decompress the document data before
- responding,
- - the document data cannot be decompressed using the algorithm
- specified by the "compression" operation attribute
-
- then the Printer should respond with 'client-error-compression-error'
- status.
-
- 3. 'client-error-document-access-error': For the Print-URI, and
- Send-URI operations, if the Printer attempts and fails to pull the
- referenced document data before responding, it should respond with
- 'client-error-document-access-error' status.
-
- Some Printers are not able to detect these errors until Job
- processing time. In that case, the errors are recorded in the
- corresponding job-state and job-state reason attributes. (There is
- no standard way for a client to determine whether a Printer can
- detect these errors at Job submission time.) For example, if auto-
- sensing happens AFTER the job is accepted (as opposed to auto-sensing
- at submit time before returning the response), the implementation
- aborts the job, puts the job in the 'aborted' state and sets the
- 'unsupported-document-format' value in the job's "job-state-reasons".
-
- A client should always provide a valid "document-format" operation
- attribute whenever practical. In the absence of other information, a
- client itself may sniff the document data to determine document
- format.
-
- Auto sensing at Job submission time may be more difficult for the
- Printer when combined with compression. For auto-sensed Jobs, a
- client may be better off deferring compression to the transfer
- protocol layer, e.g.; by using the HTTP Content-Encoding header.
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 47]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-3.1.2.3.3 For the Validate-Job operation, RETURN one of the success
- status codes
-
- If the requested operation is the Validate-Job operation, the Printer
- object returns:
-
- 1. the "successful-ok" status code, if there are no unsupported or
- conflicting Job Template attributes or values.
- 2. the "successful-ok-conflicting-attributes, if there are any
- conflicting Job Template attribute or values.
- 3. the "successful-ok-ignored-or-substituted-attributes, if there
- are only unsupported Job Template attributes or values.
-
- Note: Unsupported Operation attributes or values that are returned
- do not affect the status returned in this step. If the unsupported
- Operation attribute was a serious error, the above already rejected
- the request in a previous step. If control gets to this step with
- unsupported Operation attributes being returned, they are not serious
- errors.
-
-3.1.2.3.4 Create the Job object with attributes to support
-
- If "ipp-attribute-fidelity" is set to 'false' (or it was not supplied
- by the client), the Printer object:
-
- 1. creates a Job object, assigns a unique value to the job's
- "job-uri" and "job-id" attributes, and initializes all of the
- job's other supported Job Description attributes.
- 2. removes all unsupported attributes from the Job object.
- 3. for each unsupported value, removes either the unsupported
- value or substitutes the unsupported attribute value with some
- supported value. If an attribute has no values after removing
- unsupported values from it, the attribute is removed from the
- Job object (so that the normal default behavior at job
- processing time will take place for that attribute).
- 4. for each conflicting value, removes either the conflicting
- value or substitutes the conflicting attribute value with some
- other supported value. If an attribute has no values after
- removing conflicting values from it, the attribute is removed
- from the Job object (so that the normal default behavior at job
- processing time will take place for that attribute).
-
- If there were no attributes or values flagged as unsupported, or the
- value of 'ipp-attribute-fidelity" was 'false', the Printer object is
- able to accept the create request and create a new Job object. If
- the "ipp-attribute-fidelity" attribute is set to 'true', the Job
- Template attributes that populate the new Job object are necessarily
- all the Job Template attributes supplied in the create request. If
-
-
-
-Hastings, et al. Informational [Page 48]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- the "ipp-attribute-fidelity" attribute is set to 'false', the Job
- Template attributes that populate the new Job object are all the
- client supplied Job Template attributes that are supported or that
- have value substitution. Thus, some of the requested Job Template
- attributes will not appear in the Job object because the Printer
- object did not support those attributes. The attributes that
- populate the Job object are persistently stored with the Job object
- for that Job. A Get-Job-Attributes operation on that Job object will
- return only those attributes that are persistently stored with the
- Job object.
-
- Note: All Job Template attributes that are persistently stored with
- the Job object are intended to be "override values"; that is, they
- that take precedence over whatever other embedded instructions might
- be in the document data itself. However, it is not possible for all
- Printer objects to realize the semantics of "override". End users
- may query the Printer's "pdl-override-supported" attribute to
- determine if the Printer either attempts or does not attempt to
- override document data instructions with IPP attributes.
-
- There are some cases, where a Printer supports a Job Template
- attribute and has an associated default value set for that attribute.
- In the case where a client does not supply the corresponding
- attribute, the Printer does not use its default values to populate
- Job attributes when creating the new Job object; only Job Template
- attributes actually in the create request are used to populate the
- Job object. The Printer's default values are only used later at Job
- processing time if no other IPP attribute or instruction embedded in
- the document data is present.
-
- Note: If the default values associated with Job Template attributes
- that the client did not supply were to be used to populate the Job
- object, then these values would become "override values" rather than
- defaults. If the Printer supports the 'attempted' value of the
- "pdl-override-supported" attribute, then these override values could
- replace values specified within the document data. This is not the
- intent of the default value mechanism. A default value for an
- attribute is used only if the create request did not specify that
- attribute (or it was ignored when allowed by "ipp-attribute-fidelity"
- being 'false') and no value was provided within the content of the
- document data.
-
- If the client does not supply a value for some Job Template
- attribute, and the Printer does not support that attribute, as far as
- IPP is concerned, the result of processing that Job (with respect to
- the missing attribute) is undefined.
-
-
-
-
-
-Hastings, et al. Informational [Page 49]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-3.1.2.3.5 Return one of the success status codes
-
- Once the Job object has been created, the Printer object accepts the
- request and returns to the client:
-
- 1. the 'successful-ok' status code, if there are no unsupported or
- conflicting Job Template attributes or values.
- 2. the 'successful-ok-conflicting-attributes' status code, if
- there are any conflicting Job Template attribute or values.
- 3. the 'successful-ok-ignored-or-substituted-attributes' status
- code, if there are only unsupported Job Template attributes or
- values.
-
- Note: Unsupported Operation attributes or values that are returned
- do not affect the status returned in this step. If the unsupported
- Operation attribute was a serious error, the above already rejected
- the request in a previous step. If control gets to this step with
- unsupported Operation attributes being returned, they are not serious
- errors.
-
- The Printer object also returns Job status attributes that indicate
- the initial state of the Job ('pending', 'pending-held',
- 'processing', etc.), etc. See Print-Job Response, [RFC2911] section
- 3.2.1.2.
-
-3.1.2.3.6 Accept appended Document Content
-
- The Printer object accepts the appended Document Content data and
- either starts it printing, or spools it for later processing.
-
-3.1.2.3.7 Scheduling and Starting to Process the Job
-
- The Printer object uses its own configuration and implementation
- specific algorithms for scheduling the Job in the correct processing
- order. Once the Printer object begins processing the Job, the
- Printer changes the Job's state to 'processing'. If the Printer
- object supports PDL override (the "pdl-override-supported" attribute
- set to 'attempted'), the implementation does its best to see that IPP
- attributes take precedence over embedded instructions in the document
- data.
-
-3.1.2.3.8 Completing the Job
-
- The Printer object continues to process the Job until it can move the
- Job into the 'completed' state. If an Cancel-Job operation is
- received, the implementation eventually moves the Job into the
- 'canceled' state. If the system encounters errors during processing
- that do not allow it to progress the Job into a completed state, the
-
-
-
-Hastings, et al. Informational [Page 50]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- implementation halts all processing, cleans up any resources, and
- moves the Job into the 'aborted' state.
-
-3.1.2.3.9 Destroying the Job after completion
-
- Once the Job moves to the 'completed', 'aborted', or 'canceled'
- state, it is an implementation decision as to when to destroy the Job
- object and release all associated resources. Once the Job has been
- destroyed, the Printer would return either the "client-error-not-
- found" or "client-error-gone" status codes for operations directed at
- that Job.
-
- Note: the Printer object SHOULD NOT re-use a "job-uri" or "job-id"
- value for a sufficiently long time after a job has been destroyed, so
- that stale references kept by clients are less likely to access the
- wrong (newer) job.
-
-3.1.2.3.10 Interaction with "ipp-attribute-fidelity"
-
- Some Printer object implementations may support "ipp-attribute-
- fidelity" set to 'true' and "pdl-override-supported" set to
- 'attempted' and yet still not be able to realize exactly what the
- client specifies in the create request. This is due to legacy
- decisions and assumptions that have been made about the role of job
- instructions embedded within the document data and external job
- instructions that accompany the document data and how to handle
- conflicts between such instructions. The inability to be 100%
- precise about how a given implementation will behave is also
- compounded by the fact that the two special attributes, "ipp-
- attribute-fidelity" and "pdl-"override-supported", apply to the whole
- job rather than specific values for each attribute. For example, some
- implementations may be able to override almost all Job Template
- attributes except for "number-up". Character Sets, natural
- languages, and internationalization
-
- This section discusses character set support, natural language
- support and internationalization.
-
-3.1.2.3.11 Character set code conversion support
-
- IPP clients and IPP objects are REQUIRED to support UTF-8. They MAY
- support additional charsets. It is RECOMMENDED that an IPP object
- also support US-ASCII, since many clients support US-ASCII, and
- indicate that UTF-8 and US-ASCII are supported by populating the
- Printer's "charset-supported" with 'utf-8' and 'us-ascii' values. An
- IPP object is required to code covert with as little loss as possible
- between the charsets that it supports, as indicated in the Printer's
- "charsets-supported" attribute.
-
-
-
-Hastings, et al. Informational [Page 51]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- How should the server handle the situation where the "attributes-
- charset" of the response itself is "us-ascii", but one or more
- attributes in that response is in the "utf-8" format?
-
- Example: Consider a case where a client sends a Print-Job request
- with "utf-8" as the value of "attributes-charset" and with the "job-
- name" attribute supplied. Later another client submits a Get-Job-
- Attribute or Get-Jobs request. This second request contains the
- "attributes-charset" with value "us-ascii" and "requested-attributes"
- attribute with exactly one value "job-name".
-
- According to the RFC2911 document (section 3.1.4.2), the value of the
- "attributes-charset" for the response of the second request must be
- "us-ascii" since that is the charset specified in the request. The
- "job-name" value, however, is in "utf-8" format. Should the request
- be rejected even though both "utf-8" and "us-ascii" charsets are
- supported by the server? or should the "job-name" value be converted
- to "us-ascii" and return "successful-ok-conflicting-attributes"
- (0x0002) as the status code?
-
- Answer: An IPP object that supports both utf-8 (REQUIRED) and us-
- ascii, the second paragraph of section 3.1.4.2 applies so that the
- IPP object MUST accept the request, perform code set conversion
- between these two charsets with "the highest fidelity possible" and
- return 'successful-ok', rather than a warning 'successful-ok-
- conflicting-attributes, or an error. The printer will do the best it
- can to convert between each of the character sets that it supports --
- even if that means providing a string of question marks because none
- of the characters are representable in US ASCII. If it can't perform
- such conversion, it MUST NOT advertise us-ascii as a value of its
- "attributes-charset-supported" and MUST reject any request that
- requests 'us-ascii'.
-
- One IPP object implementation strategy is to convert all request text
- and name values to a Unicode internal representation. This is 16-bit
- and virtually universal. Then convert to the specified operation
- attributes-charset on output.
-
- Also it would be smarter for a client to ask for 'utf-8', rather than
- 'us-ascii' and throw away characters that it doesn't understand,
- rather than depending on the code conversion of the IPP object.
-
-3.1.2.3.12 What charset to return when an unsupported charset is
- requested (Issue 1.19)?
-
- Section 3.1.4.1 Request Operation attributes was clarified in
- November 1998 as follows:
-
-
-
-
-Hastings, et al. Informational [Page 52]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- All clients and IPP objects MUST support the 'utf-8' charset
- [RFC2044] and MAY support additional charsets provided that they are
- registered with IANA [IANA-CS]. If the Printer object does not
- support the client supplied charset value, the Printer object MUST
- reject the request, set the "attributes-charset" to 'utf-8' in the
- response, and return the 'client-error-charset-not-supported' status
- code and any 'text' or 'name' attributes using the 'utf-8' charset.
-
- Since the client and IPP object MUST support UTF-8, returning any
- text or name attributes in UTF-8 when the client requests a charset
- that is not supported should allow the client to display the text or
- name.
-
- Since such an error is a client error, rather than a user error, the
- client should check the status code first so that it can avoid
- displaying any other returned 'text' and 'name' attributes that are
- not in the charset requested.
-
- Furthermore, [RFC2911] section 14.1.4.14 client-error-charset-not-
- supported (0x040D) was clarified in November 1998 as follows:
-
- For any operation, if the IPP Printer does not support the charset
- supplied by the client in the "attributes-charset" operation
- attribute, the Printer MUST reject the operation and return this
- status and any 'text' or 'name' attributes using the 'utf-8' charset
- (see Section 3.1.4.1).
-
-3.1.2.3.13 Natural Language Override (NLO)
-
- The 'text' and 'name' attributes each have two forms. One has an
- implicit natural language, and the other has an explicit natural
- language. The 'textWithoutLanguage' and 'textWithLanguage' are the
- two 'text' forms. The 'nameWithoutLanguage" and 'nameWithLanguage
- are the two 'name' forms. If a receiver (IPP object or IPP client)
- supports an attribute with attribute syntax 'text', it MUST support
- both forms in a request and a response. A sender (IPP client or IPP
- object) MAY send either form for any such attribute. When a sender
- sends a WithoutLanguage form, the implicit natural language is
- specified in the "attributes-natural-language" operation attribute,
- which all senders MUST include in every request and response.
-
- When a sender sends a WithLanguage form, it MAY be different from the
- implicit natural language supplied by the sender or it MAY be the
- same. The receiver MUST treat either form equivalently.
-
- There is an implementation decision for senders, whether to always
- send the WithLanguage forms or use the WithoutLanguage form when the
- attribute's natural language is the same as the request or response.
-
-
-
-Hastings, et al. Informational [Page 53]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- The former approach makes the sender implementation simpler. The
- latter approach is more efficient on the wire and allows inter-
- working with non-conforming receivers that fail to support the
- WithLanguage forms. As each approach have advantages, the choice is
- completely up to the implementer of the sender.
-
- Furthermore, when a client receives a 'text' or 'name' job attribute
- that it had previously supplied, that client MUST NOT expect to see
- the attribute in the same form, i.e., in the same WithoutLanguage or
- WithLanguage form as the client supplied when it created the job.
- The IPP object is free to transform the attribute from the
- WithLanguage form to the WithoutLanguage form and vice versa, as long
- as the natural language is preserved. However, in order to meet this
- latter requirement, it is usually simpler for the IPP object
- implementation to store the natural language explicitly with the
- attribute value, i.e., to store using an internal representation that
- resembles the WithLanguage form.
-
- The IPP Printer MUST copy the natural language of a job, i.e., the
- value of the "attributes-natural-language" operation attribute
- supplied by the client in the create operation, to the Job object as
- a Job Description attribute, so that a client is able to query it.
- In returning a Get-Job-Attributes response, the IPP object MAY return
- one of three natural language values in the responses "attributes-
- natural-language" operation attribute: (1) that requested by the
- requester, (2) the natural language of the job, or (3) the configured
- natural language of the IPP Printer, if the requested language is not
- supported by the IPP Printer.
-
- This "attributes-natural-language" Job Description attribute is
- useful for an IPP object implementation that prints start sheets in
- the language of the user who submitted the job. This same Job
- Description attribute is useful to a multi-lingual operator who has
- to communicate with different job submitters in different natural
- languages. This same Job Description attribute is expected to be
- used in the future to generate notification messages in the natural
- language of the job submitter.
-
- Early drafts of [RFC2911] contained a job-level natural language
- override (NLO) for the Get-Jobs response. A job-level (NLO) is an
- (unrequested) Job Attribute which then specified the implicit natural
- language for any other WithoutLanguage job attributes returned in the
- response for that job. Interoperability testing of early
- implementations showed that no one was implementing the job-level NLO
- in Get-Job responses. So the job-level NLO was eliminated from the
- Get-Jobs response. This simplification makes all requests and
- responses consistent in that the implicit natural language for any
-
-
-
-
-Hastings, et al. Informational [Page 54]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- WithoutLanguage 'text' or 'name' form is always supplied in the
- request's or response's "attributes-natural-language" operation
- attribute.
-
-3.1.3 Status codes returned by operation
-
- This section corresponds to [RFC2911] section 3.1.6 "Operation
- Response Status Codes and Status Messages". This section lists all
- status codes once in the first operation (Print-Job). Then it lists
- the status codes that are different or specialized for subsequent
- operations under each operation.
-
-3.1.3.1 Printer Operations
-
-3.1.3.1.1 Print-Job
-
- The Printer object MUST return one of the following "status-code"
- values for the indicated reason. Whether all of the document data
- has been accepted or not before returning the success or error
- response depends on implementation. See Section 13 in [RFC2911] for
- a more complete description of each status code.
-
- For the following success status codes, the Job object has been
- created and the "job-id", and "job-uri" assigned and returned in the
- response:
-
- successful-ok: no request attributes were substituted or ignored.
-
- successful-ok-ignored-or-substituted-attributes: some supplied
- (1) attributes were ignored or (2) unsupported attribute syntaxes
- or values were substituted with supported values or were ignored.
- Unsupported attributes, attribute syntax's, or values MUST be
- returned in the Unsupported Attributes group of the response.
-
- successful-ok-conflicting-attributes: some supplied attribute
- values conflicted with the values of other supplied attributes and
- were either substituted or ignored. Attributes or values which
- conflict with other attributes and have been substituted or
- ignored MUST be returned in the Unsupported Attributes group of
- the response as supplied by the client.
-
- [RFC2911] section 3.1.6 Operation Status Codes and Messages states:
-
- If the Printer object supports the "status-message" operation
- attribute, it SHOULD use the REQUIRED 'utf-8' charset to return a
- status message for the following error status codes (see section
- 13 in [RFC2911]): 'client-error-bad-request', 'client-error-
- charset-not-supported', 'server-error-internal-error', 'server-
-
-
-
-Hastings, et al. Informational [Page 55]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- error-operation-not-supported', and 'server-error-version-not-
- supported'. In this case, it MUST set the value of the
- "attributes-charset" operation attribute to 'utf-8' in the error
- response.
-
- For the following error status codes, no job is created and no
- "job-id" or "job-uri" is returned:
-
- client-error-bad-request: The request syntax does not conform
- to the specification.
-
- client-error-forbidden: The request is being refused for
- authorization or authentication reasons. The implementation
- security policy is to not reveal whether the failure is one of
- authentication or authorization.
-
- client-error-not-authenticated: Either the request requires
- authentication information to be supplied or the authentication
- information is not sufficient for authorization.
-
- client-error-not-authorized: The requester is not authorized
- to perform the request on the target object.
-
- client-error-not-possible: The request cannot be carried out
- because of the state of the system. See also 'server-error-
- not-accepting-jobs' status code, which MUST take precedence if
- the Printer object's "printer-accepting-jobs" attribute is
- 'false'.
-
- client-error-timeout: not applicable.
-
- client-error-not-found: the target object does not exist.
-
- client-error-gone: the target object no longer exists and no
- forwarding address is known.
-
- client-error-request-entity-too-large: the size of the request
- and/or print data exceeds the capacity of the IPP Printer to
- process it.
-
- client-error-request-value-too-long: the size of request
- variable length attribute values, such as 'text' and 'name'
- attribute syntax's, exceed the maximum length specified in
- [RFC2911] for the attribute and MUST be returned in the
- Unsupported Attributes Group.
-
-
-
-
-
-
-Hastings, et al. Informational [Page 56]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- supplied is not supported. The "document-format" attribute
- with the unsupported value MUST be returned in the Unsupported
- Attributes Group. This error SHOULD take precedence over any
- other 'xxx-not-supported' error, except 'client-error-charset-
- not-supported'.
-
- client-error-attributes-or-values-not-supported: one or more
- supplied attributes, attribute syntax's, or values are not
- supported and the client supplied the "ipp-attributes-
- fidelity" operation attribute with a 'true' value. They MUST
- be returned in the Unsupported Attributes Group as explained
- below.
-
- client-error-uri-scheme-not-supported: not applicable.
-
- client-error-charset-not-supported: the charset supplied in
- the "attributes-charset" operation attribute is not supported.
- The Printer's "configured-charset" MUST be returned in the
- response as the value of the "attributes-charset" operation
- attribute and used for any 'text' and 'name' attributes
- returned in the error response. This error SHOULD take
- precedence over any other error, unless the request syntax is
- so bad that the client's supplied "attributes-charset" cannot
- be determined.
-
- client-error-conflicting-attributes: one or more supplied
- attribute values conflicted with each other and the client
- supplied the "ipp-attributes-fidelity" operation attribute with
- a 'true' value. They MUST be returned in the Unsupported
- Attributes Group as explained below.
-
- server-error-internal-error: an unexpected condition prevents
- the request from being fulfilled.
-
- server-error-operation-not-supported: not applicable (since
- Print-Job is REQUIRED).
-
- server-error-service-unavailable: the service is temporarily
- overloaded.
-
- server-error-version-not-supported: the version in the request
- is not supported. The "closest" version number supported MUST
- be returned in the response.
-
- server-error-device-error: a device error occurred while
- receiving or spooling the request or document data or the IPP
- Printer object can only accept one job at a time.
-
-
-
-
-Hastings, et al. Informational [Page 57]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- server-error-temporary-error: a temporary error such as a
- buffer full write error, a memory overflow, or a disk full
- condition occurred while receiving the request and/or the
- document data.
-
- server-error-not-accepting-jobs: the Printer object's
- "printer-is-not-accepting-jobs" attribute is 'false'.
-
- server-error-busy: the Printer is too busy processing jobs to
- accept another job at this time.
-
- server-error-job-canceled: the job has been canceled by an
- operator or the system while the client was transmitting the
- document data.
-
-3.1.3.1.2 Print-URI
-
- All of the Print-Job status codes described in Section 3.1.3.1.1
- Print-Job Response are applicable to Print-URI with the following
- specializations and differences. See Section 14 for a more complete
- description of each status code.
-
- client-error-uri-scheme-not-supported: the URI scheme supplied
- in the "document-uri" operation attribute is not supported and
- is returned in the Unsupported Attributes group.
-
- server-error-operation-not-supported: the Print-URI operation
- is not supported.
-
-3.1.3.1.3 Validate-Job
-
- All of the Print-Job status codes described in Section 3.1.3.1.1
- Print-Job Response are applicable to Validate-Job. See Section 13 in
- [RFC2911] for a more complete description of each status code.
-
-3.1.3.1.4 Create-Job
-
- All of the Print-Job status codes described in Section 3.1.3.1.1
- Print-Job Response are applicable to Create-Job with the following
- specializations and differences. See Section 13 in [RFC2911] for a
- more complete description of each status code.
-
- server-error-operation-not-supported: the Create-Job operation
- is not supported.
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 58]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- client-error-multiple-document-jobs-not-supported: while the
- Create-Job and Send-Document operations are supported, this
- implementation doesn't support more than one document with
- data.
-
-3.1.3.1.5 Get-Printer-Attributes
-
- All of the Print-Job status codes described in Section
- 3.1.3.1.1 Print-Job Response are applicable to the Get-
- Printer-Attributes operation with the following
- specialization's and differences. See Section 13 in [RFC2911]
- for a more complete description of each status code.
-
- For the following success status codes, the requested
- attributes are returned in Group 3 in the response:
-
- successful-ok: no operation attributes or values were
- substituted or ignored (same as Print-Job) and no requested
- attributes were unsupported.
-
- successful-ok-ignored-or-substituted-attributes: The
- "requested-attributes" operation attribute MAY, but NEED NOT,
- be returned with the unsupported values.
-
- successful-ok-conflicting-attributes: same as Print-Job.
-
- For the error status codes, Group 3 is returned containing no
- attributes or is not returned at all:
-
- client-error-not-possible: Same as Print-Job, in addition the
- Printer object is not accepting any requests.
-
- client-error-request-entity-too-large: same as Print-job,
- except that no print data is involved.
-
- client-error-attributes-or-values-not-supported: not
- applicable, since unsupported operation attributes and/or
- values MUST be ignored and an appropriate success code returned
- (see above).
-
- client-error-conflicting-attributes: same as Print-Job, except
- that "ipp-attribute-fidelity" is not involved.
-
- server-error-operation-not-supported: not applicable (since
- Get-Printer-Attributes is REQUIRED).
-
- server-error-device-error: same as Print-Job, except that no
- document data is involved.
-
-
-
-Hastings, et al. Informational [Page 59]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- server-error-temporary-error: same as Print-Job, except that
- no document data is involved.
-
- server-error-not-accepting-jobs: not applicable.
-
- server-error-busy: same as Print-Job, except the IPP object is
- too busy to accept even query requests.
-
- server-error-job-canceled: not applicable.
-
-3.1.3.1.6 Get-Jobs
-
- All of the Print-Job status codes described in Section 3.1.3.1.1
- Print-Job Response are applicable to the Get-Jobs operation with the
- following specialization's and differences. See Section 13 in
- [RFC2911] for a more complete description of each status code.
-
- For the following success status codes, the requested attributes are
- returned in Group 3 in the response:
-
- successful-ok: same as Get-Printer-Attributes (see section
- 3.1.3.1.5).
-
- successful-ok-ignored-or-substituted-attributes: same as Get-
- Printer-Attributes (see section 3.1.3.1.5).
-
- successful-ok-conflicting-attributes: same as Get-Printer-
- Attributes (see section 3.1.3.1.5).
-
- For any error status codes, Group 3 is returned containing no
- attributes or is not returned at all. The following brief error
- status code descriptions contain unique information for use with
- Get-Jobs operation. See section 14 for the other error status codes
- that apply uniformly to all operations:
-
- client-error-not-possible: Same as Print-Job, in addition the
- Printer object is not accepting any requests.
-
- client-error-request-entity-too-large: same as Print-job,
- except that no print data is involved.
-
- client-error-document-format-not-supported: not applicable.
-
- client-error-attributes-or-values-not-supported: not
- applicable, since unsupported operation attributes and/or
- values MUST be ignored and an appropriate success code returned
- (see above).
-
-
-
-
-Hastings, et al. Informational [Page 60]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- client-error-conflicting-attributes: same as Print-Job, except
- that "ipp-attribute-fidelity" is not involved.
-
- server-error-operation-not-supported: not applicable (since
- Get-Jobs is REQUIRED).
-
- server-error-device-error: same as Print-Job, except that no
- document data is involved.
-
- server-error-temporary-error: same as Print-Job, except that
- no document data is involved.
-
- server-error-not-accepting-jobs: not applicable.
-
- server-error-job-canceled: not applicable.
-
-3.1.3.1.7 Pause-Printer
-
- All of the Print-Job status codes described in Section 3.1.3.1.1
- Print-Job Response are applicable to Pause-Printer with the following
- specializations and differences. See Section 13 in [RFC2911] for a
- more complete description of each status code.
-
- For the following success status codes, the Printer object is being
- stopped from scheduling jobs on all its devices.
-
- successful-ok: no request attributes were substituted or
- ignored (same as Print-Job).
-
- successful-ok-ignored-or-substituted-attributes: same as
- Print-Job.
-
- successful-ok-conflicting-attributes: same as Print-Job.
-
- For any of the error status codes, the Printer object has not been
- stopped from scheduling jobs on all its devices.
-
- client-error-not-possible: not applicable.
-
- client-error-not-found: the target Printer object does not
- exist.
-
- client-error-gone: the target Printer object no longer exists
- and no forwarding address is known.
-
- client-error-request-entity-too-large: same as Print-Job,
- except no document data is involved.
-
-
-
-
-Hastings, et al. Informational [Page 61]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- client-error-document-format-not-supported: not applicable.
-
- client-error-conflicting-attributes: same as Print-Job, except
- that the Printer's "printer-is-accepting-jobs" attribute is not
- involved.
-
- server-error-operation-not-supported: the Pause-Printer
- operation is not supported.
-
- server-error-device-error: not applicable.
-
- server-error-temporary-error: same as Print-Job, except no
- document data is involved.
-
- server-error-not-accepting-jobs: not applicable.
-
- server-error-job-canceled: not applicable.
-
-3.1.3.1.8 Resume-Printer
-
- All of the Print-Job status code descriptions in Section 3.1.3.1.1
- Print-Job Response with the specialization's described for Pause-
- Printer are applicable to Resume-Printer. See Section 13 in
- [RFC2911] for a more complete description of each status code.
-
- For the following success status codes, the Printer object resumes
- scheduling jobs on all its devices.
-
- successful-ok: no request attributes were substituted or
- ignored (same as Print-Job).
-
- successful-ok-ignored-or-substituted-attributes: same as
- Print-Job.
-
- successful-ok-conflicting-attributes: same as Print-Job.
-
- For any of the error status codes, the Printer object does not resume
- scheduling jobs.
-
- server-error-operation-not-supported: the Resume-Printer
- operation is not supported.
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 62]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-3.1.3.1.8.1 What about Printers unable to change state due to an error
- condition?
-
- If, in case, the IPP printer is unable to change its state due to
- some problem with the actual printer device (say, it is shut down or
- there is a media-jam as indicated in [RFC2911]), what should be the
- result of the "Resume-Printer" operation? Should it still change the
- 'printer-state-reasons' and return success or should it fail ?
-
- The Resume-Printer operation must clear the 'paused' or 'moving-to-
- paused' 'printer-state-message'. The operation must return a
- 'successful-ok' status code.
-
-3.1.3.1.8.2 How is "printer-state" handled on Resume-Printer?
-
- If the Resume-Printer operation succeeds, what should be the value of
- "printer-state" and who should take care of the "printer-state"
- attribute value later on ?
-
- The Resume-Printer operation may change the "printer-state-reasons"
- value.
-
- The "printer-state" will change to one of three states:
-
- 1. 'idle' - no additional jobs and no error conditions present
-
- 2. 'processing' - job available and no error conditions present
-
- 3. current state (i.e. no change) an error condition is present
- (e.g. media jam)
-
- In the third case the "printer-state-reason" will be cleared by
- automata when it detects the error condition no longer exists. The
- "printer-state" will move to 'idle' or 'processing' when conditions
- permit. (i.e. no more error conditions)
-
-3.1.3.1.9 Purge-Printer
-
- All of the Print-Job status code descriptions in Section 3.1.3.1.1
- Print-Job Response with the specialization's described for Pause-
- Printer are applicable to Purge-Printer. See Section 13 in [RFC2911]
- for a more complete description of each status code.
-
- For the following success status codes, the Printer object purges all
- it's jobs.
-
- successful-ok: no request attributes were substituted or
- ignored (same as Print-Job).
-
-
-
-Hastings, et al. Informational [Page 63]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- successful-ok-ignored-or-substituted-attributes: same as
- Print-Job.
-
- successful-ok-conflicting-attributes: same as Print-Job.
-
- For any of the error status codes, the Printer object does not purge
- any jobs.
-
- server-error-operation-not-supported: the Purge-Printer
- operation is not supported.
-
-3.1.3.2 Job Operations
-
-3.1.3.2.1 Send-Document
-
- All of the Print-Job status codes described in Section 3.1.3.1.1
- Print-Job Response are applicable to the Get-Printer-Attributes
- operation with the following specialization's and differences. See
- Section 13 in [RFC2911] for a more complete description of each
- status code.
-
- For the following success status codes, the document has been added
- to the specified Job object and the job's "number-of-documents"
- attribute has been incremented:
-
- successful-ok: no request attributes were substituted or
- ignored (same as Print-Job).
-
- successful-ok-ignored-or-substituted-attributes: same as
- Print-Job.
-
- successful-ok-conflicting-attributes: same as Print-Job.
-
- For the error status codes, no document has been added to the Job
- object and the job's "number-of-documents" attribute has not been
- incremented:
-
- client-error-not-possible: Same as Print-Job, except that the
- Printer's "printer-is-accepting-jobs" attribute is not
- involved, so that the client is able to finish submitting a job
- that was created with a Create-Job operation after this
- attribute has been set to 'true'. Another condition is that
- the state of the job precludes Send-Document, i.e., the job has
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 64]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- already been closed out by the client. However, if the IPP
- Printer closed out the job due to timeout, the 'client-error-
- timeout' error status SHOULD be returned instead.
-
- client-error-timeout: This request was sent after the Printer
- closed the job, because it has not received a Send-Document or
- Send-URI operation within the Printer's "multiple-operation-
- time-out" period .
-
- client-error-request-entity-too-large: same as Print-Job.
-
- client-error-conflicting-attributes: same as Print-Job, except
- that "ipp-attributes-fidelity" operation attribute is not
- involved..
-
- server-error-operation-not-supported: the Send-Document
- request is not supported.
-
- server-error-not-accepting-jobs: not applicable.
-
- server-error-job-canceled: the job has been canceled by an
- operator or the system while the client was transmitting the
- data.
-
-3.1.3.2.2 Send-URI
-
- All of the Print-Job status code descriptions in Section 3.1.3.1.1
- Print-Job Response with the specialization's described for Send-
- Document are applicable to Send-URI. See Section 13 in [RFC2911] for
- a more complete description of each status code.
-
- client-error-uri-scheme-not-supported: the URI scheme supplied
- in the "document-uri" operation attribute is not supported and
- the "document-uri" attribute MUST be returned in the
- Unsupported Attributes group.
-
- server-error-operation-not-supported: the Send-URI operation is
- not supported.
-
-3.1.3.2.3 Cancel-Job
-
- All of the Print-Job status codes described in Section 3.1.3.1.1
- Print-Job Response are applicable to Cancel-Job with the following
- specializations and differences. See Section 13 in [RFC2911] for a
- more complete description of each status code.
-
- For the following success status codes, the Job object is being
- canceled or has been canceled:
-
-
-
-Hastings, et al. Informational [Page 65]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- successful-ok: no request attributes were substituted or
- ignored (same as Print-Job).
-
- successful-ok-ignored-or-substituted-attributes: same as
- Print-Job.
-
- successful-ok-conflicting-attributes: same as Print-Job.
-
- For any of the error status codes, the Job object has not been
- canceled or was previously canceled.
-
- client-error-not-possible: The request cannot be carried out
- because of the state of the Job object ('completed',
- 'canceled', or 'aborted') or the state of the system.
-
- client-error-not-found: the target Printer and/or Job object
- does not exist.
-
- client-error-gone: the target Printer and/or Job object no
- longer exists and no forwarding address is known.
-
- client-error-request-entity-too-large: same as Print-Job,
- except no document data is involved.
-
- client-error-document-format-not-supported: not applicable.
-
- client-error-attributes-or-values-not-supported: not
- applicable, since unsupported operation attributes and values
- MUST be ignored.
-
- client-error-conflicting-attributes: same as Print-Job, except
- that the Printer's "printer-is-accepting-jobs" attribute is not
- involved.
-
- server-error-operation-not-supported: not applicable (Cancel-
- Job is REQUIRED).
-
- server-error-device-error: same as Print-Job, except no
- document data is involved.
-
- server-error-temporary-error: same as Print-Job, except no
- document data is involved.
-
- server-error-not-accepting-jobs: not applicable.
-
- server-error-job-canceled: not applicable.
-
-
-
-
-
-Hastings, et al. Informational [Page 66]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-3.1.3.2.4 Get-Job-Attributes
-
- All of the Print-Job status codes described in Section 3.1.3.1.1
- Print-Job Response are applicable to Get-Job-Attributes with the
- following specializations and differences. See Section 13 in
- [RFC2911] for a more complete description of each status code.
-
- For the following success status codes, the requested attributes are
- returned in Group 3 in the response:
-
- successful-ok: same as Get-Printer-Attributes (see section
- 3.1.3.1.5).
-
- successful-ok-ignored-or-substituted-attributes: same as Get-
- Printer-Attributes (see section 3.1.3.1.5).
-
- successful-ok-conflicting-attributes: same as Get-Printer-
- Attributes (see section 3.1.3.1.5).
-
- For the error status codes, Group 3 is returned containing no
- attributes or is not returned at all.
-
- client-error-not-possible: Same as Print-Job, in addition the
- Printer object is not accepting any requests.
-
- client-error-document-format-not-supported: not applicable.
-
- client-error-attributes-or-values-not-supported: not
- applicable.
-
- client-error-uri-scheme-not-supported: not applicable.
-
- client-error-attributes-or-values-not-supported: not
- applicable, since unsupported operation attributes and/or
- values MUST be ignored and an appropriate success code returned
- (see above).
-
- client-error-conflicting-attributes: not applicable
-
- server-error-operation-not-supported: not applicable (since
- Get-Job-Attributes is REQUIRED).
-
- server-error-device-error: same as Print-Job, except no
- document data is involved.
-
- server-error-temporary-error: sane as Print-Job, except no
- document data is involved..
-
-
-
-
-Hastings, et al. Informational [Page 67]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- server-error-not-accepting-jobs: not applicable.
-
- server-error-job-canceled: not applicable.
-
-3.1.3.2.5 Hold-Job
-
- All of the Print-Job status codes described in Section 3.1.3.1.1
- Print-Job Response are applicable to Hold-Job with the following
- specializations and differences. See Section 13 in [RFC2911] for a
- more complete description of each status code.
-
- For the following success status codes, the Job object is being held
- or has been held:
-
- successful-ok: no request attributes were substituted or
- ignored (same as Print-Job).
-
- successful-ok-ignored-or-substituted-attributes: same as
- Print-Job.
-
- successful-ok-conflicting-attributes: same as Print-Job.
-
- For any of the error status codes, the Job object has not been held
- or was previously held.
-
- client-error-not-possible: The request cannot be carried out
- because of the state of the Job object ('completed',
- 'canceled', or 'aborted') or the state of the system.
-
- client-error-not-found: the target Printer and/or Job object
- does not exist.
-
- client-error-gone: the target Printer and/or Job object no
- longer exists and no forwarding address is known.
-
- client-error-request-entity-too-large: same as Print-Job,
- except no document data is involved.
-
- client-error-document-format-not-supported: not applicable.
-
- client-error-conflicting-attributes: same as Print-Job, except
- that the Printer's "printer-is-accepting-jobs" attribute is not
- involved.
-
- server-error-operation-not-supported: the Hold-Job operation is
- not supported.
-
- server-error-device-error: not applicable.
-
-
-
-Hastings, et al. Informational [Page 68]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- server-error-temporary-error: same as Print-Job, except no
- document data is involved.
-
- server-error-not-accepting-jobs: not applicable.
-
- server-error-job-canceled: not applicable.
-
-3.1.3.2.6 Release-Job
-
- All of the Print-Job status code descriptions in Section 3.1.3.1.1
- Print-Job Response with the specialization's described for Hold-Job
- are applicable to Release-Job. See Section 13 in [RFC2911] for a
- more complete description of each status code.
-
- server-error-operation-not-supported: the Release-Job operation
- is not supported.
-
-3.1.3.2.7 Restart-Job
-
- All of the Print-Job status code descriptions in Section 3.1.3.1.1
- Print-Job Response with the specialization's described for Hold-Job
- are applicable to Restart-Job. See Section 13 in [RFC2911] for a
- more complete description of each status code.
-
- server-error-operation-not-supported: the Restart-Job operation
- is not supported.
-
-3.1.3.2.7.1 Can documents be added to a restarted job?
-
- Assume I give a Create-Job request along with a set of 5 documents.
- All the documents get printed and the job state is moved to
- completed. I issue a Restart-Job request on the job. Now the issue
- is that, if I try to add new documents to the restarted job, will the
- IPP Server permit me to do so or return "client-error-not-possible "
- and again print those 5 jobs?
-
- A job can not move to the 'completed' state until all the documents
- have been processed. The 'last-document' flag indicates when the
- last document for a job is being sent from the client. This is the
- semantic equivalent of closing a job. No documents may be added once
- a job is closed. Section 3.3.7 of the IPP/1.1 model states "The job
- is moved to the 'pending' job state and restarts the beginning on the
- same IPP Printer object with the same attribute values." 'number-
- of-documents' is a job attribute.
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 69]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-3.1.4 Returning unsupported attributes in Get-Xxxx responses (Issue
- 1.18)
-
- In the Get-Printer-Attributes, Get-Jobs, or Get-Job-Attributes
- responses, the client cannot depend on getting unsupported attributes
- returned in the Unsupported Attributes group that the client
- requested, but are not supported by the IPP object. However, such
- unsupported requested attributes will not be returned in the Job
- Attributes or Printer Attributes group (since they are unsupported).
- Furthermore, the IPP object is REQUIRED to return the 'successful-
- ok-ignored-or-substituted-attributes' status code, so that the client
- knows that not all that was requested has been returned.
-
-3.1.5 Sending empty attribute groups
-
- The [RFC2911] and [RFC2910] specifications RECOMMEND that a sender
- not send an empty attribute group in a request or a response.
- However, they REQUIRE a receiver to accept an empty attribute group
- as equivalent to the omission of that group. So a client SHOULD omit
- the Job Template Attributes group entirely in a create operation that
- is not supplying any Job Template attributes. Similarly, an IPP
- object SHOULD omit an empty Unsupported Attributes group if there are
- no unsupported attributes to be returned in a response.
-
- The [RFC2910] specification REQUIRES a receiver to be able to receive
- either an empty attribute group or an omitted attribute group and
- treat them equivalently. The term "receiver" means an IPP object for
- a request and a client for a response. The term "sender' means a
- client for a request and an IPP object for a response.
-
- There is an exception to the rule for Get-Jobs when there are no
- attributes to be returned. [RFC2910] contains the following
- paragraph:
-
- The syntax allows an xxx-attributes-tag to be present when the xxx-
- attribute-sequence that follows is empty. The syntax is defined this
- way to allow for the response of Get-Jobs where no attributes are
- returned for some job-objects. Although it is RECOMMENDED that the
- sender not send an xxx-attributes-tag if there are no attributes
- (except in the Get-Jobs response just mentioned), the receiver MUST
- be able to decode such syntax.
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 70]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-3.2 Printer Operations
-
-3.2.1 Print-Job operation
-
-3.2.1.1 Flow controlling the data portion of a Print-Job request (Issue
- 1.22)
-
- A paused printer, or one that is stopped due to paper out or jam or
- spool space full or buffer space full, may flow control the data of a
- Print-Job operation (at the TCP/IP layer), so that the client is not
- able to send all the document data. Consequently, the Printer will
- not return a response until the condition is changed.
-
- The Printer should not return a Print-Job response with an error code
- in any of these conditions, since either the printer will be resumed
- and/or the condition will be freed either by human intervention or as
- jobs print.
-
- In writing test scripts to test IPP Printers, the script must also be
- written not to expect a response, if the printer has been paused,
- until the printer is resumed, in order to work with all possible
- implementations.
-
-3.2.1.2 Returning job-state in Print-Job response (Issue 1.30)
-
- An IPP client submits a small job via Print-Job. By the time the IPP
- printer/print server is putting together a response to the operation,
- the job has finished printing and been removed as an object from the
- print system. What should the job-state be in the response?
-
- The Model suggests that the Printer return a response before it even
- accepts the document content. The Job Object Attributes are returned
- only if the IPP object returns one of the success status codes. Then
- the job-state would always be "pending" or "pending-held".
-
- This issue comes up for the implementation of an IPP Printer object
- as a server that forwards jobs to devices that do not provide job
- status back to the server. If the server is reasonably certain that
- the job completed successfully, then it should return the job-state
- as 'completed'. Also the server can keep the job in its "job
- history" long after the job is no longer in the device. Then a user
- could query the server and see that the job was in the 'completed'
- state and completed as specified by the jobs "time-at-completed"
- time, which would be the same as the server submitted the job to the
- device.
-
-
-
-
-
-
-Hastings, et al. Informational [Page 71]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- An alternative is for the server to respond to the client before or
- while sending the job to the device, instead of waiting until the
- server has finished sending the job to the device. In this case, the
- server can return the job's state as 'pending' with the 'job-
- outgoing' value in the job's "job-state-reasons" attribute.
-
- If the server doesn't know for sure whether the job completed
- successfully (or at all), it could return the (out-of-band) 'unknown'
- value.
-
- On the other hand, if the server is able to query the device and/or
- setup some sort of event notification that the device initiates when
- the job makes state transitions, then the server can return the
- current job state in the Print-Job response and in subsequent queries
- because the server knows what the job state is in the device (or can
- query the device).
-
- All of these alternatives depend on implementation of the server and
- the device.
-
-3.2.2 Get-Printer-Attributes operation
-
- If a Printer supports the "printer-make-and-model" attribute and
- returns the .INF file model name of the printer in that attribute,
- the Microsoft client will automatically install the correct driver
- (if available).
-
- Clients which poll periodically for printer status or queued-job-
- count should use the "requested-attributes" operation attribute to
- limit the scope of the query in order to save Printer and network
- resources.
-
-3.2.3 Get-Jobs operation
-
-3.2.3.1 Get-Jobs, my-jobs='true', and 'requesting-user-name' (Issue
- 1.39)?
-
- In [RFC2911] section 3.2.6.1 'Get-Jobs Request', if the attribute
- 'my-jobs' is present and set to TRUE, MUST the 'requesting-user-name'
- attribute be there too, and if it's not present what should the IPP
- printer do?
-
- [RFC2911] Section 8.3 describes the various cases of "requesting-
- user-name" being present or not for any operation. If the client
- does not supply a value for "requesting-user-name", the printer MUST
- assume that the client is supplying some anonymous name, such as
- "anonymous".
-
-
-
-
-Hastings, et al. Informational [Page 72]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-3.2.3.2 Why is there a "limit" attribute in the Get-Jobs operation?
-
- When using the Get-Jobs operation a client implementer might choose
- to limit the number of jobs that the client shows on the first
- screenful. For example, if its UI can only display 50 jobs, it can
- defend itself against a printer that would otherwise return 500 jobs,
- perhaps taking a long time on a slow dial-up line. The client can
- then go and ask for a larger number of jobs in the background, while
- showing the user the first 50 jobs. Since the job history is returned
- in reverse order, namely the most recently completed jobs are
- returned first, the user is most likely interested in the first jobs
- that are returned. Limiting the number of jobs may be especially
- useful for a client that is requesting 'completed' jobs from a
- printer that keeps a long job history. Clients that don't mind
- sometimes getting very large responses, can omit the "limit"
- attribute in their Get-Jobs requests.
-
-3.2.4 Create-Job operation
-
- A Printer may respond to a Create-Job operation with "job-state"
- 'pending' or 'pending-held' and " job-state-reason" 'job-data-
- insufficient' to indicate that operation has been accepted by the
- Printer, but the Printer is expecting additional document data before
- it can move the job into the 'processing' state. Alternatively, it
- may respond with "job-state" 'processing' and "job-state-reason"
- 'job-incoming' to indicate that the Create-Job operation has been
- accepted by the Printer, but the Printer is expecting additional
- Send-Document and/or Send-URI operations and/or is
- accessing/accepting document data. The second alternative is for
- non-spooling Printers that don't implement the 'pending' state.
-
- Should the server wait for the "last-document" operation attribute
- set to 'true' before starting to "process" the job?
-
- It depends on implementation. Some servers spool the entire job,
- including all document data, before starting to process, so such an
- implementation would wait for the "last-document" before starting to
- process the job. If the time-out occurs without the "last-document",
- then the server takes one of the indicated actions in section 3.3.1
- in the [RFC2911] document. Other servers will start to process
- document data as soon as they have some. These are the so-called
- "non-spooling" printers. Currently, there isn't a way for a client to
- determine whether the Printer will spool all the data or will start
- to process (and print) as soon as it has some data.
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 73]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-3.3 Job Operations
-
-3.3.1 Validate-Job
-
- The Validate-Job operation has been designed so that its
- implementation may be a part of the Print-Job operation. Therefore,
- requiring Validate-Job is not a burden on implementers. Also it is
- useful for client's to be able to count on its presence in all
- conformance implementations, so that the client can determine before
- sending a long document, whether the job will be accepted by the IPP
- Printer or not.
-
-3.3.2 Restart-Job
-
- The Restart-Job operation allows the reprocessing of a completed job.
- Some jobs store the document data on the printer. Jobs created using
- the Print-Job operation are an example. It is required that the
- printer retains the job data after the job has moved to a 'completed
- state' in order for the Restart-Job operation to succeed.
-
- Some jobs contain only a reference to the job data. A job created
- using the Print-URI is an example of such a job. When the Restart-
- Job operation is issued the job is reprocessed. The job data MUST be
- retrieved again to print the job.
-
- It is possible that a job fails while attempting to access the print
- data. When such a job is the target of a Restart-Job the Printer
- SHALL attempt to retrieve the job data again.
-
-4 Object Attributes
-
-4.1 Attribute Syntax's
-
-4.1.1 The 'none' value for empty sets (Issue 1.37)
-
- [RFC2911] states that the 'none' value should be used as the value of
- a 1setOf when the set is empty. In most cases, sets that are
- potentially empty contain keywords so the keyword 'none' is used, but
- for the 3 finishings attributes, the values are enums and thus the
- empty set is represented by the enum 3. Currently there are no other
- attributes with 1setOf values, which can be empty and can contain
- values that are not keywords. This exception requires special code
- and is a potential place for bugs. It would have been better if we
- had chosen an out-of-band value, either "no-value" or some new value,
- such as 'none'. Since we didn't, implementations have to deal with
- the different representations of 'none', depending on the attribute
- syntax.
-
-
-
-
-Hastings, et al. Informational [Page 74]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-4.1.2 Multi-valued attributes (Issue 1.31)
-
- What is the attribute syntax for a multi-valued attribute? Since
- some attributes support values in more than one data type, such as
- "media", "job-hold-until", and "job-sheets", IPP semantics associate
- the attribute syntax with each value, not with the attribute as a
- whole. The protocol associates the attribute syntax tag with each
- value. Don't be fooled, just because the attribute syntax tag comes
- before the attribute keyword. All attribute values after the first
- have a zero length attribute keyword as the indication of a
- subsequent value of the same attribute.
-
-4.1.3 Case Sensitivity in URIs (issue 1.6)
-
- IPP client and server implementations must be aware of the diverse
- uppercase/lowercase nature of URIs. RFC 2396 defines URL schemes and
- Host names as case insensitive but reminds us that the rest of the
- URL may well demonstrate case sensitivity. When creating URL's for
- fields where the choice is completely arbitrary, it is probably best
- to select lower case. However, this cannot be guaranteed and
- implementations MUST NOT rely on any fields being case-sensitive or
- case-insensitive in the URL beyond the URL scheme and host name
- fields.
-
- The reason that the IPP specification does not make any restrictions
- on URIs, is so that implementations of IPP may use off-the-shelf
- components that conform to the standards that define URIs, such as
- RFC 2396 and the HTTP/1.1 specifications [RFC2616]. See these
- specifications for rules of matching, comparison, and case-
- sensitivity.
-
- It is also recommended that System Administrators and implementations
- avoid creating URLs for different printers that differ only in their
- case. For example, don't have Printer1 and printer1 as two different
- IPP Printers.
-
- Example of equivalent URI's
-
- http://abc.com:80/~smith/home.html
-
- http://ABC.com/%7Esmith/home.html
-
- http:/ABC.com:/%7esmith/home.html
-
- Example of equivalent URI's using the IPP scheme
-
- ipp://abc.com:631/~smith/home.html
-
-
-
-
-Hastings, et al. Informational [Page 75]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- ipp://ABC.com/%7Esmith/home.html
-
- http:/ABC.com:631/%7esmith/home.html
-
- The HTTP/1.1 specification [RFC2616] contains more details on
- comparing URLs.
-
-4.1.4 Maximum length for xxxWithLanguage and xxxWithoutLanguage
-
- The 'textWithLanguage' and 'nameWithLanguage' are compound syntaxes
- that have two components. The first component is the 'language'
- component that can contain up to 63 octets. The second component is
- the 'text' or 'name' component. The maximum length of these are 1023
- octets and 255 octets respectively. The definition of attributes
- with either syntax may further restrict the length (e.g., printer-
- name (name(127))).
-
- The length of the 'language' component has no effect on the allowable
- length of 'text' in 'textWithLanguage' or the length of 'name' in
- 'nameWithLanguage'
-
-4.2 Job Template Attributes
-
-4.2.1 multiple-document-handling(type2 keyword)
-
-4.2.1.1 Support of multiple document jobs
-
- IPP/1.0 is silent on which of the four effects an implementation
- would perform if it supports Create-Job, but does not support
- "multiple-document-handling" or multiple documents per job. IPP/1.1
- was changed so that a Printer could support Create-Job without having
- to support multiple document jobs. The "multiple-document-jobs-
- supported" (boolean) Printer description attribute was added to
- IPP/1.1 along with the 'server-error-multiple-document-jobs-not-
- supported' status code for a Printer to indicate whether or not it
- supports multiple document jobs, when it supports the Create-Job
- operation. Also IPP/1.1 was clarified that the Printer MUST support
- the "multiple-document-handling" (type2 keyword) Job Template
- attribute with at least one value if the Printer supports multiple
- documents per job.
-
-4.3 Job Description Attributes
-
-4.3.1 Getting the date and time of day
-
- The "date-time-at-creation", "date-time-at-processing", and "date-
- time-at-completed" attributes are returned as dateTime syntax. These
- attributes are OPTIONAL for a Printer to support. However, there are
-
-
-
-Hastings, et al. Informational [Page 76]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- various ways for a Printer to get the date and time of day. Some
- suggestions:
-
- 1. A Printer can get time from an NTP timeserver if there's one
- reachable on the network . See RFC 1305. Also DHCP option 32
- in RFC 2132 returns the IP address of the NTP server.
-
- 2. Get the date and time at startup from a human operator
-
- 3. Have an operator set the date and time using a web
- administrative interface
-
- 4. Get the date and time from incoming HTTP requests, though the
- problems of spoofing need to be considered. Perhaps comparing
- several HTTP requests could reduce the chances of spoofing.
-
- 5. Internal date time clock battery driven.
-
- 6. Query "http://tycho.usno.navy.mil/cgi-bin/timer.pl"
-
-4.4 Printer Description Attributes
-
-4.4.1 queued-job-count (integer(0:MAX))
-
-4.4.1.1 Why is "queued-job-count" RECOMMENDED (Issue 1.14)?
-
- The reason that "queued-job-count" is RECOMMENDED, is that some
- clients look at that attribute alone when summarizing the status of a
- list of printers, instead of doing a Get-Jobs to determine the number
- of jobs in the queue. Implementations that fail to support the
- "queued-job-count" will cause that client to display 0 jobs when
- there are actually queued jobs.
-
- We would have made it a REQUIRED Printer attribute, but some
- implementations had already been completed before the issue was
- raised, so making it a SHOULD was a compromise.
-
-4.4.1.2 Is "queued-job-count" a good measure of how busy a printer is
- (Issue 1.15)?
-
- The "queued-job-count" is not a good measure of how busy the printer
- is when there are held jobs. A future registration could be to add a
- "held-job-count" (or an "active-job-count") Printer Description
- attribute if experience shows that such an attribute (combination) is
- needed to quickly indicate how busy a printer really is.
-
-
-
-
-
-
-Hastings, et al. Informational [Page 77]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-4.4.2 printer-current-time (dateTime)
-
- A Printer implementation MAY support this attribute by obtaining the
- date and time by any number of implementation-dependent means at
- startup or subsequently. Examples include:
-
- 1. an internal date time clock,
-
- 2. from the operator at startup using the console,
-
- 3. from an operator using an administrative web page,
-
- 4. from HTTP headers supplied in client requests,
-
- 5. use HTTP to query "http://tycho.usno.navy.mil/cgi-bin/timer.pl"
-
- 6. from the network, using NTP [RFC1305] or DHCP option 32
- [RFC2132] that returns the IP address of the NTP server.
-
- If an implementation supports this attribute by obtaining the current
- time from the network (at startup or later), but the time is not
- available, then the implementation MUST return the value of this
- attribute using the out-of-band 'no-value' meaning not configured.
- See the beginning of section 4.1.
-
- Since the new "date-and-time-at-xxx" Job Description attributes refer
- to the "printer-current-time", they will be covered also.
-
-4.4.3 Printer-uri
-
- Must the operational attribute for printer-uri match one of the
- values in "printer-uri-supported"?
-
- A forgiving printer implementation would not reject the operation.
- But the implementation has its rights to reject a printer or job
- operation if the operational attribute printer-uri is not a value of
- the printer-uri-supported. The printer might not be improperly
- configured. The request obviously reached the printer. The printer
- could treat the printer-uri as the logical equivalent of a value in
- the printer-uri-supported. It would be implementation dependent for
- which value, and associated security policy, would apply. This does
- also apply to a job object specified with a printer-uri and job-id,
- or with a job-uri. See section 4.1.3 for how to compare URI's.
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 78]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-4.5 Empty Jobs
-
- The IPP object model does not prohibit a job that contains no
- documents. Such a job may be created in a number of ways including a
- 'create-job' followed by an 'add-document' that contains no data and
- has the 'last-document' flag set.
-
- An empty job is processed just as any other job. The operation that
- "closes" an empty job is not rejected because the job is empty. If
- no other conditions exist, other than the job is empty, the response
- to the operation will indicate success. After the job is scheduled
- and processed, the job state SHALL be 'completed'.
-
- There will be some variation in the value(s) of the "job-state-
- reasons" attribute. It is required that if no conditions, other than
- the job being empty, exist the "job-state-reasons" SHALL include the
-
- 'completed-successfully'. If other conditions existed, the
- 'completed-with-warnings' or 'completed-with-errors' values may be
- used.
-
-5 Directory Considerations
-
-5.1 General Directory Schema Considerations
-
- The [RFC2911] document lists RECOMMENDED and OPTIONAL Printer object
- attributes for directory schemas. See [RFC2911] APPENDIX E: Generic
- Directory Schema.
-
- The SLP printer template is defined in the "Definition of the Printer
- Abstract Service Type v2.0" document [svrloc-printer]. The LDAP
- printer template is defined in the "Internet Printing Protocol (IPP):
- LDAP Schema for Printer Services" document [ldap-printer]. Both
- documents systematically add "printer-" to any attribute that doesn't
- already start with "printer-" in order to keep the printer directory
- attributes distinct from other directory attributes. Also, instead
- of using "printer-uri-supported", "uri-authentication-supported", and
- "uri-security-supported", they use a "printer-xri-supported"
- attribute with special syntax to contain all of the same information
- in a single attribute.
-
-5.2 IPP Printer with a DNS name
-
- If the IPP printer has a DNS name should there be at least two values
- for the printer-uri-supported attribute. One URL with the fully
- qualified DNS name the other with the IP address in the URL?
-
-
-
-
-
-Hastings, et al. Informational [Page 79]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- The printer may contain one or the other or both. It's up to the
- administrator to configure this attribute.
-
-6 Security Considerations
-
- The security considerations given in [RFC2911] Section 8 "Security
- Considerations" all apply to this document. In addition, the
- following sub-sections describes security consideration that have
- arisen as a result of implementation testing.
-
-6.1 Querying jobs with IPP that were submitted using other job
- submission protocols (Issue 1.32)
-
- The following clarification was added to [RFC2911] section 8.5:
-
- 8.5 Queries on jobs submitted using non-IPP protocols If the
- device that an IPP Printer is representing is able to accept jobs
- using other job submission protocols in addition to IPP, it is
- RECOMMEND that such an implementation at least allow such
- "foreign" jobs to be queried using Get-Jobs returning "job-id" and
- "job-uri" as 'unknown'. Such an implementation NEED NOT support
- all of the same IPP job attributes as for IPP jobs. The IPP
- object returns the 'unknown' out-of-band value for any requested
- attribute of a foreign job that is supported for IPP jobs, but not
- for foreign jobs.
-
- It is further RECOMMENDED, that the IPP Printer generate "job-id"
- and "job-uri" values for such "foreign jobs", if possible, so that
- they may be targets of other IPP operations, such as Get-Job-
- Attributes and Cancel-Job. Such an implementation also needs to
- deal with the problem of authentication of such foreign jobs. One
- approach would be to treat all such foreign jobs as belonging to
- users other than the user of the IPP client. Another approach
- would be for the foreign job to belong to 'anonymous'. Only if
- the IPP client has been authenticated as an operator or
- administrator of the IPP Printer object, could the foreign jobs be
- queried by an IPP request. Alternatively, if the security policy
- were to allow users to query other users' jobs, then the foreign
- jobs would also be visible to an end-user IPP client using Get-
- Jobs and Get-Job- Attributes.
-
- Thus IPP MAY be implemented as a "universal" protocol that
- provides access to jobs submitted with any job submission
- protocol. As IPP becomes widely implemented, providing a more
- universal access makes sense.
-
-
-
-
-
-
-Hastings, et al. Informational [Page 80]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-7 Encoding and Transport
-
- This section discusses various aspects of IPP/1.1 Encoding and
- Transport [RFC2910].
-
- A server is not required to send a response until after it has
- received the client's entire request. Hence, a client must not
- expect a response until after it has sent the entire request.
- However, we recommend that the server return a response as soon as
- possible if an error is detected while the client is still sending
- the data, rather than waiting until all of the data is received.
- Therefore, we also recommend that a client listen for an error
- response that an IPP server MAY send before it receives all the data.
- In this case a client, if chunking the data, can send a premature
- zero-length chunk to end the request before sending all the data (and
- so the client can keep the connection open for other requests, rather
- than closing it). If the request is blocked for some reason, a
- client MAY determine the reason by opening another connection to
- query the server using Get-Printer-Attributes.
-
- IPP, by design, uses TCP's built-in flow control mechanisms [RFC 793]
- to throttle clients when Printers are busy. Therefore, it is
- perfectly normal for an IPP client transmitting a Job to be blocked
- for a really long time. Accordingly, socket timeouts must be
- avoided. Some socket implementations have a timeout option, which
- specifies how long a write operation on a socket can be blocked
- before it times out and the blocking ends. A client should set this
- option for infinite timeout when transmitting Job submissions.
-
- Some IPP client applications might be able to perform other useful
- work while a Job transmission is blocked. For example, the client
- may have other jobs that it could transmit to other Printers
- simultaneously. A client may have a GUI, which must remain
- responsive to the user while the Job transmission is blocked. These
- clients should be designed to spawn a thread to handle the Job
- transmission at its own pace, leaving the main application free to do
- other work. Alternatively, single-threaded applications could use
- non-blocking I/O.
-
- Some Printer conditions, such as jam or lack of paper, could cause a
- client to be blocked indefinitely. Clients may open additional
- connections to the Printer to Get-Printer-Attributes, determine the
- state of the device, alert a user if the printer is stopped, and let
- a user decide whether to abort the job transmission or not.
-
- In the following sections, there are tables of all HTTP headers,
- which describe their use in an IPP client or server. The following
- is an explanation of each column in these tables.
-
-
-
-Hastings, et al. Informational [Page 81]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- - the "header" column contains the name of a header
- - the "request/client" column indicates whether a client sends the
- header.
- - the "request/ server" column indicates whether a server supports
- the header when received.
- - the "response/ server" column indicates whether a server sends
- the header.
- - the "response /client" column indicates whether a client
- supports the header when received.
- - the "values and conditions" column specifies the allowed header
- values and the conditions for the header to be present in a
- request/response.
-
- The table for "request headers" does not have columns for responses,
- and the table for "response headers" does not have columns for
- requests.
-
- The following is an explanation of the values in the "request/client"
- and "response/ server" columns.
-
- - must: the client or server MUST send the header,
- - must-if: the client or server MUST send the header when the
- condition described in the "values and conditions" column is
- met,
- - may: the client or server MAY send the header
- - not: the client or server SHOULD NOT send the header. It is not
- relevant to an IPP implementation.
-
- The following is an explanation of the values in the
- "response/client" and "request/ server" columns.
-
- - must: the client or server MUST support the header,
- - may: the client or server MAY support the header
- - not: the client or server SHOULD NOT support the header. It is
- not relevant to an IPP implementation.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 82]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-7.1 General Headers
-
- The following is a table for the general headers.
-
- General- Request Response Values and Conditions
- Header
-
- Client Server Server Client
-
-
- Cache- not must not "no-cache" only
- Control must
-
- Connection must- must must- must "close" only. Both
- if if client and server
- SHOULD keep a
- connection for the
- duration of a sequence
- of operations. The
- client and server MUST
- include this header
- for the last operation
- in such a sequence.
-
- Date may may must may per RFC 1123 [RFC1123]
- from RFC 2616
- [RFC2616]
-
- Pragma must not must not "no-cache" only
-
- Transfer- must- must must- must "chunked" only. Header
- Encoding if if MUST be present if
- Content-Length is
- absent.
-
- Upgrade not not not not
-
- Via not not not not
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 83]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-7.2 Request Headers
-
- The following is a table for the request headers.
-
- Request- Client Server Request Values and Conditions
- Header
-
- Accept may must "application/ipp" only. This
- value is the default if the
- client omits it
-
- Accept- not not Charset information is within the
- Charset application/ipp entity
-
- Accept- may must empty and per RFC 2616 [RFC2616]
- Encoding and IANA registry for content-
- codings
-
- Accept- not not language information is within the
- Language application/ipp entity
-
- Authorization must- must per RFC 2616. A client MUST send
- if this header when it receives a
- 401 "Unauthorized" response and
- does not receive a "Proxy-
- Authenticate" header.
-
- From not not per RFC 2616. Because RFC
- recommends sending this header
- only with the user's approval,
- it is not very useful
-
- Host must must per RFC 2616
-
- If-Match not not
-
- If-Modified- not not
- Since
-
- If-None-Match not not
-
- If-Range not not
-
- If- not not
- Unmodified-
- Since
-
-
-
-
-
-Hastings, et al. Informational [Page 84]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Request- Client Server Request Values and Conditions
- Header
-
- Max-Forwards not not
-
- Proxy- must- not per RFC 2616. A client MUST send
- Authorizati if this header when it receives a
- on 401 "Unauthorized" response and
- a "Proxy-Authenticate" header.
-
- Range not not
-
- Referrer not not
-
- User-Agent not not
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 85]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-7.3 Response Headers
-
- The following is a table for the request headers.
-
- Response- Server Client Response Values and Conditions
- Header
-
-
- Accept-Ranges not not
-
- Age not not
-
- Location must- may per RFC 2616. When URI needs
- if redirection.
-
- Proxy- must per RFC 2616
- Authenticat
- e not
-
- Public may may per RFC 2616
-
- Retry-After may may per RFC 2616
-
- Server not not
-
- Vary not not
-
- Warning may may per RFC 2616
-
- WWW- must- must per RFC 2616. When a server needs
- Authenticate if to authenticate a client.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 86]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-7.4 Entity Headers
-
- The following is a table for the entity headers.
-
- Entity-Header Request Response Values and
- Conditions
-
- Client Server Server Client
-
- Allow not not not not
-
- Content-Base not not not not
-
- Content- may must must must per RFC 2616 and
- Encoding IANA registry for
- content codings.
-
- Content- not not not not Application/ipp
- Language handles language
-
- Content- must- must must- must the length of the
- Length if if message-body per
- RFC 2616. Header
- MUST be present
- if Transfer-
- Encoding is
- absent..
-
- Content- not not not not
- Location
-
- Content-MD5 may may may may per RFC 2616
-
- Content-Range not not not not
-
- Content-Type must must must must "application/ipp"
- only
-
- ETag not not not not
-
- Expires not not not not
-
- Last-Modified not not not not
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 87]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-7.5 Optional support for HTTP/1.0
-
- IPP implementations consist of an HTTP layer and an IPP layer. In
- the following discussion, the term "client" refers to the HTTP client
- layer and the term "server" refers to the HTTP server layer. The
- Encoding and Transport document [RFC2910] requires that HTTP 1.1 MUST
- be supported by all clients and all servers. However, a client
- and/or a server implementation may choose to also support HTTP 1.0.
-
- This option means that a server may choose to communicate with a
- (non-conforming) client that only supports HTTP 1.0. In such cases
- the server should not use any HTTP 1.1 specific parameters or
- features and should respond using HTTP version number 1.0.
-
- This option also means that a client may choose to communicate with a
- (non-conforming) server that only supports HTTP 1.0. In such cases,
- if the server responds with an HTTP 'unsupported version number' to
- an HTTP 1.1 request, the client should retry using HTTP version
- number 1.0.
-
-7.6 HTTP/1.1 Chunking
-
-7.6.1 Disabling IPP Server Response Chunking
-
- Clients MUST anticipate that the HTTP/1.1 server may chunk responses
- and MUST accept them in responses. However, a (non-conforming) HTTP
- client that is unable to accept chunked responses may attempt to
- request an HTTP 1.1 server not to use chunking in its response to an
- operation by using the following HTTP header:
-
- TE: identity
-
- This mechanism should not be used by a server to disable a client
- from chunking a request, since chunking of document data is an
- important feature for clients to send long documents.
-
-7.6.2 Warning About the Support of Chunked Requests
-
- This section describes some problems with the use of chunked requests
- and HTTP/1.1 servers.
-
- The HTTP/1.1 standard [RFC2616] requires that conforming servers
- support chunked requests for any method. However, in spite of this
- requirement, some HTTP/1.1 implementations support chunked responses
- in the GET method, but do not support chunked POST method requests.
- Some HTTP/1.1 implementations that support CGI scripts [CGI] and/or
- servlets [Servlet] require that the client supply a Content-Length.
- These implementations might reject a chunked POST method and return a
-
-
-
-Hastings, et al. Informational [Page 88]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- 411 status code (Length Required), might attempt to buffer the
- request and run out of room returning a 413 status code (Request
- Entity Too Large), or might successfully accept the chunked request.
-
- Because of this lack of conformance of HTTP servers to the HTTP/1.1
- standard, the IPP standard [RFC2910] REQUIRES that a conforming IPP
- Printer object implementation support chunked requests and that
- conforming clients accept chunked responses. Therefore, IPP object
- implementers are warned to seek HTTP server implementations that
- support chunked POST requests in order to conform to the IPP standard
- and/or use implementation techniques that support chunked POST
- requests.
-
-8 References
-
- [CGI] CGI/1.1 (http://www.w3.org/CGI/).
-
- [IANA-CS] IANA Registry of Coded Character Sets:
- http://www.iana.org/assignments/character-sets
-
- [ldap-printer] Fleming, P., Jones, K., Lewis, H. and I. McDonald,
- "Internet Printing Protocol (IPP): LDAP Schema for
- Printer Services", Work in Progress.
-
- [RFC793] Postel, J., "Transmission Control Protocol", STD 7,
- RFC 793, September 1981.
-
- [RFC1123] Braden, R., "Requirements for Internet Hosts -
- Application and Support", RFC 1123, October, 1989.
-
- [RFC2026] Bradner, S., "The Internet Standards Process --
- Revision 3", BCP 9, RFC 2026, October 1996.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119 , March 1997.
-
- [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter,
- "Uniform Resource Identifiers (URI): Generic
- Syntax", RFC 2396, August 1998.
-
- [RFC2565] DeBry, R., Hastings, T., Herriot, R., Isaacson, S.
- and P. Powell, "Internet Printing Protocol/1.0:
- Model and Semantics", RFC 2566, April 1999.
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 89]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- [RFC2566] Herriot, R., Butler, S., Moore, P. and R. Turner,
- "Internet Printing Protocol/1.0: Encoding and
- Transport", RFC 2565, April 1999.
-
- [RFC2567] Wright, D., "Design Goals for an Internet Printing
- Protocol", RFC 2567, April 1999.
-
- [RFC2568] Zilles, S., "Rationale for the Structure and Model
- and Protocol for the Internet Printing Protocol",
- RFC 2568, April 1999.
-
- [RFC2569] Herriot, R., Hastings, T., Jacobs, N. and J.
- Martin, "Mapping between LPD and IPP Protocols",
- RFC 2569, April 1999.
-
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
- Masinter, L., Leach, P. and T. Berners-Lee,
- "Hypertext Transfer Protocol - HTTP/1.1", RFC 2616,
- June 1999.
-
- [RFC2910] Herriot, R., Butler, S., Moore, P. and R. Turner,
- "Internet Printing Protocol/1.0: Encoding and
- Transport", RFC 2910, September, 2000.
-
- [RFC2911] DeBry, R., Hastings, T., Herriot, R., Isaacson, S.
- and P. Powell, "Internet Printing Protocol/1.0:
- Model and Semantics", RFC 2911, September, 2000.
-
- [Servlet] Servlet Specification Version 2.1
- (http://java.sun.com/products/servlet/2.1/
- index.html).
-
- [svrloc-printer] St. Pierre, P., Isaacson, S., McDonald, I.,
- "Definition of the Printer Abstract Service Type
- v2.0", http://www.isi.edu/in-
- notes/iana/assignments/svrloc-
- templates/printer.2.0.en (IANA Registered, May 27,
- 2000).
-
- [SSL] Netscape, The SSL Protocol, Version 3, (Text
- version 3.02), November 1996.
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 90]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-9. Authors' Addresses
-
- Thomas N. Hastings
- Xerox Corporation
- 701 Aviation Blvd.
- El Segundo, CA 90245
-
- EMail: hastings@cp10.es.xerox.com
-
-
- Carl-Uno Manros
- Independent Consultant
- 1601 N. Sepulveda Blvd. #505
- Manhattan Beach, CA 90266
-
- Email: carl@manros.com
-
-
- Carl Kugler
- Mail Stop 003G
- IBM Printing Systems Co
- 6300 Diagonal Hwy
- Boulder CO 80301
-
- EMail: Kugler@us.ibm.com
-
-
- Henrik Holst
- i-data Printing Systems
- Vadstrupvej 35-43
- 2880 Bagsvaerd, Denmark
-
- EMail: hh@I-data.com
-
-
- Peter Zehler
- Xerox Corporation
- 800 Philips Road
- Webster, NY 14580
-
- EMail: PZehler@crt.xerox.com
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 91]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- IPP Web Page: http://www.pwg.org/ipp/
- IPP Mailing List: ipp@pwg.org
-
- To subscribe to the ipp mailing list, send the following email:
-
- 1) send it to majordomo@pwg.org
- 2) leave the subject line blank
- 3) put the following two lines in the message body:
- subscribe ipp
- end
-
- Implementers of this specification document are encouraged to join
- the IPP Mailing List in order to participate in any discussions of
- clarification issues and review of registration proposals for
- additional attributes and values. In order to reduce spam the
- mailing list rejects mail from non-subscribers, so you must subscribe
- to the mailing list in order to send a question or comment to the
- mailing list.
-
- Other Participants:
-
- Chuck Adams - Tektronix Shivaun Albright - HP
-
- Stefan Andersson - Axis Jeff Barnett - IBM
-
- Ron Bergman - Hitachi Koki Dennis Carney - IBM
- Imaging Systems
-
- Keith Carter - IBM Angelo Caruso - Xerox
-
- Rajesh Chawla - TR Computing Nancy Chen - Okidata
- Solutions
-
- Josh Cohen - Microsoft Jeff Copeland - QMS
-
- Andy Davidson - Tektronix Roger deBry - IBM
-
- Maulik Desai - Auco Mabry Dozier - QMS
-
- Lee Farrell - Canon Information Satoshi Fujitami - Ricoh
- Systems
-
- Steve Gebert - IBM Sue Gleeson - Digital
-
- Charles Gordon - Osicom Brian Grimshaw - Apple
-
- Jerry Hadsell - IBM Richard Hart - Digital
-
-
-
-
-Hastings, et al. Informational [Page 92]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Tom Hastings - Xerox Henrik Holst - I-data
-
- Stephen Holmstead Zhi-Hong Huang - Zenographics
-
- Scott Isaacson - Novell Babek Jahromi - Microsoft
-
- Swen Johnson - Xerox David Kellerman - Northlake
- Software
-
- Robert Kline - TrueSpectra Charles Kong - Panasonic
-
- Carl Kugler - IBM Dave Kuntz - Hewlett-Packard
-
- Takami Kurono - Brother Rick Landau - Digital
-
- Scott Lawrence - Agranot Systems Greg LeClair - Epson
-
- Dwight Lewis - Lexmark Harry Lewis - IBM
-
- Tony Liao - Vivid Image Roy Lomicka - Digital
-
- Pete Loya - HP Ray Lutz - Cognisys
-
- Mike MacKay - Novell, Inc. David Manchala - Xerox
-
- Carl-Uno Manros - Xerox Jay Martin - Underscore
-
- Stan McConnell - Xerox Larry Masinter - Xerox
-
- Sandra Matts - Hewlett Packard Peter Michalek - Shinesoft
-
- Ira McDonald - High North Inc. Mike Moldovan - G3 Nova
-
- Tetsuya Morita - Ricoh Yuichi Niwa - Ricoh
-
- Pat Nogay - IBM Ron Norton - Printronics
-
- Hugo Parra, Novell Bob Pentecost - Hewlett-Packard
-
- Patrick Powell - Astart Jeff Rackowitz - Intermec
- Technologies
-
- Eric Random - Peerless Rob Rhoads - Intel
-
- Xavier Riley - Xerox Gary Roberts - Ricoh
-
- David Roach - Unisys Stuart Rowley - Kyocera
-
-
-
-
-Hastings, et al. Informational [Page 93]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- Yuji Sasaki - Japan Computer Richard Schneider - Epson
- Industry
-
- Kris Schoff - HP Katsuaki Sekiguchi - Canon
-
- Bob Setterbo - Adobe Gail Songer - Peerless
-
- Hideki Tanaka - Canon Devon Taylor - Novell, Inc.
-
- Mike Timperman - Lexmark Atsushi Uchino - Epson
-
- Shigeru Ueda - Canon Bob Von Andel - Allegro Software
-
- William Wagner - NetSilicon/DPI Jim Walker - DAZEL
-
- Chris Wellens - Interworking Labs Trevor Wells - Hewlett Packard
-
- Craig Whittle - Sharp Labs Rob Whittle - Novell, Inc.
-
- Jasper Wong - Xionics Don Wright - Lexmark
-
- Michael Wu - Heidelberg Digital Rick Yardumian - Xerox
-
- Michael Yeung - Toshiba Lloyd Young - Lexmark
-
- Atsushi Yuki - Kyocera Peter Zehler - Xerox
-
- William Zhang- Canon Information Frank Zhao - Panasonic
- Systems
-
- Steve Zilles - Adobe Rob Zirnstein - Canon
- Information Systems
-
-10. Description of the Base IPP Documents
-
- In addition to this document, the base set of IPP documents includes:
-
- Design Goals for an Internet Printing Protocol [RFC2567]
- Rationale for the Structure and Model and Protocol for the
- Internet
- Printing Protocol [RFC2568]
- Internet Printing Protocol/1.1: Model and Semantics [RFC2911]
- Internet Printing Protocol/1.1: Encoding and Transport [RFC2910]
- Mapping between LPD and IPP Protocols [RFC2569]
-
- The "Design Goals for an Internet Printing Protocol" document takes a
- broad look at distributed printing functionality, and it enumerates
- real-life scenarios that help to clarify the features that need to be
-
-
-
-Hastings, et al. Informational [Page 94]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
- included in a printing protocol for the Internet. It identifies
- requirements for three types of users: end users, operators, and
- administrators. It calls out a subset of end user requirements that
- are satisfied in IPP/1.0 [RFC2566, RFC2565]. A few OPTIONAL operator
- operations have been added to IPP/1.1 [RFC2911, RFC2910].
-
- The "Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol" document describes IPP from a high level
- view, defines a roadmap for the various documents that form the suite
- of IPP specification documents, and gives background and rationale
- for the IETF IPP working group's major decisions.
-
- The "Internet Printing Protocol/1.1: Model and Semantics" document
- describes a simplified model with abstract objects, their attributes,
- and their operations. The model introduces a Printer and a Job. The
- Job supports multiple documents per Job. The model document also
- addresses how security, internationalization, and directory issues
- are addressed.
-
- The "Internet Printing Protocol/1.1: Encoding and Transport" document
- is a formal mapping of the abstract operations and attributes defined
- in the model document onto HTTP/1.1 [RFC2616]. It also defines the
- encoding rules for a new Internet MIME media type called
- "application/ipp". This document also defines the rules for
- transporting a message body over HTTP whose Content-Type is
- "application/ipp". This document defines the 'ipp' scheme for
- identifying IPP printers and jobs.
-
- The "Mapping between LPD and IPP Protocols" document gives some
- advice to implementers of gateways between IPP and LPD (Line Printer
- Daemon) implementations.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 95]
-\f
-RFC 3196 Internet Printing Protocol/1.1 November 2001
-
-
-11 Full Copyright Statement
-
- Copyright (C) The Internet Society (2001). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 96]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group C. Kugler
-Request for Comments: 3239 H. Lewis
-Category: Informational IBM Corporation
- T. Hastings
- Xerox Corporation
- February 2002
-
-
- Internet Printing Protocol (IPP):
- Requirements for Job, Printer, and Device Administrative Operations
-
-
-Status of this Memo
-
- This memo provides information for the Internet community. It does
- not specify an Internet standard of any kind. Distribution of this
- memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
-Abstract
-
- This document specifies the requirements and uses cases for some
- optional administrative operations for use with the Internet Printing
- Protocol (IPP) version 1.0 and version 1.1. Some of these
- administrative operations operate on the IPP Job and Printer objects.
- The remaining operations operate on a new Device object that more
- closely models a single output device.
-
-Table of Contents
-
- 1 Introduction.....................................................2
- 2 Terminology......................................................2
- 3 Requirements and Use Cases.......................................3
- 4 IANA Considerations.............................................10
- 5 Internationalization Considerations.............................10
- 6 Security Considerations.........................................10
- 7 References......................................................11
- Appendix A: Description of base IPP documents......................12
- Authors' Addresses.................................................14
- Full Copyright Statement...........................................15
-
-List of Tables
-
- Table 1 - List of Printer Operations and corresponding Device
- Operations ..................................................... 9
-
-
-
-Kugler, Lewis & Hastings Informational [Page 1]
-\f
-RFC 3239 IPP: Req. for Job and Printer Admin Ops February 2002
-
-
-1 Introduction
-
- The Internet Printing Protocol (IPP) is an application level protocol
- that can be used for distributed printing using Internet tools and
- technologies. IPP version 1.1 ([RFC2911, RFC2910]) focuses on end
- user functionality with a few administrative operations included (for
- a description of the base IPP documents, see Appendix A). This
- document defines the requirements and use cases for additional
- optional end user, operator, and administrator operations used to
- control Job objects, Printer objects (see [RFC2911]) and a new Device
- object. The new Device object more closely models a single output
- device and has no notion of a job, while the Printer object models a
- print service which understands jobs and may represent one or more
- output devices.
-
- The scope of IPP is characterized in RFC 2567 [RFC2567] "Design Goals
- for an Internet Printing Protocol". It is not the intent of this
- document to revise or clarify this scope or conjecture as to the
- degree of industry adoption or trends related to IPP within printing
- systems. It is the intent of this document to extend the original
- set of operations - in a similar fashion to the Set1 extensions which
- referred to IPP/1.0 and were later incorporated into IPP/1.1.
-
-2 Terminology
-
- This section defines terminology used throughout this document and
- the corresponding documents that define the Administrative operations
- on Job, Printer, and Device objects.
-
- This document uses terms such as "client", "Printer", "Job",
- "attributes", "keywords", and "support". These terms have special
- meaning and are defined in the model terminology [RFC2911] section
- 12.2.
-
- In addition, the following capitalized terms are defined:
-
- IPP Printer object (or Printer for short) - a software abstraction
- defined by [RFC2911].
-
- Printer Operation - an operation whose target is an IPP Printer
- object and whose effect is on the Printer object.
-
- Output Device - the physical imaging mechanism that an IPP Printer
- controls. Note: while this term is capitalized in this
- specification (but not in [RFC2911]), there is no formal object
- called an Output Device.
-
-
-
-
-
-Kugler, Lewis & Hastings Informational [Page 2]
-\f
-RFC 3239 IPP: Req. for Job and Printer Admin Ops February 2002
-
-
- Device Operation - an operation whose target is an IPP Printer
- object and whose defined effect is on an Output Device.
-
- Output Device Fan-Out - a configuration in which an IPP Printer
- controls more that one output-device.
-
- Printer fan-out - a configuration in which an IPP Printer object
- controls more than one Subordinate IPP Printer object.
-
- Printer fan-in - a configuration in which an IPP Printer object is
- controlled by more than one IPP Printer object.
-
- Subordinate Printer - an IPP Printer object that is controlled by
- another IPP Printer object. Such a Subordinate Printer may
- have one or more Subordinate Printers.
-
- Leaf Printer - a Subordinate Printer that has no Subordinate
- Printers.
-
- Non-Leaf Printer - an IPP Printer object that has one or more
- Subordinate Printers.
-
- Chained Printer - a Non-Leaf Printer that has exactly one
- Subordinate Printer.
-
- Job Creation operations - IPP operations that create a Job object:
- Print-Job, Print-URI, and Create-Job.
-
-3 Requirements and Use Cases
-
- The Administrative operations for Job and Printer objects will be
- defined in one document [ipp-ops-set2]. The Administrative
- operations for Device objects will be defined in a separate document.
- The requirements are presented here together to show the parallelism.
-
- 1. Have separate operations for affecting the IPP Printer
- versus affecting the Output Device, so its clear what the
- intent of each is, and implementers can implement one or the
- other or both.
-
- 2. Support fan-out of Printer objects.
-
- 3. Support fan-out of Output Devices.
-
- 4. Support fan-in of Printer objects, as long as it doesn't
- make the semantics more complicated when not supporting
- fan-in.
-
-
-
-
-Kugler, Lewis & Hastings Informational [Page 3]
-\f
-RFC 3239 IPP: Req. for Job and Printer Admin Ops February 2002
-
-
- 5. Support fan-in of output objects, as long as it doesn't make
- the semantics more complicated when not supporting fan-in.
-
- 6. Instead of having operation attributes that alter the
- behavior of the operation significantly, have separate
- operations, so that it is simple and clear to a client which
- semantics the Printer is supporting (by querying the
- "operations-supported" attribute) and it is simple to
- describe the capabilities of a Printer implementation in
- written documentation (just list the optional operations
- supported).
-
- 7. Need a Printer Operation to prevent a Printer object from
- accepting new IPP jobs, but currently accepted jobs continue
- unaffected to be scheduled and processed. Need a companion
- one to restore the Printer object to accept new IPP jobs.
-
- Usage: Operator is preparing to take the IPP Printer out of
- service or to change the configuration of the IPP Printer.
-
- Suggested name and operations: Disable-Printer and Enable-
- Printer
-
- 8. Need a Device Operation to prevent an Output Device from
- accepting any new jobs from any job submission protocol and
- a companion one to restore the Output Device to accepting
- any jobs.
-
- Usage: Operator is preparing to take the Output Device out
- of service.
-
- Suggested name and operations: Disable-Device and Enable
- Device
-
- 9. Need a Printer Operation to stop the processing after the
- current IPP job completes and not start processing any
- additional IPP jobs (either by scheduling the jobs or
- sending them to the Output Device), but continue to accept
- new IPP jobs. Need a companion operation to start
- processing/sending IPP jobs again.
-
- Usage: Operator wants to gracefully stop the IPP Printer at
- the next job boundary. The Pause-Printer-After-Current-Job
- operation is also invoked implicitly by the Deactivate-
- Printer and the Shutdown-Printer Operations.
-
- Suggested name and operations: Pause-Printer-After-
- Current-Job, (IPP/1.1) Resume-Printer
-
-
-
-Kugler, Lewis & Hastings Informational [Page 4]
-\f
-RFC 3239 IPP: Req. for Job and Printer Admin Ops February 2002
-
-
- 10. Need a Device Operation to stop the processing the current
- job "immediately", no matter what protocol. Its like the
- Pause button on the Output Device. This operation is for
- emergencies. The stop point depends on implementation, but
- can be mid page, end of page, end of sheet, or after a few
- sheets for Output Devices that can't stop that quickly. The
- paper path isn't run out. Need a companion operation to
- start processing the current any-protocol job without losing
- any thing.
-
- Usage: Operator sees something bad about to happen, such as
- the paper is about to jam, or the toner is running out, or
- the device is overheating or wants to add more paper.
-
- Suggested name and operations: Pause-Device-Now, Resume-
- Device
-
- 11. Need a Printer Operation to stop the processing of IPP jobs
- after all of the currently accepted jobs have been
- processed, but any newly accepted jobs go into the
- 'processing-held' state.
-
- Usage: This allows an operator to reconfigure the Output
- Device in order to let jobs that are held waiting for
- resources, such as special media, get a chance. Then the
- operator uses another operation after reconfiguring. He
- repeats the two operations to restore the Output Device to
- its normal media.
-
- Suggested name and operations: Hold-New-Jobs, Release-
- Held-New-Jobs
-
- 12. Need a Device Operation to stop processing the current any-
- protocol job at a convenient point, such as after the
- current copy (or end of job if last or only copy). Need a
- companion operation to start processing the current any-
- protocol job or next job without losing any thing.
-
- Usage: The operator wants to empty the output bin that is
- near full. The paper path is run out.
-
- Suggested name and operations: Pause-Device-After-Current-
- Copy, Resume-Device
-
-
-
-
-
-
-
-
-Kugler, Lewis & Hastings Informational [Page 5]
-\f
-RFC 3239 IPP: Req. for Job and Printer Admin Ops February 2002
-
-
- 13. Need a Device Operation that always pauses on a device-
- defined boundary, no matter how many copies, in order to not
- break up a job. Need a companion operation to start
- processing the current any-protocol job or next job without
- losing any thing.
-
- Usage: The operator wants to empty the output bin that is
- near full, but he doesn't want to break up a job in case it
- has multiple copies. The paper path is run out.
-
- Suggested name and operations: Pause-Device-After-Current-
- Job, Resume-Device
-
- 14. Need a Printer Operation that combines Disable-Printer,
- Pause-Printer-After-Current-Job, and rejects all other Job,
- Printer, and Device Operations, except Job and Printer
- queries, System Administrator Set-Printer-Attributes, and
- the companion operation to resume activity. In other words,
- this operation makes the Printer a read-only object in a
- graceful manner for end-users and the operator.
-
- Usage: The administrator wants to reconfigure the Printer
- object using the Set-Printer-Attributes operation without
- disturbing the current in process work, but wants to make
- sure that the operator isn't also trying to change the
- Printer object as part of running the Printer.
-
- Suggested name and operation: Deactivate-Printer,
- Activate-Printer
-
- 15. Need a Device Operation that combines Disable-Device,
- Pause-Device-After-Current-Job, and rejects all other Device
- Operations, except Job and Printer queries and the companion
- operation to resume activity. In other words, this
- operation makes the Output Device a read-only object in a
- graceful manner.
-
- Usage: The field service person wants to open up the device
- without disturbing the current in process work, perhaps to
- replace staples, or replace the toner cartridge.
-
- Suggested name and operation: Deactivate-Device, Activate-
- Device
-
-
-
-
-
-
-
-
-Kugler, Lewis & Hastings Informational [Page 6]
-\f
-RFC 3239 IPP: Req. for Job and Printer Admin Ops February 2002
-
-
- 16. Need a Printer Operation to recover from the IPP Printer
- software that has gotten confused (run out of heap memory or
- gotten into a state that it doesn't seem to be able to get
- out of). This is a condition that shouldn't happen, but
- does in real life. Any volatile information is saved if
- possible before the software is re-initialized. No
- companion operation is needed to undo this. We don't want
- to go back to the "confused" state :-).
-
- Usage: The IPP Printer software has gotten confused or
- isn't responding properly.
-
- Suggested name and operation: Restart-Printer
-
- 17. Need a Device Operation to recover from the Output Device
- hardware and software that has gotten confused (gotten into
- a state that it doesn't seem to be able to get out of, run
- out of heap memory, etc.). This is a condition that
- shouldn't happen, but does in real life. This is the same
- and has the same options as the Printer MIB reset. No
- companion operation is needed to undo this. We don't want
- to go back to the "confused" state :-).
-
- Usage: The Output Device has gotten confused or need
- resetting to some initial conditions.
-
- Suggested name and operation: Reset-Device
-
- 18. Need a Printer Operation to put the IPP Printer object out
- of business with no way in the protocol to bring that
- instantiation back to life (but see Startup-Printer which
- brings up exactly one new instantiation to life with the
- same URL). Any volatile information is saved if possible.
-
- Usage: The Printer is being moved or the building's power
- is being shut off.
-
- Suggested name and operation: Shutdown-Printer
-
- 19. Need a Printer Operation to bring an IPP Printer to life
- when there is an already running host.
-
- Usage: After the host is started (by means outside the IPP
- protocol), the operator is able to ask the host to bring up
- any number of Printer objects (that the host has been
- configured in some way) each with distinct URLs.
-
- Suggested name and operation: Startup-Printer
-
-
-
-Kugler, Lewis & Hastings Informational [Page 7]
-\f
-RFC 3239 IPP: Req. for Job and Printer Admin Ops February 2002
-
-
- 20. Need a Device Operation to power off the Output Device after
- writing out any software state. It is assumed that other
- operations have more gracefully prepared the Output Device
- for this drastic and immediate. There is no companion
- Device Operation to bring the power back on.
-
- Usage: The Output Device is going to be moved, the power in
- the building is going to be shutoff, the repair man has
- arrived and needs to take the Output Device apart.
-
- Suggested name and operation: Power-Off-Device
-
- 21. Need a Device Operation to startup a powered-off device.
-
- Usage: After a Power-Off-Device, if the device can be
- powered back up (possibly by an intervening host that
- supports the Device Operation).
-
- Suggest name and operation: Power-On-Device
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Kugler, Lewis & Hastings Informational [Page 8]
-\f
-RFC 3239 IPP: Req. for Job and Printer Admin Ops February 2002
-
-
- The tentative list of Printer and the corresponding Device Operations
- is shown in Table 1:
-
- Table 1 - List of Printer Operations and corresponding Device
- Operations
-
- Printer Operation Corresponding Device Operation
- equivalent
-
- Disable-Printer Disable-Device
-
- Enable-Printer Enable-Device
-
- Pause-Printer (IPP/1.1 - [RFC2911] Pause-Device-Now
- - one interpretation)
-
- no Pause-Device-After-Current-Copy
-
- Pause-Printer-After-Current-Job Pause-Device-After-Current-Job
-
- Resume-Printer (IPP/1.1 - Resume-Device
- [RFC2911])
-
- Hold-New-Jobs no
-
- Release-Held-New-Jobs no
-
- Deactivate-Printer Deactivate-Device
-
- Activate-Printer Activate-Device
-
- Purge-Jobs (IPP/1.1 - [RFC2911]) Purge-Device
-
- Restart-Printer Reset-Device
-
- Shutdown-Printer Power-Off-Device
-
- Startup-Printer Power-On-Device
-
- There are no conformance dependencies between Printer Operations and
- Device Operations. Either may be supported without supporting the
- corresponding operations.
-
-
-
-
-
-
-
-
-
-Kugler, Lewis & Hastings Informational [Page 9]
-\f
-RFC 3239 IPP: Req. for Job and Printer Admin Ops February 2002
-
-
-4 IANA Considerations
-
- This document does not define anything to be registered. When a
- document is produced that defines operations that meet the
- requirements in this document, those operations will be registered
- according to the procedures in [RFC2911] section 6.4.
-
-5 Internationalization Considerations
-
- This document has the same localization considerations as the
- [RFC2911].
-
-6 Security Considerations
-
- This document defines the requirements for operations that are
- intended to be used by an operator or system administrator. These
- operations, when defined, would affect how the Printer behaves and
- establish policy and/or operating behavior that ordinary users
- shouldn't be able to perform. Printer implementations that support
- such operations should authenticate users and authorized them as
- being an operator or a system administrator for the system.
- Otherwise, unprivileged users could affect the policy and behavior of
- IPP Printers, thereby affecting other users. Similarly clients that
- supports such operations should be prepared to provide the necessary
- authentication information. See the security provisions in [RFC2911]
- for authentication, such as TLS.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Kugler, Lewis & Hastings Informational [Page 10]
-\f
-RFC 3239 IPP: Req. for Job and Printer Admin Ops February 2002
-
-
-7 References
-
- [ipp-ntfy] Herriot, R., Hastings, T., Isaacson, S., Martin, J.,
- deBry, R., Shepherd, M. and R. Bergman, "Internet
- Printing Protocol/1.1: IPP Event Notifications and
- Subscriptions", Work in Progress.
-
- [ipp-ops-set2] Kugler, C., Hastings, T. and H. Lewis, "Internet
- Printing Protocol (IPP): Job and Printer
- Administrative Operations", Work in Progress.
-
- [RFC2565] Herriot, R., Butler, S., Moore, P. and R. Tuner,
- "Internet Printing Protocol/1.0: Encoding and
- Transport", RFC 2565, April 1999.
-
- [RFC2566] deBry, R., Hastings, T., Herriot, R. and S. Isaacson,
- P. Powell, "Internet Printing Protocol/1.0: Model and
- Semantics", RFC 2566, April 1999.
-
- [RFC2567] Wright, D., "Design Goals for an Internet Printing
- Protocol", RFC 2567, April 1999.
-
- [RFC2568] Zilles, S., "Rationale for the Structure and Model and
- Protocol for the Internet Printing Protocol", RFC
- 2568, April 1999.
-
- [RFC2569] Herriot, R., Hastings, T., Jacobs, N. and J. Martin,
- "Mapping between LPD and IPP Protocols", RFC 2569,
- April 1999.
-
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
- Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext
- Transfer Protocol - HTTP/1.1", RFC 2616, June 1999.
-
- [RFC2910] Herriot, R., Butler, S., Moore, P. and R. Tuner,
- "Internet Printing Protocol/1.1: Encoding and
- Transport", RFC 2910, September 2000.
-
- [RFC2911] deBry, R., Hastings, T., Herriot, R., Isaacson, S. and
- P. Powell, "Internet Printing Protocol/1.0: Model and
- Semantics", RFC 2911, September 2000.
-
- [RFC3196] Hastings, T., Manros, C., Zehler, P., Kuger, C. and H.
- Holst, "Internet Printing Protocol/1.1: Implementer's
- Guide", RFC 3196, November 2001.
-
-
-
-
-
-
-Kugler, Lewis & Hastings Informational [Page 11]
-\f
-RFC 3239 IPP: Req. for Job and Printer Admin Ops February 2002
-
-
-Appendix A: Description of base IPP documents
-
- The base set of IPP documents includes:
-
- Design Goals for an Internet Printing Protocol [RFC2567]
- Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol [RFC2568]
- Internet Printing Protocol/1.1: Model and Semantics [RFC2911]
- Internet Printing Protocol/1.1: Encoding and Transport [RFC2910]
- Internet Printing Protocol/1.1: Implementer's Guide [RFC3196]
- Mapping between LPD and IPP Protocols [RFC2569]
- Internet Printing Protocol (IPP): IPP Event Notifications and
- Subscriptions [ipp-ntfy]
-
- The "Design Goals for an Internet Printing Protocol" document takes a
- broad look at distributed printing functionality, and it enumerates
- real-life scenarios that help to clarify the features that need to be
- included in a printing protocol for the Internet. It identifies
- requirements for three types of users: end users, operators, and
- administrators. It calls out a subset of end user requirements that
- are satisfied in IPP/1.0. A few optional operator operations have
- been added to IPP/1.1.
-
- The "Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol" document describes IPP from a high level
- view, defines a roadmap for the various documents that form the suite
- of IPP specification documents, and gives background and rationale
- for the IETF working group's major decisions.
-
- The "Internet Printing Protocol/1.1: Model and Semantics" document
- describes a simplified model with abstract objects, their attributes,
- and their operations that are independent of encoding and transport.
- It introduces a Printer and a Job object. The Job object optionally
- supports multiple documents per Job. It also addresses security,
- internationalization, and directory issues.
-
- The "Internet Printing Protocol/1.1: Encoding and Transport" document
- is a formal mapping of the abstract operations and attributes defined
- in the model document onto HTTP/1.1 [RFC2616]. It defines the
- encoding rules for a new Internet MIME media type called
- "application/ipp". This document also defines the rules for
- transporting over HTTP a message body whose Content-Type is
- "application/ipp". This document defines the 'ippget' scheme for
- identifying IPP printers and jobs.
-
-
-
-
-
-
-
-Kugler, Lewis & Hastings Informational [Page 12]
-\f
-RFC 3239 IPP: Req. for Job and Printer Admin Ops February 2002
-
-
- The "Internet Printing Protocol/1.1: Implementer's Guide" document
- gives insight and advice to implementers of IPP clients and IPP
- objects. It is intended to help them understand IPP/1.1 and some of
- the considerations that may assist them in the design of their client
- and/or IPP object implementations. For example, a typical order of
- processing requests is given, including error checking. Motivation
- for some of the specification decisions is also included.
-
- The "Mapping between LPD and IPP Protocols" document gives some
- advice to implementers of gateways between IPP and LPD (Line Printer
- Daemon) implementations.
-
- The "IPP Event Notifications and Subscriptions" document defines an
- extension to IPP/1.0 [RFC2566, RFC2565] and IPP/1.1 [RFC2911,
- RFC2910]. This extension allows a client to subscribe to printing
- related Events and defines the semantics for delivering asynchronous
-
- Event Notifications to the specified Notification Recipient via a
- specified Delivery Method (i.e., protocols) defined in (separate)
- Delivery Method documents.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Kugler, Lewis & Hastings Informational [Page 13]
-\f
-RFC 3239 IPP: Req. for Job and Printer Admin Ops February 2002
-
-
-Authors' Addresses
-
- Carl Kugler
- IBM
- Boulder CO
-
- Phone: (303) 924-5060
- EMail: kugler@us.ibm.com
-
-
- Tom Hastings
- Xerox Corporation
- 737 Hawaii St. ESAE 231
- El Segundo, CA 90245
-
- Phone: 310-333-6413
- Fax: 310-333-5514
- EMail: hastings@cp10.es.xerox.com
-
-
- Harry Lewis
- IBM
- Boulder CO
-
- Phone: (303) 924-5337
- EMail: harryl@us.ibm.com
-
- IPP Web Page: http://www.pwg.org/ipp/
- IPP Mailing List: ipp@pwg.org
-
- To subscribe to the ipp mailing list, send the following email:
-
- 1) send it to majordomo@pwg.org
- 2) leave the subject line blank
- 3) put the following two lines in the message body:
- subscribe ipp
- end
-
- Implementers of this specification document are encouraged to join
- the IPP Mailing List in order to participate in any discussions of
- clarification issues and review of registration proposals for
- additional attributes and values. In order to reduce spam the
- mailing list rejects mail from non-subscribers, so you must subscribe
- to the mailing list in order to send a question or comment to the
- mailing list.
-
-
-
-
-
-
-Kugler, Lewis & Hastings Informational [Page 14]
-\f
-RFC 3239 IPP: Req. for Job and Printer Admin Ops February 2002
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Kugler, Lewis & Hastings Informational [Page 15]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group H. Alvestrand
-Request for Comments: 3282 Cisco Systems
-Obsoletes: 1766 May 2002
-Category: Standards Track
-
-
- Content Language Headers
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
-Abstract
-
- This document defines a "Content-language:" header, for use in cases
- where one desires to indicate the language of something that has RFC
- 822-like headers, like MIME body parts or Web documents, and an
- "Accept-Language:" header for use in cases where one wishes to
- indicate one's preferences with regard to language.
-
-1. Introduction
-
- There are a number of languages presently or previously used by human
- beings in this world.
-
- A great number of these people would prefer to have information
- presented in a language which they understand.
-
- In some contexts, it is possible to have information available in
- more than one language, or it might be possible to provide tools
- (such as dictionaries) to assist in the understanding of a language.
-
- In other cases, it may be desirable to use a computer program to
- convert information from one format (such as plaintext) into another
- (such as computer-synthesized speech, or Braille, or high-quality
- print renderings).
-
-
-
-
-
-
-
-Alvestrand Standards Track [Page 1]
-\f
-RFC 3282 Content Language Headers May 2002
-
-
- A prerequisite for any such function is a means of labelling the
- information content with an identifier for the language that is used
- in this information content, such as is defined by [TAGS]. This
- document specifies a protocol element for use with protocols that use
- RFC 822-like headers for carrying language tags as defined in [TAGS].
-
- The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in [RFC 2119].
-
-2. The Content-language header
-
- The "Content-Language" header is intended for use in the case where
- one desires to indicate the language(s) of something that has RFC
- 822-like headers, such as MIME body parts or Web documents.
-
- The RFC 822 EBNF of the Content-Language header is:
-
- Content-Language = "Content-Language" ":" 1#Language-tag
-
- In the more strict RFC 2234 ABNF:
-
- Content-Language = "Content-Language" ":" [CFWS] Language-List
- Language-List = Language-Tag [CFWS]
- *("," [CFWS] Language-Tag [CFWS])
-
- The Content-Language header may list several languages in a comma-
- separated list.
-
- The CFWS construct is intended to function like the whitespace
- convention in RFC 822, which means also that one can place
- parenthesized comments anywhere in the language sequence, or use
- continuation lines. A formal definition is given in RFC 2822
- [RFC2822].
-
- In keeping with the tradition of RFC 2822, a more liberal "obsolete"
- grammar is also given:
-
- obs-content-language = "Content-Language" *WSP ":"
- [CFWS] Language-List
-
- Like RFC 2822, this specification says that conforming
- implementations MUST accept the obs-content-language syntax, but MUST
- NOT generate it; all generated headers MUST conform to the Content-
- Language syntax.
-
-
-
-
-
-
-Alvestrand Standards Track [Page 2]
-\f
-RFC 3282 Content Language Headers May 2002
-
-
-2.1 Examples of Content-language values
-
- Voice recording from Liverpool downtown
-
- Content-type: audio/basic
- Content-Language: en-scouse
-
- Document in Mingo, an American Indian language which does not have an
- ISO 639 code:
-
- Content-type: text/plain
- Content-Language: i-mingo
-
- A English-French dictionary
-
- Content-type: application/dictionary
- Content-Language: en, fr (This is a dictionary)
-
- An official European Commission document (in a few of its official
- languages):
-
- Content-type: multipart/alternative
- Content-Language: da, de, el, en, fr, it
-
- An excerpt from Star Trek
-
- Content-type: video/mpeg
- Content-Language: i-klingon
-
-3. The Accept-Language header
-
- The "Accept-Language" header is intended for use in cases where a
- user or a process desires to identify the preferred language(s) when
- RFC 822-like headers, such as MIME body parts or Web documents, are
- used.
-
- The RFC 822 EBNF of the Accept-Language header is:
-
- Accept-Language = "Accept-Language" ":"
- 1#( language-range [ ";" "q" "=" qvalue ] )
-
- A slightly more restrictive RFC 2234 ABNF definition is:
-
- Accept-Language = "Accept-Language:" [CFWS] language-q
- *( "," [CFWS] language-q )
- language-q = language-range [";" [CFWS] "q=" qvalue ] [CFWS]
- qvalue = ( "0" [ "." 0*3DIGIT ] )
- / ( "1" [ "." 0*3("0") ] )
-
-
-
-Alvestrand Standards Track [Page 3]
-\f
-RFC 3282 Content Language Headers May 2002
-
-
-
- A more liberal RFC 2234 ABNF definition is:
-
- Obs-accept-language = "Accept-Language" *WSP ":" [CFWS]
- obs-language-q *( "," [CFWS] obs-language-q ) [CFWS]
- obs-language-q = language-range
- [ [CFWS] ";" [CFWS] "q" [CFWS] "=" qvalue ]
-
- Like RFC 2822, this specification says that conforming
- implementations MUST accept the obs-accept-language syntax, but MUST
- NOT generate it; all generated messages MUST conform to the Accept-
- Language syntax.
-
- The syntax and semantics of language-range is defined in [TAGS]. The
- Accept-Language header may list several language-ranges in a comma-
- separated list, and each may include a quality value Q. If no Q
- values are given, the language-ranges are given in priority order,
- with the leftmost language-range being the most preferred language;
- this is an extension to the HTTP/1.1 rules, but matches current
- practice.
-
- If Q values are given, refer to HTTP/1.1 [RFC 2616] for the details
- on how to evaluate it.
-
-4. Security Considerations
-
- The only security issue that has been raised with language tags since
- the publication of RFC 1766, which stated that "Security issues are
- believed to be irrelevant to this memo", is a concern with language
- ranges used in content negotiation - that they may be used to infer
- the nationality of the sender, and thus identify potential targets
- for surveillance.
-
- This is a special case of the general problem that anything you send
- is visible to the receiving party; it is useful to be aware that such
- concerns can exist in some cases.
-
- The exact magnitude of the threat, and any possible countermeasures,
- is left to each application protocol.
-
-5. Character set considerations
-
- This document adds no new considerations beyond what is mentioned in
- [TAGS].
-
-
-
-
-
-
-
-Alvestrand Standards Track [Page 4]
-\f
-RFC 3282 Content Language Headers May 2002
-
-
-6. Acknowledgements
-
- This document has benefited from many rounds of review and comments
- in various fora of the IETF and the Internet working groups.
-
- Any list of contributors is bound to be incomplete; please regard the
- following as only a selection from the group of people who have
- contributed to make this document what it is today.
-
- In alphabetical order:
-
- Tim Berners-Lee, Nathaniel Borenstein, Sean M. Burke, John Clews, Jim
- Conklin, John Cowan, Dave Crocker, Martin Duerst, Michael Everson,
- Ned Freed, Tim Goodwin, Dirk-Willem van Gulik, Marion Gunn, Paul
- Hoffman, Olle Jarnefors, John Klensin, Bruce Lilly, Keith Moore,
- Chris Newman, Masataka Ohta, Keld Jorn Simonsen, Rhys Weatherley,
- Misha Wolf, Francois Yergeau and many, many others.
-
- Special thanks must go to Michael Everson, who has served as language
- tag reviewer for almost the entire period, since the publication of
- RFC 1766, and has provided a great deal of input to this revision.
- Bruce Lilly did a special job of reading and commenting on my ABNF
- definitions.
-
-7. References
-
- [TAGS] Alvestrand, H., "Tags for the Identification of
- Languages", BCP 47, RFC 3066
-
- [ISO 639] ISO 639:1988 (E/F) - Code for the representation of names
- of languages - The International Organization for
- Standardization, 1st edition, 1988-04-01 Prepared by
- ISO/TC 37 - Terminology (principles and coordination).
- Note that a new version (ISO 639-1:2000) is in
- preparation at the time of this writing.
-
- [ISO 639-2] ISO 639-2:1998 - Codes for the representation of names of
- languages -- Part 2: Alpha-3 code - edition 1, 1998-11-
- 01, 66 pages, prepared by ISO/TC 37/SC 2
-
- [ISO 3166] ISO 3166:1988 (E/F) - Codes for the representation of
- names of countries - The International Organization for
- Standardization, 3rd edition, 1988-08-15.
-
- [ISO 15924] ISO/DIS 15924 - Codes for the representation of names of
- scripts (under development by ISO TC46/SC2)
-
-
-
-
-
-Alvestrand Standards Track [Page 5]
-\f
-RFC 3282 Content Language Headers May 2002
-
-
- [RFC 2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part One: Format of Internet Message
- Bodies", RFC 2045, November 1996.
-
- [RFC 2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part Two: Media Types", RFC 2046,
- November 1996.
-
- [RFC 2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions)
- Part Three: Message Header Extensions for Non-ASCII
- Text", RFC 2047, November 1996.
-
- [RFC 2048] Freed, N., Klensin, J. and J. Postel, "Multipurpose
- Internet Mail Extensions (MIME) Part Four: Registration
- Procedures", RFC 2048, November 1996.
-
- [RFC 2049] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part Five: Conformance Criteria and
- Examples", RFC 2049, November 1996.
-
- [RFC 2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC 2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", RFC 2234, November 1997.
-
- [RFC 2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
- Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext
- Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
-
- [RFC 2822] Resnick, P., "Internet Message Format", RFC 2822, April
- 2001.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Alvestrand Standards Track [Page 6]
-\f
-RFC 3282 Content Language Headers May 2002
-
-
-Appendix A: Changes from RFC 1766
-
- The definition of the language tags has been split, and is now RFC
- 3066. The differences parameter to multipart/alternative is no
- longer part of this standard, because no implementations of the
- function were ever found. Consult RFC 1766 if you need the
- information.
-
- The ABNF for content-language has been updated to use the RFC 2234
- ABNF.
-
-Author's Address
-
- Harald Tveit Alvestrand
- Cisco Systems
- Weidemanns vei 27
- 7043 Trondheim
- NORWAY
-
- EMail: Harald@Alvestrand.no
- Phone: +47 73 50 33 52
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Alvestrand Standards Track [Page 7]
-\f
-RFC 3282 Content Language Headers May 2002
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Alvestrand Standards Track [Page 8]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group T. Hastings
-Request for Comments: 3380 Xerox Corporation
-Updates: 2910, 2911 R. Herriot
-Category: Standards Track Consultant
- C. Kugler
- H. Lewis
- IBM Corporation
- September 2002
-
-
- Internet Printing Protocol (IPP):
- Job and Printer Set Operations
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
-Abstract
-
- This document is an OPTIONAL extension to the Internet Printing
- Protocol (IPP/1.0 and IPP/1.1). This document specifies 3 additional
- OPTIONAL operations for use with the Internet Printing Protocol/1.0
- (IPP) and IPP/1.1. The end user, operator, and administrator Set-
- Job-Attributes and Set-Printer-Attributes operations are used to
- modify IPP Job objects and Printer objects, respectively. The Get-
- Printer-Supported-Values administrative operation returns values that
- the IPP Printer will accept for setting its "xxx-supported"
- attributes.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 1]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-Table of Contents
-
- 1 Introduction......................................................4
- 2 Terminology.......................................................5
- 2.1 Conformance Terminology.........................................5
- 2.2 Other terminology...............................................5
- 3 Requirements and Use Cases........................................5
- 4 Definition of the Set operations..................................6
- 4.1 Set-Printer-Attributes Operation................................7
- 4.1.1 Settable and READ-ONLY Printer Description attributes.........9
- 4.1.2 Set-Printer-Attributes Request...............................10
- 4.1.3 Set-Printer-Attributes Response..............................12
- 4.2 Set-Job-Attributes Operation...................................13
- 4.2.1 Settable and READ-ONLY Job Description attributes............16
- 4.2.2 Set-Job-Attributes Request...................................17
- 4.2.3 Set-Job-Attributes Response..................................18
- 4.3 Get-Printer-Supported-Values Operation.........................19
- 4.3.1 Definition of the usage of the 'admin-define' out-of-band
- attribute value..............................................20
- 5 New Operation attributes.........................................22
- 5.1 printer-message-from-operator (text(127))......................22
- 5.2 job-message-from-operator (text(127))..........................23
- 6 New Printer Description Attributes...............................24
- 6.1 printer-settable-attributes-supported (1setOf type2 keyword)...24
- 6.2 job-settable-attributes-supported (1setOf type2 keyword).......25
- 6.3 document-format-varying-attributes (1setOf type2 keyword)......25
- 6.4 printer-message-time (integer(MIN:MAX))........................25
- 6.5 printer-message-date-time (dateTime)...........................26
- 6.6 printer-xri-supported (1setOf collection)......................26
- 6.7 xri-uri-scheme-supported (1setOf uriScheme)....................28
- 6.8 xri-authentication-supported (1setOf type2 keyword)............29
- 6.9 xri-security-supported (1setOf type2 keyword)..................29
- 7 Additional status codes..........................................29
- 7.1 client-error-attributes-not-settable (0x0413)..................29
- 8 Additional out-of-band values....................................30
- 8.1 'not-settable' out-of-band value...............................30
- 8.1.1 Encoding of the 'not-settable' out-of-band attribute value...30
- 8.2 'delete-attribute' out-of-band value...........................30
- 8.2.1 Encoding of the 'delete-attribute' out-of-band value.........31
- 8.3 'admin-define' out-of-band attribute value.....................31
- 8.3.1 Encoding of the 'admin-define' out-of-band attribute value...32
- 9 New Values for Existing Printer Description Attributes...........33
- 9.1 operations-supported (1setOf type2 enum).......................33
- 10 Conformance Requirements........................................33
- 11 IANA Considerations.............................................34
- 11.1 Operation Registrations.......................................35
- 11.2 Additional Enum Attribute Value Registrations for the
- "operations-supported" Printer Attribute......................35
-
-
-
-Hastings, et. al. Standards Track [Page 2]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- 11.3 Attribute Registrations.......................................35
- 11.4 Status code Registrations.....................................36
- 11.5 Out-of-band Attribute Value Registrations.....................36
- 12 Internationalization Considerations.............................37
- 13 Security Considerations.........................................37
- 14 References......................................................38
- 14.1 Normative References..........................................38
- 14.2 Informative References........................................38
- Appendix A: Allowed Values for Set-Printer-Attributes and Set-Job-
- Attributes requests (Normative)........................39
- Appendix B: Attributes returned from Get-Printer-Supported-Values
- (Normative)............................................50
- Appendix C: Description of the Base IPP Documents (Informative)....55
- Authors' Addresses.................................................56
- Full Copyright Statement...........................................58
-
-Table of Tables
-
- Table 1 - Operation-Id assignments.................................7
- Table 2 - Job State Transition Table for the Set-Job-Attributes
- operation ..............................................15
- Table 3 - Member attributes of "printer-xri-supported" (1setOf
- collection) ............................................27
- Table 4 - Operation-id assignments................................33
- Table 5 - Validation rules for 'Any of "xxx-supported" '..........40
- Table 6 - Validation rules for 'From Get-Printer-Supported-Values'41
- Table 7 - Values allowed for Job Template Attributes in the Set-Job-
- Attributes Operation ...................................42
- Table 8 - Values allowed for Job Description Attributes in the Set-
- Job-Attributes Operation ...............................43
- Table 9 - Values allowed for Printer Job Template Attributes in the
- Set-Printer-Attributes Operation .......................44
- Table 10 - Values allowed for Printer Description Attributes in the
- Set-Printer-Attributes Operation .......................47
- Table 11 - Printer Job Template Attributes returned from Get-Printer-
- Supported-Values .......................................51
- Table 12 - Printer Job Template Attributes returned from Get-Printer-
- Supported-Values .......................................51
- Table 13 - Printer Description Attributes returned from Get-Printer-
- Supported-Values .......................................51
- Table 14 - Printer Job Template Attributes returned from Get-Printer-
- Supported-Values .......................................52
- Table 15 - Printer Job Template Attributes returned from Get-Printer-
- Supported-Values .......................................52
- Table 16 - Printer Description Attributes returned from Get-Printer-
- Supported-Values .......................................53
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 3]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-1 Introduction
-
- This document is an OPTIONAL extension to IPP/1.0 [RFC2565, RFC2566]
- and IPP/1.1 [RFC2911, RFC2910]. For a description of the base IPP
- documents see Appendix C.
-
- The Internet Printing Protocol (IPP) is an application level protocol
- that can be used for distributed printing using Internet tools and
- technologies. IPP version 1.1 [RFC2911, RFC2910] focuses on end user
- functionality with a few administrative operations included. This
- document defines additional OPTIONAL end user, operator, and
- administrator Set-Job-Attributes and Set-Printer-Attributes
- operations used to modify IPP Job objects and Printer objects,
- respectively. It also defines a third Get-Printer-Supported-Values
- administrator operation that returns values that the IPP Printer will
- accept for setting its "xxx-supported" attributes. The Get-Printer-
- Supported-Values operation MUST be supported, if the implementation
- supports setting any "xxx-supported" Printer attributes using the
- Set-Printer-Attributes operation.
-
- Nine Printer Description attributes are defined:
-
- printer-settable-attributes-supported (1setOf type2 keyword)
- job-settable-attributes-supported (1setOf type2 keyword)
- document-format-varying-attributes (1setOf type2 keyword)
- printer-message-time (integer(MIN:MAX))
- printer-message-date-time (dateTime)
- printer-xri-supported (1setOf collection)
- xri-uri-scheme-supported (1setOf uriScheme)
- xri-authentication-supported (1setOf type2 keyword)
- xri-security-supported (1setOf type2 keyword)
-
- Three out-of-band values are defined for use with these three
- operations: 'delete-attribute' for deleting Job attributes with the
- Set-Job-Attributes request, 'not-settable' for use in either the
- Set-Job-Attributes or Set-Printer-Attributes responses, and 'admin-
- define' for use in the Get-Printer-Supported-Values response.
-
- Two operation attributes: "printer-message-from-operator" (text) and
- "job-message-from-operator" (text) are defined to set the
- corresponding IPP/1.1 Printer and Job Description attributes with the
- same names. These operation attributes may be used with any
- operation that affect the Printer or Job object for which an
- operation might want to indicate a message. For the Set-Job-
- Attributes and Set-Printer-Attributes operations, the client MUST
- explicitly set them, rather than using these operation attributes.
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 4]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- A Printer implementation can make the value of some attributes
- dependent on the document-format, e.g., "resolution-supported".
-
-2 Terminology
-
- This section defines terminology used throughout this document.
-
-2.1 Conformance Terminology
-
- Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD
- NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to
- conformance as defined in BCP 14, RFC 2119 [RFC2119] and [RFC2911]
- section 12.1. If an implementation supports the extension defined in
- this document, then these terms apply; otherwise, they do not. These
- terms define conformance to this document only; they do not affect
- conformance to other documents, unless explicitly stated otherwise.
-
-2.2 Other terminology
-
- This document uses terms such as Job object (or Job), IPP Printer
- object (or Printer), "operation", "request", response", "attributes",
- "keywords", and "support". These terms have special meaning and are
- defined in the model terminology [RFC2911], section 12.2. The
- following additional terms are introduced in this document:
-
- READ-ONLY: used in an attribute definition document to indicate that
- the attribute MUST NOT be settable using an IPP protocol Set
- operation. In other words, the attribute is not settable by
- definition.
-
- not-settable: an implementation does not support setting an attribute
- (whether or not the attribute's definition is READ-ONLY).
-
-3 Requirements and Use Cases
-
- The following requirements and usage are intended to be met by the
- specification in this document.
-
- 1. The end-user and the operator need a way to modify a Job that is
- in the 'pending' or 'pending-held' state.
-
- Usage: The end-user discovers that he/she forgot to include a
- print instruction, such as "finishings" = 'staple' after
- submitting a job. Rather than canceling the job and resubmitting
- it to the same IPP Printer, the end-user is able to modify the job
- on the IPP Printer.
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 5]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- The operator needs to modify a job because it is requesting a
- particular kind of media for which there is no more, but the
- policy is to print the job on a comparable medium.
-
- 2. The system administrator needs a way to re-configure or change the
- policy of the IPP Printer remotely.
-
- Usage: The system administrator is adding additional named media
- to the supported media list (setting 'name' values to the "media-
- supported" Printer attribute).
-
- The system administrator is reducing the capability of the IPP
- Printer by removing one of the operations from the supported
- operations list, such as Cancel-Job, because the policy is to run
- the IPP Printer like a public facsimile machine. After having
- removed Cancel-Job from the list of supported operations, an
- administrative client needs to be able to display to an
- administrator that the implementation is capable of being
- reconfigured to support Cancel-Job once again.
-
- The system administrator is remotely configuring the IPP Printer
- after installing it, and so is replacing the Printer Description
- attributes that have the out-of-band 'no-value' value (see
- [RFC2911], section 4.1) with the proper values.
-
- The operator is changing the media loaded in the input tray, and
- so is replacing the "media-ready" Job Template Printer attribute
- value with the proper values.
-
-4 Definition of the Set operations
-
- The Set-Printer-Attributes operations (as are all Printer operations)
- are directed at Printer objects. A client MUST always supply the
- "printer-uri" operation attribute in order to identify the correct
- target of the operation. These descriptions assume all of the common
- semantics of the IPP/1.1 Model and Semantics document [RFC2911],
- section 3.1.
-
- The Set-Job-Attributes operations (as are all Job operations) are
- directed at Job objects. A client MUST always supply some means of
- identifying the Job object in order to identify the correct target of
- the operation. That job identification MAY either be a single Job
- URI or a combination of a Printer URI with a Job ID, as defined in
- [RFC2911]. The IPP object implementation MUST support both forms of
- identification for every job. If possible, a client SHOULD use the
- Printer URI with a Job ID rather than a Job URI, since the 32-bit
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 6]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- "job-id" is more readily translated to and from other print protocols
- that MAY be serving as gateways into or out of the IPP
- implementation.
-
- The Set Printer operations are summarized in Table 1:
-
- Table 1 - Operation-Id assignments
-
- Operation Name Operation Brief description
- -Id
-
- Set-Printer- 0x0013 Sets attribute values of the target
- Attributes Printer object
-
- Set-Job-Attributes 0x0014 Sets attribute values of the target
- Job object
-
- Get-Printer- 0x0015 Gets values that are valid for
- Supported-Values setting "xxx-supported" attributes
- using the Set-Printer-Attributes
- operation
-
-4.1 Set-Printer-Attributes Operation
-
- This OPTIONAL operation allows a client to set the values of the
- attributes of a Printer object. In the request, the client supplies
- the set of Printer keyword attribute names and values that are to be
- set. In the response, the Printer object returns success or rejects
- the entire request with indications of which attribute or attributes
- could not be set.
-
- The Printer object validates the client-supplied attributes in the
- Set-Printer-Attributes request. For an attribute to validate, it
- MUST meet all of the following rules:
-
- 1. The number of attributes supplied by the client MUST NOT exceed
- the maximum number that the Printer supports in a Set-Printer-
- Attributes request. A Printer MUST accept at least one attribute,
- but SHOULD accept a reasonable number in a single Set-Printer-
- Attributes request.
-
- Note: There is no way for the client to determine the maximum
- number of attributes that the Printer supports in a Set-Printer-
- Attributes request, except to try a reasonable number.
-
- 2. The Printer MUST support the attribute.
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 7]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- 3. The attribute MUST NOT be READ-ONLY, i.e., the definition of the
- attribute MUST NOT indicate that the attribute is READ-ONLY (see
- Appendix A for an indication of which IPP/1.1 attributes are
- READ-ONLY).
-
- 4. The attribute MUST be settable in this implementation.
-
- 5. The Printer MUST support the value, according to the rules defined
- in Appendix A, i.e., each value of each supplied "xxx" attribute
- MUST be validated against the value of a corresponding "xxx-
- supported" Printer attribute. One of those rules permits an
- administrator to set arbitrary 'name' values to those "xxx-
- supported" Printer attributes that include the 'name' attribute
- syntax if the implementation supports the 'admin-define' out-of-
- band value for that "xxx-supported" attribute (see section 8.3 and
- Appendix A).
-
- 6. The attribute's values MUST NOT conflict with the values of other
- Printer attributes, including ones being set in this same
- operation.
-
- If any of the supplied attributes are not validate, the Printer
- object MUST reject the entire operation; the Printer object MUST NOT
- partially set some of the supplied attributes. In other words, after
- the operation, all the supplied attributes MUST be set or none of
- them MUST be set, thus making the Set-Printer-Attributes an atomic
- operation.
-
- The Printer MUST accept this operation when its READ-ONLY "printer-
- state" attribute (see [RFC2911], section 4.4.11) is 'idle' or
- 'stopped', and SHOULD accept it when the value is 'processing'. The
- Printer MUST accept this operation for any of the values of the
- Printer object's READ-ONLY "printer-state-reasons" and "printer-is-
- accepting-jobs" attributes, unless explicitly defined otherwise in
- the definition of these attributes' values.
-
- This operation MUST NOT change the value of attributes not specified
- in the operation unless the definition of the attribute explicitly
- specifies such side-effects. For example, this document explicitly
- specifies that when this operation sets "printer-message-from-
- operator", the Printer also MUST set the READ-ONLY "printer-message-
- time" and READ-ONLY "printer-message-date-time" attributes to the
- time of the operation as a side effect. In particular, if this
- operation changes an "xxx-default" attribute, the new value MUST be
- in the "xxx-supported" attributes or the request MUST contain a new
- value for "xxx-supported", which contains the new value for the
- "xxx-default". Otherwise, the Printer MUST reject the operation. In
- general, Printer attribute definitions that are settable will not
-
-
-
-Hastings, et. al. Standards Track [Page 8]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- define side-effects on other attributes that are settable, only side
- effects on READ-ONLY attributes, if any.
-
-4.1.1 Settable and READ-ONLY Printer Description attributes
-
- If the Printer supports the Set-Printer-Attributes operation, then it
- SHOULD support the setting of:
-
- all Job Template Default ("xxx-default") attributes
- all Job Template Supported ("xxx-supported") attributes
- all Job Template Ready ("xxx-ready") attributes
-
- that the implementation supports (see [RFC2911] section 4.2 and
- extensions).
-
- Some Printer Description attributes (see [RFC2911] section 4.4) MUST
- NOT be settable, i.e., they are defined to be READ-ONLY. An
- attribute marked as "READ-ONLY" in the Printer Description attribute
- table in Appendix A is such an attribute. The Printer attributes
- that are not marked as "READ-ONLY" MAY be settable using the Set-
- Printer-Attributes operation, depending on implementation.
-
- Note: From now on, all extensions that define new object attributes
- will indicate whether or not the attributes are READ-ONLY, by
- including the "READ-ONLY" adjective in their descriptions and/or
- explicitly stating whether they MAY be settable.
-
- The current values of each "xxx-supported" Printer attribute MUST
- reflect the current policy for support of the corresponding "xxx"
- attribute. If an "xxx-supported" Printer attribute is settable in an
- implementation, then its value(s) MUST affect the behavior of the
- implementation. If an "xxx-supported" Printer attribute is defined
- to be READ-ONLY or is not-settable in an implementation, then its
- values MUST NOT be settable using the Set-Printer-Attributes
- operation. Consider the following examples:
-
- For example, if the "operations-supported" Printer Description
- attribute (see [RFC2911] section 4.4.15) is settable in a
- particular implementation, then changing its value with a Set-
- Printer-Attributes operation MUST affect the operations that the
- implementation accepts or rejects. Such an implementation will
- need to be able to reject values for operations that it contains
- no code support for (see section 4.3). If the "operations-
- supported" Printer Description attribute is not settable in a
- particular implementation, then that implementation MUST reject an
- attempt to set it with a Set-Printer-Attributes operation, return
- the 'client-error-attributes-not-settable' status code (see
- section 7.1), and return the "operations-supported" attribute,
-
-
-
-Hastings, et. al. Standards Track [Page 9]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- with the out-of-band 'not-settable' value in the Unsupported
- Attributes Group.
-
- As another example, consider an implementation in which the
- "media-default" and "media-supported" are settable. If a client
- supplies a Set-Printer-Attributes request that contains the
- "media-default" attribute with a value that is not a member of the
- Printer's "media-supported" attribute, the Printer MUST reject the
- request and return the "client-error-conflicting-attributes"
- status code with the "media-default" and "media-supported"
- attributes and their values (see [RFC2911] section 3.1.7).
-
- As a third example, if a client supplies a Set-Printer-Attributes
- request that contains both the "media-default" and the "media-
- supported" attributes, but includes a value in the "media-default"
- that is not a member of the supplied "media-supported" attribute,
- the Printer MUST reject the request and return the "client-error-
- conflicting-attributes" status code with the "media-default" and
- "media-supported" attributes and their values (see [RFC2911]
- section 3.1.7).
-
- Access Rights: The authenticated user (see [RFC2911] section 8.3)
- performing this operation must be an operator or administrator of the
- Printer object (see [RFC2911] Sections 1 and 8.5). Most Printer
- attributes will require administrator access rights to set, such as
- "xxx-supported", while some will require operator access rights only,
- such as "media-ready" and "printer-message-from-operator". Which
- attributes require which access rights depends on implementation, and
- MAY depend on site policy.
-
-4.1.2 Set-Printer-Attributes Request
-
- The following sets of attributes are part of the Set-Printer-
- Attributes Request:
-
- Group 1: Operation Attributes
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes, as described in [RFC2911], section 3.1.4.1.
-
- Target:
- The "printer-uri" (uri) operation attribute, which is the
- target for this operation, as described in [RFC2911], section
- 3.1.5.
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 10]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Requesting User Name:
- The "requesting-user-name" (name(MAX)) attribute SHOULD be
- supplied by the client, as described in [RFC2911], section 8.3.
-
- "document-format" (mimeMediaType):
- The client OPTIONALLY supplies this attribute. The Printer
- object MUST support this attribute. This attribute is useful
- for a client to select the document-format to which the
- attribute modification should be applied. A Printer
- implementation MAY allow some attributes to have different
- values for each document format that it supports. See
- [RFC2911], section 3.2.5.1 "Get-Printer-Attributes Request".
-
- If the client includes this attribute, the Printer MUST change
- the supplied attributes for the document format specified by
- this attribute. If a supplied attribute is a member of the
- "document-format-varying-attributes" (i.e., the attribute
- varies by document format, see section 6.3), the Printer MUST
- change the supplied attribute for the document format specified
- by this attribute, but not for other document formats. If a
- supplied attribute isn't a member of the "document-format-
- varying-attributes" (i.e., it doesn't vary by document format),
- the Printer MUST change the supplied attribute for all document
- formats.
-
- If the client omits this attribute, the Printer MUST change the
- supplied attributes for all document formats, whether or not
- they vary by document-format.
-
- If the client supplies a value for the "document-format"
- Operation attribute, that is either 'application/octet-stream'
- or not supported by the Printer, i.e., is not among the values
- of the Printer object's "document-format-supported" attribute,
- the Printer object MUST reject the operation and return the
- 'client-error-document-format-not-supported' status code.
- Note: the document-format 'application/octet-stream' is the
- union of several document-formats (see [RFC2911] section
- 3.2.5.1, Get-Printer-Attributes) and is not a true document-
- format.
-
- Group 2: Printer Attributes
-
- The client MUST supply a set of Printer attributes with one or
- more values (including explicitly allowed out-of-band values) as
- defined in [RFC2911] section 4.2 Job Template Attributes ("xxx-
- default", "xxx-supported", and "xxx-ready" attributes), section
- 4.4 Printer Description Attributes, and any attribute extensions
- supported by the Printer. The value(s) of each Printer attribute
-
-
-
-Hastings, et. al. Standards Track [Page 11]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- supplied in Group 2 replaces the value(s) of the corresponding
- Printer attribute on the target Printer object. For attributes
- that can have multiple values (1setOf), all values supplied by the
- client replace all values of the corresponding Printer object
- attribute. If a Printer object attribute had not yet been
- configured, and so assumed the 'no-value' out-of-band value (see
- [RFC2911] section 4.1), the supplied value(s) replaces the 'no-
- value' value.
-
-4.1.3 Set-Printer-Attributes Response
-
- The Printer object returns the following sets of attributes as part
- of the Get-Printer-Attributes Response:
-
- Group 1: Operation Attributes
-
- Status Message:
- In addition to the REQUIRED status code returned in every
- response, the response OPTIONALLY includes a "status-message"
- (text(255)) and/or a "detailed-status-message" (text(MAX))
- operation attribute, as described in [RFC2911] sections 3.1.6
- and 13.
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes, as described in [RFC2911], section 3.1.4.2.
-
- Group 2: Unsupported Attributes
-
- See [RFC2911], section 3.1.7, for details on returning Unsupported
- Attributes.
-
- If some of the attributes in the operation fail to validate, the
- Printer MUST reject the operation, MUST NOT change any Printer
- attributes, and MUST return the indicated status code below. In
- this group, the Printer MUST also return all attributes that fail
- to validate. The following are the reasons that an attribute
- fails to validate and the value returns for the attribute, along
- with the indicated status code and order of detection:
-
- 1. The number of attributes supplied by the client exceeds the
- maximum number that the Printer supports in a Set-Printer-
- Attributes request: return the 'client-error-request-entity-
- too-large' (see [RFC2911], section 13.1.4.9).
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 12]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- 2. The Printer doesn't support the attribute: return the attribute
- with the "out-of-band" value 'unsupported' (see [RFC2911]
- section 3.1.7 and [RFC2910]) and the 'client-error-attributes-
- or-values-not-supported (see [RFC2911], section 13.1.4.12).
-
- 3. The attribute is either READ-ONLY (in its definition) or is
- not-settable in this implementation: return the attribute with
- the "out-of-band" value 'not-settable' (see section 8.1) and
- the 'client-error-attributes-not-settable' status code (see
- section 7.1).
-
- 4. The Printer doesn't support the value: if the attribute in the
- operation has a single value, return it. If the attribute in
- the operation is multi-valued, return only those values in a
- 1setOf that are not supported. Return the 'client-error-
- attributes-or-values-not-supported' status code (see [RFC2911],
- section 13.1.4.12).
-
- 5. The values of some of the supplied attributes conflict with one
- another and/or other Printer attribute values not being set: if
- the conflicting attribute in the operation has a single value,
- return the attribute and the value. If the attribute in the
- operation is multi-valued, return only the attribute and those
- values in a 1setOf that are conflicting with other attributes.
- Return the 'client-error-conflicting-attributes' status code
- (see [RFC2911], section 13.1.4.15).
-
-4.2 Set-Job-Attributes Operation
-
- This OPTIONAL operation allows a client to set the values of the
- attributes of a Job object. In the request, the client supplies the
- set of Job keyword attribute names and values that are to be set. In
- the response, the IPP object returns success or rejects the entire
- request with indications of which attribute or attributes could not
- be set.
-
- This operation is almost identical to the Set-Printer-Attributes
- operation and follows the same rules for validation (see section
- 4.1). The only differences are that the Set-Job-Attributes operation
- is directed at a Job object rather than a Printer object, there is no
- "document-format" operation attribute used when setting a Job object,
- the operation can add an attribute to the (Job) object, the 'delete-
- attributes' out-of-band value is permitted to remove an attribute,
- and the validation is the same as the Job Creation operations
- (Print-Job, Print-URI, and Create-Job), i.e., depends on the "xxx-
- supported" Printer Description attributes (see [RFC2911] section
- 3.1). Using the Set-Printer-Attributes operation, the administrator
- can set arbitrary 'name' values to those "xxx-supported" Printer
-
-
-
-Hastings, et. al. Standards Track [Page 13]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- attributes, that include the 'name' attribute syntax, if the
- implementation supports the 'admin-define' out-of-band value for that
- "xxx-supported" attribute (see section 8.3 and Appendix A). However,
- the Set-Job-Attributes cannot be used to add unsupported names to the
- Job object.
-
- If a client supplies a job attribute in a Set-Job-Attributes request
- that the Printer supports, and the job was originally submitted
- without supplying that attribute, the Printer adds the attribute to
- the Job object.
-
- If the client supplies a job attribute with the "out-of-band" value
- 'delete-attribute' (see section 8.2), then the Printer MUST remove
- the attribute and all of its values from the Job object, if present.
- The semantic effect of the client supplying the 'delete-attribute'
- value in a Set-Job-Attributes operation MUST be the same as if the
- attribute had not been supplied with the Job object in the Job
- Creation operation, i.e., the Printer applies its default attribute
- or behavior with lower precedence that the PDL (see the beginning of
- [RFC2911] section 4.2 and [RFC2911] 3.2.1.1). Any subsequent query
- of the Job object using Get-Job-Attributes or Get-Jobs, MUST NOT
- return any attribute that has been deleted using the 'delete-
- attribute' out-of-band value. However, a client can re-establish
- such a deleted Job attribute with any supported value(s), using a
- subsequent Set-Job-Attributes operation.
-
- If the client supplies an attribute in a Set-Job-Attributes request
- with the 'delete-attribute' value and that attribute is not present
- on the Job object, the Printer ignores that supplied attribute in the
- request, does not return the attribute in the Unsupported Attributes
- group, and returns the 'successful-ok' status code, if there are no
- other problems with the request.
-
- The validation of the Set-Job-Attributes request is performed by the
- Printer as if the job had been submitted originally with the new
- attribute values (and the deleted attributes removed) and with "ipp-
- attribute-fidelity" set to 'true', i.e., all modified attributes Job
- attributes and values MUST be supported in combination with the Job
- attributes not modified. If such a Job Creation operation would have
- been accepted, then the Set-Job-Attributes MUST be accepted. If such
- a Job Creation operation would have been rejected, then the Set-Job-
- Attributes MUST be rejected and the Job MUST be unchanged. In
- addition, if any of the supplied attributes are not supported, are
- not settable, or the values are not supported, the Printer object
- MUST reject the entire operation; the Printer object MUST NOT
- partially set some of the supplied attributes. In other words, after
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 14]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- the operation, all the supplied attributes MUST be set or none of
- them MUST be set, thus making the Set-Job-Attributes an atomic
- operation.
-
- The IPP object MUST accept or reject this operation when the Job's
- READ-ONLY "job-state" attribute has the values shown in Table 2. The
- job's current state MUST affect whether the IPP object accepts or
- rejects the request. For example, in the case where the operation
- creates a request for unavailable resources, the Job transitions to a
- new state. Table 2 shows the allowed behaviors in each job state and
- the transitions.
-
- Table 2 - Job State Transition Table for the Set-Job-Attributes
- operation
-
- Current New IPP object's response status code
- "job-state" "job-state" and "action":
-
-
- 'pending' 'pending' 'successful-ok'
-
- 'pending' 'pending-held' 'successful-ok' - needed resources
- are not ready
-
- 'pending-held' 'pending-held' 'successful-ok'
-
- 'pending-held' 'pending' 'successful-ok' - needed resources
- are ready
-
- 'processing' 'processing' 'successful-ok' or 'client-error-
- not-possible' depending on
- implementation, including the
- attributes being set, whether the
- job has started marking media,
- etc.
-
- 'processing- 'processing- 'successful-ok' or 'client-error-
- stopped' stopped' not-possible' depending on
- implementation, including the
- attributes being set, whether the
- job has started marking media,
- etc.
-
- 'completed' 'completed' 'client-error-not-possible'
-
- 'canceled' 'canceled' 'client-error-not-possible'
-
- 'aborted' 'aborted' 'client-error-not-possible'
-
-
-
-Hastings, et. al. Standards Track [Page 15]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- This operation MUST NOT change the value of attributes not specified
- in the operation unless the definition of the attribute explicitly
- specifies such side-effects. In general, Job attribute definitions
- that are settable will not define side-effects on other attributes
- that are settable, only side effects on READ-ONLY attributes, if any.
-
-4.2.1 Settable and READ-ONLY Job Description attributes
-
- If the Printer supports the "job-message-from-operator" Job
- Description attribute (see [RFC2911] section 4.3.16) and the client
- explicitly supplies a new value for the "job-message-from-operator"
- Job Description attribute in Group 2 in the Set-Job-Attributes
- request, then the Printer MUST set the "job-message-from-operator"
- Job Description attribute to this new value.
-
- If the Printer supports the Set-Job-Attributes operation, then it
- SHOULD support the setting of:
-
- all Job Template job ("xxx") attributes
-
- that the implementation supports (see [RFC2911] section 4.2 and
- extensions).
-
- Some Job Description attributes (see [RFC2911] section 4.3) MUST NOT
- be settable, i.e., they are defined to be READ-ONLY. An attribute
- marked as "READ-ONLY" in the Job Description attribute table in
- Appendix A is such an attribute. The Job attributes not marked as
- "READ-ONLY" MAY be settable using the Set-Job-Attributes operation,
- depending on implementation.
-
- Note: From now on, all extensions that define new object attributes
- will indicate whether or not the attributes are READ-ONLY, by
- including the "READ-ONLY" adjective in their descriptions and/or
- explicitly stating whether they MAY be settable.
-
- Access Rights: The authenticated user (see [RFC2911] section 8.3)
- performing this operation must either be the job owner (as determined
- in the Job Creation operation) or an operator or administrator of the
- Printer object (see [RFC2911] Sections 1 and 8.5).
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 16]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-4.2.2 Set-Job-Attributes Request
-
- The following sets of attributes are part of the Set-Job-Attributes
- Request:
-
- Group 1: Operation Attributes
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in [RFC2911], section 3.1.4.1.
-
- Target:
- Either (1) the "printer-uri" (uri) plus "job-id"
- (integer(1:MAX)) or (2) the "job-uri" (uri) operation
- attribute(s), which defines the target for this operation as
- described in [RFC2911], section 3.1.5.
-
- Requesting User Name:
- The "requesting-user-name" (name(MAX)) attribute SHOULD be
- supplied by the client, as described in [RFC2911], section 8.3.
-
- Group 2: Job Attributes
-
- The client MUST supply a set of Job attributes with one or more
- values (including explicitly allowed out-of-band values) as
- defined in [RFC2911], section 4.2, Job Template Attributes ("xxx"
- attributes), section 4.3, Job Description Attributes, and any
- attribute extensions supported by the Printer. The value(s) of
- each Job attribute supplied in Group 2 replaces the value(s) of
- the corresponding Job attribute on the target Job object. For
- attributes that can have multiple values (1setOf), all values
- supplied by the client replace all values of the corresponding Job
- object attribute.
-
- If the client supplies an "xxx" attribute with the 'delete-
- attribute' out-of-band value (see section 8.2), the Printer MUST
- remove the "xxx" attribute from the Job object, if present.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 17]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-4.2.3 Set-Job-Attributes Response
-
- The IPP object returns the following sets of attributes as part of
- the Set-Job-Attributes Response:
-
- Group 1: Operation Attributes
-
- Status Message:
- In addition to the REQUIRED status code returned in every
- response, the response OPTIONALLY includes a "status-message"
- (text(255)) and/or a "detailed-status-message" (text(MAX))
- operation attribute as described in [RFC2911], sections 3.1.6
- and 13.
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in [RFC2911], section 3.1.4.2.
-
- Group 2: Unsupported Attributes
-
- See [RFC2911], section 3.1.7, for details on returning Unsupported
- Attributes.
-
- If some of the attributes in the operation fail to validate, the
- Printer MUST reject the operation, MUST NOT change any Job
- attributes, and MUST return the indicated status code below. In
- this group, the Printer MUST also return all attributes that fail
- to validate. The following are the reasons that an attribute
- fails to validate and the value returns for the attribute, along
- with the indicated status code and order of detection:
-
- 1. The number of attributes supplied by the client exceeds the
- maximum number that the Printer supports in a Set-Printer-
- Attributes request: return the 'client-error-request-entity-
- too-large' (see [RFC2911], section 13.1.4.9).
-
- 2. The Printer doesn't support the attribute: return the attribute
- with the 'unsupported' out-of-band attribute value (see
- [RFC2911], section 3.1.7 and [RFC2910]) and the 'client-error-
- attributes-or-values-not-supported (see [RFC2911], section
- 13.1.4.12).
-
- 3. The attribute is READ-ONLY (in its definition) or is not-
- settable in this implementation: return the attribute with the
- 'not-settable' out-of-band attribute value (see section 8.1)
- and the 'client-error-attributes-not-settable' status code (see
- section 7.1).
-
-
-
-
-Hastings, et. al. Standards Track [Page 18]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- 4. The Printer doesn't support the value: if the attribute in the
- operation has a single value return it. If the attribute in
- the operation is multi-valued, return only those values in a
- 1setOf that are not supported. Return the 'client-error-
- attributes-or-values-not-supported' status code (see [RFC2911],
- section 13.1.4.12).
-
- 5. The values of some of the supplied attributes conflict with one
- another and/or other Job attribute values not being set: if
- the conflicting attribute in the operation has a single value,
- return the attribute and the value. If the attribute in the
- operation is multi-valued, return only the attribute and those
- values in a 1setOf that are conflicting with other attributes.
- Return the 'client-error-conflicting-attributes' status code
- (see [RFC2911],y section 13.1.4.15).
-
-4.3 Get-Printer-Supported-Values Operation
-
- This OPTIONAL operation allows a client to request the values that
- the Printer allows in the Set-Printer-Attributes operation for "xxx-
- supported" attributes. If the Printer supports the Set-Printer-
- Attributes operation AND some of its "xxx-supported" Printer
- attributes are settable, then the Printer MUST also support this
- operation.
-
- The Printer MUST return in the Get-Printer-Supported-Values response,
- those, and only those, "xxx-supported" Printer attributes that it
- supports setting with the Set-Printer-Attributes operation.
- Furthermore, if a client requests the value of an attribute that is
- not settable or is not supported (as in the Get-Printer-Attributes
- response), the Unsupported Attributes Group of the response NEED NOT
- contain the "requested-attributes" operation attribute with any such
- requested (attribute keyword) values.
-
- This operation has identical request/response attributes to the Get-
- Printer-Attributes operation in IPP/1.1 [RFC2911]. The operation
- also behaves identically to the Get-Printer-Attributes operation in
- IPP/1.1 [RFC2911], with the following exceptions:
-
- 1. The Get-Printer-Supported-Values operation supports only "xxx-
- supported" attributes.
-
- 2. The Get-Printer-Attributes operation returns the few "xxx-
- supported" attributes that are defined to be single valued, such
- as "page-ranges-supported" (boolean) or "pdl-override-supported"
- (type2 keyword), as single values, while Get-Printer-Supported-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 19]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Values returns the possible values that can be set as a 1setOf of
- the same attribute syntax type (See Appendix B: Attributes
- returned from Get-Printer-Supported-Values).
-
- 3. The Get-Printer-Attributes operation returns the current values of
- requested attributes, while the Get-Printer-Supported-Values
- operation returns the values that are inherently supported by the
- implementation code, i.e., the values that an administrative
- client can set in a Set-Printer-Attributes request.
-
- 4. The Get-Printer-Attributes operation returns the current values of
- requested "xxx-supported" attributes that the Printer is
- configured to accept in Job Creation operations, including
- additional values defined by the administrator, while the Get-
- Printer-Supported-Values operation returns only the values of
- "xxx-supported" attributes that are inherently supported by the
- implementation and does not return any additional values defined
- by the administrator, where the implementation supports the
- 'admin-define' out-of-band value.
-
- 5. The Get-Printer-Attributes never returns the 'admin-define' out-
- of-band attribute value, while the Get-Printer-Supported-
- Attributes operation does, if the implementation allows the
- administrator to define name values by setting that "xxx-
- supported" attribute with any 'name' value(s).
-
- 6. The Get-Printer-Attributes operation only requires end-user access
- rights, while the Get-Printer-Supported-Values requires
- administrator access rights.
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation must be an administrator of the Printer
- object (see [RFC2911], Sections 1 and 8.5).
-
-4.3.1 Definition of the usage of the 'admin-define' out-of-band
- attribute value
-
- If the Set-Printer-Attributes operation allows the System
- Administrator to define arbitrary 'name' values for an "xxx-
- supported" attribute, then the Get-Printer-Supported-Values operation
- MUST return the 'admin-define' out-of-band attribute value (see
- section 8.3) as one of the values of the "xxx-supported" attribute.
- In other words, the 'admin-define' out-of-band attribute value
- indicates that the Printer implementation supports clients setting
- arbitrary 'name' attribute syntax values for that "xxx-supported"
- attribute using the Set-Printer-Attributes operation, as long as the
- attribute is defined with the 'name' attribute syntax.
-
-
-
-
-Hastings, et. al. Standards Track [Page 20]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- For example, if the Get-Printer-Supported-Values operation returns
- several keywords as the value of the "media-supported" attribute,
- then the Set-Printer-Attributes operation MUST accept any of these
- keywords as values for the "media-supported" attribute. If the Get-
- Printer-Supported-Values operation returns an 'admin-define' out-of-
- band attribute value as one of the values of the "media-supported"
- attribute, then the Set-Printer-Attributes operation MUST accept any
- value whose attribute syntax is 'name', as a value for the "media-
- supported" attribute (provided that the user is properly
- authenticated to use the Set-Printer-Attributes operation, e.g., has
- administrative access rights).
-
- The Get-Printer-Supported-Values MAY return the 'admin-define' out-
- of-band attribute value for any IPP/1.1 or extension Job Template
- attribute if the implementation supports allowing the System
- Administrator to add values to the "xxx-supported" attribute using
- the Set-Printer-Attributes operation. In this case, the Printer MUST
- accept any 'name' value of the correct attribute syntax in a Set-
- Printer-Attributes operation that is setting that attribute. For
- "xxx-supported" attributes that are defined with a choice of
- attribute syntaxes, such as 'keyword | name', it is the 'name'
- attribute syntax that the System Administrator can use to add new
- values, not the 'keyword' attribute syntax. For IPP/1.1, this
- requirement includes the following Job Template attributes:
-
- media-supported
- job-hold-until-supported
- job-sheets-supported
-
- Implementations that support additional Job Template attributes that
- include the 'name' attribute syntax, MAY use the 'admin-define' out-
- of-band value with them.
-
- If the 'admin-define' out-of-band attribute value is not one of the
- values of an "xxx-supported" attribute returned in a Get-Printer-
- Supported-Values response, then the Printer MUST NOT allow the Set-
- Printer-Attributes operation for that attribute to contain a value
- that is not one of the explicit 'keyword' or 'name' values returned
- in a Get-Printer-Supported-Values response.
-
- See Appendix B: Attributes returned from Get-Printer-Supported-Values
- for a full list of values returned by this operation.
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 21]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-5 New Operation attributes
-
- This section defines new operation attributes for use with the
- IPP/1.1 operations indicated. As new operations are defined, they
- will also indicate explicitly whether these operation attributes are
- defined for use with them.
-
-5.1 printer-message-from-operator (text(127))
-
- The Printer SHOULD support this Operation attribute in following
- operations if it supports the corresponding "printer-message-from-
- operator" Printer Description attribute.
-
- Pause-Printer
- Resume-Printer
- Purge-Jobs
-
- The client OPTIONALLY supplies this Operation attribute in the above
- operations. The value of this attribute is a message from the
- operator about the Printer object on which the operator is performing
- the operation. If this operation attribute is supported, the Printer
- copies the value to its "printer-message-from-operator" Printer
- Description attribute (see [RFC2911], section 4.4.25), even if this
- Operation attribute is a zero-length text value or consists solely of
- white space.
-
- If the Printer supports this operation attribute, it MUST support
- both a zero-length text value and the 'no-value' out-of-band value
- (see [RFC2911] section 4.1) to indicate that the operator has sent no
- message. In this case, the Printer sets the value of the "printer-
- message-from-operator" to the zero-length value or 'no-value' out-
- of-band value, respectively. If the client queries the "printer-
- message-from-operator" Printer attribute, the Printer returns the
- attribute with the zero-length value or the 'no-value' value,
- respectively.
-
- In addition, the Printer automatically copies:
-
- 1. the value of its "printer-up-time" attribute (see [RFC2911],
- section 4.4.29) to its "printer-message-time" attribute,
-
- 2. the value of its printer-current-time" (dateTime) attribute (see
- [RFC2911], section 4.4.30) to its "printer-message-date-time"
- attribute, if supported.
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 22]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- If the client omits this operation attribute, the Printer does not
- change the value of its "printer-message-from-operator", "printer-
- message-time" and "printer-message-date-time" Printer Description
- attributes.
-
- The "printer-message-from-operator" operation attribute MUST NOT be
- supported as an operation attribute for the Set-Printer-Attributes
- operation. If the operator wants to set the Printer's "printer-
- message-from-operator" Printer Description attribute when issuing the
- Set-Printer-Attributes operation, the client supplies the "printer-
- message-from-operator" explicitly with its new value as one of the
- Printer Description attributes in Group 2 in the request; the Printer
- also updates its "printer-message-time" and "printer-message-date-
- time" Printer Description attributes. If the client does not
- explicitly supply the "printer-message-from-operator" with its new
- value in the Set-Printer-Attributes request, the Printer leaves the
- value of the Printer's "printer-message-from-operator" Printer
- Description attribute unchanged.
-
-5.2 job-message-from-operator (text(127))
-
- The Printer SHOULD support this Operation attribute in following
- operations if it supports the corresponding "job-message-from-
- operator" Job Description attribute.
-
- Cancel-Job
- Hold-Job
- Release-Job
- Restart-Job
-
- The client OPTIONALLY supplies this attribute in the above
- operations. The value of this attribute is a message from the
- operator about the Job object on which the operator has just
- performed an operation. If supported, the Printer copies the value
- to the Job's "job-message-from-operator" Job Description attribute
- (see [RFC2911], section 4.3.16) (even if this Operation attribute is
- a zero-length text value or consists solely of white space).
-
- If the Printer supports this operation attribute, it MUST support
- both a zero-length text value and the 'no-value' out-of-band value
- (see [RFC2911], section 4.1), to indicate that the operator has sent
- no message. In this case, the Printer sets the value of the "job-
- message-from-operator" to the zero-length value or 'no-value' out-
- of-band value, respectively. If the client queries the "job-
- message-from-operator" Job attribute, the IPP object returns the
- attribute with the zero-length value or the 'no-value' value,
- respectively.
-
-
-
-
-Hastings, et. al. Standards Track [Page 23]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- If the client omits this attribute, the Printer does not change the
- value of its "job-message-from-operator" Job Description attribute.
-
- Note: There are no corresponding 'job-message-time" and "job-
- message-date-time" Job Description attributes, since the usual
- lifetime of a job is limited.
-
- The "job-message-from-operator" operation attribute MUST NOT be
- supported as an operation attribute for the Set-Job-Attributes
- operation. If the operator wants to set the Job's "job-message-
- from-operator" Job Description attribute when issuing the Set-Job-
- Attributes operation, the client MUST supply the "job-message-from-
- operator" with its new value as one of the Job Description attributes
- in Group 2 in the request. Otherwise, the Printer leaves the value
- of the Job's "job-message-from-operator" Job Description attribute
- unchanged by not explicitly setting the attribute. If the client
- does not explicitly supply the "job-message-from-operator" with its
- new value in the Set-Job-Attributes request, the Printer leaves the
- value of the Job's "job-message-from-operator" Job Description
- attribute unchanged.
-
-6 New Printer Description Attributes
-
- The following new Printer Description attributes are needed to
- support the new operations defined in this document.
-
-6.1 printer-settable-attributes-supported (1setOf type2 keyword)
-
- This REQUIRED READ-ONLY Printer Description attribute identifies the
- Printer object attributes that are settable in this implementation,
- i.e., that are settable using the Set-Printer-Attributes operations
- (see section 4.1). This attribute MUST be supported if the Set-
- Printer-Attributes operations is supported. The Printer MUST reject
- attempts to set any Printer attributes that are not one of the values
- of this attribute, returning the 'client-error-attributes-not-
- settable' status code (see section 7.1). The value of this attribute
- MAY depend on the value of the "document-format" operation attribute
- supplied in the Get-Printer-Attributes operation (see [RFC2911],
- section 3.2.5.1).
-
- Standard keyword values are:
-
- 'none': There are no settable Printer attributes.
- 'xxx': Where 'xxx' is any of the keyword attribute names allowed
- by section 4.1.1.
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 24]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-6.2 job-settable-attributes-supported (1setOf type2 keyword)
-
- This REQUIRED READ-ONLY Printer Description attribute identifies the
- Job object attributes that are settable in this implementation, i.e.,
- that are settable using the Set-Job-Attributes operation (see section
- 4.2). This attribute MUST be supported if the Set-Job-Attributes
- operations are supported. The Printer MUST reject attempts to set
- any Job attributes that are not one of the values of this attribute,
- returning the 'client-error-attributes-not-settable' status code (see
- section 7.1).
-
- Standard keyword values are:
-
- 'none': There are no settable Job attributes.
- 'xxx': Where 'xxx' is any of the keyword attribute names allowed
- by section 4.2.1.
-
-6.3 document-format-varying-attributes (1setOf type2 keyword)
-
- This OPTIONAL READ-ONLY Printer Description attribute contains a set
- of attribute name keywords. This attribute SHOULD be supported by a
- Printer object if the Printer object has Printer attributes whose
- value vary depending on document format (see [RFC2911], Get-Printer-
- Attributes operation). This attribute specifies which attribute
- values can vary by document-format. If an attribute's name, "xxx",
- is a member of this attribute and the value of attribute "xxx" is
- changed with the Set-Printer-Attributes operation that included the
- "document-format" operation attribute, then the Printer MUST change
- the value for the specified document format and no other document
- formats (see section 4.1.2). If an attribute's name, "xxx", is not a
- member of this attribute and the value of attribute "xxx" is changed
- with the Set-Printer-Attributes operation, then the attribute is
- changed for all document formats (whether or not the client supplied
- the "document-format" operation attribute).
-
-6.4 printer-message-time (integer(MIN:MAX))
-
- This OPTIONAL READ-ONLY Printer Description attribute contains the
- time that the Printer's "printer-message-from-operator" was changed
- by the operator using any operation where the client supplied the
- "printer-message-from-operator" operation attribute (see section 5.1)
- or was explicitly set using the Set-Printer-Attributes operation (see
- section 4.1). This attribute allows the users to know when the
- "printer-message-from-operator" Printer Description attribute was
- last set.
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 25]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- The Printer sets the value of this attribute by copying the value of
- the Printer's "printer-up-time" attribute (see [RFC2911], section
- 4.3.14). If the Printer resets its "printer-up-time" attribute to 1
- on power-up, then it MUST change the value of the "printer-message-
- time" to 0 or a negative number as specified in [RFC2911], section
- 4.3.14.
-
- Note: This attribute helps users better understand the context for
- the "printer-message-from-operator" message.
-
-6.5 printer-message-date-time (dateTime)
-
- This OPTIONAL READ-ONLY Printer Description attribute contains the
- date and time that the Printer's "printer-message-from-operator" was
- changed by the operator, using any operation where the client
- supplied the "printer-message-from-operator" operation attribute (see
- section 5.1) or was explicitly set using the Set-Printer-Attributes
- operation (see section 4.1). This attribute allows the users to know
- when the "printer-message-from-operator" Printer Description
- attribute was last set.
-
- This attribute MUST be supported if the Printer supports both the
- "printer-message-time" and the "printer-current-time" (dateTime)
- attributes (see [RFC2911], section 4.4.30).
-
- Note: This attribute helps users better understand the context for
- the "printer-message-from-operator" message.
-
-6.6 printer-xri-supported (1setOf collection)
-
- This OPTIONAL Printer Description attribute is a multi-valued
- attribute where each value has the 'collection' attribute syntax (see
- [RFC3382]), containing member attributes with the same semantics as
- the following IPP/1.1 READ-ONLY Printer Description attributes,
- except for cardinality:
-
- printer-uri-supported (1setOf uri)
- - see [RFC2911], section 4.4.1
- uri-authentication-supported (1setOf type2 keyword)
- - see [RFC2911], section 4.4.2.
- uri-security-supported (1setOf type2 keyword)
- - see [RFC2911], section 4.4.3.
-
- When setting the "printer-xri-supported" attribute with a Set-
- Printer-Attributes request, the Printer MUST also set these three
- IPP/1.1 READ-ONLY Printer Description attributes as a defined side
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 26]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- effect. Thus, this collection attribute provides the means to set
- these three IPP/1.1 READ-ONLY attributes atomically so that they are
- never left in a partially inconsistent state.
-
- An IPP Printer MUST NOT provide any other way, using IPP, to set
- these three IPP/1.1 READ-ONLY Printer Description attributes, since
- they are READ-ONLY and MUST have consistent values at all times.
- Note: The "printer-xri-supported" (1setOf collection) attribute can
- be put into a directory schema that requires a single text string
- value, such as could be used with SLPv2 [RFC2608], [RFC2609] or
- LDAPv3 [RFC2251], [RFC2252], [RFC2926], by using suitable delimiting
- characters to separate member attributes of the collection and/or
- terminating collection values.
-
- The member attributes of the "printer-xri-supported" (1setOf
- collection) are given in Table 3.
-
- Table 3 - Member attributes of "printer-xri-supported" (1setOf
- collection)
-
- Member attribute client Printer
- MUST MUST
- supply support
-
- xri-uri (uri) yes yes
-
- xri-authentication (type2 keyword) yes yes
-
- xri-security (type2 keyword) yes yes
-
- Other than the uniqueness and the cardinality requirements, the
- semantics of these three member attributes is given in [RFC2911]
- sections 4.4.1, 4.4.2, and 4.4.3, respectively.
-
- A client can query the current values using the Get-Printer-
- Attributes operation by supplying either:
-
- 1. the three IPP/1.1 attribute names: "printer-uri-supported", "uri-
- authentication-supported", "uri-security-supported" and getting
- back the parallel values OR
-
- 2. the single attribute name: "printer-xri-supported" and getting
- back the 1setOf collection which contains the same information
- semantically, but in a different form.
-
- A client can query what member attribute values can be set by
- supplying the three attribute names: "xri-uri-scheme-supported",
- "xri-authentication-supported", and "xri-security-supported" in a
-
-
-
-Hastings, et. al. Standards Track [Page 27]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Get-Printer-Supported-Values request and getting back the uriScheme
- and type2 keyword values that can be set. Since the "printer-xri-
- supported", "uri-authentication-supported", and "uri-security-
- supported" attributes are READ-ONLY, they are not queriable with the
- Get-Printer-Supported-Values operation (see section 4.3). See Table
- 16.
-
- For example:
-
- "printer-xri-supported =
- { "xri-uri" = ipp://abc.com/p1
- "xri-authentication" = basic
- "xri-security" = tls
- },
- { "xri-uri" = ipp://abc.com/p2
- "xri-authentication" = digest
- "xri-security" = tls
- },
- { "xri-uri" = ipp://abc.com/p3
- "xri-authentication" = none
- "xri-security" = none
- }
-
- would cause the Printer to set the three corresponding IPP/1.1 READ-
- ONLY attributes, each with three parallel values as follows:
-
- "printer-uri-supported" = { ipp://abc.com/p1, ipp://abc.com/p2,
- ipp://abc.com/p3 }
- "uri-authentication-supported" = { basic, digest, none }
- "uri-security-supported" = { tls, tls, none }
-
-6.7 xri-uri-scheme-supported (1setOf uriScheme)
-
- This OPTIONAL READ-ONLY Printer Description attribute identifies the
- URI schemes that the implementation supports for use in the
- "printer-uri-supported" (1setOf uri) Printer Description attribute
- (see [RFC2911] section 4.4.1) and the "xri-uri" member attribute of
- the "printer-xri-supported" (1setOf collection) Printer Description
- attribute (see section 6.6).
-
- A Printer MUST support this attribute if it supports the setting of
- the "printer-xri-supported" (1setOf collection) with the Set-
- Printer-Attributes operation.
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 28]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-6.8 xri-authentication-supported (1setOf type2 keyword)
-
- This OPTIONAL READ-ONLY Printer Description attribute identifies the
- Client Authentication mechanisms that the implementation supports for
- use in the "uri-authentication-supported" (1setOf type2 keyword)
- Printer Description attribute (see [RFC2911], section 4.4.2) and the
- "xri-authentication" member attribute of the "printer-xri-supported"
- (1setOf collection) Printer Description attribute (see section 6.6).
-
- A Printer MUST support this attribute if it supports setting the
- "printer-xri-supported" (1setOf collection) with the Set-Printer-
- Attributes operation.
-
-6.9 xri-security-supported (1setOf type2 keyword)
-
- This OPTIONAL READ-ONLY Printer Description attribute identifies the
- URI schemes that the implementation supports for use in the "uri-
- security-supported" (1setOf type2 keyword) Printer Description
- attribute (see [RFC2911], section 4.4.3) and the "xri-security"
- member attribute of the "printer-xri-supported" (1setOf collection)
- Printer Description attribute (see section 6.6).
-
- A Printer MUST support this attribute if it supports setting the
- "printer-xri-supported" (1setOf collection) with the Set-Printer-
- Attributes operation.
-
-7 Additional status codes
-
- This section defines new status codes used by the operations defined
- in this document.
-
-7.1 client-error-attributes-not-settable (0x0413)
-
- The Set-Printer-Attributes or Set-Job-Attributes operation failed
- because one or more of the specified attributes cannot be set, either
- because the attribute is defined to be READ-ONLY or the attribute is
- not settable in this implementation (see sections 4.1.3 and 4.2.3).
- The Printer MUST return this error code and the attribute keyword
- name(s) and the 'not-settable' out-of-band value (see section 8.1) in
- the Unsupported Attributes Group (see [RFC2911], section 3.1.7) for
- all of the attributes that could not be set. When the Printer
- returns this status, it MUST NOT change any of the attributes
- supplied in the operation.
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 29]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-8 Additional out-of-band values
-
- This section defines additional out-of-band values. As with all
- out-of-band values, a client or a Printer MUST NOT use an out-of-band
- value unless the definition of the attribute in an operation request
- and/or response explicitly allows such usage. See the beginning of
- [RFC2911], section 4.1.
-
-8.1 'not-settable' out-of-band value
-
- The 'not-settable' out-of-band attribute value is returned by the IPP
- Printer in the Unsupported Attributes group of a response to indicate
- that the attribute supplied by the client in the request is READ-ONLY
- by definition or is not settable in this implementation.
-
- The 'not-settable' out-of-band attribute value is defined for use
- with the Set-Job-Attributes and Set-Printer-Attributes responses
- only. If a future additional "set" operation allows the 'not-
- settable' out-of-band value, its definition document MUST indicate
- such use explicitly, including with which attributes.
-
- An IPP object MUST support the 'not-settable' out-of-band value in a
- Set-Job-Attributes or Set-Printer-Attributes request if it supports
- those operations. A client MUST NOT supply the 'not-settable' out-
- of-band value in any request. An IPP object MUST NOT support the
- 'not-settable' out-of-band value in other operations, unless the
- operations' definition document explicitly defines such usage. If a
- Printer receives this out-of-band value in any operation request, the
- Printer MUST either (1) reject the entire request and return the
- 'client-error-bad-request' status code or (2) ignore the attribute
- and return it with the 'unsupported' out-of-band value.
-
- See sections 4.1.3 and 4.2.3 in this document for an example
- definition of the usage of the 'not-settable' out-of-band value in
- the Set-Printer-Attributes and Set-Job-Attributes responses.
-
-8.1.1 Encoding of the 'not-settable' out-of-band attribute value
-
- The encoding of the 'not-settable' out-of-band value is 0x15 (see
- [RFC2910]). The value-length MUST be 0 and the value empty.
-
-8.2 'delete-attribute' out-of-band value
-
- The 'delete-attribute' out-of-band attribute value is supplied by the
- client in a request to indicate that the Printer is to remove the
- supplied attribute and all of its values from the target object, if
- present.
-
-
-
-
-Hastings, et. al. Standards Track [Page 30]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- The 'delete-attribute' out-of-band attribute value is defined for use
- with the Set-Job-Attributes request only. If a future additional
- "set" operation allows the 'delete-attribute' out-of-band value, its
- definition document MUST indicate such use explicitly, including with
- which attributes.
-
- An IPP Printer MUST support the 'delete-attribute' out-of-band value
- if it supports the Set-Job-Attributes operation. A client MUST NOT
- supply, and an IPP object MUST NOT support, the 'delete-attribute'
- out-of-band value in other operations, unless the operations'
- definition document explicitly defines such usage. For example, the
- 'delete-attribute' out-of-band value MUST NOT be used in the Set-
- Printer-Attributes operation, where the absence of an attribute from
- an IPP object indicates that the attribute is not supported. If a
- Printer receives this out-of-band value in other operation requests,
- the Printer MUST either (1) reject the entire request and return the
- 'client-error-bad-request' status code or (2) ignore the attribute
- and return it with the 'unsupported' out-of-band value.
-
- See section 4.2 in this document for the definition of the usage of
- the 'delete-attribute' out-of-band value in the Set-Job-Attributes
- request.
-
-8.2.1 Encoding of the 'delete-attribute' out-of-band value
-
- The encoding of the 'delete-attribute' out-of-band value is 0x16 (see
- [RFC2910]). The value-length MUST be 0 and the value empty.
-
-8.3 'admin-define' out-of-band attribute value
-
- Section 4.3 defines the Get-Printer-Supported-Values response to
- contain the values of an "xxx-supported" attribute that are supported
- by the implementation before any additional values are defined by the
- administrator. The 'admin-define' out-of-band attribute value is
- returned as an additional value of an "xxx-supported" attribute in a
- Get-Printer-Supported-Values response to indicate that the
- implementation supports allowing an administrator to define
- additional arbitrary 'name' values for that "xxx-supported"
- attribute.
-
- For example, if the "media-supported" (1setOf (type3 keyword | name))
- attribute contains this value, then the Printer MUST permit an
- administrator to add new media names to the Printer's "media-
- supported" attribute. In order for an administrator to add new
- values to a Printer's "xxx-supported" attribute, the client supplies
- the existing and new values in a Set-Printer-Attributes request for
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 31]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- that attribute. The client MUST supply any such administratively
- defined values in the Set-Printer-Attributes request, using the
- 'name' attribute syntax.
-
- The 'admin-define' out-of-band attribute value is defined for use
- with the Get-Printer-Supported-Values response only. A Printer MUST
- NOT return the 'admin-define' out-of-band value in a Get-Printer-
- Attributes response, since such a response indicates what an end-user
- client can supply in a Job Creation operation. If a future
- additional "get" operation allows the 'admin-define' out-of-band
- value, its definition document MUST indicate such use explicitly,
- including with which attributes.
-
- An IPP Printer MUST support the 'admin-define' out-of-band value, if
- it supports a client setting arbitrary 'name' values of an "xxx-
- supported" Printer attribute using the Set-Printer-Attributes
- operation. A client MUST NOT supply the 'admin-define' out-of-band
- value in any request. An IPP object MUST NOT support the 'admin-
- define' out-of-band value in other operations, unless the operations'
- definition document explicitly defines such usage. If a Printer
- receives this out-of-band value in any operation request, the Printer
- MUST either (1) reject the entire request and return the 'client-
- error-bad-request' status code or (2) ignore the attribute and return
- it with the 'unsupported' out-of-band value.
-
- This document defines that the 'admin-define' out-of-band value MUST
- be used only with "xxx-supported" attributes that are defined to
- include the 'name' attribute syntax. This out-of-band value is not
- intended to be used with "xxx-supported" attributes of other
- attribute syntaxes, such as 'uri', even though the administrator
- defines arbitrary values for such attributes. If other documents
- extend the use of the 'admin-define' out-of-band value to other
- attribute syntaxes, such a document MUST define such use explicitly,
- including with which attributes.
-
- See section 4.3 in this document for an example definition of the
- usage of the 'admin-define' out-of-band attribute value in any "xxx-
- supported" attribute returned in a Get-Printer-Supported-Values
- response that is defined to include the 'name' attribute syntax.
-
-8.3.1 Encoding of the 'admin-define' out-of-band attribute value
-
- The encoding of the 'admin-define' out-of-band attribute value is
- 0x17 (see [RFC2910]). The value-length MUST be 0 and the value
- empty.
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 32]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-9 New Values for Existing Printer Description Attributes
-
- This section contains those attributes for which additional values
- are added.
-
-9.1 operations-supported (1setOf type2 enum)
-
- The following "operation-id" values are added in order to support the
- new operations defined in this document:
-
- Table 4 - Operation-id assignments
-
- Value Operation Name
-
- 0x0013 Set-Printer-Attributes
-
- 0x0014 Set-Job-Attributes
-
- 0x0015 Get-Printer-Supported-Values
-
-10 Conformance Requirements
-
- This section specifies the conformance requirements for clients and
- IPP objects.
-
- Both the Set-Job-Attributes and the Set-Printer-Attributes operations
- defined in the document are OPTIONAL for an IPP object to support.
- Either one MAY be supported without the other or both MAY be
- supported. However, if the Set-Printer-Attributes operation is
- supported, then the Get-Printer-Supported-Values operation MUST be
- supported if any "xxx-supported" attributes are settable. Otherwise,
- the Get-Printer-Supported-Values operation is OPTIONAL for an IPP
- Printer to support.
-
- If the Set-Printer-Attributes operation is supported, then the
- Printer MUST support the following additional items:
-
- 1. the Get-Printer-Supported-Values operation (see section 5), if
- any "xxx-supported" attributes are settable.
-
- 2. the "printer-settable-attributes-supported" Printer Description
- attribute (see section 6.1).
-
- 3. the 'not-settable' out-of-band value in responses (see section
- 8.1).
-
- 4. the 'client-error-not-settable' status code (see section 7.1).
-
-
-
-
-Hastings, et. al. Standards Track [Page 33]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- 5. if the "printer-message-from-operator" Printer Description
- attribute is supported (see [RFC2911], section 4.4.25), then it
- MUST be settable.
-
- 6. the Get-Printer-Supported-Values operation (see section 4.3),
- if any "xxx-supported" attributes are settable.
-
- 7. If a client can set a value with the 'name' attribute syntax
- for one or more "xxx-supported" attributes, then the 'admin-
- define' out-of-band attribute value (see section 8.3) MUST be
- supported in the Get-Printer-Supported-Values response for each
- such settable attribute (see section 4.3)
-
- If the Set-Job-Attributes operation is supported, then the Printer
- MUST support the following additional items:
-
- 1. the "job-settable-attributes-supported" Printer Description
- attribute (see section 6.2).
-
- 2. the 'not-settable' out-of-band value in responses (see section
- 8.1).
-
- 3. the 'delete-attribute' out-of-band value in requests (see
- section 8.2).
-
- 4. the 'client-error-not-settable' status code (see section 7.1).
-
- 5. if the "job-message-from-operator" Printer Description
- attribute is supported (see [RFC2911], 4.3.16), then it MUST be
- settable.
-
- It is OPTIONAL for the Printer object to support the "printer-
- message-time" (integer) and "printer-message-date-time" (dateTime)
- Printer Description attributes. If both the "printer-message-time"
- (integer) and the "printer-current-time" (dateTime) (see [RFC2911],
- section 4.4.30) attributes are supported, then the "printer-message-
- date-time" (dateTime) Printer Description attribute MUST be
- supported.
-
- As with all out-of-band values, a client or a Printer MUST NOT use an
- out-of-band value, unless the definition document for the attribute
- in an operation request and/or response explicitly allows such usage.
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 34]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-11 IANA Considerations
-
- This section contains registration information for IANA to add to the
- various IPP Registries according to the procedures defined in RFC
- 2911 [RFC2911], section 6. The resulting registrations will be
- published in the http://www.iana.org/assignments/ipp-registrations
- registry.
-
-11.1 Operation Registrations
-
- The following table lists all of the operations defined in this
- document. These are to be registered according to the procedures
- defined in RFC 2911 [RFC2911], section 6.4.
-
- Operations: Ref. Section:
- Set-Printer-Attributes RFC 3380 4.1
- Set-Job-Attributes RFC 3380 4.2
- Get-Printer-Supported-Values RFC 3380 4.3
-
-11.2 Additional Enum Attribute Value Registrations for the
- "operations-supported" Printer Attribute
-
- The following table lists all the new enum attribute values defined
- in this document as additional type2 enum values for use with the
- "operations-supported" Printer Description attribute. These are to
- be registered according to the procedures defined in RFC 2911 [RFC
- 2911], section 6.1.
-
- Enum Attribute Values: Value Ref. Section:
- Set-Printer-Attributes 0x0013 RFC 3380 4
- Set-Job-Attributes 0x0014 RFC 3380 4
- Get-Printer-Supported-Values 0x0015 RFC 3380 4
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 35]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-11.3 Keyword attribute value registrations
-
- The following table lists all of the attributes defined in this
- standard which have keywords values defined:
-
- printer-settable-attributes-supported (1setOf type2 keyword)
- RFC 3380 6.1
- none RFC 3380 6.1
- <Any other Printer attribute keyword name>
- job-settable-attributes-supported (1setOf type2 keyword)
- RFC 3380 6.2
- none RFC 3380 6.2
- <Any other Job attribute keyword name>
- document-format-varying-attributes (1setOf type2 keyword)
- RFC 3380 6.3
- none
- <Any Printer attribute keyword name>
- xri-security-supported (1setOf type2 keyword) RFC 3380 6.9
- none RFC 2911 4.4.3
- ssl3 RFC 2911 4.4.3
- tls' RFC 2911 4.4.3
- xri-authentication-supported (1setOf type2 keyword)
- none RFC 2911 4.4.2
- requesting-user-name RFC 2911 4.4.2
- basic RFC 2911 4.4.2
- digest RFC 2911 4.4.2
- certificate RFC 2911 4.4.2
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 36]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-11.4 Attribute Registrations
-
- The following table lists all of the attributes defined in this
- document. These are to be registered according to the procedures in
- RFC 2911 [RFC2911], section 6.2.
-
- Operation attributes: Ref. Section:
- printer-message-from-operator (text(127)) RFC 3380 5.1
- job-message-from-operator (text(127)) RFC 3380 5.2
-
- Printer Description attributes: Ref. Section:
- printer-settable-attributes-supported (1setOf type2 keyword)
- RFC 3380 6.1
- job-settable-attributes-supported (1setOf type2 keyword)
- RFC 3380 6.2
- document-format-varying-attributes (1setOf type2 keyword)
- RFC 3380 6.3
- printer-message-time (integer(MIN:MAX)) RFC 3380 6.4
- printer-message-date-time (dateTime) RFC 3380 6.5
- printer-xri-supported (1setOf collection) RFC 3380 6.6
- xri-uri (uri) RFC 3380 6.6
- xri-authentication (type2 keyword) RFC 3380 6.6
- xri-security (type2 keyword) RFC 3380 6.6
- xri-uri-scheme-supported (1setOf uriScheme) RFC 3380 6.7
- xri-authentication-supported (1setOf type2 keyword) 6.8
- xri-security-supported (1setOf type2 keyword) RFC 3380 6.9
-
-11.5 Status code Registrations
-
- The following table lists the status code defined in this document.
- This is to be registered according to the procedures in RFC 2911
- [RFC2911], section 6.6.
-
- Status codes: Ref. Section:
- client-error-attributes-not-settable (0x0413) RFC 3380 7.1
-
-11.6 Out-of-band Attribute Value Registrations
-
- The following table lists all of the out-of-band attribute values
- defined in this document. These are to be registered according to
- the procedures in RFC 2911 [RFC2911] section 6.7.
-
- Value: Out-of-band Attribute value name: Ref. Section:
- 0x15 not-settable RFC 3380 8.1
- 0x16 delete-attribute RFC 3380 8.2
- 0x17 admin-define RFC 3380 8.3
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 37]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-12 Internationalization Considerations
-
- This document has the same localization considerations as [RFC2911].
-
-13 Security Considerations
-
- The IPP Model and Semantics document ([RFC2911], section 8) discusses
- high level security requirements (Client Authentication, Server
- Authentication and Operation Privacy). Client Authentication is the
- mechanism by which the client proves its identity to the server in a
- secure manner. Server Authentication is the mechanism by which the
- server proves its identity to the client in a secure manner.
- Operation Privacy is defined as a mechanism for protecting operations
- from eavesdropping.
-
- In addition, the introduction of the Set-Printer-Attributes and Set-
- Job-Attributes operations creates another security threat, since the
- client is able to modify the Printer and Job attributes stored in the
- Printer. Such modifications could lead to denial of service.
-
- A malicious user could alter the policy established by the system
- administrator and stored in the Printer attributes. Such alteration
- could either grant access to more resources or deny access to
- resources that the system administrator has established. For
- example, the malicious user could remove all of the document-format
- values from the "document-format-supported" Printer attribute so that
- the Printer would refuse to accept all jobs.
-
- The general remedy for such malicious user actions against Printer
- attributes is to have strong Client Authentication coupled with
- Printer access control, to limit the users who have System
- Administrator or Operator privileges.
-
- A malicious user could modify the Job Template attributes of another
- user's Job, such as the "copies" attribute. For example, setting the
- number of copies to a large number.
-
- The general remedy for such malicious user actions against another
- user's job is to have strong Client Authentication coupled with
- Printer access control to limit the users who have System
- Administrator or Operator privileges who can modify any job and, in
- addition, store the Client Authentication with each Job so that only
- the job owner End User can modify his/her own job.
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 38]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-14 References
-
-14.1 Normative References
-
- [RFC2565] Herriot, R., Butler, S., Moore, P. and R. Tuner, "Internet
- Printing Protocol/1.0: Encoding and Transport", RFC 2565,
- April 1999.
-
- [RFC2566] deBry, R., Hastings, T., Herriot, R., Isaacson, S. and P.
- Powell, "Internet Printing Protocol/1.0: Model and
- Semantics", RFC 2566, April 1999.
-
- [RFC2910] Herriot, R., Butler, S., Moore, P. and R. Turner,
- "Internet Printing Protocol/1.1: Encoding and Transport",
- RFC 2910, September 2000.
-
- [RFC2911] Hastings, T., Herriot, R., deBry, R., Isaacson, S. and P.
- Powell, "Internet Printing Protocol/1.0: Model and
- Semantics", RFC 2911, September 2000.
-
- [RFC3382] deBry, R., Hastings, T., Herriot, R., Ocke, K. and P.
- Zehler, "Internet Printing Protocol (IPP): The
- 'collection' attribute syntax", RFC 3382, September 2002.
-
-14.2 Informative References
-
- [RFC2251] Wahl, M., Howes, T. abd S. Kille, "Lightweight Directory
- Access Protocol (v3)", RFC 2251, December 1997.
-
- [RFC2252] Wahl, M., Coulbeck, A., Howes, T. and S. Kille,
- "Lightweight Directory Access Protocol (v3): Attribute
- Syntax Definitions", RFC 2252, December 1997.
-
- [RFC2608] Guttman, E., Perkins, C., Veizades, J. and M. Day,
- "Service Location Protocol, Version 2", RFC 2608, June
- 1999.
-
- [RFC2609] Guttman, E., Perkins, C. and J. Kempf, "Service Templates
- and service: Schemes", RFC 2609, June 1999.
-
- [RFC3196] Hastings, T., Manros, C., Zehler, P., Kugler, C. and H.
- Holst, "Internet Printing Protocol/1.1: Implementor's
- Guide", RFC 3196, November 2001.
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 39]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-Appendix A: Allowed Values for Set-Printer-Attributes and
- Set-Job-Attributes requests (Normative)
-
- This appendix is a normative part of this document and contains a
- table of all IPP/1.1 attributes. Each row contains:
-
- - an attribute and
-
- - the values allowed in the Set-Printer-Attributes or Set-Job-
- Attributes request for the attribute. The entry in each cell
- is the name (first few words) of each item below 1, 2, 3, 4a-g,
- and 5.
-
- The allowed values include the following cases:
-
- 1. READ-ONLY: the Set-Printer-Attributes or Set-Job-Attributes
- operation MUST NOT change this attribute and MUST reject the
- entire operation (see section 7.1).
-
- 2. Any of "xxx-supported": the Set-Printer-Attributes or Set-
- Job-Attributes operation accepts values that are allowed
- according to the IPP/1.1 rules for validating the value(s) of
- an "xxx" Printer or Job attribute against the value(s) of the
- corresponding "xxx-supported" Printer attribute. Table 5
- summarizes those validation rules depending on each attribute
- syntax and value of an "xxx" attribute supplied in the request
- and that of the corresponding "xxx-supported" Printer
- attribute. The "xxx-supported" attribute syntax type and
- value(s) are obtained from a Get-Printer-Supported-Values
- response (see the tables in this Appendix).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 40]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Table 5 - Validation rules for 'Any of "xxx-supported" '
-
- Type of "xxx" Type of "xxx- Validates if:
- value to be supported" value
- set
-
- integer rangeOfInteger each value is in one of the
- "xxx-supported" ranges
-
- uri uriScheme each uri scheme matches one
- of the "xxx-supported"
- schemes
-
- any boolean if the boolean "xxx-
- supported" is 'true'
-
- any same type each value matches an "xxx-
- supported" value of the same
- type
-
- For additional non-normative explanatory information see section
- 3.1.2.3 of the "Internet Printing Protocol/1.1: Implementer's Guide"
- [RFC3196].
-
- 3. From Get-Printer-Supported-Values: the Set-Printer-Attributes
- operation accepts values that are allowed according to the
- IPP/1.1 rules for validating the value(s) of an "xxx" Printer
- attribute against the value(s) of the corresponding "xxx-
- supported" Printer attribute. Table 6 summarizes those
- validation rules depending on each attribute syntax and value
- of an "xxx" attribute supplied in the request and that of the
- corresponding "xxx-supported" Printer attribute. The "xxx-
- supported" attribute syntax type and attribute value(s) are
- obtained from a Get-Printer-Supported-Values response (see
- Appendix B: Attributes returned from Get-Printer-Supported-
- Values below).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 41]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Table 6 - Validation rules for 'From Get-Printer-Supported-Values'
-
- Type of -
- "xxx" supported" value Validates if:
- value to
- be set Type of "xxx
-
-
- integer rangeOfInteger each 'integer' value is in one of
- the "xxx-supported" ranges
-
- uri uriScheme the uri scheme of each value
- matches one of the "xxx-supported"
- schemes
-
- any boolean if the boolean "xxx-supported" is
- 'true'
-
- name 'admin-define' any 'name' value matches
- out-of-band
- value
-
- any same type each value matches an "xxx-
- supported" value of the same type
-
- For additional non-normative explanatory information see section
- 3.1.2.3 of the "Internet Printing Protocol/1.1: Implementer's Guide"
- [RFC3196].
-
- 4. Any value of the proper attribute syntax: the Set-Printer-
- Attributes or Set-Job-Attributes operation accepts any value of
- the specified attribute syntax. The attribute syntaxes
- supported are enumerated below.
-
- a. Any text(127)
- b. Any name(127)
- c. Any uri
- d. Any boolean
- e. Any positive integer
- f. Any dateTime
- g. 1setOf any uri
-
- 5. Combination of 'Any of "xxx-supported"' or 'Any name'. If a
- Printer implementation doesn't want to allow setting values
- indicated in this Appendix as "any xxx", it can make the value
- be not-settable.
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 42]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Table 7 - Values allowed for Job Template Attributes in the
- Set-Job-Attributes Operation
-
- Job Template Attributes Values allowed for
- Set
-
- job-priority (integer(1:100)) Any of "xxx-
- supported"
-
- job-hold-until (type3 keyword | name (MAX)) Any of "xxx-
- supported"
-
- job-sheets (type3 keyword | name(MAX)) Any of "xxx-
- supported"
-
- multiple-document-handling (type2 keyword) Any of "xxx-
- supported"
-
- copies (integer(1:MAX)) Any of "xxx-
- supported"
-
- finishings (1setOf type2 enum) Any of "xxx-
- supported"
-
- page-ranges (1setOf rangeOfInteger (1:MAX)) Any of "xxx-
- supported"
-
- sides (type2 keyword) Any of "xxx-
- supported"
-
- number-up (integer(1:MAX)) Any of "xxx-
- supported"
-
- orientation-requested (type2 enum) Any of "xxx-
- supported"
-
- media (type3 keyword | name(MAX)) Any of "xxx-
- supported"
-
- printer-resolution (resolution) Any of "xxx-
- supported"
-
- print-quality (type2 enum) Any of "xxx-
- supported"
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 43]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Table 8 - Values allowed for Job Description Attributes in the
- Set-Job-Attributes Operation
-
- Job Description Attributes Values allowed for
- Set
-
- job-uri (uri) READ-ONLY
-
- job-id (integer(1:MAX)) READ-ONLY
-
- job-printer-uri (uri) READ-ONLY
-
- job-more-info (uri) READ-ONLY
-
- job-name (name(MAX)) Any name(MAX)
-
- job-originating-user-name (name(MAX)) READ-ONLY
-
- job-state (type1 enum) READ-ONLY
-
- job-state-reasons (1setOf type2 keyword) READ-ONLY
-
- job-state-message (text(MAX)) READ-ONLY
-
- job-detailed-status-messages (1setOf READ-ONLY
- text(MAX))
-
- job-document-access-errors (1setOf READ-ONLY
- text(MAX))
-
- number-of-documents (integer(0:MAX)) READ-ONLY
-
- output-device-assigned (name(127)) READ-ONLY
-
- time-at-creation (integer(MIN:MAX)) READ-ONLY
-
- time-at-processing (integer(MIN:MAX)) READ-ONLY
-
- time-at-completed (integer(MIN:MAX)) READ-ONLY
-
- job-printer-up-time (integer(1:MAX)) READ-ONLY
-
- date-time-at-creation (dateTime) READ-ONLY
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 44]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Job Description Attributes Values allowed for
- Set
-
- date-time-at-processing (dateTime) READ-ONLY
-
- date-time-at-completed (dateTime) READ-ONLY
-
- number-of-intervening-jobs (integer(0:MAX)) READ-ONLY
-
- job-message-from-operator (text(127)) Any text(127)
-
- job-k-octets (integer(0:MAX)) READ-ONLY
-
- job-impressions (integer(0:MAX)) READ-ONLY
-
- job-media-sheets (integer(0:MAX)) READ-ONLY
-
- job-k-octets-processed (integer(0:MAX)) READ-ONLY
-
- job-impressions-completed (integer(0:MAX)) READ-ONLY
-
- job-media-sheets-completed (integer(0:MAX)) READ-ONLY
-
- attributes-charset (charset) READ-ONLY
-
- attributes-natural-language READ-ONLY
- (naturalLanguage)
-
- Table 9 - Values allowed for Printer Job Template Attributes in
- the Set-Printer-Attributes Operation
-
- Printer Job Template Attributes Values allowed
- for Set
-
- job-priority-default (integer(1:100)) Any of "xxx-
- supported"
-
- job-hold-until-default (type3 keyword | name Any of "xxx-
- (MAX)) supported"
-
- job-sheets-default (type3 keyword | name(MAX)) Any of "xxx-
- supported"
-
- multiple-document-handling-default (type2 Any of "xxx-
- keyword) supported"
-
- copies-default (integer(1:MAX)) Any of "xxx-
- supported"
-
-
-
-Hastings, et. al. Standards Track [Page 45]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Printer Job Template Attributes Values allowed
- for Set
-
- finishings-default (1setOf type2 enum) Any of "xxx-
- supported"
-
- sides-default (type2 keyword) Any of "xxx-
- supported"
-
- number-up-default (integer(1:MAX)) Any of "xxx-
- supported"
-
- orientation-requested-default (type2 enum) Any of "xxx-
- supported"
-
- media-default (type3 keyword | name(MAX)) Any of "xxx-
- supported"
-
- printer-resolution-default (resolution) Any of "xxx-
- supported"
-
- print-quality-default (type2 enum) Any of "xxx-
- supported"
-
- job-priority-supported (integer(1:100)) From Get-
- Printer-
- Supported-Values
-
- job-hold-until-supported (1setOf(type3 keyword From Get-
- | name (MAX))) Printer-
- Supported-Values
-
- job-sheets-supported (1setOf(type3 keyword | From Get-
- name(MAX))) Printer-
- Supported-Values
-
- multiple-document-handling-supported (1setOf From Get-
- type2 keyword) Printer-
- Supported-Values
-
- copies-supported (rangeOfInteger(1:MAX)) From Get-
- Printer-
- Supported-Values
-
- finishings-supported (1setOf type2 enum) From Get-
- Printer-
- Supported-Values
-
-
-
-
-Hastings, et. al. Standards Track [Page 46]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Printer Job Template Attributes Values allowed
- for Set
-
- page-ranges-supported (boolean) From Get-
- Printer-
- Supported-Values
-
- sides-supported (1setOf type2 keyword) From Get-
- Printer-
- Supported-Values
-
- number-up-supported (1setOf (integer(1:MAX) | From Get-
- rangeOfInteger(1:MAX))) Printer-
- Supported-Values
-
- orientation-requested-supported (1setOf type2 From Get-
- enum) Printer-
- Supported-Values
-
- media-supported (1setOf (type3 keyword | From Get-
- name(MAX))) Printer-
- Supported-Values
-
- printer-resolution-supported (1setOf From Get-
- resolution) Printer-
- Supported-Values
-
- print-quality-supported (1setOf type2 enum) From Get-
- Printer-
- Supported-Values
-
- media-ready (type3 keyword | name(MAX)) From Get-
- Printer-
- Supported-Values
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 47]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Table 10 - Values allowed for Printer Description Attributes in
- the Set-Printer-Attributes Operation
-
- Printer Description Attributes Values allowed for
- Set
-
- printer-uri-supported (1setOf uri) READ-ONLY
-
- uri-authentication-supported (1setOf type2 READ-ONLY
- keyword)
-
- uri-security-supported (1setOf type2 READ-ONLY
- keyword)
-
- printer-xri-supported (1setOf collection)
- member attributes:
-
- xri-uri (uri) any uriScheme of
- "xri-uri-scheme-
- supported" from
- Get-Printer-
- Attributes
-
- xri-authentication (type2 keyword) any keyword of
- "xri-
- authentication-
- supported" from
- Get-Printer-
- Attributes
-
- xri-security (type2 keyword) any keyword of
- "xri-security-
- supported" from
- Get-Printer-
- Attributes
-
- xri-uri-scheme-supported (1setOf uriScheme) READ-ONLY
-
- xri-authentication-supported (1setOf type2 READ-ONLY
- keyword)
-
- xri-security-supported (1setOf type2 READ-ONLY
- keyword)
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 48]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Printer Description Attributes Values allowed for
- Set
-
- printer-name (name(127)) Any name(127)
-
- printer-location (text(127)) Any text(127)
-
- printer-info (text(127)) Any text(127)
-
- printer-more-info (uri) Any uri
-
- printer-driver-installer (uri) Any uri
-
- printer-make-and-model (text(127)) Any text(127)
-
- printer-more-info-manufacturer (uri) Any uri
-
- printer-state (type1 enum) READ-ONLY
-
- printer-state-reasons (1setOf type2 READ-ONLY
- keyword)
-
- printer-state-message (text(MAX)) READ-ONLY
-
- ipp-versions-supported (1setOf type2 From Get-Printer-
- keyword) Supported-Values
-
- operations-supported (1setOf type2 enum) From Get-Printer-
- Supported-Values
-
- multiple-document-jobs-supported (boolean) From Get-Printer-
- Supported-Values
-
- charset-configured (charset) Any of "xxx-
- supported", use
- "charset-supported"
-
- charset-supported (1setOf charset) From Get-Printer-
- Supported-Values
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 49]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Printer Description Attributes Values allowed for
- Set
-
- natural-language-configured Any of "xxx-
- (naturalLanguage) supported", use
- "generated-natural-
- language-supported"
-
- generated-natural-language-supported From Get-Printer-
- (1setOf naturalLanguage) Supported-Values
-
- document-format-default (mimeMediaType) Any of "xxx-
- supported"
-
- document-format-supported (1setOf From Get-Printer-
- mimeMediaType) Supported-Values
-
- printer-is-accepting-jobs (boolean) READ-ONLY
-
- queued-job-count (integer(0:MAX)) READ-ONLY
-
- printer-message-from-operator (text(127)) Any text(127)
-
- color-supported (boolean) From Get-Printer-
- Supported-Values
-
- reference-uri-schemes-supported (1setOf From Get-Printer-
- uriScheme) Supported-Values
-
- pdl-override-supported (type2 keyword) From Get-Printer-
- Supported-Values
-
- printer-up-time (integer(1:MAX)) READ-ONLY
-
- printer-current-time (dateTime) Any dateTime **
-
- multiple-operation-time-out any positive
- (integer(1:MAX)) integer
-
- compression-supported (1setOf type3 From Get-Printer-
- keyword) Supported-Values
-
- job-k-octets-supported From Get-Printer-
- (rangeOfInteger(0:MAX)) Supported-Values
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 50]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Printer Description Attributes Values allowed for
- Set
-
- job-impressions-supported From-Get-Printer-
- (rangeOfInteger(0:MAX)) Supported-Values
-
- job-media-sheets-supported From Get-Printer-
- (rangeOfInteger(0:MAX)) Supported-Values
-
- pages-per-minute (integer(0:MAX)) READ-ONLY
-
- pages-per-minute-color (integer(0:MAX)) READ-ONLY
-
- printer-settable-attributes-supported From Get-Printer-
- (1setOf type2 keyword) Supported-Values
-
- job-settable-attributes-supported (1setOf From Get-Printer-
- type2 keyword) Supported-Values
-
- document-format-varying-attributes (1setOf READ-ONLY
- type2 keyword)
-
- printer-message-time (integer(MIN:MAX)) READ-ONLY
-
- printer-message-date-time(dateTime) READ-ONLY
-
- ** - The "printer-current-time" (dateTime) attribute is settable in
- order to allow an administrator to correct an incorrect dateTime or
- time zone.
-
-Appendix B: Attributes returned from Get-Printer-Supported-Values
- (Normative)
-
- This Appendix is a normative part of this document and lists all the
- attributes that are possible for an implementation to return in a
- Get-Printer-Supported-Values response, i.e., all the "xxx-supported"
- attributes that can be supplied in a Set-Printer-Attributes request.
- READ-ONLY attributes MUST NOT be returned in a Get-Printer-
- Supported-Values response and are indicated in the tables as "READ-
- ONLY - MUST NOT be returned."
-
- For the following attributes, the value allowed by the Set-Printer-
- Attributes operation MUST be a single integer value in the range
- specified by the value returned by the Get-Printer-Supported-Values
- operation.
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 51]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Table 11 - Printer Job Template Attributes returned from
- Get-Printer-Supported-Values
-
- Printer Job Template Attributes Values Returned
-
- job-priority-supported (integer(1:100)) rangeOfInteger(1:100)
-
- For the following attributes, the value allowed by the Set-Printer-
- Attributes operation MUST be a single rangeOfInteger value whose
- bounds do not exceed those of the range specified by the value
- returned by the Get-Printer-Supported-Values operation.
-
- Table 12 - Printer Job Template Attributes returned from
- Get-Printer-Supported-Values
-
- Printer Job Template Attributes Values Returned
-
- copies-supported (rangeOfInteger(1:MAX)) rangeOfInteger(1:MAX)
-
- The following table has the same criteria as the last, but is for
- Printer Description attributes.
-
- Table 13 - Printer Description Attributes returned from
- Get-Printer-Supported-Values
-
- Printer Description Attributes Values allowed for Set
-
- job-k-octets-supported rangeOfInteger(0:MAX)
- (rangeOfInteger(0:MAX))
-
- job-impressions-supported
- (rangeOfInteger(0:MAX)) rangeOfInteger(0:MAX)
-
- job-media-sheets-supported rangeOfInteger(0:MAX)
- (rangeOfInteger(0:MAX))
-
- For the following attributes, the value allowed by the Set-Printer-
- Attributes operation MUST be one or more integers and rangeOfInteger
- values, such that the integer values described by these integers and
- rangeOfInteger is the same as or a subset of the integers described
- by the integers and rangeOf Integer of values returned by the Get-
- Printer-Supported-Values operation.
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 52]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Table 14 - Printer Job Template Attributes returned from
- Get-Printer-Supported-Values
-
- Printer Job Template Attributes Values Returned
-
- number-up-supported (1setOf (integer(1:MAX) 1setOf
- | rangeOfInteger(1:MAX))) (integer(1:MAX) |
- rangeOfInteger(1:MA
- X))
-
- For the following attributes, the value allowed by the Set-Printer-
- Attributes operation MUST be one or more values, where each such
- value matches a value returned by the Get-Printer-Supported-Values
- operation. A keyword, enum, boolean, charset, naturalLanguage,
- uriScheme, mimeMediaType or resolution value matches if it is equal.
- For Job Template attributes, with the attribute syntax 'type3 keyword
- | name', any 'name' attribute syntax value matches the 'admin-define'
- out-of-band value, if the implementation allows the administrator to
- set any name values for the attribute.
-
- Table 15 - Printer Job Template Attributes returned from
- Get-Printer-Supported-Values
-
- Printer Job Template Attributes Values Returned
-
- job-hold-until-supported (1setOf(type3 1setOf (type3
- keyword | name (MAX))) keyword | 'admin-
- define')
-
- job-sheets-supported (1setOf(type3 keyword 1setOf (type3
- | name(MAX))) keyword | 'admin-
- define')
-
- multiple-document-handling-supported 1setOf type2
- (1setOf type2 keyword) keyword
-
- finishings-supported (1setOf type2 enum) 1setOf type2 enum
-
- page-ranges-supported (boolean) 1setOf boolean **
-
- sides-supported (1setOf type2 keyword) 1setOf type2
- keyword
-
- orientation-requested-supported (1setOf 1setOf type2 enum
- type2 enum)
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 53]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Printer Job Template Attributes Values Returned
-
- media-supported (1setOf (type3 keyword | 1setOf (type3
- name(MAX))) keyword | 'admin-
- define')
-
- printer-resolution-supported (1setOf 1setOf resolution
- resolution)
-
- print-quality-supported (1setOf type2 enum) 1setOf type2 enum
-
- ** Note: the Get-Printer-Supported-Values returns a '1setOf boolean'
- so that all possible values are indicated, while ** Get-Printer-
- Attributes returns only a single 'boolean' value.
-
- The following table has the same criteria as the last, but is for
- Printer Description attributes.
-
- Table 16 - Printer Description Attributes returned from
- Get-Printer-Supported-Values
-
- Printer Description Attributes Values allowed for
- Set
-
- printer-uri-supported (1setOf uri) READ-ONLY - MUST
- NOT be returned
-
- uri-authentication-supported (1setOf type2 READ-ONLY - MUST
- keyword) NOT be returned
-
- uri-security-supported (1setOf type2 READ-ONLY - MUST
- keyword) NOT be returned
-
- printer-xri-supported (1setOf collection) MUST NOT be
- returned; see next
- three attributes
- returned with Get-
- Printer-Attributes:
-
- xri-uri-scheme-supported (1setOf uriScheme) READ-ONLY - MUST
- NOT be returned
-
- xri-authentication-supported (1setOf type2 READ-ONLY - MUST
- keyword) NOT be returned
-
- xri-security-supported (1setOf type2 READ-ONLY - MUST
- keyword) NOT be returned
-
-
-
-
-Hastings, et. al. Standards Track [Page 54]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- Printer Description Attributes Values allowed for
- Set
-
- ipp-versions-supported (1setOf type2 1setOf type2
- keyword) keyword
-
- operations-supported (1setOf type2 enum) 1setOf type2
- keyword
-
- multiple-document-jobs-supported (boolean) 1setOf boolean **
-
- charset-supported (1setOf charset) 1setOf charset
-
- generated-natural-language-supported 1setOf
- (1setOf naturalLanguage) naturalLanguage
-
- document-format-supported (1setOf 1setOf
- mimeMediaType) mimeMediaType
-
- color-supported (boolean) 1setOf boolean **
-
- reference-uri-schemes-supported (1setOf 1setOf uriScheme
- uriScheme)
-
- pdl-override-supported (type2 keyword) 1setOf type2
- keyword **
-
- compression-supported (1setOf type3 1setOf type3
- keyword) keyword
-
- printer-settable-attributes-supported 1setOf type2
- (1setOf type2 keyword) keyword
-
- job-settable-attributes-supported (1setOf 1setOf type2
- type2 keyword) keyword
-
- ** Note: the Get-Printer-Supported-Values returns a '1setOf X' so
- that all possible values are indicated, while Get-Printer-Attributes
- returns only a single 'X' value.
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 55]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-Appendix C: Description of the Base IPP Documents (Informative)
-
- The base set of IPP documents includes:
-
- Design Goals for an Internet Printing Protocol [RFC2567]
- Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol [RFC2568]
- Internet Printing Protocol/1.1: Model and Semantics [RFC2911]
- Internet Printing Protocol/1.1: Encoding and Transport [RFC2910]
- Internet Printing Protocol/1.1: Implementer's Guide [RFC3196]
- Mapping between LPD and IPP Protocols [RFC2569]
-
- The "Design Goals for an Internet Printing Protocol" document takes a
- broad look at distributed printing functionality, and it enumerates
- real-life scenarios that help to clarify the features that need to be
- included in a printing protocol for the Internet. It identifies
- requirements for three types of users: end users, operators, and
- administrators. It calls out a subset of end user requirements that
- are satisfied in IPP/1.0 [RFC2566, RFC2565]. A few OPTIONAL operator
- operations have been added to IPP/1.1 [RFC2911, RFC2910].
-
- The "Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol" document describes IPP from a high level
- view, defines a roadmap for the various documents that form the suite
- of IPP specification documents, and gives background and rationale
- for the IETF IPP working group's major decisions.
-
- The "Internet Printing Protocol/1.1: Model and Semantics" document
- describes a simplified model with abstract objects, their attributes,
- and their operations. The model introduces a Printer and a Job. The
- Job supports multiple documents per Job. The model document also
- addresses how security, internationalization, and directory issues
- are addressed.
-
- The "Internet Printing Protocol/1.1: Encoding and Transport" document
- is a formal mapping of the abstract operations and attributes defined
- in the model document onto HTTP/1.1 [RFC2616]. It also defines the
- encoding rules for a new Internet MIME media type called
- "application/ipp". This document also defines the rules for
- transporting over HTTP, a message body whose Content-Type is
- "application/ipp". This document defines the 'ipp' scheme for
- identifying IPP printers and jobs.
-
- The "Internet Printing Protocol/1.1: Implementer's Guide" document
- gives insight and advice to implementers of IPP clients and IPP
- objects. It is intended to help them understand IPP/1.1 and some of
- the considerations that may assist them in the design of their client
-
-
-
-
-Hastings, et. al. Standards Track [Page 56]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- and/or IPP object implementations. For example, a typical order of
- processing requests is given, including error checking. Motivation
- for some of the specification decisions are also included.
-
- The "Mapping between LPD and IPP Protocols" document gives some
- advice to implementers of gateways between IPP and LPD (Line Printer
- Daemon) implementations.
-
-Authors' Addresses
-
- Carl Kugler
- IBM
- P.O. Box 1900
- Boulder, CO 80301-9191
-
- Phone: (303) 924-5060
- EMail: kugler@us.ibm.com
-
-
- Tom Hastings
- Xerox Corporation
- 737 Hawaii St. ESAE 231
- El Segundo, CA 90245
-
- Phone: 310-333-6413
- Fax: 310-333-5514
- EMail: hastings@cp10.es.xerox.com
-
-
- Robert Herriot
- Consultant
- 706 Colorado Ave
- Palo Alto, CA 94303
-
- Phone: 650-327-4466
- Fax: 650-327-4466
- EMail: bob@Herriot.com
-
-
- Harry Lewis
- IBM
- 6300 Diagonal Hwy.
- Boulder, CO 80301-9191
-
- Phone: (303) 924-5337
- EMail: harryl@us.ibm.com
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 57]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
- IPP Web Page: http://www.pwg.org/ipp/
- IPP Mailing List: ipp@pwg.org
-
- To subscribe to the ipp mailing list, send the following email:
-
- 1) send it to majordomo@pwg.org
- 2) leave the subject line blank
- 3) put the following two lines in the message body:
- subscribe ipp
- end
-
- Implementers of this specification document are encouraged to join
- the IPP Mailing List in order to participate in any discussions of
- clarification issues and review of registration proposals for
- additional attributes and values. In order to reduce spam the
- mailing list rejects mail from non-subscribers, so you must subscribe
- to the mailing list in order to send a question or comment to the
- mailing list.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 58]
-\f
-RFC 3380 IPP: Job and Printer Set Operations September 2002
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 59]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group T. Hastings
-Request for Comments: 3381 Xerox Corporation
-Updates: 2910 H. Lewis
-Category: Standards Track IBM Printing Company
- R. Bergman
- Hitachi Koki Imaging Solutions
- September 2002
-
-
- Internet Printing Protocol (IPP):
- Job Progress Attributes
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
-Abstract
-
- This document defines four new Job Description attributes for
- monitoring job progress to be registered as OPTIONAL extensions to
- the Internet Printing Protocol (IPP/1.0 and IPP/1.1). These
- attributes are drawn from the PWG Job Monitoring MIB. This document
- also defines a new "sheet-collate" Job Template attribute to control
- sheet collation and to help with the interpretation of the job
- progress attributes.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 1]
-\f
-RFC 3381 IPP: Job Progress Attributes September 2002
-
-
-Table of Contents
-
- 1 Introduction.....................................................2
- 2 Terminology......................................................2
- 2.1 Conformance Terminology........................................4
- 2.2 Other terminology..............................................4
- 3 Job Template attributes..........................................4
- 3.1 sheet-collate (type2 keyword)..................................4
- 4 IPP Job Description attributes for monitoring Job Progress.......6
- 4.1 job-collation-type (type2 enum)................................9
- 4.2 sheet-completed-copy-number (integer(0:MAX))..................11
- 4.3 sheet-completed-document-number (integer(0:MAX))..............11
- 4.4 impressions-completed-current-copy (integer(0:MAX))...........11
- 5 Conformance Requirements........................................11
- 6 IANA Considerations.............................................12
- 6.1 Attributes....................................................
- 6.2 Keyword Attribute Values......................................
- 6.3 Enum Attribute Values.........................................
- 7 Internationalization Considerations.............................12
- 8 Security Considerations.........................................12
- 9 References......................................................12
- 10 Description of the Base IPP Documents..........................13
- 11 Authors' Addresses.............................................15
- 12 Full Copyright Statement.......................................16
-
-1 Introduction
-
- This document defines four new Job Description attributes for
- monitoring job progress to be registered as OPTIONAL extensions to
- IPP/1.0 [RFC2566] and IPP/1.1 [RFC2911]. These attributes are drawn
- from the PWG Job Monitoring MIB [RFC2707]. See section 10 for a
- description of the base IPP documents. The new Job Description
- attributes are:
-
- "job-collation-type" (type2 enum)
- "sheet-completed-copy-number" (integer(0:MAX))
- "sheet-completed-document-number" (integer(0:MAX))
- "impressions-completed-current-copy" (integer(0:MAX))
-
- This document also defines a new "sheet-collate" Job Template
- attribute to control sheet collation and to help with the
- interpretation of the job progress attributes. These new attributes
- may also be used by themselves in combination with the IPP/1.1 "job-
- impressions-completed" attribute, as useful job progress monitoring
- attributes and/or may be passed in an IPP Notification (see [ipp-
- ntfy]).
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 2]
-\f
-RFC 3381 IPP: Job Progress Attributes September 2002
-
-
-2 Terminology
-
- This section defines terminology used throughout this document.
-
-2.1 Conformance Terminology
-
- Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD
- NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to
- conformance, as defined in RFC 2119 [RFC2119] and [RFC2911] section
- 12.1. If an implementation supports the extension defined in this
- document, then these terms apply; otherwise, they do not. These
- terms define conformance to this document only; they do not affect
- conformance to other documents, unless explicitly stated otherwise.
-
-2.2 Other terminology
-
- This document uses terms such as Job object (or Job), IPP Printer
- object (or Printer), "operation", "attribute", "keyword", "support",
- and "impression". These terms have special meaning and are defined
- in the model terminology [RFC2911], section 12.2.
-
-3 Job Template attributes
-
-3.1 sheet-collate (type2 keyword)
-
- +===================+======================+=====================+
- | Job Attribute |Printer: Default Value| Printer: Supported |
- | | Attribute | Values Attribute |
- +===================+======================+=====================+
- | sheet-collate | sheet-collate-default| sheet-collate- |
- | (type2 keyword) | (type2 keyword) | supported (1setOf |
- | | | type2 keyword) |
- +-------------------+----------------------+---------------------+
-
- This attribute specifies whether or not the media sheets of each copy
- of each printed document in a job are to be in sequence, when
- multiple copies of the document are specified by the 'copies'
- attribute.
-
- Standard keyword values are:
-
- 'uncollated': each print-stream sheet is printed a number of
- times in succession equal to the value of the 'copies'
- attribute, followed by the next print-stream sheet.
-
- 'collated': each copy of each document is printed with the
- print-stream sheets in sequence, followed by the next document
- copy.
-
-
-
-Hastings, et. al. Standards Track [Page 3]
-\f
-RFC 3381 IPP: Job Progress Attributes September 2002
-
-
- For example, suppose a document produces two media sheets as output,
- and "copies" is equal to '6'. For the 'uncollated' case, six copies
- of the first media sheet are printed, followed by six copies of the
- second media sheet. For the 'collated' case, one copy of each of the
- six sheets is printed, followed by another copy of each of the six
- media sheets.
-
- Whether the effect of sheet collation is achieved by placing copies
- of a document in multiple output bins, or in the same output bin with
- implementation defined document separation, is implementation
- dependent. Also whether it is achieved by making multiple passes
- over the job or by using an output sorter, is implementation
- dependent.
-
- Note: IPP/1.0 [RFC2566] and IPP/1.1 [RFC2911] are silent on whether
- or not sheets within documents are collated. The "sheet-collate-
- supported" Printer attribute permits a Printer object to indicate
- whether or not it collates sheets with each document and whether it
- allows the client to control sheet collation. An implementation is
- able to indicate that it supports uncollated sheets, collated sheets,
- or both, using the 'uncollated', 'collated', or both 'uncollated' and
- 'collated' values, respectively.
-
- This attribute is affected by "multiple-document-handling". The
- "multiple-document-handling" attribute describes the collation of
- documents, and the "sheet-collate" attribute describes the semantics
- of collating individual pages within a document. To better explain
- the interaction between these two attributes, the term "set" is
- introduced. A "set" is a logical boundary between the delivered
- media sheets of a printed job. For example, in the case of a ten
- page single document with collated pages and a request for 50 copies,
- each of the 50 printed copies of the document constitutes a "set".
- In the above example if the pages were uncollated, then 50 copies of
- each of the individual pages within the document would represent each
- "set".
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 4]
-\f
-RFC 3381 IPP: Job Progress Attributes September 2002
-
-
- The following table describes the interaction of "sheet-collate" with
- multiple document handling.
-
- "sheet- "multiple- Semantics
- collate" document-
- handling"
-
- 'collated' 'single- Each copy of the concatenated
- document' documents, with their pages in
- sequence, represents a "set".
-
- 'collated' 'single- Each copy of the concatenated
- document-new- documents, with their pages in
- sheet' sequence, represents a "set".
-
- 'collated' 'separate- Each copy of each separate
- documents- document, with its pages in
- collated- sequence, represents a "set".
- copies'
-
- 'collated' 'separate- Each copy of each separate
- documents- document, with its pages in
- uncollated- sequence, represents a "set".
- copies
-
- 'uncollated' 'single- Each media sheet of the document
- document' is printed a number of times equal
- to the "copies" attribute; which
- constitutes a "set".
-
- 'uncollated' 'single- Each media sheet of the
- document-new- concatenated documents is printed
- sheet' a number of times equal to the
- "copies" attribute; which
- constitutes a "set".
-
- 'uncollated' 'separate- This is a degenerate case, and the
- documents- printer object MUST reject the job
- collated- and return the status, "client-
- copies' error-conflicting-attributes".
-
- 'uncollated' 'separate- This is a degenerate case, and the
- documents- printer object MUST reject the job
- uncollated- and return the status "client-
- copies error-conflicting-attributes".
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 5]
-\f
-RFC 3381 IPP: Job Progress Attributes September 2002
-
-
- From the above table it is obvious that the implicit value of the
- "sheet-collate" attribute in a printer that does not support the
- "sheet-collate" attribute, is 'collated.' The semantics of
- "multiple-document-handling" are otherwise nonsensical in the case
- of separate documents.
-
-4 IPP Job Description attributes for monitoring Job Progress
-
- The following IPP Job Description attributes are proposed to be added
- to IPP through the type2 registration procedures. They are useful
- for monitoring the progress of a job. They are also used as
- attributes in the notification content in a notification report
- [ipp-ntfy].
-
- There are a number of Job Description attributes for monitoring the
- progress of a job. These objects and attributes count the number of
- K octets, impressions, sheets, and pages requested or completed. For
- impressions and sheets, "completed" means stacked, unless the
- implementation is unable to detect when each sheet is stacked, in
- which case, stacked is approximated when the processing of each sheet
- is completed. There are objects and attributes for the overall job
- and for the current copy of the document currently being stacked.
- For the latter, the rate at which the various objects and attributes
- count, depends on the sheet and document collation of the job.
-
- Consider the following four Job Description attributes that are used
- to monitor the progress of a job's impressions:
-
- 1. "job-impressions-completed" - counts the total number of
- impressions stacked for the job (see [RFC2911] section
- 4.3.18.2).
-
- 2. "impressions-completed-current-copy" - counts the number of
- impressions stacked for the current document copy.
-
- 3. "sheet-completed-copy-number" - identifies the number of the
- copy for the current document being stacked, where the first
- copy is 1.
-
- 4. "sheet-completed-document-number" - identifies the current
- document within the job that is being stacked, where the first
- document in a job is 1. NOTE: this attribute SHOULD NOT be
- implemented for implementations that only support one document
- per job.
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 6]
-\f
-RFC 3381 IPP: Job Progress Attributes September 2002
-
-
- For each of the three types of job collation, a job with three copies
- of two documents (1, 2), where each document consists of 3
- impressions, the four variables have the following values, as each
- sheet is stacked for one-sided printing:
-
- "job-collation-type" = 'uncollated-sheets(3)'
-
- "job- "impressions- "sheet- "sheet-
- impressions- completed- completed- completed-
- completed" current-copy" copy-number" document-
- number"
-
- 0 0 0 0
- 1 1 1 1
- 2 1 2 1
- 3 1 3 1
- 4 2 1 1
- 5 2 2 1
- 6 2 3 1
- 7 3 1 1
- 8 3 2 1
- 9 3 3 1
- 10 1 1 2
- 11 1 2 2
- 12 1 3 2
- 13 2 1 2
- 14 2 2 2
- 15 2 3 2
- 16 3 1 2
- 17 3 2 2
- 18 3 3 2
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 7]
-\f
-RFC 3381 IPP: Job Progress Attributes September 2002
-
-
- "job-collation-type" = 'collated-documents(4)'
-
- "job- "impressions- "sheet- "sheet-
- impressions- completed- completed- completed-
- completed" current-copy" copy- document-
- number" number"
-
- 0 0 0 0
- 1 1 1 1
- 2 2 1 1
- 3 3 1 1
- 4 1 1 2
- 5 2 1 2
- 6 3 1 2
- 7 1 2 1
- 8 2 2 1
- 9 3 2 1
- 10 1 2 2
- 11 2 2 2
- 12 3 2 2
- 13 1 3 1
- 14 2 3 1
- 15 3 3 1
- 16 1 3 2
- 17 2 3 2
- 18 3 3 2
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 8]
-\f
-RFC 3381 IPP: Job Progress Attributes September 2002
-
-
- "job-collation-type" = 'uncollated-documents(5)'
-
- "job- "impressions- "sheet- "sheet-
- impressions- completed- completed- completed-
- completed" current-copy" copy-t document-
- number" number"
-
- 0 0 0 0
- 1 1 1 1
- 2 2 1 1
- 3 3 1 1
- 4 1 2 1
- 5 2 2 1
- 6 3 2 1
- 7 1 3 1
- 8 2 3 1
- 9 3 3 1
- 10 1 1 2
- 11 2 1 2
- 12 3 1 2
- 13 1 2 2
- 14 2 2 2
- 15 3 2 2
- 16 1 3 2
- 17 2 3 2
- 18 3 3 2
-
-4.1 job-collation-type (type2 enum)
-
- Job Collation includes sheet collation and document collation. Sheet
- collation is defined to be the ordering of sheets within a document
- copy. Document collation is defined to be the ordering of document
- copies within a multi-document job. The value of the "job-
- collation-type" is affected by the value of the "sheet-collate" Job
- Template attribute (see section 3.1), if supplied and supported.
-
- The Standard enum values are:
-
- '1' 'other': not one of the defined values
-
- '2' 'unknown': the collation type is unknown
-
- '3' 'uncollated-sheets': No collation of the sheets within each
- document copy, i.e., each sheet of a document that
- is to produce multiple copies, is replicated before
- the next sheet in the document is processed and
- stacked. If the device has an output bin collator,
- the 'uncollated-sheets(3)' value may actually
-
-
-
-Hastings, et. al. Standards Track [Page 9]
-\f
-RFC 3381 IPP: Job Progress Attributes September 2002
-
-
- produce collated sheets as far as the user is
- concerned (in the output bins). However, when the
- job collation is the 'uncollated-sheets(3)' value,
- job progress is indistinguishable from a monitoring
- application between a device that has an output bin
- collator and one that does not.
-
- '4' 'collated-documents': Collation of the sheets within each
- document copy is performed within the printing
- device by making multiple passes over, either the
- source or an intermediate representation of the
- document. In addition, when there are multiple
- documents per job, the i'th copy of each document is
- stacked before the j'th copy of each document, i.e.,
- the documents are collated within each job copy.
- For example, if a job is submitted with documents, A
- and B, the job is made available to the end user as:
- A, B, A, B, .... The 'collated-documents(4)' value
- corresponds to the IPP [RFC2911] 'separate-
- documents-collated-copies' keyword value of the
- "multiple-document-handling" attribute.
-
- If the job's "copies" attribute is '1' (or not
- supplied), then the "job-collation-type" attribute
- is defined to be '4'.
-
- '5' 'uncollated-documents': Collation of the sheets within each
- document copy is performed within the printing
- device by making multiple passes over either the
- source or an intermediate representation of the
- document. In addition, when there are multiple
- documents per job, all copies of the first document
- in the job are stacked before any copied of the next
- document in the job, i.e., the documents are
- uncollated within the job. For example, if a job is
- submitted with documents, A and B, the job is made
- available to the end user as: A, A, ..., B, B, ....
- The 'uncollated-documents(5)' value corresponds to
- the IPP [RFC2911] 'separate-documents-uncollated-
- copies' keyword value of the "multiple-document-
- handling" attribute.
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 10]
-\f
-RFC 3381 IPP: Job Progress Attributes September 2002
-
-
-4.2 sheet-completed-copy-number (integer(0:MAX))
-
- The number of the copy being stacked for the current document. This
- number starts at 0, is set to 1 when the first sheet of the first
- copy for each document is being stacked and is equal to n where n is
- the nth sheet stacked in the current document copy. If the value is
- unknown, the Printer MUST return the 'unknown' out-of-band value (see
- [RFC2911] section 4.1), rather than the -2 value used in some MIBs
- [RFC2707].
-
-4.3 sheet-completed-document-number (integer(0:MAX))
-
- The ordinal number of the document in the job that is currently being
- stacked. This number starts at 0, increments to 1 when the first
- sheet of the first document in the job is being stacked, and is equal
- to n where n is the nth document in the job, starting with 1. If the
- value is unknown, the Printer MUST return the 'unknown' out-of-band
- value (see [RFC2911] section 4.1), rather than the -2 value used in
- some MIBs [RFC2707].
-
- Implementations that only support one document job SHOULD NOT
- implement this attribute.
-
-4.4 impressions-completed-current-copy (integer(0:MAX))
-
- The number of impressions completed by the device for the current
- copy of the current document so far. For printing, the impressions
- completed includes interpreting, marking, and stacking the output.
- For other types of job services, the number of impressions completed
- includes the number of impressions processed. If the value is
- unknown, the Printer MUST return the 'unknown' out-of-band value (see
- [RFC2911] section 4.1), rather than the -2 value used in some MIBs
- [RFC2707].
-
- This value MUST be reset to 0 for each document in the job and for
- each document copy.
-
-5 Conformance Requirements
-
- This section summarizes the Conformance Requirements detailed in the
- definitions in this document. In general each of the attributes
- defined in this document are OPTIONAL for a client and/or a Printer
- to support, so that client and Printer implementers MAY implement any
- combination of these attributes.
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 11]
-\f
-RFC 3381 IPP: Job Progress Attributes September 2002
-
-
-6 IANA Considerations
-
- This section contains registration information for IANA to add to the
- IPP Registry according to the procedures defined in RFC 2911
- [RFC2911], section 6. The resulting registrations will be published
- in the http://www.iana.org/assignments/ipp-registrations registry.
-
-6.1 Attributes
-
- Job Template attributes: Ref. Section:
- sheet-collate (type2 keyword) RFC 3381 3.1
- sheet-default (type2 keyword) RFC 3381 3.1
- sheet-supported (1setOf type2 keyword) RFC 3381 3.1
-
- Job Description attributes: Ref. Section:
- job-collation-type (type2 enum) RFC 3381 4.1
- sheet-completed-copy-number (integer(0:MAX)) RFC 3381 4.2
- sheet-completed-document-number (integer(0:MAX))RFC 3381 4.3
- impressions-completed-current-copy (integer(0:MAX))
- RFC 3381 4.4
-6.2 Keyword Attribute Values
-
- The following table provides registration information for all of the
- attributes defined in this document that have keyword values. These
- keywords are to be registered according to the procedures defined in
- RFC 2911 [RFC2911] section 6.1.
-
- sheet-collate (type2 keyword) RFC 3381 3.1
- 'uncollated' RFC 3381 3.1
- 'collated' RFC 3381 3.1
- sheet-collate-default (type2 keyword) RFC 3381 3.1
- See "sheet-collate" attribute
- sheet-collate-supported (1setOf type2 keyword) RFC 3381 3.1
- See "sheet-collate" attribute
-
-6.3 Enum Attribute Values
-
- The following table provides registration information for all of the
- attributes defined in this document that have enum values. These
- enums are to be registered according to the procedures defined in RFC
- 2911 [RFC2911] section 6.1.
-
- job-collation-type (type2 enum) RFC 3381 4.1
- '1' 'other' RFC 3381 4.1
- '2' 'unknown' RFC 3381 4.1
- '3' 'uncollated-sheets' RFC 3381 4.1
- '4' 'collated-documents' RFC 3381 4.1
- '5' 'uncollated-documents' RFC 3381 4.1
-
-
-
-Hastings, et. al. Standards Track [Page 12]
-\f
-RFC 3381 IPP: Job Progress Attributes September 2002
-
-
-7 Internationalization Considerations
-
- The IPP extensions defined in this document require the same
- internationalization considerations as any of the Job Template and
- Job Description attributes defined in IPP/1.1 [RFC2911].
-
-8 Security Considerations
-
- The IPP extensions defined in this document require the same security
- considerations as any of the Job Template attributes and Job
- Description attributes defined in IPP/1.1 [RFC2911].
-
-9 References
-
-9.1 Normative References
-
- [RFC2910] Herriot, R., Butler, S., Moore, P. and R. Turner,
- "Internet Printing Protocol/1.1: Encoding and Transport",
- RFC 2910, September 2000.
-
- [RFC2911] Hastings, T., Herriot, R., deBry, R., Isaacson, S. and P.
- Powell, "Internet Printing Protocol/1.1: Model and
- Semantics", RFC 2911, September 2000.
-
-9.2 Informative References
-
- [RFC2565] Herriot, R., Butler, S., Moore, P. and R. Turner,
- "Internet Printing Protocol/1.0: Encoding and Transport",
- RFC 2565, April 1999.
-
- [RFC2566] deBry, R., Hastings, T., Herriot, R., Isaacson, S. and P.
- Powell, "Internet Printing Protocol/1.0: Model and
- Semantics", RFC 2566, April 1999.
-
- [RFC2567] Wright, F.D., "Design Goals for an Internet Printing
- Protocol", RFC 2567, April 1999.
-
- [RFC2568] Zilles, S., "Rationale for the Structure and Model and
- Protocol for the Internet Printing Protocol", RFC 2568,
- April 1999.
-
- [RFC2569] Herriot, R., Hastings, T., Jacobs, N. and J. Martin,
- "Mapping between LPD and IPP Protocols", RFC 2569, April
- 1999.
-
- [RFC2707] Bergman, R., Hastings, T., Isaacson, S. and H. Lewis, "PWG
- Job Monitoring MIB - V1", RFC 2707, November 1999.
-
-
-
-
-Hastings, et. al. Standards Track [Page 13]
-\f
-RFC 3381 IPP: Job Progress Attributes September 2002
-
-
- [RFC3196] Hastings, T., Manros, C., Zehler, P., Kugler, C. and H.
- Holst, "Internet Printing Protocol/1.1: Implementor's
- Guide", RFC 3196, November 2001.
-
- [ipp-ntfy] Herriot, R., Hastings, T., et. al., "Internet Printing
- Protocol (IPP): Event Notification and Subscriptions",
- Work in Progress.
-
-10 Description of the Base IPP Documents
-
- The base set of IPP documents includes:
-
- Design Goals for an Internet Printing Protocol [RFC2567]
- Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol [RFC2568]
- Internet Printing Protocol/1.1: Model and Semantics [RFC2911]
- Internet Printing Protocol/1.1: Encoding and Transport [RFC2910]
- Internet Printing Protocol/1.1: Implementer's Guide [RFC3196]
- Mapping between LPD and IPP Protocols [RFC2569]
-
- The "Design Goals for an Internet Printing Protocol" document takes a
- broad look at distributed printing functionality, and enumerates
- real-life scenarios that help to clarify the features that need to be
- included in a printing protocol for the Internet. It identifies
- requirements for three types of users: end users, operators, and
- administrators. It calls out a subset of end user requirements that
- are satisfied in IPP/1.0 [RFC2566, RFC2565]. A few OPTIONAL operator
- operations have been added to IPP/1.1 [RFC2911, RFC2910].
-
- The "Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol" document describes IPP from a high level
- view, defines a roadmap for the various documents that form the suite
- of IPP specification documents, and gives background and rationale
- for the IETF IPP working group's major decisions.
-
- The "Internet Printing Protocol/1.1: Model and Semantics" document
- describes a simplified model with abstract objects, their attributes,
- and their operations. The model introduces a Printer and a Job. The
- Job supports multiple documents per Job. The model document also
- addresses how security, internationalization, and directory issues
- are addressed.
-
- The "Internet Printing Protocol/1.1: Encoding and Transport" document
- is a formal mapping of the abstract operations and attributes defined
- in the model document onto HTTP/1.1 [RFC2616]. It also defines the
- encoding rules for a new Internet MIME media type called
- "application/ipp". This document also defines the rules for
- transporting over HTTP a message body whose Content-Type is
-
-
-
-Hastings, et. al. Standards Track [Page 14]
-\f
-RFC 3381 IPP: Job Progress Attributes September 2002
-
-
- "application/ipp". This document defines the 'ipp' scheme for
- identifying IPP printers and jobs.
-
- The "Internet Printing Protocol/1.1: Implementer's Guide" document
- gives insight and advice to implementers of IPP clients and IPP
- objects. It is intended to help them understand IPP/1.1 and some of
- the considerations that may assist them in the design of their client
- and/or IPP object implementations. For example, a typical order of
- processing requests is given, including error checking. Motivation
- for some of the specification decisions is also included.
-
- The "Mapping between LPD and IPP Protocols" document gives some
- advice to implementers of gateways between IPP and LPD (Line Printer
- Daemon) implementations.
-
- In addition to the base IPP documents, the "Event Notification
- Specification" document [ipp-ntfy] defines OPTIONAL operations that
- allow a client to subscribe to printing related events.
- Subscriptions include "Per-Job subscriptions" and "Per-Printer
- subscriptions". Subscriptions are modeled as Subscription objects.
- Four other operations are defined for subscription objects: get
- attributes, get subscriptions, renew a subscription, and cancel a
- subscription.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 15]
-\f
-RFC 3381 IPP: Job Progress Attributes September 2002
-
-
-11 Authors' Addresses
-
- Tom Hastings
- Xerox Corporation
- 737 Hawaii St. ESAE 231
- El Segundo, CA 90245
-
- Phone: 310-333-6413
- Fax: 310-333-5514
- EMail: hastings@cp10.es.xerox.com
-
- Harry Lewis
- IBM
- 6300 Diagonal Hwy
- Boulder, CO 80301-9191
-
- Phone: (303) 924-5337
- EMail: harryl@us.ibm.com
-
- Ron Bergman (Editor)
- Hitachi Koki Imaging Solutions
- 1757 Tapo Canyon Road
- Simi Valley, CA 93063-3394
-
- Phone: 805-578-4421
- Fax: 805-578-4001
- EMail: rbergma@hitachi-hkis.com
-
- IPP Web Page: http://www.pwg.org/ipp/
- IPP Mailing List: ipp@pwg.org
-
- To subscribe to the ipp mailing list, send the following email:
-
- 1) send it to majordomo@pwg.org
- 2) leave the subject line blank
- 3) put the following two lines in the message body:
- subscribe ipp
- end
-
- Implementers of this specification document are encouraged to join
- the IPP Mailing List in order to participate in any discussions of
- clarification issues and review of registration proposals for
- additional attributes and values. In order to reduce spam, the
- mailing list rejects mail from non-subscribers, so you must subscribe
- to the mailing list in order to send a question or comment to the
- mailing list.
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 16]
-\f
-RFC 3381 IPP: Job Progress Attributes September 2002
-
-
-12 Full Copyright Statement
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et. al. Standards Track [Page 17]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group R. deBry
-Request for Comments: 3382 Utah Valley State College
-Updates: 2910, 2911 R. Herriot
-Category: Standards Track Consultant
- T. Hastings
- K. Ocke
- P. Zehler
- Xerox Corporation
- September 2002
-
-
- Internet Printing Protocol (IPP):
- The 'collection' attribute syntax
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
-Abstract
-
- This document specifies an OPTIONAL attribute syntax called
- 'collection' for use with the Internet Printing Protocol (IPP/1.0 and
- IPP/1.1). A 'collection' is a container holding one or more named
- values, which are called "member" attributes. A collection allows
- data to be grouped like a PostScript dictionary or a Java Map. This
- document also specifies the conformance requirements for a definition
- document that defines a collection attribute. Finally, this document
- gives some illustrative example collection attribute definitions that
- are not intended as actual attribute specifications.
-
-Table of Contents
-
- 1 Introduction.....................................................3
- 1.1 Problem Statement..............................................3
- 1.2 Solution.......................................................3
- 2 Terminology......................................................4
- 2.1 Conformance Terminology........................................4
- 2.2 Other terminology..............................................5
- 3 Definition of a Collection Attribute.............................5
- 3.1 Information to Include.........................................5
-
-
-
-deBry, et. al. Standards Track [Page 1]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- 3.2 Nested Collections.............................................9
- 4 Collection Attributes as Attributes in Operations................9
- 4.1 General Rules..................................................9
- 4.2 Unsupported Values.............................................9
- 5 Example definition of a collection attribute.....................9
- 5.1 media-col (collection)........................................10
- 5.1.1 media-color (type3 keyword | name(MAX)......................10
- 5.1.2 media-size (collection).....................................11
- 5.2 media-col-default (collection)................................11
- 5.3 media-col-ready (1setOf collection)...........................12
- 5.4 media-col-supported (1setOf type2 keyword)....................12
- 6 A Second Example Definition Of A Collection Attribute...........12
- 7 Encoding........................................................13
- 7.1 Additional tags defined for representing a collection
- attribute value...............................................13
- 7.2 Example encoding: "media-col" (collection)....................14
- 8 Legacy issues...................................................20
- 9 IANA Considerations.............................................20
- 10 Internationalization Considerations............................20
- 11 Security Considerations........................................21
- 12 References.....................................................21
- Appendix A: Encoding Example of a Simple Collection (Informative).22
- Appendix B: Encoding Example of 1setOf Collection (Informative)...25
- Appendix C: Encoding Example of Collection containing 1setOf XXX
- attribute (Informative)...............................31
- Appendix D: Description of the Base IPP Documents (Informative)...35
- Authors' Addresses................................................36
- Full Copyright Statement..........................................38
-
-Table of Tables
-
- Table 1 - "media-col" member attributes...........................10
- Table 2 - "media-size" collection member attributes...............11
- Table 3 - Tags defined for encoding the 'collection' attribute
- syntax .................................................13
- Table 4 - Overview Encoding of "media-col" collection.............15
- Table 5 - Example Encoding of "media-col" collection..............16
- Table 6 - Overview Encoding of simple collection..................22
- Table 7 - Example Encoding of simple collection...................22
- Table 8 - Overview Encoding of 1setOf collection..................25
- Table 9 - Example Encoding of 1setOf collection...................26
- Table 10 - Overview Encoding of collection with 1setOf value......31
- Table 11 - Example Encoding of collection with 1setOf value.......32
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 2]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
-1 Introduction
-
- This document is an OPTIONAL extension to IPP/1.0 [RFC2565, RFC2566]
- and IPP/1.1 [RFC2911, RFC2910]. For a description of the base IPP
- documents see Appendix D.
-
-1.1 Problem Statement
-
- The IPP Model and Semantics [RFC2911] supports most of the common
- data structures that are available in programming languages. It
- lacks a mechanism for grouping several attributes of different types.
- The Java language uses the Map to solve this problem and PostScript
- has a dictionary. The new mechanism for grouping attributes together
- (called 'collection' mechanism) must allow for optional members and
- the subsequent addition of new members.
-
- The 'collection' mechanism must be encoded in a manner consistent
- with existing 1.0 and 1.1 parsing rules (see [RFC2910]). Current 1.0
- and 1.1 parsers that don't support the 'collection' mechanism must
- not confuse collections or parts of a collection they receive with
- other attributes.
-
-1.2 Solution
-
- The new mechanism is a new IPP attribute syntax called a
- 'collection'. As such, each collection value is a value of an
- attribute whose attribute syntax type is defined to be a
- 'collection'. Such an attribute is called a collection attribute.
- The name of the collection attribute serves to identify the
- collection value in an operation request or response, as with any
- attribute value.
-
- The 'collection' attribute syntax is a container holding one or more
- named values (i.e., attributes), which are called member attributes.
- Each collection attribute definition document lists the mandatory and
- optional member attributes of each collection value. A collection
- value is similar to an IPP attribute group in a request or a
- response, such as the operation attributes group. They both consist
- of a set of attributes.
-
- As with any attribute syntax, the document that defines a collection
- attribute specifies whether the attribute is single-valued
- (collection) or multi-valued (1setOf collection). If the attribute
- is multi-valued (1setOf collection), each collection value MUST be a
- separate instance of a single definition of a collection, i.e., it
- MUST have the same member attributes except for OPTIONAL member
- attributes. If we view each collection definition as a separate
- syntax type, this rule continues the IPP/1.1 notion that each
-
-
-
-deBry, et. al. Standards Track [Page 3]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- attribute has a single type or pattern (e.g., "keyword | name" is a
- pattern). Without this rule, the supported values would be more
- difficult to describe and the mechanism defined in item 4 of section
- 3.1 would not be sufficient.
-
- The name of each member attribute MUST be unique for a collection
- attribute, but MAY be the same as the name of a member attribute in
- another collection attribute and/or MAY be the same as the name of an
- attribute that is not a member of a collection. The rules for naming
- member attributes are given in section 3.1.
-
- Each member attribute can have any attribute syntax type, including
- 'collection', and can be either single-valued or multi-valued. The
- length of a collection value is not limited. However, the length of
- each member attribute MUST NOT exceed the limit of its attribute
- syntax.
-
- The member attributes in a collection MAY be in any order in a
- request or response. When a client sends a collection attribute to
- the Printer, the order that the Printer stores the member attributes
- of the collection value and the order returned in a response MAY be
- different from the order sent by the client.
-
- A collection value MUST NOT contain two or more member attributes
- with the same attribute name. Such a collection is mal-formed.
- Clients MUST NOT submit such malformed requests and Printers MUST NOT
- return such malformed responses. If such a malformed request is
- submitted to a Printer, the Printer MUST (depending on
- implementation) either (1) reject the request with the 'client-
- error-bad-request' status code (see [RFC2911] section 13.1.4.1), or
- (2) accept the request and use only one of each duplicate member
- attributes.
-
-2 Terminology
-
- This section defines terminology used throughout this document.
-
-2.1 Conformance Terminology
-
- Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD
- NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to
- conformance as defined in BCP 14, RFC 2119 [RFC2119] and [RFC2911],
- section 12.1. If an implementation supports the extension defined in
- this document, then these terms apply; otherwise, they do not. These
- terms define conformance to this document only; they do not affect
- conformance to other documents, unless explicitly stated otherwise.
-
-
-
-
-
-deBry, et. al. Standards Track [Page 4]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
-2.2 Other terminology
-
- This document uses terms such as Job object (or Job), IPP Printer
- object (or Printer), "operation", "request", response", "attributes",
- "keywords", and "support". These terms have special meaning and are
- defined in the model terminology [RFC2911] section 12.2. The
- following additional terms are introduced in this document:
-
- collection: an attribute syntax in which each attribute value is a
- set of attributes, called member attributes.
-
- member attribute: an attribute that is defined to be used as one
- of the attributes in a collection.
-
- collection attribute: an attribute whose definition specifies the
- 'collection' attribute syntax and each of the member attributes
- that MAY occur in a collection attribute value.
-
-3 Definition of a Collection Attribute
-
- This section describes the requirements for any collection attribute
- definition.
-
-3.1 Information to Include
-
- When a specification document defines an "xxx" collection attribute,
- i.e., an attribute whose attribute syntax type is 'collection' or
- '1setOf collection'; the definition document MUST include the
- following aspects of the attribute semantics. Suppose the "xxx"
- collection attribute contains N member attributes named "aaa1",
- "aaa2", ..., "aaaN" ("aaaI" represents any one of these N member
- attributes).
-
- 1. The name of the collection attribute MUST be specified (e.g.,
- "xxx"). The selection of the name "xxx" MUST follow the same
- rules for uniqueness as for attributes of any other syntax type,
- (as defined by IPP/1.1) unless "xxx" is a member attribute of
- another collection. Then the selection of the name "xxx" MUST
- follow the rules for uniqueness defined in item 5a) of this list.
-
- 2. The collection attribute syntax MUST be of type 'collection' or
- '1setOf collection'.
-
- 3. The context of the collection attribute MUST be specified, i.e.,
- whether the attribute is an operation attribute, a Job Template
- attribute, a Job Description attribute, a Printer Description
- attribute, a member attribute of a particular collection
- attribute, etc.
-
-
-
-deBry, et. al. Standards Track [Page 5]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- 4. An "xxx-supported" attribute MUST be specified and it has one of
- the following two forms:
-
- a) "xxx-supported" is a "1setOf collection", which enumerates all
- of the supported collection values of "xxx". If a collection
- of this form contains a nested collection, it MUST be of the
- same form.
-
- For example, "media-size-supported" might have the values {{x-
- dimension:210, y-dimension:297},{x-dimension:297, y-
- dimension:420}} to show that it supports two values of "media
- size": A4 (210x297) and A3 (297x420). It does not support
- other combinations of "x-dimension" and "y-dimension" member
- attributes, such as 210x420 or 297x297, and it does not support
- non-enumerated values, such as 420x595.
-
- b) "xxx-supported" is a "1setOf type2 keyword", which enumerates
- the names of all of the member attributes of "xxx": "aaa1",
- "aaa2", ..., "aaaN". If a collection of this form contains a
- nested collection, it MAY be of either form. See item 5f)
- below for details on supported values of member attributes.
-
- For example, "media-col-supported" might have the keyword
- values: "media-size" and "media-color".
-
- 5. The member attributes MUST be defined. For each member attribute,
- the definition document MUST provide the following information:
-
- a) The member attribute's name (e.g., "aaa") MUST be unique within
- the collection being defined and MUST either:
-
- i) reuse the attribute name of another attribute (that is
- unique across the entire IPP attribute name space) and
- have the same syntax and semantics as the reused attribute
- (if the condition of item 4b) above is met). For example,
- a member attribute definition could reuse the IPP/1.1
- "media" attribute.
-
- ii) potentially occur elsewhere in the entire IPP attribute
- name space. (if the condition of item 4a) above is met).
- For example, a member attribute could be "x-dimension",
- which could potentially occur in another collection or as
- an attribute outside of a collection.
-
- iii) be unique across the entire IPP attribute name space (if
- the condition of item 4b) above is met). For example, a
- member attribute could be "media-color" which must be
- unique across the entire IPP attribute name space.
-
-
-
-deBry, et. al. Standards Track [Page 6]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- b) Whether the member attribute is REQUIRED or OPTIONAL for the
- Printer to support.
-
- c) Whether the member attribute is REQUIRED or OPTIONAL for the
- client to supply in a request.
-
- d) The member attribute's syntax type, which can be any attribute
- syntax, including '1setOf X', 'collection', and '1setOf
- collection'. If this attribute name reuses the name of another
- attribute (case of item a1 above), it MUST have the same
- attribute syntax, including cardinality (whether or not
- 1setOf).
-
- e) The semantics of the "aaa" member attribute. The semantic
- definition MUST include a description of any constraint or
- boundary conditions the member attribute places on the
- associated attribute, especially if the attribute reuses the
- name of another attribute (case of item a1 above).
-
- f) The supported values for each "aaaI" member attribute (of the
- member attributes "aaa1", "aaa2", ..., "aaaN") is specified by
- one of two mechanisms.
-
- i) If "xxx-supported" is a "1setOf collection" (see item 4a)
- above), the value for each "aaaI" is specified in each
- collection value of "xxx-supported", in the context of
- other member attributes. That is, "xxx-supported"
- enumerates all supported values of "xxx".
-
- ii) If the value of "xxx-supported" is a "1setOf type2
- keyword" (see item 4b) above), the supported values of
- "aaaI" are the values specified by either i) the "aaaI-
- supported" attribute or ii) the definition of the member
- attribute "aaaI" within the document defining the "xxx"
- attribute. The values of each member attribute "aaaI" are
- specified independently of other member attributes, though
- a Printer is not required to support all combinations of
- supported values.
-
- For example, "media-col-supported" might have the keyword
- values: "media-size" and "media-color". Using the first
- method for defining supported values (an "aaaI-supported"
- attribute), the collection values of "media-col" are
- combinations of values of "media-size-supported" and
- "media-color-supported". If "media-size-supported" has
- the values of '210x297' and '297x420' and "media-color-
- supported" has the values of 'white' and 'pink', the
-
-
-
-
-deBry, et. al. Standards Track [Page 7]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Printer might support only the combinations 'white-
- 210x297', 'pink-210x297' and 'white-297x420', and not
- 'pink-297x420'.
-
- If a collection contains a member "aaaI", whose syntax
- type is "text", the supported values would probably be
- defined by the definition of "xxx" rather than by the
- attribute "aaaI-supported".
-
- g) the default value of each "aaaI" member attribute if it is
- OPTIONAL for a client to supply the "aaa" member attribute in a
- request. The default value is specified by the attribute's
- definition within a document and MUST be one of the following:
-
- i) a fixed default
-
- ii) a mechanism by which the Printer determines default
-
- iii) an indefinite default that is left to the implementation.
-
- iv) an attribute that the Printer uses to determine the
- default
-
- 6. The default value of "xxx", if a client does not supply it. The
- default value is specified by the attribute's definition within a
- document and MUST be one of the following:
-
- a) a fixed default
-
- b) a mechanism by which the Printer determines default
-
- c) an indefinite default that is left to the implementation
-
- d) a Printer attribute "xxx-default" which is a collection with
- the same member attributes as "xxx". If optional member
- attributes are absent, the Printer uses the defaulting rules of
- item 5g) above.
-
- 7. The "xxx-ready (1setOf collection)" attribute, if human
- intervention is required to make many of the supported values
- available. For example, "media-col" is an attribute which has a
- "ready" attribute. Most attributes do not have a "ready"
- attribute.
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 8]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
-3.2 Nested Collections
-
- A member attribute may have a syntax type of 'collection' or '1setOf
- collection', in which case it is called a nested collection
- attribute. The rules for a nested collection attribute are the same
- as for a collection attribute as specified in section 3.1.
-
-4 Collection Attributes as Attributes in Operations
-
-4.1 General Rules
-
- A collection value is like any other IPP/1.1 value, except that it is
- structured. The rules for attributes with collection values are the
- same as for attributes of any other syntax type (see IPP/1.1), be
- they in any group of a request of a response.
-
-4.2 Unsupported Values
-
- The rules for returning an unsupported collection attribute are an
- extension to the current rules:
-
- 1. If the entire collection attribute is unsupported, then the
- Printer returns just the collection attribute name with the
- 'unsupported' out-of-band value (see the beginning of [RFC2911]
- section 4.1) in the Unsupported Attributes Group.
-
- 2. If a collection contains unrecognized, unsupported member
- attributes and/or conflicting values, the attribute returned in
- the Unsupported Group is a collection containing the unrecognized,
- unsupported member attributes, and/or conflicting values. The
- unrecognized member attributes have an out-of-band value of
- 'unsupported' (see the beginning of [RFC2911] section 4.1). The
- unsupported member attributes and conflicting values have their
- unsupported or conflicting values.
-
-5 Example definition of a collection attribute
-
- In some printing environments, it is desirable to allow the client to
- select the media by its properties, e.g., weight, color, size, etc.,
- instead of by name. In IPP/1.1 (see [RFC2911]), the "media (type3
- keyword | name) Job Template attribute allows selection by name. It
- is tempting to extend the "media" attribute syntax to include
- "collection", but then existing clients could not understand default
- or supported media values that use the collection value. To preserve
- interoperability, a new attribute MUST BE added, e.g., "media-col
- (collection)". The following subsections contain a sample definition
- of a simplified "media-col" attribute. The definition follows the
- rules in section 3.
-
-
-
-deBry, et. al. Standards Track [Page 9]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- All of the example attribute definitions in this document are
- illustrative examples, rather than actual definitions. These
- examples are intended to illustrate how to define collection
- attributes. Other documents MUST define collection attributes for
- use in actual interchange. Such definitions may be very similar to
- the examples in this document, since we attempted to pick useful
- examples.
-
- Note: we picked the name "media-col" because the name "media" is
- already in use. Ordinarily the collection attribute would have a
- name like any other attribute and would not end in "col".
-
- The member attributes of "media-col" attribute ("media-color (type 3
- keyword)" and "media-size (collection)") both follow the naming rules
- of item 4a3 of section 3, i.e., the names are unique across the
- entire IPP attribute name space. The member attributes of the
- "media-size (collection)" member attribute ("x-dimension
- (integer(0:MAX))" and "y-dimension (integer(0:MAX))") both follow the
- naming rules of item 4a2 of section 3, i.e., they potentially occur
- elsewhere in the IPP attribute name space.
-
-5.1 media-col (collection)
-
- The "media-col" (collection) attribute augments the IPP/1.1 [RFC2911]
- "media" attribute. This collection attribute enables a client end
- user to submit a list of media characteristics to the Printer. When
- the client specifies media using the "media-col" collection
- attribute, the Printer object MUST match the requested media exactly.
- The 'collection' consists of the following member attributes:
-
- Table 1 - "media-col" member attributes
-
- Attribute name attribute syntax request Printer
- Support
-
- media-color type3 keyword | name (MAX) MAY MUST
-
- media-size collection MUST MUST
-
- The definitions for the member attributes is given in the following
- sub-sections:
-
-5.1.1 media-color (type3 keyword | name(MAX)
-
- This member attribute identifies the color of the media. Valid
- values are 'red', 'white' and 'blue'.
-
-
-
-
-
-deBry, et. al. Standards Track [Page 10]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- The "media-color-supported" (1setOf (type3 keyword | name(MAX)))
- Printer attribute identifies the values of this "media-color" member
- attribute that the Printer supports, i.e., the colors supported.
-
- If the client omits this member attribute, the Printer determines the
- value in an implementation dependent manner.
-
-5.1.2 media-size (collection)
-
- This member attribute identifies the size of the media. The
- 'collection' consists of the member attributes shown in Table 2:
-
- Table 2 - "media-size" collection member attributes
-
- Attribute name attribute syntax request Printer
- Support
-
- x-dimension integer (0:MAX) MUST MUST
-
- y-dimension integer (0:MAX) MUST MUST
-
- The definitions for the member attributes are given in the following
- sub-sections:
-
-5.1.2.1 x-dimension (integer(0:MAX))
-
- This attribute identifies the width of the media in inch units along
- the X axis.
-
-5.1.2.2 y-dimension (integer(0:MAX))
-
- This attribute identifies the height of the media in inch units along
- the Y axis.
-
- The "media-size-supported" (1setOf collection) Printer attribute
- identifies the values of this "media-size" member attribute that the
- Printer supports, i.e., the size combinations supported. The names
- of the member attributes are the same as the member attributes of the
- "media-size" collection attribute, namely "x-dimension", and "y-
- dimension", since they have the same attribute syntax and the same
- semantics.
-
-5.2 media-col-default (collection)
-
- The "media-col-default" Printer attribute specifies the media that
- the Printer uses, if any, if the client omits the "media-col" and
- "media". Job Template attributes in the Job Creation operation and
- the PDL do not include a media specification. The member attributes
-
-
-
-deBry, et. al. Standards Track [Page 11]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- are defined in Table 1. A Printer MUST support the same member
- attributes for this default collection attribute as it supports for
- the corresponding "media-col" Job Template attribute.
-
-5.3 media-col-ready (1setOf collection)
-
- The "media-col-ready" Printer attribute identifies the media that are
- available for use without human intervention, i.e., the media that
- are ready to be used without human intervention. The collection
- value MUST have all of the member attributes that are supported in
- Table 1.
-
-5.4 media-col-supported (1setOf type2 keyword)
-
- The "media-col-supported" Printer attribute identifies the keyword
- names of the member attributes supported in the "media-col"
- collection Job Template attribute, i.e., the keyword names of the
- member attributes in Table 1 that the Printer supports.
-
-6 A Second Example Definition Of A Collection Attribute
-
- All of the example attribute definitions in this document are
- illustrative examples, rather than actual definitions. These
- examples are intended to illustrate how to define collection
- attributes. Other documents MUST define collection attributes for
- use in actual interchange. Such definitions may be very similar to
- the examples in this document, since we attempted to pick useful
- examples.
-
- In some printing environments, it is desirable to allow the client to
- select the media for the job start sheet. The reason for not adding
- the 'collection' attribute syntax to the existing "job-sheets" Job
- Template attribute is the same as for "media". Instead, a new Job
- Template attribute is introduced, e.g., "job-sheet-col (collection)".
-
- The member attributes of "job-sheet-col" attribute ("job-sheets (type
- 3 keyword)" and "media (type3 keyword | name)") both follow the
- naming rules of item 4a1 of section 3, i.e., they reuse existing IPP
- attributes. According to the rules, their supported values come from
- the existing IPP attributes: "job-sheets-supported" and "media-
- supported". However, their default values do not come from "job-
- sheets-default" and "media-default", respectively. Rather, the
- definition of "job-sheet-col" says that "job-sheets (type 3 keyword)"
- is required and if "media (type3 keyword | name)" is absent, the
- Printer uses the same media as the rest of the job uses.
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 12]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- If "job-sheet-col" attribute was defined to contain the member
- attribute "job-sheet-media (type3 keyword | name)" instead of "media
- (type3 keyword | name)", then the definition would also have to
- specify a "job-sheet-media-supported (1setOf (type3 keyword | name))"
- whose values would be independent of "media-supported (1setOf (type3
- keyword | name))" and would be set separately by a System
- Administrator.
-
- The actual text for the definition of the attribute is left as an
- exercise for the reader.
-
-7 Encoding
-
- This section defines the additional encoding tags used according to
- [RFC2910] and gives an example of their use. The encoding tags
- defined in this document MUST be used by all collection attributes
- defined in other documents. However, the example of their use is
- illustrative only.
-
-7.1 Additional tags defined for representing a collection attribute
- value
-
- The 'collection' attribute syntax uses the tags defined in Table 3.
-
- Table 3 - Tags defined for encoding the 'collection' attribute syntax
-
- Tag name Tag
- value Meaning
-
- begCollection 0x34 Begin the collection attribute value.
-
- endCollection 0x37 End the collection attribute value.
-
- memberAttrName 0x4A The value is the name of the
- collection member attribute
-
- When encoding a collection attribute "xxx" that contains an attribute
- "aaa" and is not inside another collection, the encoding follows
- these rules:
-
- 1. The beginning of the collection is indicated with a value tag that
- MUST be syntax type 'begCollection' (0x34) with a name length and
- Name field that represent the name of the collection attribute
- ("xxx") as with any attribute, followed by a value. The Printer
- MAY ignore the value and its length MAY be 0. In the future,
- however, this field MAY contain useful information, such as the
- collection name (cf. the name of a C struct).
-
-
-
-
-deBry, et. al. Standards Track [Page 13]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- 2. Each member attribute is encoded as a sequence of two or more
- values that appear to be part of a single multi-valued attribute,
- i.e., 1setOf. The first value after the 'begCollection' value has
- the attribute syntax, 'memberAttrName' (0x4A), and its value holds
- the name of the first member attribute (e.g., "aaa"). The second
- value holds the first member's attribute value, which can be of
- any attribute syntax, except 'memberAttrName' or 'endCollection'.
- If the first member's attribute value is multi-valued, the third
- value holds the second value of the first member's value.
- Otherwise, the third value holds the name of second member
- attribute (e.g., "bbb"), and its attribute syntax is
- 'memberAttrName'. In this case, the fourth member's value is the
- value of "bbb".
-
- Note that the technique of encoding a 'collection' as a '1setOf'
- makes it easy for a Printer that doesn't support a particular
- collection attribute (or the collection attribute syntax at all)
- to simply skip over the entire collection value.
-
- 3. The end of the collection is indicated with a value tag that MUST
- be syntax type 'endCollection' (e.g., 0x37) and MAY have a zero
- name length and a zero value length. In the future, this field
- MAY contain useful information, such as the collection name that
- matches the one in the 'begCollection' .
-
- 4. It is valid to have a member attribute that is itself, a
- collection attribute, i.e., collections can be nested within
- collections. This is represented by the occurrence of a member
- attribute that is of attribute syntax type 'begCollection'. Such
- a collection is terminated by a matching 'endCollection'. The
- name of such a member attribute is in the immediately preceding
- value, whose syntax type is 'memberAttrName'.
-
- 5. It is valid for a collection attribute to be multi-valued, i.e.,
- have more than one collection value. If the next attribute
- immediately following the 'endCollection' has a zero name length
- and a tag of 'begCollection', then the collection attribute is a
- multi-valued collection, as with any attribute. This statement
- applies to collections within collections and collections that are
- not in collections.
-
-7.2 Example encoding: "media-col" (collection)
-
- The collection specified in section 5 is used for the encoding
- example shown in Table 5. The example also shows nested collections,
- since the "media-size" member attribute is a 'collection. The
- encoding example represents a blue 4x6-index card and takes 216
- octets. The Appendices contain more complex examples.
-
-
-
-deBry, et. al. Standards Track [Page 14]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Additional examples have been included in the appendices.
-
- The overall structure of the two collection values can be pictorially
- represented as:
-
- "media-col" =
- { "media-color" = 'blue';
- "media-size" =
- { "x-dimension" = 6;
- "y-dimension" = 4
- }
- },
-
- The full encoding is in table 5. A simplified view of the encoding
- looks like this:
-
- Table 4 - Overview Encoding of "media-col" collection
-
- Tag Value Name Value
-
- begCollection media-col ""
-
- memberAttrName "" media-color
-
- keyword "" blue
-
- memberAttrName "" media-size
-
- begCollection "" ""
-
- memberAttrName "" x-dimension
-
- integer "" 6
-
- memberAttrName "" y-dimension
-
- integer "" 4
-
- endCollection "" ""
-
- endCollection "" ""
-
-
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 15]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Table 5 - Example Encoding of "media-col" collection
-
- Octets Symbolic Value Protocol comments
- field
-
- 0x34 begCollection value-tag beginning of the "media-
- col" collection attribute
-
- 0x0009 name- length of (collection)
- length attribute name
-
- media-col media-col name name of (collection)
- attribute
-
- 0x0000 value- defined to be 0 for this
- length type
-
- no value (since value-
- length was 0)
-
- 0x4A memberAttrName value-tag starts a new member
- attribute: "media-color"
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
- 0x000B value- length of "media-color"
- length keyword
-
- media-color media-color value value is name of 1st
- member attribute
-
-
- 0x44 keyword type value-tag keyword type
-
- 0x0000 name- 0 indicates 1setOf
- length
-
- no name (since name-length
- was 0)
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 16]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Octets Symbolic Value Protocol comments
- field
-
- 0x0004 value-
- length
-
- blue blue value value of 1st member
- attribute
-
-
- 0x4A memberAttrName value-tag starts a new member
- attribute: "media-size"
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
- 0x000A value- length of "media-size"
- length keyword
-
- media-size media-size value Name of 2nd member
- attribute
-
- 0x34 begCollection value-tag Beginning of the "media-
- size" collection attribute
- which is a sub-collection
-
- 0x0000 name- 0 indicates 1setOf
- length
-
- no name (since name-length
- was 0)
-
- 0x0000 value- collection attribute names
- length have no value
-
- no value (since value-
- length was 0)
-
- 0x4A memberAttrName value-tag starts a new member
- attribute: "x-dimension"
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 17]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Octets Symbolic Value Protocol comments
- field
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
- 0x000B value- length of "x-dimension"
- length keyword
-
- x-dimension x-dimension value name of 1st sub-
- collection member
- attribute
-
-
- 0x21 integer type value-tag attribute type
-
- 0x0000 name- 0 indicates 1setOf
- length
-
- no name (since name-length
- was 0)
-
- 0x0004 value- length of an integer = 4
- length
-
- 0x0006 value value of 1st sub-
- collection member
- attribute
-
- 0x4A memberAttrName value-tag starts a new member
- attribute: "y-dimension"
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
- 0x000B value- length of the "y-
- length dimension" keyword
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 18]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Octets Symbolic Value Protocol comments
- field
-
- y-dimension y-dimension value name of 2nd sub-
- collection member
- attribute
-
- 0x21 integer type value-tag attribute type
-
- 0x0000 name- 0 indicates 1setOf
- length
-
- no name (since name-length
- was 0)
-
- 0x0004 value- length of an integer = 4
- length
-
- 0x0004 value value of 2nd sub-
- collection member
- attribute
-
- 0x37 endCollection value-tag end of the sub-collection
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
- 0x0000 value- defined to be 0 for this
- length type
-
- no value (since value-
- length was 0)
-
- 0x37 endCollection value-tag end of the 1st collection
- value in 1setOf
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
-
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 19]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Octets Symbolic Value Protocol comments
- field
-
- no name (since name-length
- was 0)
-
- 0x0000 value- defined to be 0 for this
- length type
-
- no value (since value-
- length was 0)
-
-8 Legacy issues
-
- IPP 1.x Printers and Clients will gracefully ignore collections and
- its member attributes if it does not understand the collection. The
- begCollection and endCollection elements each look like an attribute
- with an attribute syntax that the recipient doesn't support and so
- should ignore the entire attribute. The individual member attributes
- and their values will look like a 1setOf values of the collection
- attribute, so that the Printer simply ignores the entire attribute
- and all of its values. Returning unsupported attributes is also
- simple, since only the name of the collection attribute is returned
- with the 'unsupported' out-of-band value (see section 4.2).
-
-9 IANA Considerations
-
- The following table provides registration for the 'collection'
- attribute syntax defined in this document. This is to be registered
- according to the procedures in RFC 2911 [RFC2911] section 6.3.
-
- Tag value: Attribute Syntaxes: Ref. Section:
- collection RFC 3382 3
- 0x34 begCollection RFC 3382 7.1
- 0x37 endCollection RFC 3382 7.1
- 0x4A memberAttrName RFC 3382 7.1
-
- The resulting attribute syntax registration will be published in the
- http://www.iana.org/assignments/ipp-registrations registry.
-
-10 Internationalization Considerations
-
- This attribute syntax by itself has no impact on
- internationalization. However, the member attributes that are
- subsequently defined for use in a collection may have
- internationalization considerations, as may any attribute, according
- to [RFC2911].
-
-
-
-
-deBry, et. al. Standards Track [Page 20]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
-11 Security Considerations
-
- This attribute syntax causes no more security concerns than any other
- attribute syntax. It is only the attributes that are subsequently
- defined, to use this or any other attribute syntax, that may have
- security concerns, depending on the semantics of the attribute,
- according to [RFC2911].
-
-12 References
-
-12.1 Normative References
-
- [RFC2910] Herriot, R., Butler, S., Moore, P. and R. Turner, "Internet
- Printing Protocol/1.1: Encoding and Transport", RFC 2910,
- September 2000.
-
- [RFC2911] Isaacson, S., deBry, R., Hastings, T., Herriot, R. and P.
- Powell, "Internet Printing Protocol/1.1: Model and
- Semantics", RFC 2911, September 2000.
-
-12.2 Informative References
-
- [RFC2565] Herriot, R., Butler, S., Moore, P. and R. Tuner, "Internet
- Printing Protocol/1.0: Encoding and Transport", RFC 2565,
- April 1999.
-
- [RFC2566] deBry, R., Hastings, T., Herriot, R., Isaacson, S. and P.
- Powell, "Internet Printing Protocol/1.0: Model and
- Semantics", RFC 2566, April 1999.
-
- [RFC2567] Wright, D., "Design Goals for an Internet Printing
- Protocol", RFC 2567, April 1999.
-
- [RFC2568] Zilles, S., "Rationale for the Structure and Model and
- Protocol for the Internet Printing Protocol", RFC 2568,
- April 1999.
-
- [RFC2569] Herriot, R., Hastings, T., Jacobs, N. and J. Martin,
- "Mapping between LPD and IPP Protocols", RFC 2569, April
- 1999.
-
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter,
- L., Leach, P. and T. Berners-Lee, "Hypertext Transfer
- Protocol - HTTP/1.1", RFC 2616, June 1999.
-
- [RFC3196] Hastings, T., Manros, C., Zehler, P., Kugler, C. and H.
- Holst, "Internet Printing Protocol/1.1: Implementor's
- Guide", RFC 3196, November 2001.
-
-
-
-deBry, et. al. Standards Track [Page 21]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
-Appendix A: Encoding Example of a Simple Collection (Informative)
-
- The overall structure of the collection value can be pictorially
- represented as:
-
- "media-size" =
- { "x-dimension" = 6;
- "y-dimension" = 4
- }
-
- A simplified view of the encoding would look like this:
-
- Table 6 - Overview Encoding of simple collection
-
- Tag Value Name Value
-
- begCollection media-size ""
-
- memberAttrName "" x-dimension
-
- integer "" 6
-
- memberAttrName "" y-dimension
-
- integer "" 4
-
- endCollection "" ""
-
- Note: "" represents a name or value whose length is 0.
-
- Table 7 - Example Encoding of simple collection
-
- Octets Symbolic Value Protocol comments
- field
-
- 0x34 begCollection value-tag beginning of the "media-
- size" collection attribute
-
- 0x000A name- length of (collection)
- length attribute name
-
- media-size media-size name name of (collection)
- attribute
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 22]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Octets Symbolic Value Protocol comments
- field
-
- 0x0000 value- defined to be 0 for this
- length type
-
- no value (since value-
- length was 0)
-
- 0x4A memberAttrName value-tag starts member attribute:
- "x-dimension"
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
- 0x000B value- length of "x-dimension"
- length keyword
-
- x-dimension x-dimension value name of 1st collection
- member attribute
-
-
- 0x21 integer type value-tag attribute type
-
- 0x0000 name- 0 indicates 1setOf
- length
-
- no name (since name-length
- was 0)
-
- 0x0004 value- length of an integer = 4
- length
-
- 0x0006 value value of 1st collection
- member attribute
-
- 0x4A memberAttrName value-tag starts a new member
- attribute: "y-dimension"
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
-
-
-
-deBry, et. al. Standards Track [Page 23]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Octets Symbolic Value Protocol comments
- field
-
- 0x000B value- length of the "y-
- length dimension" keyword
-
- y-dimension y-dimension value name of 2nd collection
- member attribute
-
- 0x21 integer type value-tag attribute type
-
- 0x0000 name- 0 indicates 1setOf for
- length media-size
-
- no name (since name-length
- was 0)
-
- 0x0004 value- length of an integer = 4
- length
-
- 0x0004 value value of 2nd collection
- member attribute
-
- 0x37 endCollection value-tag end of the collection
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
- 0x0000 value- defined to be 0 for this
- length type
-
- no value (since value-
- length was 0)
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 24]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
-Appendix B: Encoding Example of 1setOf Collection (Informative)
-
- The overall structure of the collection value can be pictorially
- represented as:
-
- "media-size-supported" =
- { "x-dimension" = 6;
- "y-dimension" = 4
- },
- { "x-dimension" = 3;
- "y-dimension" = 5
- };
-
- A simplified view of the encoding would look like this:
-
- Table 8 - Overview Encoding of 1setOf collection
-
- Tag Value Name Value
-
- begCollection media-size- ""
- supported
-
- memberAttrName "" x-dimension
-
- integer "" 6
-
- memberAttrName "" y-dimension
-
- integer "" 4
-
- endCollection "" ""
-
- begCollection "" ""
-
- memberAttrName "" x-dimension
-
- integer "" 3
-
- memberAttrName "" y-dimension
-
- integer "" 5
-
- endCollection "" ""
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 25]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Table 9 - Example Encoding of 1setOf collection
-
- Octets Symbolic Value Protocol comments
- field
-
- 0x34 begCollection value-tag beginning of the "media-
- size-supported (1setOf
- collection" attribute
-
- 0x00014 name- length of (collection)
- length attribute name
-
- media-size- media-size- name name of (collection)
- supported supported attribute
-
- 0x0000 value- defined to be 0 for this
- length type
-
- no value (since value-
- length was 0)
-
- 0x4A memberAttrName value-tag starts member attribute:
- "x-dimension"
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
- 0x000B value- length of "x-dimension"
- length keyword
-
- x-dimension x-dimension value name of 1st collection
- member attribute
-
- 0x21 integer type value-tag attribute type
-
- 0x0000 name- 0 indicates 1setOf
- length
-
- no name (since name-length
- was 0)
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 26]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Octets Symbolic Value Protocol comments
- field
-
- 0x0004 value- length of an integer = 4
- length
-
- 0x0006 value value of 1st collection
- member attribute
-
- 0x4A memberAttrName value-tag starts member attribute:
- "y-dimension"
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
- 0x000B value- length of the "y-
- length dimension" keyword
-
- y-dimension y-dimension value name of 2nd collection
- member attribute
-
- 0x21 integer type value-tag attribute type
-
- 0x0000 name- 0 indicates 1setOf
- length
-
- no name (since name-length
- was 0)
-
- 0x0004 value- length of an integer = 4
- length
-
- 0x0004 value value of 2nd collection
- member attribute
-
- 0x37 endCollection value-tag end of the collection
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 27]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Octets Symbolic Value Protocol comments
- field
-
- 0x0000 value- defined to be 0 for this
- length type
-
- no value (since value-
- length was 0)
-
- 0x34 begCollection value-tag beginning of the 2nd
- member of the 1setOf
- "sizes-avail " collection
- attribute
-
- 0x0000 name- Zero length name indicates
- length this is member of previous
- attribute
-
- name no name (since name-length
- was 0)
-
- 0x0000 value- defined to be 0 for this
- length type
-
- no value (since value-
- length was 0)
-
- 0x4A memberAttrName value-tag starts member attribute:
- "x-dimension"
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
- 0x000B value- length of "x-dimension"
- length keyword
-
- x-dimension x-dimension value name of 1st collection
- member attribute
-
- 0x21 integer type value-tag attribute type
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 28]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Octets Symbolic Value Protocol comments
- field
-
- 0x0000 name- 0 indicates 1setOf
- length
-
- no name (since name-length
- was 0)
-
- 0x0004 value- length of an integer = 4
- length
-
- 0x0003 value value of 1st collection
- member attribute
-
- 0x4A memberAttrName value-tag starts member attribute:
- "y-dimension"
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
- 0x000B value- length of the "y-
- length dimension" keyword
-
- y-dimension y-dimension value name of 2nd collection
- member attribute
-
- 0x21 integer type value-tag attribute type
-
- 0x0000 name- 0 indicates 1setOf
- length
-
- no name (since name-length
- was 0)
-
- 0x0004 value- length of an integer = 4
- length
-
- 0x0005 value value of 2nd collection
- member attribute
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 29]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Octets Symbolic Value Protocol comments
- field
-
- 0x37 endCollection value-tag end of the 1setOf
- collection value
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
- 0x0000 value- defined to be 0 for this
- length type
-
- no value (since value-
- length was 0)
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 30]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
-Appendix C: Encoding Example of Collection containing 1setOf XXX
- attribute (Informative)
-
- The overall structure of the collection value can be pictorially
- represented as:
-
- "wagons" =
- { "colors" = red, blue;
- "sizes" = 4, 6, 8
- }
-
- A simplified view of the encoding would look like this:
-
- Table 10 - Overview Encoding of collection with 1setOf value
-
- Tag Value Name Value
-
- begCollection wagons ""
-
- memberAttrName "" colors
-
- keyword "" red
-
- keyword "" blue
-
- memberAttrName "" sizes
-
- integer "" 4
-
- integer "" 6
-
- integer "" 8
-
- endCollection "" ""
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 31]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Table 11 - Example Encoding of collection with 1setOf value
-
- Octets Symbolic Value Protocol comments
- field
-
- 0x34 begCollection value-tag beginning of the "wagons"
- collection attribute
-
- 0x0005 name- length of (collection)
- length attribute name
-
- wagons wagons name name of (collection)
- attribute
-
- 0x0000 value- defined to be 0 for this
- length type
-
- no value (since value-
- length was 0)
-
- 0x4A memberAttrName value-tag starts a new member
- attribute: "colors"
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
- 0x0006 value- length of "colors" keyword
- length
-
- colors colors value value is name of 1st
- member attribute
-
- 0x44 keyword type value-tag keyword type
-
- 0x0000 name- 0 indicates 1setOf wagons
- length
-
- no name (since name-length
- was 0)
-
- 0x0004 value-
- length
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 32]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Octets Symbolic Value Protocol comments
- field
-
- blue blue value value of 1st member
- attribute
-
- 0x44 keyword type value-tag keyword type
-
- 0x0000 name- 0 indicates 1setOf wagons
- length
-
- no name (since name-length
- was 0)
-
- 0x0003 value-
- length
-
- red red value value of 1st member
- attribute
-
- 0x4A memberAttrName value-tag starts a new member
- attribute: "sizes"
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
- 0x0005 value- length of "length-avail"
- length keyword
-
- sizes sizes value Name of 2nd member
- attribute
-
- 0x21 integer type value-tag attribute type
-
- 0x0000 name- 0 indicates 1setOf wagons
- length
-
- no name (since name-length
- was 0)
-
- 0x0004 value- length of an integer = 4
- length
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 33]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Octets Symbolic Value Protocol comments
- field
-
- 0x0004 value 1st value for 1setOf
- integer attribute
-
- 0x21 integer type value-tag attribute type
-
- 0x0000 name- 0 indicates 1setOf
- length
-
- no name (since name-length
- was 0)
-
- 0x0004 value-
- length length of an integer = 4
-
- 0x0006 value 2nd value for 1setOf
- integer attribute
-
- 0x21 integer type value-tag attribute type
-
- 0x0000 name- 0 indicates 1setOf
- length
-
- no name (since name-length
- was 0)
-
- 0x0004 value- length of an integer = 4
- length
-
- 0x0008 value 3rd value for 1setOf
- integer attribute
-
- 0x37 endCollection value-tag end of the collection
-
- 0x0000 name- defined to be 0 for this
- length type, so part of 1setOf
-
- no name (since name-length
- was 0)
-
- 0x0000 value- defined to be 0 for this
- length type
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 34]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Octets Symbolic Value Protocol comments
- field
-
- no value (since value-
- length was 0)
-
-Appendix D: Description of the Base IPP Documents (Informative)
-
- The base set of IPP documents includes:
-
- Design Goals for an Internet Printing Protocol [RFC2567]
- Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol [RFC2568]
- Internet Printing Protocol/1.1: Model and Semantics [RFC2911]
- Internet Printing Protocol/1.1: Encoding and Transport [RFC2910]
- Internet Printing Protocol/1.1: Implementer's Guide [RFC3196]
- Mapping between LPD and IPP Protocols [RFC2569]
-
- The "Design Goals for an Internet Printing Protocol" document takes a
- broad look at distributed printing functionality, and it enumerates
- real-life scenarios that help to clarify the features that need to be
- included in a printing protocol for the Internet. It identifies
- requirements for three types of users: end users, operators, and
- administrators. It calls out a subset of end user requirements that
- are satisfied in IPP/1.0 [RFC2566, RFC2565]. A few OPTIONAL operator
- operations have been added to IPP/1.1 [RFC2911, RFC2910].
-
- The "Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol" document describes IPP from a high level
- view, defines a roadmap for the various documents that form the suite
- of IPP specification documents, and gives background and rationale
- for the IETF IPP working group's major decisions.
-
- The "Internet Printing Protocol/1.1: Model and Semantics" document
- describes a simplified model with abstract objects, their attributes,
- and their operations. The model introduces a Printer and a Job. The
- Job supports multiple documents per Job. The model document also
- addresses how security, internationalization, and directory issues
- are addressed.
-
- The "Internet Printing Protocol/1.1: Encoding and Transport" document
- is a formal mapping of the abstract operations and attributes defined
- in the model document onto HTTP/1.1 [RFC2616]. It also defines the
- encoding rules for a new Internet MIME media type called
- "application/ipp". This document also defines the rules for
- transporting over HTTP a message body whose Content-Type is
- "application/ipp". This document defines the 'ipp' scheme for
- identifying IPP printers and jobs.
-
-
-
-deBry, et. al. Standards Track [Page 35]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- The "Internet Printing Protocol/1.1: Implementer's Guide" document
- gives insight and advice to implementers of IPP clients and IPP
- objects. It is intended to help them understand IPP/1.1 and some of
- the considerations that may assist them in the design of their client
- and/or IPP object implementations. For example, a typical order of
- processing requests is given, including error checking. Motivation
- for some of the specification decisions is also included.
-
- The "Mapping between LPD and IPP Protocols" document gives some
- advice to implementers of gateways between IPP and LPD (Line Printer
- Daemon) implementations.
-
-Authors' Addresses
-
- Roger deBry
- Utah Valley State College
- Orem, UT 84058
-
- Phone: (801) 222-8000
- EMail: debryro@uvsc.edu
-
-
- Tom Hastings
- Xerox Corporation
- 737 Hawaii St. ESAE 231
- El Segundo, CA 90245
-
- Phone: 310-333-6413
- Fax: 310-333-5514
- EMail: hastings@cp10.es.xerox.com
-
-
- Robert Herriot
- Consultant
- 706 Colorado Ave
- Palo Alto, CA 94303
-
- Phone: 650-327-4466
- Fax: 650-327-4466
- EMail: bob@herriot.com
-
-
-
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 36]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
- Kirk Ocke
- Xerox Corp.
- 800 Phillips Rd
- M/S 128-30E
- Webster, NY 14580
-
- Phone: (585) 442-4832
- EMail: KOcke@crt.xerox.com
-
-
- Peter Zehler
- Xerox Corp.
- 800 Phillips Rd
- M/S 128-30E
- Webster, NY 14580
-
- Phone: (585) 265-8755
- EMail: PZehler@crt.xerox.com
-
- IPP Web Page: http://www.pwg.org/ipp/
- IPP Mailing List: ipp@pwg.org
-
- To subscribe to the ipp mailing list, send the following email:
-
- 1) send it to majordomo@pwg.org
- 2) leave the subject line blank
- 3) put the following two lines in the message body:
- subscribe ipp
- end
-
- Implementers of this specification document are encouraged to join
- the IPP Mailing List in order to participate in any discussions of
- clarification issues and review of registration proposals for
- additional attributes and values. In order to reduce spam the
- mailing list rejects mail from non-subscribers, so you must subscribe
- to the mailing list in order to send a question or comment to the
- mailing list.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 37]
-\f
-RFC 3382 IPP: The 'collection' attribute syntax September 2002
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-deBry, et. al. Standards Track [Page 38]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group R. Herriot
-Request for Comments: 3391 December 2002
-Category: Informational
-
-
- The MIME Application/Vnd.pwg-multiplexed Content-Type
-
-Status of this Memo
-
- This memo provides information for the Internet community. It does
- not specify an Internet standard of any kind. Distribution of this
- memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
-IESG Note
-
- The IESG believes use of this media type is only appropriate in
- situations where the producer is fully aware of the capabilities and
- limitations of the consumer. In particular, this mechanism is very
- dependent on the producer knowing when the consumer will need a
- particular component of a multipart object. But consumers
- potentially work in many different ways and different consumers may
- need different things at different times. This mechanism provides no
- means for a producer to determine the needs of a particular consumer
- and how they are to be accommodated.
-
- Alternative mechanisms, such as a protocol based on BEEP which is
- capable of bidirectional communication between the producer and
- consumer, should be considered when the capabilities of the consumer
- are not known by the producer.
-
-Abstract
-
- The Application/Vnd.pwg-multiplexed content-type, like the
- Multipart/Related content-type, provides a mechanism for representing
- objects that consist of multiple components. An
- Application/Vnd.pwg-multiplexed entity contains a sequence of chunks.
- Each chunk contains a MIME message or a part of a MIME message. Each
- MIME message represents a component of the compound object, just as a
- body part of a Multipart/Related entity represents a component. With
- a Multipart/Related entity, a body part and its reference in some
- other body part may be separated by many octets. With an
- Application/Vnd.pwg-multiplexed entity, a message and its reference
- in some other message can be made quite close by chunking the message
- containing the reference. For example, if a long message contains
-
-
-
-Herriot Informational [Page 1]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- references to images and the producer does not know of the need for
- each image until it generates the reference, then
- Application/Vnd.pwg-multiplexed allows the consumer to process the
- reference to the image and the image before it consumes the entire
- long message. This ability is important in printing and scanning
- applications. This document defines the Application/Vnd.pwg-
- multiplexed content-type. It also provides examples of its use.
-
-Table of Contents
-
- 1. Introduction....................................................2
- 2. Terminology.....................................................7
- 3. Details.........................................................9
- 3.1 Syntax of Application/Vnd.pwg-multiplexed Contents...........10
- 3.2 Parameters for Application/Vnd.pwg-multiplexed...............12
- 3.2.1 The "type" Parameter.......................................12
- 3.2.2 Syntax.....................................................12
- 4. Handling Application/Vnd.pwg-multiplexed Entities..............12
- 5. Examples.......................................................13
- 5.1 Example With Multipart/Related...............................14
- 5.2 Examples with Application/Vnd.pwg-multiplexed................15
- 5.2.1 Example Where Each Chunk Has a Complete Message............15
- 5.2.2 Example of Chunking the Root Message.......................17
- 5.2.3 Example of Chunking the Several Messages...................18
- 5.2.4 Example of Chunks with Empty Payloads......................20
- 6. Security Considerations........................................22
- 7. Registration Information for Application/Vnd.pwg-multiplexed...22
- 8. Acknowledgments................................................23
- 9. References.....................................................23
- 10. Author's Address..............................................24
- 11. Full Copyright Statement......................................25
-
-1. Introduction
-
- The simple MIME content-types, such as "text/plain" provide a
- mechanism for representing a simple object, such as a text document.
- The Multipart/Related [RFC2387] content-type provides a mechanism for
- representing a compound object, such as a text document with two gif
- images.
-
- A compound object consists of multiple components. One such
- component is the root component, which contains references to other
- components of the compound object. These components may, in turn,
- contain references to other components of the compound object. For
- example, a compound object could consist of a root html text
- component and two gif image components -- each referenced by the root
- component.
-
-
-
-
-Herriot Informational [Page 2]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- A compound object and a component are both abstractions. For
- transmission over the wire or writing to storage, each needs a
- representation. A "Multipart/Related entity" is one possible
- representation of a compound object, and a "body part" is one
- possible representation of a component.
-
- However, the Multipart/Related content-type is not a good solution
- for applications that require each component to be close to its
- corresponding reference in the root component. This document defines
- a new MIME content-type Application/Vnd.pwg-multiplexed that provides
- a better solution for some applications. The Application/Vnd.pwg-
- multiplexed content-type, like the Multipart/Related content-type,
- provides a common mechanism for representing a compound object. A
- Multipart/Related entity consists of a sequence of body parts
- separated by boundary strings. Each body part represents a component
- of the compound object. An Application/Vnd.pwg-multiplexed entity
- consists of a sequence of chunks, each of whose length is specified
- in the chunk header. Each chunk contains a message or a part of a
- message. Each message represents a component of the compound object.
- Chunks from different messages can be interleaved. HTTP is the
- typical transport for an Application/Vnd.pwg-multiplexed entity over
- the wire. An Application/Vnd.pwg-multiplexed entity could be stored
- in a Microsoft HTML (message/rfc822) file whose suffix is .mht.
-
- The following paragraphs contain three examples of applications. For
- each application, there is a discussion of its solution with the
- Application/Vnd.pwg-multiplexed content-type, the Multipart/Related
- content-type and BEEP [RFC3080].
-
- Example 1: a printing application. A Producer creates a print stream
- that consists of a very long series of page descriptions, each of
- which references one or more images. The root component is the long
- series of page descriptions. An image may be referenced from
- multiple pages descriptions, and there is a mechanism to indicate
- when there are no additional references to an image (i.e., the image
- is out of scope). The Producer does not know what images to include
- with a page until it generates that page. The Consumer is presumed
- to have enough storage to hold all in-scope images and enough of the
- root component to process at least one page. The Producer doesn't
- need any knowledge of the Consumer's storage capabilities in order to
- create an entity that the Consumer can successfully process.
- However, the Producer needs to be prudent about the number of images
- that are in-scope at any time. Of course, a malicious Producer may
- try to exceed the storage capabilities of the Consumer, and the
- Consumer must guard against such entities (see section 6). Here are
- ways to represent this compound object.
-
-
-
-
-
-Herriot Informational [Page 3]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- With the Application/Vnd.pwg-multiplexed content-type, each image
- is a message and the root component is a message. The Producer
- breaks the root component message into chunks with each image
- message occurring shortly before its first reference. When the
- Consumer encounters a reference, it can assume that it has already
- received the referenced image in an earlier chunk.
-
- With the Multipart/Related content-type, each image must either
- precede or follow the root component.
-
- If images follow the root component, the Consumer must read all
- remaining pages of the root component before it can print the
- first page that references such images. The Consumer must wait
- to print such a page until it has received the entire root
- component, and the Consumer may not have the space to hold the
- remaining pages.
-
- If images precede the root component, the Producer must
- determine and send all such images before it sends the root
- component. The Consumer must, in the best case, wait some
- additional time before it receives the first page of the root
- component. In the worse case, the Consumer may not have enough
- storage for all the images.
-
- The Multipart/Related solution is not a good solution because
- of the wait time and because, in some cases, the Consumer may
- not have sufficient storage for all of the images.
-
- With BEEP, the images and root component can be sent in separate
- channels. The Producer can push each image when it encounters the
- first reference or the Consumer can request it when it encounters
- the first reference. The over-the-wire stream of octets is
- similar to an Application/Vnd.pwg-multiplexed entity. However,
- there is a substantial difference in behavior for a printing
- application. With the Application/Vnd.pwg-multiplexed content-
- type, the Producer puts each image message before its first
- reference so that when the Consumer encounters a reference, the
- image is guaranteed to be present on the printer. With BEEP, if
- the Consumer pulls the image, the Consumer has to wait while the
- image comes over the network. If the Producer pushes the image,
- BEEP may put the image message after its first reference and the
- Consumer may still have to wait for the image. A high-speed
- printer should not have to risk waiting for images; otherwise it
- cannot run at full speed.
-
- Example 2: a scanning (fax-like) application. The Producer is a
- scanner, which scans pages and sends them along with a vnd.pwg-
- xhtml-print+xml root component that contains references to each page
-
-
-
-Herriot Informational [Page 4]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- image. Each page is referenced exactly once in the root-component.
- The Consumer is a printer that consumes vnd.pwg-xhtml-print+xml
- entities and their attachments. That is, the Consumer is not limited
- to print jobs that come from scanners. A Producer and Consumer are
- each presumed to have enough storage to hold a few page images and
- most if not all of the root component. The Producer doesn't need any
- additional knowledge of the Consumer's storage capabilities in order
- to create an entity that the Consumer can successfully process. Of
- course, a malicious Producer may try to exceed the storage
- capabilities of the Consumer and the Consumer must guard against such
- entities (see section 6). Here are ways to represent this compound
- object.
-
- With the Application/Vnd.pwg-multiplexed content-type, each page
- image is a message and the root component is a message. The
- Producer breaks the root component message into chunks with each
- image message just before or just after its reference.
-
- With the Multipart/Related content-type, the images cannot precede
- the root component because the Consumer might not have enough
- space to store them until the root component arrived. In this
- case, the printer could fail to print the job correctly and the
- Producer might not know. Therefore the images must follow the
- root component, and the Producer must scan all pages before it can
- send the first page. At the very least, this solution delays the
- printing of the pages until all have been scanned. In the worst
- case, the Producer does not have sufficient memory to buffer the
- images, and the job fails.
-
- With BEEP, the issues are the same as in the previous example,
- except that speed is not as important in this case. So BEEP is a
- viable alternative for this example.
-
- Example 3: a printing application. A Producer creates a print stream
- that consists of a series of pages, each of which references zero or
- more images. Each image is referenced exactly once. The Producer
- does not know what images to include with a page until it generates
- that page, and the Producer doesn't know the layout details; the
- Consumer handles layout. The Producer has enough storage to send the
- root component and all images. However, it may not have enough
- storage to hold the entire root component or all octets of any of the
- images. The Consumer is presumed to have enough storage to render
- the root component and to render each image. It may not have enough
- storage to hold the entire root component or all octets of any of the
- images. The Producer doesn't determine the Consumer's storage
- capabilities. Rather it arranges the components so that the Consumer
- is mostly likely to succeed. Of course, a malicious Producer may try
-
-
-
-
-Herriot Informational [Page 5]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- to exceed the storage capabilities of the Consumer, and the Consumer
- must guard against such entities (see section 6). Here are ways to
- represent this compound object.
-
- With the Application/Vnd.pwg-multiplexed content-type, each image
- is a message and the root component is a message. The Producer
- breaks the root component message into chunks with each image
- message just after its reference. The references appear first so
- that the Consumer knows the location of each image before it
- processes the image. This strategy minimizes storage needs for
- Producer and Consumer and provides a good strategy in case of
- failure. Here are the cases to consider.
-
- a) When the document consists of vertically aligned blocks where
- each block contains either lines of text or a single image, the
- sequence of chunks is the same as the sequence of printable
- blocks, thus minimizing Consumer buffering needs.
-
- b) When a block can contain N side-by-side images, the Consumer
- must buffer N-1 images unless the Producer interleaves the
- images. If the Producer doesn't interleave the images, and the
- Consumer runs out of storage before it has received N-1,
- images, it can print what it has and print the remaining images
- below; not what the Producer intended, but better than nothing.
- If the Producer interleaves images, and the Consumer runs out
- of storage before it has received the bands of N images, the
- Consumer would print portions of images interleaved with
- portions of other images. So, a Producer should not interleave
- images.
-
- c) When a block contains text and image side-by-side (i.e., run-
- around text), there are additional buffering requirements.
- When the Consumer processes the text that follows the
- reference, it will place some of it next to the image (run-
- around text) and will place the remaining text after the image.
- The Producer doesn't know where the run-around ends, and thus
- doesn't know where to end the text chunk and start the image
- chunk. If the Producer ends the text too soon, then the
- Consumer either has to process the entire image (if it has
- enough storage) in order to get the remaining run-around text,
- or it ends the run-around text prematurely. If the Producer
- ends the text too late, then the Consumer may have to store too
- much text and possibly put the image later than the Producer
- requested. Because text data requires significantly less
- storage than image data, a good strategy for Producer is to err
- on the side of sending too much rather than too little text
- before the image data.
-
-
-
-
-Herriot Informational [Page 6]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- d) When a block contains text and multiple side-by-side images,
- the problem becomes a combination of items b) and c) above.
-
- The Application/Vnd.pwg-multiplexed content-type can be made to
- work in this example, but a Consumer must have failure strategies
- and the result may not be quite what the producer intended. With
- the Multipart/Related content-type, the images cannot precede the
- root component because the Consumer might not have enough space to
- store them until the root component arrived. Also, the images
- cannot follow the root component because the Consumer might not
- have enough storage for the root component before the first image
- arrives. So the Multipart/Related content-type is not an
- acceptable solution for this example.
-
- With BEEP, the Producer can send the root component on channel 1
- and the Consumer can request images on even numbered channels when
- it encounters a reference. This solution allows more flexibility
- than the Application/Vnd.pwg-multiplexed content-type. If there
- are side-by-side images and/or run-around text, the Consumer can
- request bands of each image or run-around text over separate
- channels.
-
- In all of these examples, the Application/Vnd.pwg-multiplexed
- content-type provides a much better solution than Multipart/Related.
- However, it is evenly matched with BEEP. For applications where
- speed is important and ordering of the chunks is important in order
- to avoid printing delays, the Application/Vnd.pwg-multiplexed
- content-type is best. For applications, where the Consumer needs
- more control over the ordering of received octets, BEEP is best.
-
-2. Terminology
-
- This document uses some of the MIME terms that are defined in
- [RFC2045]. The following are the terms used in this document:
-
- Entity: the headers and the content. In this document, the term
- "entity" describes all the octets that represent a compound
- object.
-
- Message: an entity as in [RFC2045]. In this document, the term
- "message" describes all octets that represent one component of a
- compound object. That is, it has MIME headers and content.
-
- Body Part: an entity inside a multipart. That is, a body part is
- the headers and content (i.e., octets) between the multipart
- boundary strings not including the CRLF at the beginning and end.
- This document never uses "entity" to mean "body part".
-
-
-
-
-Herriot Informational [Page 7]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- Headers: the initial lines of an entity, message or body part. An
- empty line (i.e., two adjacent CRLFs) terminates the headers.
- Sometimes the term "MIME header" is used instead of just "header".
-
- Content: the part of an entity, message or body part that follows
- the headers (i.e., follows the two adjacent CRLFs). The content
- of a body part ends at the octet preceding the CRLF before the
- multipart boundary string. The content of a message ends at the
- octets specified by the length field in the Chunk Header.
-
- This document uses the following additional terms.
-
- Chunk: a chunk of data, consisting of a chunk header, a chunk
- payload and a CRLF.
-
- Chunk Header: the first line of a chunk. The line consists of the
- "CHK" keyword, the message number, the length and the continuation
- indicator, each separated by a single space character (ASCII 32).
- A CRLF terminates the line. Each message in an
- Application/Vnd.pwg-multiplexed entity has a message number that
- normally differs from the message numbers of all other messages in
- the Application/Vnd.pwg-multiplexed entity. The message number 0
- is reserved for final Chunk Header in the Application/Vnd.pwg-
- multiplexed entity.
-
- Chunk Payload: the octets between the Chunk Header and the Chunk
- Header of the next chunk. The length field in the header's length
- field specifies the number of octets in the Chunk Payload. The
- Chunk Payload is either a complete message or a part of a message.
- The continuation field in the header specifies whether the chunk
- is the last chunk of the message.
-
- CRLF: the sequence of octets corresponding to the two US-ASCII
- characters CR (decimal value 13) and LF (decimal value 10) which,
- taken together, in this order, denote a line break. A CRLF
- terminates each chunk in order to provide visual separation from
- the next chunk header.
-
- Consumer: the software that receives and processes a MIME entity,
- e.g., software in a printer or software that reads a file.
-
- Producer: the software that creates and sends a MIME entity, e.g.,
- software in a scanner or software that writes a file.
-
-
-
-
-
-
-
-
-Herriot Informational [Page 8]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
-3. Details
-
- The Application/Vnd.pwg-multiplexed content-type, like
- Multipart/Related, is intended to represent a compound object
- consisting of several inter-related components. This document does
- not specify the representation of these relationships, but [RFC2557]
- contains examples of Multipart/Related entities that use the
- Content-ID and Content-Location headers to identify body parts and
- URLs (including the "cid" URL) to reference body parts. It is
- expected that Application/Vnd.pwg-multiplexed entities would use the
- patterns described in [RFC2557].
-
- For an Application/Vnd.pwg-multiplexed entity, there is one parameter
- for the Content-Type header. It is a "type" parameter, and it is
- like the "type" parameter for the Multipart/Related content-type.
- The value of the "type" parameter must be the content-type of the
- root message and it effectively specifies the type of the compound
- object.
-
- An Application/Vnd.pwg-multiplexed entity contains a sequence of
- chunks. Each chunk consists of a chunk header, a chunk payload and a
- CRLF.
-
- - The chunk header consists of a "CHK" keyword followed by the
- message number, the chunk payload length, whether the chunk is
- the last chunk of a message and, finally, a CRLF. The length
- field removes the need for boundary strings that Multipart uses.
- (See section 3.1 for the syntax of a chunk header).
-
- - The chunk payload is a sequence of octets that is either a
- complete message or a part of a message.
-
- - The CRLF provides visual separation from the following chunk.
-
- Each message represents a component of the compound object, and a
- message is intended to have exactly the same representation, octet
- for octet, as a body part of a Multipart/Related entity that
- represents the same component. When a message is split across
- multiple chunks, the chunks need not be contiguous.
-
- The contents of an Application/Vnd.pwg-multiplexed entity have the
- following properties:
-
- 1) The first chunk contains a complete or partial message that (in
- either case) represents the root component of the compound
- object.
-
-
-
-
-
-Herriot Informational [Page 9]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- 2) Additional chunks contain messages or partial messages that
- represent some component of the compound object.
-
- 3) The final chunk's header contains a message number of 0, a
- length of 0 and a last-chunk-of-message mark (i.e., the chunk
- header line is "CHK 0 0 LAST"). The final chunk contains no
- chunk payload.
-
- 4) A message can be broken into multiple parts and each break can
- occur anywhere within the message. Each part of the message is
- zero or more bytes in length and each part of the message is
- the contents of its own chunk. The order of the chunks within
- the Application/Vnd.pwg-multiplexed entity must be the same as
- the order of the parts within the message.
-
- 5) A message represents a component of a compound object, and it
- is intended that it have exactly the same representation, octet
- for octet, as a body part of a Multipart/Related entity that
- represents the same component. In particular, the message may
- contain a Content-Type header to specify the content-type of
- the message content. Also, the message may contain a Content-
- ID header and/or Content-Location header to identify a message
- that is referenced from within another message. If a message
- contains no Content-Type header, then the message has an
- implicit content-type of "text/plain; charset=us-ascii", cf.
- [RFC2045].
-
- See section 4 for a discussion displaying an Application/Vnd.pwg-
- multiplexed entity.
-
-3.1 Syntax of Application/Vnd.pwg-multiplexed Contents
-
- The ABNF [RFC2234] for the contents of an Application/Vnd.pwg-
- multiplexed entity is:
-
- contents = *chunk finalChunk
- chunk = header payload CRLF
- header = "CHK" SP messageNumber SP length SP isMore CRLF
- messageNumber = 1..2147483647
- length = 0..2147483647
- isMore = "MORE" / "LAST"
- payload = *OCTET
- finalChunk = finalHeader CRLF
- finalHeader = "CHK" SP "0" SP "0" SP "LAST" CRLF
-
-
-
-
-
-
-
-Herriot Informational [Page 10]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- The messageNumber field specifies the message that the chunk is
- associated with. See the end of this section for more details.
-
- The length field specifies the number of octets in the chunk payload
- (represented in ABNF as "payload"). The first octet of the chunk
- payload is the one immediately following the LF (i.e., final octet)
- of the chunk header. The last octet of the chunk payload is the one
- immediately preceding the two octets CRLF that end the chunk.
-
- The isMore field has a value of "LAST" for the last chunk of a
- message and "MORE" for all other chunks of a message.
-
- Normally each message in an Application/Vnd.pwg-multiplexed entity
- has a unique message number, and a message consists of the
- concatenation of all the octets from the one or more chunks with the
- same message number. The isMore field of the chunk header of the
- last chunk of each message must have a value of "LAST" and the isMore
- field of the chunk header of all other chunks must have a value of
- "MORE".
-
- Two or more messages may have the same message number, though such
- reuse of message numbers is not recommended. The chunks with the
- same message number represent a sequence of one or more messages
- where the isMore field of the chunk header of the last chunk of each
- message has a value of "LAST". All chunks whose isMore field of the
- chunk header has the value of "MORE" belong to the same message as
- the next chunk (in sequence) whose isMore field of the chunk header
- has the value of "LAST". In other words, if two messages have the
- same message number, the last chunk of the first message must occur
- before the first chunk of the second message.
-
- The behavior of the Consumer is undefined if the final Chunk (i.e.,
- the Chunk whose chunk header is "CHK 0 0 LAST") occurs before the
- last chunk of every message occurs.
-
- Two adjacent chunks usually have different message numbers. However,
- they may have the same message number. If two adjacent chunks have
- the same message number, the two chunks could be combined into a
- single chunk, but they need not be combined.
-
- The number of octets in a chunk payload may be zero, and an
- Application/Vnd.pwg-multiplexed entity may contain any number of
- chunks with zero octets of chunk payload. For example, the last
- chunk of each message may contain zero octets for programming
- convenience. As another example, suppose that a particular compound
- object format requires that referenced messages occur before the root
- message. This document requires that the first chunk of an
- Application/Vnd.pwg-multiplexed entity contain the root message or a
-
-
-
-Herriot Informational [Page 11]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- part of it. So, the first chunk contains a chunk payload of zero
- octets with the first octet of the root message in the second chunk.
- That is, all of the message headers of the root message are in the
- second chunk. As an extreme but unlikely example, it would be
- possible to have a message broken into ten chunks with zero octet
- chunk payloads in all chunks except for chunks 4 and 7.
-
-3.2 Parameters for Application/Vnd.pwg-multiplexed
-
- This section defines additional parameters for Application/Vnd.pwg-
- multiplexed.
-
-3.2.1 The "type" Parameter
-
- The type parameter must be specified. Its value is the content-type
- of the "root" message. It permits a Consumer to determine the
- content-type without reference to the enclosed message. If the value
- of the type parameter differs from the content-type of the root
- message, the Consumer's behavior is undefined.
-
-3.2.2 Syntax
-
- The syntax for "parameter" is:
-
- parameter := "type" "=" type "/" subtype ; cf. [RFC2045]
-
-4. Handling Application/Vnd.pwg-multiplexed Entities
-
- The application that handles the Application/Vnd.pwg-multiplexed
- entity has the responsibility for displaying the entity. However,
- Application/Vnd.pwg-multiplexed messages may contain Content-
- Disposition headers that provide suggestions for the display and
- storage of a message, and in some cases the application may pay
- attention to such headers.
-
- As a reminder, Content-Disposition headers [RFC1806] allow the sender
- to suggest presentation styles for MIME messages. There are two
- presentation styles, 'inline' and 'attachment'. Content-Disposition
- headers have a parameter for specifying a suggested file name for
- storage.
-
- There are three cases to consider for handling Application/Vnd.pwg-
- multiplexed entities:
-
- a) The Consumer recognizes Application/Vnd.pwg-multiplexed and the
- content-type of the root. The Consumer determines the
- presentation style for the compound object; it handles the
- display of the components of the compound object in the context
-
-
-
-Herriot Informational [Page 12]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- of the compound object. In this case, the Content-Disposition
- header information is redundant or even misleading, and the
- Consumer shall ignore them for purposes of display. The
- Consumer may use the suggested file name if the entity is
- stored.
-
- b) The Consumer recognizes Application/Vnd.pwg-multiplexed, but
- not the content-type of the root. The Consumer will give the
- user the choice of suppressing the entire Application/Vnd.pwg-
- multiplexed entity or treating the Application/Vnd.pwg-
- multiplexed entity as a Multipart/Mixed entity where each
- message is a body part of the Multipart/Mixed entity. In this
- case (where the entity is not suppressed), the Consumer may
- find the Content-Disposition information useful for displaying
- each body part of the resulting Multipart/Mixed entity. If a
- body part has no Content-Disposition header, the Consumer
- should display the body part as an attachment.
-
- c) The Consumer does not recognize Application/Vnd.pwg-
- multiplexed. The Consumer treats the Application/Vnd.pwg-
- multiplexed entity as opaque and can do nothing with it.
-
-5. Examples
-
- This section contains five examples. Each example is a different
- representation of the same compound object. The compound object has
- four components: an XHTML text component and three image components.
- The images are encoded in binary. The string "<<binary data>>" and
- "<<part of binary data>>" in each example represents all or part of
- the binary data of each image. Two of the images are potentially
- side by side and the third image is displayed later in the document.
- All of the images are identified by Content-Id and two of the images
- are also identified by a Content-Location. One of the images
- references the Content-Location.
-
- The first example shows a Multipart/Related representation of the
- compound object in order to provide a representation that the reader
- is familiar with. The remaining examples show Application/Vnd.pwg-
- multiplexed representations of the same compound object. In the
- second example, each chunk contains a whole message. In the third
- example, the XHTML message is split across 3 chunks, and these chunks
- are interleaved among the three image messages. In the fourth
- example, the XHTML message is split across 4 chunks, and the two
- side-by-side images are each split across two chunks. The XHTML
- chunks are interleaved among the image chunks. In the fifth example,
- there are chunks with empty payloads and adjacent chunks with the
- same message number.
-
-
-
-
-Herriot Informational [Page 13]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- The last example may seem to address useless cases, but sometimes it
- is easier to write software if these cases are allowed. For example,
- when a buffer fills, it may be easiest to write a chunk and not worry
- if the previous chunk had the same message number. Likewise, it may
- be easiest to end a message with an empty chunk. Finally, the
- Application/Vnd.pwg-multiplexed content-type requires that the first
- chunk be part of the root message. Sometimes, it is more convenient
- for the Producer if the root message starts after the occurrence of
- some attachments. Since a chunk can be empty, the first chunk of the
- root message can be empty, i.e., it doesn't even contain any headers.
- Then the first chunk contains a part of the root message, but the
- Producer doesn't generate any octets for that chunk.
-
- Each body part of the Multipart/Related entity and each message of
- the Application/Vnd.pwg-multiplexed entity contain a content-
- disposition, which the Consumer uses according to the rules in
- section 4. Note the location of the content-disposition headers in
- the examples.
-
-5.1 Example With Multipart/Related
-
- In this example, the compound object is represented as a
- Multipart/Related entity so that the reader can compare it with the
- Application/Vnd.pwg-multiplexed entities.
-
- Content-Type: multipart/related; boundary="boundary-example";
- type="text/xhtml+xml"
-
- --boundary-example
- Content-ID: <49568.44343xxx@foo.com>
- Content-Type: application/vnd.pwg-xhtml-print+xml
- Content-Disposition: inline
-
- <?xml version="1.0"?>
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
- <html xmlns="http://www.w3.org/TR/xhtml1">
- <body>
- <p>some text
- <img src="cid:49568.45876xxx@foo.com"/>
- <img src="http://foo.com/images/image2.gif"/>
- some more text after the images
- </p>
- <p>some more text without images
- </p>
- <p>some more text
- <img src="cid:49568.47333xxx@foo.com"/>
- </p>
-
-
-
-Herriot Informational [Page 14]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- <p>some final text
- </p>
- </body>
- </html>
- --boundary-example
- Content-ID: <49568.45876xxx@foo.com>
- Content-Location: http://foo.com/images/image1.gif
- Content-Type: image/gif
- Content-Disposition: attachment
-
- <<binary data>>
- --boundary-example
- Content-ID: <49568.46000xxx@foo.com>
- Content-Location: http://foo.com/images/image2.gif
- Content-Type: image/gif
- Content-Disposition: attachment
-
- <<binary data>>
- --boundary-example
- Content-ID: <49568.47333xxx@foo.com>
- Content-Type: image/gif
- Content-Disposition: attachment
-
- <<binary data>>
- --boundary-example--
-
-5.2 Examples with Application/Vnd.pwg-multiplexed
-
- The four examples in this section show Application/Vnd.pwg-
- multiplexed representations of the same compound object. Note that
- each CRLF is represented by a visual line break.
-
-5.2.1 Example Where Each Chunk Has a Complete Message
-
- In this example, the compound object is represented as an
- Application/Vnd.pwg-multiplexed entity. Each chunk contains an
- entire message, i.e., none of the messages are split across multiple
- chunks. Each message in this example is identical to the
- corresponding body part in the preceding Multipart/Relate example.
-
- Content-Type: application/vnd.pwg-multiplexed;
- type="application/vnd.pwg-xhtml-print+xml"
-
- CHK 1 550 LAST
- Content-ID: <49568.44343xxx@foo.com>
- Content-Type: application/vnd.pwg-xhtml-print+xml
- Content-Disposition: inline
-
-
-
-
-Herriot Informational [Page 15]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- <?xml version="1.0"?>
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
- <html xmlns="http://www.w3.org/TR/xhtml1">
- <body>
- <p>some text
- <img src="cid:49568.45876xxx@foo.com"/>
- <img src="http://foo.com/images/image2.gif"/>
- some more text after the images
- </p>
- <p>some more text without images
- </p>
- <p>some more text
- <img src="cid:49568.47333xxx@foo.com"/>
- </p>
- <p>some final text
- </p>
- </body>
- </html>
-
- CHK 2 6346 LAST
- Content-ID: <49568.45876xxx@foo.com>
- Content-Location: http://foo.com/images/image1.gif
- Content-Type: image/gif
- Content-Disposition: attachment
-
- <<binary data>>
- CHK 3 6401 LAST
- Content-ID: <49568.46000xxx@foo.com>
- Content-Location: http://foo.com/images/image2.gif
- Content-Type: image/gif
- Content-Disposition: attachment
-
- <<binary data>>
- CHK 4 7603 LAST
- Content-ID: <49568.47333xxx@foo.com>
- Content-Type: image/gif
- Content-Disposition: attachment
-
- <<binary data>>
- CHK 0 0 LAST
-
-
-
-
-
-
-
-
-
-
-Herriot Informational [Page 16]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
-5.2.2 Example of Chunking the Root Message
-
- In this example, the compound object is represented as an
- Application/Vnd.pwg-multiplexed entity. The message containing the
- XHTML component is split into 3 pieces so that the reference to an
- image is as close as possible to the beginning of the chunk. The
- chunk containing the referenced image message occurs just before the
- chunk with the reference. This minimizes the distance between
- reference and referenced message.
-
- Note that there are other possible arrangements (see the third
- example in section 5.2.3). For example, a sender could split the
- XHTML message so that the reference to an image is as close as
- possible to the end of the chunk. Then the chunk containing the
- referenced image message should occur just after the chunk with the
- reference. The sender could mix this strategy with the one used in
- this example.
-
- Content-Type: application/vnd.pwg-multiplexed;
- type=" application/vnd.pwg-xhtml-print+xml"
-
- CHK 1 267 MORE
- Content-ID: <49568.44343xxx@foo.com>
- Content-Type: application/vnd.pwg-xhtml-print+xml
- Content-Disposition: inline
-
- <?xml version="1.0"?>
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
- <html xmlns="http://www.w3.org/TR/xhtml1">
- <body>
- <p>some text
-
- CHK 2 6346 LAST
- Content-ID: <49568.45876xxx@foo.com>
- Content-Location: http://foo.com/images/image1.gif
- Content-Type: image/gif
- Content-Disposition: attachment
-
- <<binary data>>
- CHK 3 6401 LAST
- Content-ID: <49568.46000xxx@foo.com>
- Content-Location: http://foo.com/images/image2.gif
- Content-Type: image/gif
- Content-Disposition: attachment
-
-
-
-
-
-
-Herriot Informational [Page 17]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- <<binary data>>
- CHK 1 166 MORE
- <img src="cid:49568.45876xxx@foo.com"/>
- <img src="http://foo.com/images/image2.gif"/>
- some more text after the images
- </p>
- <p>some more text without images
- </p>
- <p>some more text
-
- CHK 4 7603 LAST
- Content-ID: <49568.47333xxx@foo.com>
- Content-Type: image/gif
- Content-Disposition: attachment
-
- <<binary data>>
- CHK 1 80 LAST
- <img src="cid:49568.47333xxx@foo.com"/>
- </p>
- <p>some final text
- </p>
- </body>
- </html>
-
- CHK 0 0 LAST
-
-5.2.3 Example of Chunking the Several Messages
-
- In this example, the compound object is represented as an
- Application/Vnd.pwg-multiplexed entity. The message containing the
- XHTML component is split into 4 pieces so that the reference to an
- image is as close as possible to either the beginning or the end of
- the chunk. The references to the first and second images closely
- follow the referenced images. The reference to the third image
- closely precedes the referenced image. This minimizes the distance
- between reference and referenced message. In addition, the first two
- image messages are split into two chunks each.
-
- Content-Type: application/vnd.pwg-multiplexed;
- type=" application/vnd.pwg-xhtml-print+xml"
-
- CHK 1 303 MORE
- Content-ID: <49568.44343xxx@foo.com>
- Content-Type: application/vnd.pwg-xhtml-print+xml
- Content-Disposition: inline
-
-
-
-
-
-
-Herriot Informational [Page 18]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- <?xml version="1.0"?>
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
- <html xmlns="http://www.w3.org/TR/xhtml1">
- <body>
- <p>some text
-
- CHK 2 184 MORE
- Content-ID: <49568.45876xxx@foo.com>
- Content-Location: http://foo.com/images/image1.gif
- Content-Type: image/gif
- Content-Disposition: attachment
-
- <<part of binary data>>
- CHK 3 200 MORE
- Content-ID: <49568.46000xxx@foo.com>
- Content-Location: http://foo.com/images/image2.gif
- Content-Type: image/gif
- Content-Disposition: attachment
-
- <<part of binary data>>
- CHK 1 78 MORE
- <img src="cid:49568.45876xxx@foo.com"/>
- <img src="http://foo.com/images/image2.gif"/>
-
- CHK 2 6162 LAST
- <<part of binary data>>
- CHK 3 6201 LAST
- <<part of binary data>>
- CHK 1 127 MORE
- some more text after the images
- </p>
- <p>some more text without images
- </p>
- <p>some more text
- <img src="cid:49568.47333xxx@foo.com"/>
-
- CHK 4 7603 LAST
- Content-ID: <49568.47333xxx@foo.com>
- Content-Type: image/gif
- Content-Disposition: attachment
-
-
-
-
-
-
-
-
-
-
-Herriot Informational [Page 19]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- <<binary data>>
- CHK 1 41 LAST
- </p>
- <p>some final text
- </p>
- </body>
- </html>
-
- CHK 0 0 LAST
-
-5.2.4 Example of Chunks with Empty Payloads
-
- This example is identical to the previous one, except that some
- chunks have a chunk payload of zero octets. The root message starts
- with a chunk whose payload is empty and every message ends with a
- chunk whose payload is empty. This example also shows two adjacent
- chunks that are from the same message. These two chunks could be
- coalesced into a single chunk, but they might be kept separate for
- programming convenience.
-
- Content-Type: application/vnd.pwg-multiplexed;
- type=" application/vnd.pwg-xhtml-print+xml"
-
- CHK 1 0 MORE
-
- CHK 2 184 MORE
- Content-ID: <49568.45876xxx@foo.com>
- Content-Location: http://foo.com/images/image1.gif
- Content-Type: image/gif
- Content-Disposition: attachment
-
- <<part of binary data>>
- CHK 3 200 MORE
- Content-ID: <49568.46000xxx@foo.com>
- Content-Location: http://foo.com/images/image2.gif
- Content-Type: image/gif
- Content-Disposition: attachment
-
- <<part of binary data>>
- CHK 1 303 MORE
- Content-ID: <49568.44343xxx@foo.com>
- Content-Type: application/vnd.pwg-xhtml-print+xml
- Content-Disposition: inline
-
-
-
-
-
-
-
-
-Herriot Informational [Page 20]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- <?xml version="1.0"?>
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
- <html xmlns="http://www.w3.org/TR/xhtml1">
- <body>
- <p>some text
-
- CHK 2 6162 MORE
- <<part of binary data>>
- CHK 3 6201 MORE
- <<part of binary data>>
- CHK 2 0 LAST
-
- CHK 3 0 LAST
-
- CHK 1 78 MORE
- <img src="cid:49568.45876xxx@foo.com"/>
- <img src="http://foo.com/images/image2.gif"/>
-
- CHK 4 7603 MORE
- Content-ID: <49568.47333xxx@foo.com>
- Content-Type: image/gif
- Content-Disposition: attachment
-
- <<binary data>>
- CHK 4 0 LAST
-
- CHK 1 127 MORE
- some more text after the images
- </p>
- <p>some more text without images
- </p>
- <p>some more text
- <img src="cid:49568.47333xxx@foo.com"/>
-
- CHK 1 41 MORE
- </p>
- <p>some final text
- </p>
- </body>
- </html>
-
- CHK 1 0 LAST
-
- CHK 0 0 LAST
-
-
-
-
-
-
-Herriot Informational [Page 21]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
-6. Security Considerations
-
- There are security considerations that pertain to each message of an
- Application/Vnd.pwg-multiplexed entity. Those security
- considerations are described by the document that defines the
- content-type of the message. They are not addressed in this
- document.
-
- There are also security considerations that pertain to the
- Application/Vnd.pwg-multiplexed entity as a whole. A Producer that
- is buggy or malicious may send an Application/Vnd.pwg-multiplexed
- entity that could cause a Consumer to request more storage than it
- has, even if it has a large amount of storage. A Consumer must be
- able to deal gracefully with the following scenarios and combinations
- of them:
-
- - The chunks of one or more messages are separated by a very large
- number of octets. In the extreme case some or all of the
- messages don't terminate, i.e., they don't contain a closing
- chunk.
- - A very large number of messages are started and interleaved
- before their final chunk occurs.
- - A message contains one or more references to other messages that
- never occur or don't occur for a large number of octets.
- - A very large number of referenced messages occur before the
- Consumer knows that it can discard them.
-
-7. Registration Information for Application/Vnd.pwg-multiplexed
-
- The following form is copied from RFC 1590, Appendix A.
-
- To: iana@iana.org
-
- Subject: Registration of new Media Type
- application/Vnd.pwg-multiplexed
- Media Type name: Application
- Media subtype name: Vendor Tree - vnd.pwg-multiplexed
- Required parameters: Type, a media type/subtype.
- Optional parameters: No optional parameters
- Encoding considerations: Each message of an
- Application/Vnd.pwg-multiplexed entity can be
- encoded in any manner allowed by the Content-
- Type of the message. However, using the
- reasoning of Multipart, the
- Application/Vnd.pwg-multiplexed entity cannot
- be encoded. Otherwise, a message would be
-
-
-
-
-
-Herriot Informational [Page 22]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- encoded twice, once at the message level and
- once at the Application/Vnd.pwg-multiplexed
- level.
- Security considerations: See section 6 (Security
- Considerations) of RFC 3391.
- Published specification: RFC 3391.
- Person & email address to contact for further information:
-
- Robert Herriot
- 706 Colorado Ave.
- Palo Alto, CA 94303
- USA
- Phone: 1-650-327-4466
- Fax: 1-650-327-4466
- EMail: bob@herriot.com
-
-8. Acknowledgments
-
- The author gratefully acknowledges the contributions of: Ugo Corda,
- Dave Crocker, Melinda Sue Grant, Graham Klyne, Carl-Uno Manros, Larry
- Masinter, Ira McDonald, Chris Newman, Henrik Frystyk Nielsen and Dale
- R. Worley. In particular, Chris Newman provided invaluable help.
-
-9. References
-
- [RFC1806] Troost, R. and S. Dorner, "Communicating Presentation
- Information in Internet Messages: The Content-Disposition
- Header", RFC 1806, June 1995.
-
- [RFC1873] Levinson, E. and J. Clark, "Message/External-Body Content-
- ID Access Type", RFC 1873, December 1995.
- Levinson, E., "Message/External-Body Content-ID Access
- Type", Work in Progress.
-
- [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part One: Format of Internet Message
- Bodies", RFC 2045, November 1996.
-
- [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part Two: Media Types", RFC 2046,
- November 1996.
-
- [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for
- SyntaxSpecifications: ABNF", RFC 2234, November 1997.
-
- [RFC2387] Levinson, E., "The MIME Multipart/Related Content-type",
- RFC 2387, August 1998.
-
-
-
-
-Herriot Informational [Page 23]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
- [RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource
- Locators", RFC 2392, August 1998.
-
- [RFC2557] Palme, J., "MIME Encapsulation of Aggregate Documents, such
- as HTML (MHTML", RFC 2557, March 1999.
-
- [RFC2822] Resnick, P., Editor, "Internet Message Format", RFC 2822,
- April 2001.
-
- [RFC3080] Rose, M., "The Blocks Extensible Exchange Protocol Core",
- RFC 3080, March 2001.
-
-10. Author's Address
-
- Robert Herriot
- 706 Colorado Ave.
- Palo Alto, CA 94303
- USA
-
- Phone: 1-650-327-4466
- Fax: 1-650-327-4466
- EMail: bob@herriot.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot Informational [Page 24]
-\f
-RFC 3391 Application/Multiplexed December 2002
-
-
-11. Full Copyright Statement
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot Informational [Page 25]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group R. Herriot
-Request for Comments: 3510 I. McDonald
-Updates: 2910 High North Inc.
-Category: Standards Track April 2003
-
-
- Internet Printing Protocol/1.1:
- IPP URL Scheme
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2003). All Rights Reserved.
-
-Abstract
-
- This memo defines the "ipp" URL (Uniform Resource Locator) scheme.
- This memo updates IPP/1.1: Encoding and Transport (RFC 2910), by
- expanding and clarifying Section 5, "IPP URL Scheme", of RFC 2910.
- An "ipp" URL is used to specify the network location of a print
- service that supports the IPP Protocol (RFC 2910), or of a network
- resource (for example, a print job) managed by such a print service.
-
-Table of Contents
-
- 1. Introduction ............................................... 2
- 2. Terminology ................................................ 3
- 2.1. Conformance Terminology .............................. 3
- 2.2. Model Terminology .................................... 3
- 3. IPP Model for Printers and Jobs ............................ 3
- 4. IPP URL Scheme ............................................. 4
- 4.1. IPP URL Scheme Applicability ......................... 4
- 4.2. IPP URL Scheme Associated Port ....................... 4
- 4.3. IPP URL Scheme Associated MIME Type .................. 5
- 4.4. IPP URL Scheme Character Encoding .................... 5
- 4.5. IPP URL Scheme Syntax ................................ 5
- 4.6. IPP URL Examples ..................................... 6
- 4.6.1. IPP Printer URL Examples ..................... 6
- 4.6.2. IPP Job URL Examples ......................... 6
- 4.7. IPP URL Comparisons .................................. 7
-
-
-
-
-Herriot & McDonald Standards Track [Page 1]
-\f
-RFC 3510 IPP URL Scheme April 2003
-
-
- 5. Conformance Requirements ................................... 8
- 5.1. IPP Client Conformance Requirements .................. 8
- 5.2. IPP Printer Conformance Requirements ................. 8
- 6. IANA Considerations ........................................ 9
- 7. Internationalization Considerations ........................ 9
- 8. Security Considerations .................................... 9
- 9. Intellectual Property Rights ............................... 10
- 10. Normative References ....................................... 11
- 11. Informative References ..................................... 11
- 12. Acknowledgments ............................................ 12
- Appendix A - Registration of "ipp" URL Scheme .................. 13
- Authors' Addresses ............................................. 15
- Full Copyright Statement ....................................... 16
-
-1. Introduction
-
- This memo conforms to all of the requirements in Registration
- Procedures for URL Scheme Names [RFC2717]. This memo also follows
- all of the recommendations in Guidelines for new URL Schemes
- [RFC2718].
-
- See section 1, "Introduction", of [RFC2911] and section 1,
- "Introduction", of [RFC3196] for overview information about IPP. See
- section 10, "Description of the Base IPP Documents", of [RFC3196] for
- a full description of the IPP document set.
-
- This memo updates IPP/1.1: Encoding and Transport (RFC 2910), by
- expanding and clarifying Section 5, "IPP URL Scheme", of RFC 2910,
- but does not define any new parameters or other new extensions to the
- syntax of IPP URLs.
-
- The IPP URL scheme defined in this document is based on the ABNF for
- the HTTP URL scheme defined in HTTP [RFC2616], which in turn is
- derived from the URI Generic Syntax [RFC2396] and further updated for
- IPv6 by [RFC2732]. An IPP URL is transformed into an HTTP URL
- according to the rules specified in section 5 of IPP Protocol
- [RFC2910].
-
- This document defines IPP URL scheme applicability, associated port
- (631), associated MIME type ("application/ipp"), character encoding,
- and syntax.
-
- This document is laid out as follows:
-
- - Section 2 defines the terminology used throughout the document.
-
- - Section 3 supplies references to the IPP Printer and IPP Job
- object model defined in IPP Model [RFC2911].
-
-
-
-Herriot & McDonald Standards Track [Page 2]
-\f
-RFC 3510 IPP URL Scheme April 2003
-
-
- - Section 4 specifies the IPP URL scheme.
-
- - Section 5 specifies the conformance requirements for IPP Clients
- and IPP Printers that claim conformance to this document.
-
- - Sections 6, 7, and 8 specify IANA, internationalization, and
- security considerations.
-
- - Sections 9, 10, 11, 12, and 13 specify normative references,
- informative references, acknowledgements, authors' addresses, and
- full IETF copyright statement.
-
- - Section 14 (Appendix A) is a completed registration template for
- the IPP URL Scheme (see section 6.0 of [RFC2717]).
-
-2. Terminology
-
- This specification document uses the terminology defined in this
- section.
-
-2.1. Conformance Terminology
-
- The uppercase terms "MUST", "MUST NOT", "REQUIRED", "SHALL",
- "SHALL NOT" "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
- "OPTIONAL" in this document are to be interpreted as described in
- [RFC2119]. These terms are used to specify conformance
- requirements for all implementations (both print clients and print
- services) of this specification.
-
-2.2. Model Terminology
-
- See section 12.2, "Model Terminology", in IPP Model [RFC2911].
-
-3. IPP Model for Printers and Jobs
-
- See section 2, "IPP Objects", section 2.1, "Printer Object", and
- section 2.2, "Job Object", in [RFC2911] for a full description of
- the IPP object model and terminology.
-
- In this document, "IPP Client" means the software (on some
- hardware platform) that submits, monitors, and/or manages print
- jobs via the IPP Protocol [RFC2910] to a print spooler, print
- gateway, or physical printing device.
-
-
-
-
-
-
-
-
-Herriot & McDonald Standards Track [Page 3]
-\f
-RFC 3510 IPP URL Scheme April 2003
-
-
- In this document, "IPP Printer object" means the software (on some
- hardware platform) that receives print jobs and/or printer/job
- operations via the IPP Protocol [RFC2910] from an "IPP Client".
-
- In this document, "IPP Printer" is a synonym for "IPP Printer
- object".
-
- In this document, "IPP Job object" means the set of attributes and
- documents for one print job instantiated on an "IPP Printer".
-
- In this document, "IPP Job" is a synonym for "IPP Job object".
-
- In this document, "IPP URL" means a URL with the "ipp" scheme.
-
- Note: In this document, "IPP URL" is a synonym for "ipp-URL" (in
- section 4, "IPP URL Scheme", of this document) and "ipp-URL" (in
- section 5, "IPP URL Scheme", of [RFC2910]).
-
-4. IPP URL Scheme
-
-4.1. IPP URL Scheme Applicability
-
- The "ipp" URL scheme MUST only be used to specify absolute URLs
- (relative IPP URLs are not allowed) for IPP print services and
- their associated network resources. The "ipp" URL scheme MUST
- only be used to specify the use of the abstract protocol defined
- in IPP Model [RFC2911] over an HTTP [RFC2616] transport, as
- defined in IPP Protocol [RFC2910]. Any other transport binding
- for the abstract protocol defined in IPP Model [RFC2911] would
- require a different URL scheme.
-
- The "ipp" URL scheme allows an IPP client to choose an appropriate
- IPP print service (for example, from a directory). The IPP client
- can establish an HTTP connection to the specified IPP print
- service. The IPP client can send IPP protocol requests (for
- example, a "Print-Job" request) and receive IPP protocol responses
- over that HTTP connection.
-
-4.2. IPP URL Scheme Associated Port
-
- All IPP URLs which do NOT explicitly specify a port MUST be
- resolved to IANA-assigned well-known port 631, as registered in
- [IANA-PORTREG].
-
- See: IANA Port Numbers Registry [IANA-PORTREG].
- See: IPP Protocol [RFC2910].
-
-
-
-
-
-Herriot & McDonald Standards Track [Page 4]
-\f
-RFC 3510 IPP URL Scheme April 2003
-
-
-4.3. IPP URL Scheme Associated MIME Type
-
- All IPP URLs MUST be used to specify network print services which
- support the "application/ipp" MIME media type as registered in
- [IANA-MIMEREG] for IPP protocol requests and responses.
-
- See: IANA MIME Media Types Registry [IANA-MIMEREG].
- See: IPP Protocol [RFC2910].
-
-4.4. IPP URL Scheme Character Encoding
-
- IPP URLs MUST use [RFC2396] encoding, as do their equivalent HTTP
- URLs. Characters other than those in the "reserved" and "unsafe"
- sets [RFC2396] are equivalent to their ""%" HEX HEX" encoding.
-
-4.5. IPP URL Scheme Syntax
-
- The abstract protocol defined in IPP Model [RFC2911] places a
- limit of 1023 octets (NOT characters) on the length of a URI (see
- section 4.1.5, "uri", in [RFC2911]).
-
- Note: IPP Printers ought to be cautious about depending on URI
- lengths above 255 bytes, because some older client implementations
- might not properly support these lengths.
-
- IPP URLs MUST be represented in absolute form. Absolute URLs MUST
- always begin with a scheme name followed by a colon. For definitive
- information on URL syntax and semantics, see "Uniform Resource
- Identifiers (URI): Generic Syntax and Semantics" [RFC2396]. This
- specification adopts the definitions of "host", "port", "abs_path",
- and "query" from [RFC2396], as updated for IPv6 by [RFC2732].
-
- The IPP URL scheme syntax in ABNF is as follows:
-
- ipp-URL = "ipp:" "//" host [ ":" port ] [ abs_path [ "?" query ]]
-
- If the port is empty or not given, port 631 is assumed. The
- semantics are that the identified resource (see section 5.1.2 of
- [RFC2616]) is located at the IPP print service listening for HTTP
- connections on that port of that host, and the Request-URI for the
- identified resource is 'abs_path'.
-
- If the 'abs_path' is not present in the URL, it MUST be given as "/"
- when used as a Request-URI for a resource (see section 5.1.2 of
- [RFC2616]).
-
-
-
-
-
-
-Herriot & McDonald Standards Track [Page 5]
-\f
-RFC 3510 IPP URL Scheme April 2003
-
-
-4.6. IPP URL Examples
-
- Note: Literal IPv4 or IPv6 addresses SHOULD NOT be used in IPP URLs.
-
-4.6.1. IPP Printer URL Examples
-
- The following are examples of well-formed IPP URLs for IPP Printers
- (for example, to be used as protocol elements in 'printer-uri'
- operation attributes of 'Print-Job' request messages):
-
- ipp://example.com
- ipp://example.com/printer
- ipp://example.com/printer/tiger
- ipp://example.com/printer/fox
- ipp://example.com/printer/tiger/bob
- ipp://example.com/printer/tiger/ira
-
- Each of the above URLs are well-formed URLs for IPP Printers and each
- would reference a logically different IPP Printer, even though some
- of those IPP Printers might share the same host system. The 'bob' or
- 'ira' last path components might represent two different physical
- printer devices, while 'tiger' might represent some grouping of IPP
- Printers (for example, a load-balancing spooler). Or the 'bob' and
- 'ira' last path components might represent separate human recipients
- on the same physical printer device (for example, a physical printer
- supporting two job queues). In either case, both 'bob' and 'ira'
- would behave as different and independent IPP Printers.
-
- The following are examples of well-formed IPP URLs for IPP Printers
- with (optional) ports and paths:
-
- ipp://example.com
- ipp://example.com/~smith/printer
- ipp://example.com:631/~smith/printer
-
- The first and second IPP URLs above MUST be resolved to port 631
- (IANA assigned well-known port for IPP). The second and third IPP
- URLs above are equivalent (see section 4.7 below).
-
-4.6.2. IPP Job URL Examples
-
- The following are examples of well-formed IPP URLs for IPP Jobs (for
- example, to be used as protocol elements in 'job-uri' attributes of
- 'Print-Job' response messages):
-
- ipp://example.com/printer/123
- ipp://example.com/printer/tiger/job123
-
-
-
-
-Herriot & McDonald Standards Track [Page 6]
-\f
-RFC 3510 IPP URL Scheme April 2003
-
-
- IPP Job URLs are valid and meaningful only until Job completion and
- possibly an implementation defined optional period of persistence
- after Job completion (see IPP Model [RFC2911]).
-
- Ambiguously, section 4.3.1 'job-uri' of IPP Model [RFC2911] states
- that:
-
- "the precise format of a Job URI is implementation dependent."
-
- Thus, the relationship between the value of the "printer-uri"
- operation attribute used in a 'Print-Job' request and the value of
- the "job-uri" attribute returned in the corresponding 'Print-Job'
- response is implementation dependent. Also, section 4.3.3 'job-
- printer-uri' of IPP Model [RFC2911] states that the 'job-printer-uri'
- attribute of a Job object:
-
- "permits a client to identify the Printer object that created this
- Job object when only the Job object's URI is available to the
- client."
-
- However, the above statement is false, because the transform from an
- IPP Job URL to the corresponding IPP Printer URL is unspecified in
- either IPP Model [RFC2911] or IPP Protocol [RFC2910].
-
- IPP Printers that conform to this specification SHOULD only generate
- IPP Job URLs (for example, in the "job-uri" attribute in a 'Print-
- Job' response) by appending exactly one path component to the
- corresponding IPP Printer URL (for interoperability).
-
-4.7. IPP URL Comparisons
-
- When comparing two IPP URLs to decide if they match or not, an IPP
- Client MUST use the same rules as those defined for HTTP URI
- comparisons in [RFC2616], with the sole following exception:
-
- - A port that is empty or not given MUST be treated as equivalent to
- the well-known port for that IPP URL (port 631);
-
- See: Section 3.2.3, "URI Comparison", in [RFC2616].
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot & McDonald Standards Track [Page 7]
-\f
-RFC 3510 IPP URL Scheme April 2003
-
-
-5. Conformance Requirements
-
-5.1. IPP Client Conformance Requirements
-
- IPP Clients that conform to this specification:
-
- a) MUST only send IPP protocol connections to the port specified in
- each given IPP URL (if present) or otherwise to IANA assigned
- well-known port 631;
-
- b) MUST only send IPP URLs used as protocol elements in outgoing IPP
- protocol request messages (for example, in the "printer-uri"
- operation attribute in a 'Print-Job' request) that conform to the
- ABNF specified in section 4.5, "IPP URL Scheme Syntax, of this
- document;
-
- c) MUST only convert IPP URLs to their corresponding HTTP URL forms
- according to the rules in section 5, "IPP URL Scheme", in
- [RFC2910].
-
-5.2. IPP Printer Conformance Requirements
-
- IPP Printers that conform to this specification:
-
- a) MUST listen for incoming IPP protocol connections on IANA-assigned
- well-known port 631, unless explicitly configured by system
- administrators or site policies;
-
- b) SHOULD NOT listen for incoming IPP protocol connections on any
- other port, unless explicitly configured by system administrators
- or site policies;
-
- c) SHOULD only accept IPP URLs used as protocol elements in incoming
- IPP protocol request messages (for example, in the "printer-uri"
- operation attribute in a 'Print-Job' request) that conform to the
- ABNF specified in section 4.5, "IPP URL Scheme Syntax", of this
- document;
-
- d) SHOULD only send IPP URLs used as protocol elements in outgoing
- IPP protocol response messages (for example, in the "job-uri"
- attribute in a 'Print-Job' response) that conform to the ABNF
- specified in section 4.5, "IPP URL Scheme Syntax", of this
- document;
-
- e) SHOULD only generate IPP Job URLs (for example, in the "job-uri"
- attribute in a 'Print-Job' response) by appending exactly one path
- component to the corresponding IPP Printer URL (for
- interoperability);
-
-
-
-Herriot & McDonald Standards Track [Page 8]
-\f
-RFC 3510 IPP URL Scheme April 2003
-
-
- f) SHOULD NOT use literal IPv6 or IPv4 addresses in configured or
- locally generated IPP URLs.
-
-6. IANA Considerations
-
- This IPP URL Scheme specification does not introduce any additional
- IANA considerations, beyond those described in [RFC2910] and
- [RFC2911].
-
- See: Section 6, "IANA Considerations" in [RFC2910]
- See: Section 6, "IANA Considerations" in [RFC2911].
-
-7. Internationalization Considerations
-
- This IPP URL Scheme specification does not introduce any additional
- internationalization considerations, beyond those described in
- [RFC2910] and [RFC2911].
-
- See: Section 7, "Internationalization Considerations", in [RFC2910].
- See: Section 7, "Internationalization Considerations", in [RFC2911].
-
-8. Security Considerations
-
- This IPP URL Scheme specification does not introduce any additional
- security considerations, beyond those described in [RFC2910] and
- [RFC2911], except the following:
-
- a) An IPP URL might be faked to point to a rogue IPP print service,
- thus collecting confidential document contents from IPP clients.
- Server authentication mechanisms and security mechanisms specified
- in the IPP Protocol [RFC2910] are sufficient to address this
- threat.
-
- b) An IPP URL might be used to access an IPP print service by an
- unauthorized IPP client. Client authentication mechanisms and
- security mechanisms specified in the IPP Protocol [RFC2910] are
- sufficient to address this threat.
-
- c) An IPP URL might be used to access an IPP print service at a print
- protocol application layer gateway (for example, an IPP to LPD
- gateway [RFC2569]) causing silent compromise of IPP security
- mechanisms. There is no practical defense against this threat by
- a client system. System administrators should avoid such
- compromising configurations.
-
- d) An IPP URL does not have parameters to specify the required client
- authentication mechanism (for example, 'certificate' as defined in
- section 4.4.2, "uri-authentication-supported", of IPP Model
-
-
-
-Herriot & McDonald Standards Track [Page 9]
-\f
-RFC 3510 IPP URL Scheme April 2003
-
-
- [RFC2911]) and required security mechanism (for example, 'tls' as
- defined in section 4.4.3, "uri-security-supported", of IPP Model
- [RFC2911]). Service discovery or directory protocols might be
- used to discover the required client authentication and security
- mechanisms associated with given IPP URLs.
-
- Historical Note: During the development of this document,
- consideration was given to the addition of standard IPP URL
- parameters for the client authentication and security mechanisms.
- However, based on a strong IETF IPP Working Group consensus, no
- parameters were added to the "ipp" URL scheme as originally defined
- in IPP Protocol [RFC2910] in September 2000, for reasons of backwards
- compatibility with the many currently shipping implementations of
- IPP/1.1.
-
- See: Section 8, "Security Considerations", in [RFC2910].
- See: Section 8, "Security Considerations", in [RFC2911].
-
-9. Intellectual Property Rights
-
- The IETF takes no position regarding the validity or scope of any
- intellectual property or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; neither does it represent that it
- has made any effort to identify any such rights. Information on the
- IETF's procedures with respect to rights in standards-track and
- standards-related documentation can be found in BCP-11. Copies of
- claims of rights made available for publication and any assurances of
- licenses to be made available, or the result of an attempt made to
- obtain a general license or permission for the use of such
- proprietary rights by implementors or users of this specification can
- be obtained from the IETF Secretariat.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights which may cover technology that may be required to practice
- this standard. Please address the information to the IETF Executive
- Director.
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot & McDonald Standards Track [Page 10]
-\f
-RFC 3510 IPP URL Scheme April 2003
-
-
-10. Normative References
-
- [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", RFC 2234, November 1997.
-
- [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter,
- "Uniform Resource Identifiers (URI): Generic Syntax",
- RFC 2396, August 1998.
-
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
- Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext
- Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
-
- [RFC2732] Hinden, R., Carpenter, B. and L. Masinter, "Format for
- Literal IPv6 Addresses in URL's", RFC 2732, December
- 1999.
-
- [RFC2910] Herriot, R., Butler, S., Moore, P., Turner, R. and J.
- Wenn, "IPP/1.1 Encoding and Transport [IPP Protocol]",
- RFC 2910, September 2000.
-
- [RFC2911] Hastings, T., Herriot, R., deBry, R., Isaacson, S. and
- P. Powell, "IPP/1.1 Model and Semantics [IPP Model]",
- RFC 2911, September 2000.
-
- [US-ASCII] Coded Character Set -- 7-bit American Standard Code
- for Information Interchange, ANSI X3.4-1986.
-
-11. Informative References
-
- [IANA-MIMEREG] IANA MIME Media Types Registry.
- ftp://ftp.iana.org/in-notes/iana/assignments/media-
- types/...
-
- [IANA-PORTREG] IANA Port Numbers Registry. ftp://ftp.iana.org/in-
- notes/iana/assignments/port-numbers
-
- [RFC2569] Herriot, R., Hastings, T., Jacobs, N. and J. Martin,
- "Mapping between LPD and IPP Protocols", RFC 2569,
- April 1999.
-
- [RFC2717] Petke, R. and I. King, "Registration Procedures for
- URL Scheme Names", RFC 2717, November 1999.
-
- [RFC2718] Masinter, L., Alvestrand, H., Zigmond, D. and R.
- Petke, "Guidelines for new URL Schemes", RFC 2718,
- November 1999.
-
-
-
-
-Herriot & McDonald Standards Track [Page 11]
-\f
-RFC 3510 IPP URL Scheme April 2003
-
-
- [RFC3196] Hastings, T., Manros, C., Zehler, P., Kugler, C. and
- H. Holst, "Internet Printing Protocol/1.1:
- Implementor's Guide", RFC 3196, November 2001.
-
-12. Acknowledgments
-
- This document is a product of the Internet Printing Protocol Working
- Group of the Internet Engineering Task Force (IETF).
-
- Thanks to Pat Fleming (IBM), Tom Hastings (Xerox), Harry Lewis (IBM),
- Hugo Parra (Novell), Don Wright (Lexmark), and all the members of the
- IETF IPP WG.
-
- Section 5, "IPP URL Scheme", in IPP Protocol [RFC2910] was the
- primary input to this IPP URL Scheme specification.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot & McDonald Standards Track [Page 12]
-\f
-RFC 3510 IPP URL Scheme April 2003
-
-
-Appendix A - Registration of "ipp" URL Scheme
-
- Note: The following registration obsoletes section 5, "IPP URL
- Scheme", of IPP Protocol [RFC2911].
-
- URL Scheme Name: ipp
-
- URL Scheme Syntax:
-
- ipp-URL = "ipp:" "//" host [ ":" port ] [ abs_path [ "?" query ]]
-
- Character Encoding Considerations:
-
- IPP URLs MUST use [RFC2396] encoding, as do their equivalent HTTP
- URLs. Characters other than those in the "reserved" and "unsafe"
- sets [RFC2396] are equivalent to their ""%" HEX HEX" encoding.
-
- Intended Usage:
-
- The intended usage of the "ipp" URL scheme is COMMON.
-
- An "ipp" URL is used to specify the network location of a print
- service that supports the IPP Protocol [RFC2910], or of a network
- resource (for example, a print job) managed by such a print
- service. An IPP client can choose to establish an HTTP connection
- to the specified print service for transmission of IPP protocol
- requests (for example, IPP print job submission requests).
-
- Applications or Protocols which use this URL scheme:
-
- See: Section 5, "IPP URL Scheme", in IPP Protocol [RFC2910].
-
- Interoperability Considerations:
-
- See: Section 9, "Interoperability with IPP/1.0 Implementations",
- in IPP Protocol [RFC2910].
-
- Security Considerations:
-
- See: Section 8, "Security Considerations", in IPP Protocol
- [RFC2910].
-
- Relevant Publications:
-
- [RFC2910] Herriot, R., Butler, S., Moore, P., Turner, R. and J. Wenn,
- "IPP/1.1 Encoding and Transport [IPP Protocol]", RFC 2910,
- September 2000.
-
-
-
-
-Herriot & McDonald Standards Track [Page 13]
-\f
-RFC 3510 IPP URL Scheme April 2003
-
-
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter,
- L., Leach, P. and T. Berners-Lee, "Hypertext Transfer
- Protocol -- HTTP/1.1", RFC 2616, June 1999.
-
- [RFC3510] Herriot, R. and I. McDonald, "IPP/1.1: IPP URL Scheme", RFC
- 3510, April 2003.
-
- Person & email address to contact for further information:
-
- Robert Herriot
- Consultant
- 706 Colorado Ave
- Palo Alto, CA 94303
-
- Phone: +1 650-327-4466
- EMail: bob@herriot.com
-
- Ira McDonald
- High North Inc
- 221 Ridge Ave
- Grand Marais, MI 49839
-
- Phone: +1 906-494-2434
- EMail: imcdonald@sharplabs.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot & McDonald Standards Track [Page 14]
-\f
-RFC 3510 IPP URL Scheme April 2003
-
-
-Authors' Addresses
-
- Robert Herriot
- Consultant
- 706 Colorado Ave
- Palo Alto, CA 94303
-
- Phone: +1 650-327-4466
- EMail: bob@herriot.com
-
-
- Ira McDonald
- High North Inc
- 221 Ridge Ave
- Grand Marais, MI 49839
-
- Phone: +1 906-494-2434
- EMail: imcdonald@sharplabs.com
-
- Usage questions and comments on this IPP URL Scheme should be sent
- directly to the editors at their above addresses (and to the IPP
- mailing list, if you are a subscriber - see below).
-
- IPP Web Page: http://www.pwg.org/ipp/
- IPP Mailing List: ipp@pwg.org
-
- To subscribe to the IPP mailing list, send the following email:
-
- 1) send it to majordomo@pwg.org
-
- 2) leave the subject line blank
-
- 3) put the following two lines in the message body: subscribe ipp
-
- Implementers of this specification are encouraged to join the IPP
- Mailing List in order to participate in any discussions of
- clarification issues and comments. In order to reduce spam the
- mailing list rejects mail from non-subscribers, so you must subscribe
- to the mailing list in order to send a question or comment to the IPP
- mailing list.
-
-
-
-
-
-
-
-
-
-
-
-Herriot & McDonald Standards Track [Page 15]
-\f
-RFC 3510 IPP URL Scheme April 2003
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2003). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot & McDonald Standards Track [Page 16]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group P. Fleming
-Request for Comments: 3712 IBM
-Category: Informational I. McDonald
- High North
- February 2004
-
-
- Lightweight Directory Access Protocol (LDAP):
- Schema for Printer Services
-
-Status of this Memo
-
- This memo provides information for the Internet community. It does
- not specify an Internet standard of any kind. Distribution of this
- memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2004). All Rights Reserved.
-
-Abstract
-
- This document defines a schema, object classes and attributes, for
- printers and printer services, for use with directories that support
- Lightweight Directory Access Protocol v3 (LDAP-TS). This document is
- based on the printer attributes listed in Appendix E of Internet
- Printing Protocol/1.1 (IPP) (RFC 2911). A few additional printer
- attributes are based on definitions in the Printer MIB (RFC 1759).
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 1.1. Rationale for using DirectoryString Syntax . . . . . . . 3
- 1.2. Rationale for using caseIgnoreMatch. . . . . . . . . . . 4
- 1.3. Rationale for using caseIgnoreSubstringsMatch. . . . . . 5
- 2. Terminology and Conventions. . . . . . . . . . . . . . . . . . 5
- 3. Definition of Object Classes . . . . . . . . . . . . . . . . . 6
- 3.1. slpServicePrinter. . . . . . . . . . . . . . . . . . . . 6
- 3.2. printerAbstract. . . . . . . . . . . . . . . . . . . . . 7
- 3.3. printerService . . . . . . . . . . . . . . . . . . . . . 8
- 3.4. printerServiceAuxClass . . . . . . . . . . . . . . . . . 8
- 3.5. printerIPP . . . . . . . . . . . . . . . . . . . . . . . 8
- 3.6. printerLPR . . . . . . . . . . . . . . . . . . . . . . . 9
- 4. Definition of Attribute Types. . . . . . . . . . . . . . . . . 9
- 4.1. printer-uri. . . . . . . . . . . . . . . . . . . . . . . 11
- 4.2. printer-xri-supported. . . . . . . . . . . . . . . . . . 11
- 4.3. printer-name . . . . . . . . . . . . . . . . . . . . . . 13
- 4.4. printer-natural-language-configured. . . . . . . . . . . 13
-
-
-
-Fleming & McDonald Informational [Page 1]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- 4.5. printer-location . . . . . . . . . . . . . . . . . . . . 14
- 4.6. printer-info . . . . . . . . . . . . . . . . . . . . . . 14
- 4.7. printer-more-info. . . . . . . . . . . . . . . . . . . . 14
- 4.8. printer-make-and-model . . . . . . . . . . . . . . . . . 15
- 4.9. printer-ipp-versions-supported . . . . . . . . . . . . . 15
- 4.10. printer-multiple-document-jobs-supported . . . . . . . . 16
- 4.11. printer-charset-configured . . . . . . . . . . . . . . . 16
- 4.12. printer-charset-supported. . . . . . . . . . . . . . . . 16
- 4.13. printer-generated-natural-language-supported . . . . . . 17
- 4.14. printer-document-format-supported. . . . . . . . . . . . 17
- 4.15. printer-color-supported. . . . . . . . . . . . . . . . . 18
- 4.16. printer-compression-supported. . . . . . . . . . . . . . 18
- 4.17. printer-pages-per-minute . . . . . . . . . . . . . . . . 18
- 4.18. printer-pages-per-minute-color . . . . . . . . . . . . . 19
- 4.19. printer-finishings-supported . . . . . . . . . . . . . . 19
- 4.20. printer-number-up-supported. . . . . . . . . . . . . . . 19
- 4.21. printer-sides-supported. . . . . . . . . . . . . . . . . 20
- 4.22. printer-media-supported. . . . . . . . . . . . . . . . . 20
- 4.23. printer-media-local-supported. . . . . . . . . . . . . . 20
- 4.24. printer-resolution-supported . . . . . . . . . . . . . . 21
- 4.25. printer-print-quality-supported. . . . . . . . . . . . . 22
- 4.26. printer-job-priority-supported . . . . . . . . . . . . . 22
- 4.27. printer-copies-supported . . . . . . . . . . . . . . . . 22
- 4.28. printer-job-k-octets-supported . . . . . . . . . . . . . 23
- 4.29. printer-current-operator . . . . . . . . . . . . . . . . 23
- 4.30. printer-service-person . . . . . . . . . . . . . . . . . 24
- 4.31. printer-delivery-orientation-supported . . . . . . . . . 24
- 4.32. printer-stacking-order-supported . . . . . . . . . . . . 24
- 4.33. printer-output-features-supported. . . . . . . . . . . . 25
- 4.34. printer-aliases. . . . . . . . . . . . . . . . . . . . . 25
- 5. Definition of Syntaxes . . . . . . . . . . . . . . . . . . . . 26
- 6. Definition of Matching Rules . . . . . . . . . . . . . . . . . 26
- 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26
- 7.1. Registration of Object Classes . . . . . . . . . . . . . 26
- 7.2. Registration of Attribute Types. . . . . . . . . . . . . 27
- 8. Internationalization Considerations. . . . . . . . . . . . . . 28
- 9. Security Considerations. . . . . . . . . . . . . . . . . . . . 29
- 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29
- 10.1. Normative References . . . . . . . . . . . . . . . . . . 29
- 10.2. Informative References . . . . . . . . . . . . . . . . . 30
- 11. Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . 32
- 12. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 32
- 13. Full Copyright Statement . . . . . . . . . . . . . . . . . . . 33
-
-
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 2]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
-1. Introduction
-
- This document defines several object classes to provide Lightweight
- Directory Access Protocol v3 [LDAP-TS] applications with flexible
- options in defining printer information using LDAP schema. Classes
- are provided for defining directory entries with common printer
- information as well as for extending existing directory entries with
- SLPv2 [RFC2608], IPP/1.1 [RFC2911], and LPR [RFC1179] specific
- information.
-
- The schema defined in this document is based on the printer
- attributes listed in Appendix E 'Generic Directory Schema' of
- Internet Printing Protocol/1.1 (IPP) [RFC2911]. A few additional
- printer attributes are based on definitions in the Printer MIB
- [RFC1759].
-
- The schema defined in this document is technically aligned with the
- stable IANA-registered 'service:printer:' v2.0 template [SLP-PRT],
- for compatibility with already deployed Service Location Protocol
- (SLPv2) [RFC2608] service advertising and discovery infrastructure.
- The attribute syntaxes are technically aligned with the
- 'service:printer:' v2.0 template - therefore simpler types are
- sometimes used (for example, 'DirectoryString' [RFC2252] rather than
- 'labeledURI' [RFC2079] for the 'printer-uri' attribute).
-
- Please send comments directly to the authors at the addresses listed
- in Section 13 "Authors' Addresses".
-
-1.1. Rationale for using DirectoryString Syntax
-
- The attribute syntax 'DirectoryString' (UTF-8 [RFC2279]) defined in
- [RFC2252] is specified for several groups of string attributes that
- are defined in this document:
-
- 1) URI
- - printer-uri, printer-xri-supported, printer-more-info
-
- The UTF-8 encoding is forward compatible with any future
- deployment of (UTF-8 based) IRI (Internationalized Resource
- Identifiers) [W3C-IRI] currently being developed by the W3C
- Internationalization Working Group.
-
- 2) Description
- - printer-name, printer-location, printer-info,
- printer-make-and-model
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 3]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- The UTF-8 encoding supports descriptions in any language,
- conformant with the "IETF Policy on Character Sets and Languages"
- [RFC2277].
-
- Note: The printer-natural-language-configured attribute contains
- a language tag [RFC3066] for these description attributes (for
- example, to support text-to-speech conversions).
-
- 3) Keyword
- - printer-compression-supported, printer-finishings-supported,
- printer-media-supported, printer-media-local-supported,
- printer-print-quality-supported
-
- The UTF-8 encoding is compatible with the current IPP/1.1
- [RFC2911] definition of the equivalent attributes, most of which
- have the IPP/1.1 union syntax 'keyword or name'. The keyword
- attributes defined in this document are extensible by
- site-specific or vendor-specific 'names' which behave like new
- 'keywords'
-
- Note: In IPP/1.1, each value is strongly typed over-the-wire as
- either 'keyword' or 'name'. This union selector is not preserved
- in the definitions of these equivalent LDAP attributes.
-
-1.2. Rationale for using caseIgnoreMatch
-
- The EQUALITY matching rule 'caseIgnoreMatch' defined in [RFC2252] is
- specified for several groups of string attributes that are defined in
- this document:
-
- 1) URI
-
- These URI attributes specify EQUALITY matching with
- 'caseIgnoreMatch' (rather than with 'caseExactMatch') in order to
- conform to the spirit of [RFC2396], which requires case
- insensitive matching on the host part of a URI versus case
- sensitive matching on the remainder of a URI.
-
- These URI attributes follow existing practice of supporting case
- insensitive equality matching for host names in the
- associatedDomain attribute defined in [RFC1274].
-
- Either equality matching rule choice would be a compromise:
- a) case sensitive whole URI matching may lead to false negative
- matches and has been shown to be fragile (given deployed client
- applications that 'pretty up' host names displayed and
- transferred in URI);
-
-
-
-
-Fleming & McDonald Informational [Page 4]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- b) case insensitive whole URI matching may lead to false positive
- matches, although it is a dangerous practice to publish URI that
- differ only by case (for example, in the path elements).
-
- 2) Description
-
- Case insensitive equality matching is more user-friendly for
- description attributes.
-
- 3) Keyword
-
- Case insensitive equality matching is more user-friendly for
- keyword attributes.
-
-1.3. Rationale for using caseIgnoreSubstringsMatch
-
- The SUBSTR matching rule 'caseIgnoreSubstringsMatch' defined in
- [RFC2252] is specified for several groups of string attributes that
- are defined in this document:
-
- 1) URI
-
- These URI attributes follow existing practice of supporting case
- insensitive equality matching for host names in the
- associatedDomain attribute defined in [RFC1274].
-
- 2) Description
-
- Support for case insensitive substring matching is more
- user-friendly for description attributes.
-
- 3) Keyword
-
- Support for case insensitive substring matching is more
- user-friendly for keyword attributes.
-
-2. Terminology and Conventions
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in BCP 14 [RFC2119].
-
- Schema definitions are provided using LDAPv3 [LDAP-TS] description
- formats. Definitions provided here are formatted (line wrapped) for
- readability.
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 5]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
-3. Definition of Object Classes
-
- We define the following LDAP object classes for use with both generic
- printer related information and services specific to SLPv2 [RFC2608],
- IPP/1.1 [RFC2911], and LPR [RFC1179].
-
- slpServicePrinter - auxiliary class for SLP registered printers
- printerAbstract - abstract class for all printer classes
- printerService - structural class for printers
- printerServiceAuxClass - auxiliary class for printers
- printerIPP - auxiliary class for IPP printers
- printerLPR - auxiliary class for LPR printers
-
- The following are some examples of how applications may choose to use
- these classes when creating directory entries:
-
- 1) Use printerService for directory entries containing common
- printer information.
-
- 2) Use both printerService and slpServicePrinter for directory
- entries containing common printer information for SLP registered
- printers.
-
- 3) Use printerService, printerLPR and printerIPP for directory
- entries containing common printer information for printers that
- support both LPR and IPP.
-
- 4) Use printerServiceAuxClass and object classes not defined by this
- document for directory entries containing common printer
- information. In this example, printerServiceAuxClass is used for
- extending other structural classes defining printer information
- with common printer information defined in this document.
-
- Refer to Section 4 for definition of attribute types referenced by
- these object classes. We use attribute names instead of OIDs in
- object class definitions for clarity. Some attribute names described
- in [RFC2911] have been prefixed with 'printer-' as recommended in
- [RFC2926] and [SLP-PRT].
-
-3.1. slpServicePrinter
-
- ( 1.3.18.0.2.6.254
- NAME 'slpServicePrinter'
- DESC 'Service Location Protocol (SLP) information.'
- AUXILIARY
- SUP slpService
- )
-
-
-
-
-Fleming & McDonald Informational [Page 6]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- This auxiliary class defines Service Location Protocol (SLPv2)
- [RFC2608] specific information. It should be used with a structural
- class such as printerService. It may be used to create new or extend
- existing directory entries with SLP 'service:printer' abstract
- service type information as defined in [SLP-PRT]. This object class
- is derived from 'slpService', the parent class for all SLP services,
- defined in [RFC2926].
-
-3.2. printerAbstract
-
- ( 1.3.18.0.2.6.258
- NAME 'printerAbstract'
- DESC 'Printer related information.'
- ABSTRACT
- SUP top
- MAY ( printer-name $
- printer-natural-language-configured $
- printer-location $ printer-info $ printer-more-info $
- printer-make-and-model $
- printer-multiple-document-jobs-supported $
- printer-charset-configured $ printer-charset-supported $
- printer-generated-natural-language-supported $
- printer-document-format-supported $ printer-color-supported $
- printer-compression-supported $ printer-pages-per-minute $
- printer-pages-per-minute-color $
- printer-finishings-supported $ printer-number-up-supported $
- printer-sides-supported $ printer-media-supported $
- printer-media-local-supported $
- printer-resolution-supported $
- printer-print-quality-supported $
- printer-job-priority-supported $ printer-copies-supported $
- printer-job-k-octets-supported $ printer-current-operator $
- printer-service-person $
- printer-delivery-orientation-supported $
- printer-stacking-order-supported $
- printer-output-features-supported )
- )
-
- This abstract class defines printer information. It is a base class
- for deriving other printer related classes, such as, but not limited
- to, classes defined in this document. It defines a common set of
- printer attributes that are not specific to any one type of service,
- protocol or operating system.
-
-
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 7]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
-3.3. printerService
-
- ( 1.3.18.0.2.6.255
- NAME 'printerService'
- DESC 'Printer information.'
- STRUCTURAL
- SUP printerAbstract
- MAY ( printer-uri $ printer-xri-supported )
- )
-
- This structural class defines printer information. It is derived
- from class printerAbstract and thus inherits common printer
- attributes. This class can be used with or without auxiliary classes
- to define printer information. Auxiliary classes can be used to
- extend the common printer information with protocol, service or
- operating system specific information.
-
- Note: When extending other structural classes with auxiliary
- classes, printerService should not be used.
-
-3.4. printerServiceAuxClass
-
- ( 1.3.18.0.2.6.257
- NAME 'printerServiceAuxClass'
- DESC 'Printer information.'
- AUXILIARY
- SUP printerAbstract
- MAY ( printer-uri $ printer-xri-supported )
- )
-
- This auxiliary class defines printer information. It is derived from
- class printerAbstract and thus inherits common printer attributes.
- This class should be used with a structural class.
-
-3.5. printerIPP
-
- ( 1.3.18.0.2.6.256
- NAME 'printerIPP'
- DESC 'Internet Printing Protocol (IPP) information.'
- AUXILIARY
- SUP top
- MAY ( printer-ipp-versions-supported $
- printer-multiple-document-jobs-supported )
- )
-
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 8]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- This auxiliary class defines Internet Printing Protocol (IPP/1.1)
- [RFC2911] information. It should be used with a structural class
- such as printerService. It is used to extend structural classes with
- IPP specific printer information.
-
-3.6. printerLPR
-
- ( 1.3.18.0.2.6.253
- NAME 'printerLPR'
- DESC 'LPR information.'
- AUXILIARY
- SUP top
- MUST ( printer-name )
- MAY ( printer-aliases)
- )
-
- This auxiliary class defines LPR [RFC1179] information. It should be
- used with a structural class such as printerService. It is used to
- identify directory entries that support LPR.
-
-4. Definition of Attribute Types
-
- The following attribute types are referenced by the object classes
- defined in Section 3.
-
- The following attribute types reference syntax OIDs defined in
- Section 6 of [RFC2252] (see Section 5 'Definition of Syntaxes'
- below).
-
- The following attribute types reference matching rule names (instead
- of OIDs) for clarity (see Section 6 below). For optional attributes,
- if the printer information is not known, the attribute value should
- not be set. In the following definitions, referenced matching rules
- are defined in Section 8 of [RFC2252] and/or Section 2 of [RFC3698]
- (see Section 6 'Definition of Matching Rules' below).
-
- The following table is a summary of the attribute names defined by
- this document and their corresponding names from [RFC2911]. Some
- attribute names described in [RFC2911] have been prefixed with
- 'printer-' as recommended in [RFC2926], to address the flat namespace
- for LDAP identifiers.
-
-
-
-
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 9]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- LDAP & SLP Printer Schema IPP Model [RFC2911]
- ------------------------------ -------------------------------------
- printer-uri
- printer-xri-supported
- [IPP printer-uri-supported]
- [IPP uri-authentication-supported]
- [IPP uri-security-supported]
- printer-name printer-name
- printer-natural-language-configured
- natural-language-configured
- printer-location printer-location
- printer-info printer-info
- printer-more-info printer-more-info
- printer-make-and-model printer-make-and-model
- printer-ipp-versions-supported ipp-versions-supported
- printer-multiple-document-jobs-supported
- multiple-document-jobs-supported
- printer-charset-configured charset-configured
- printer-charset-supported charset-supported
- printer-generated-natural-language-supported
- generated-natural-language-supported
- printer-document-format-supported
- document-format-supported
- printer-color-supported color-supported
- printer-compression-supported compression-supported
- printer-pages-per-minute pages-per-minute
- printer-pages-per-minute-color pages-per-minute-color
- printer-finishings-supported finishings-supported
- printer-number-up-supported number-up-supported
- printer-sides-supported sides-supported
- printer-media-supported media-supported
- printer-media-local-supported [site names from IPP media-supported]
- printer-resolution-supported printer-resolution-supported
- printer-print-quality-supported print-quality-supported
- printer-job-priority-supported job-priority-supported
- printer-copies-supported copies-supported
- printer-job-k-octets-supported job-k-octets-supported
- printer-current-operator
- printer-service-person
- printer-delivery-orientation-supported
- printer-stacking-order-supported
- printer-output-features-supported
- printer-aliases
-
-
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 10]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
-4.1. printer-uri
-
- ( 1.3.18.0.2.4.1140
- NAME 'printer-uri'
- DESC 'A URI supported by this printer.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
- SINGLE-VALUE
- )
-
- If the printer-xri-supported LDAP attribute is implemented, then this
- printer-uri value should be listed in printer-xri-supported.
-
- Values of URI should conform to [RFC2396], although URI schemes may
- be defined which do not conform to [RFC2396] (see [RFC2717] and
- [RFC2718]).
-
- Note: LDAP application clients should not attempt to use malformed
- URI values read from this attribute. LDAP administrative clients
- should not write malformed URI values into this attribute.
-
- Note: For SLP registered printers, the LDAP printer-uri attribute
- should be set to the value of the SLP-registered URL of the printer,
- for interworking with SLPv2 [RFC2608] service discovery.
-
- Note: See Sections 1.1, 1.2, and 1.3 for rationale for design
- choices.
-
-4.2. printer-xri-supported
-
- ( 1.3.18.0.2.4.1107
- NAME 'printer-xri-supported'
- DESC 'The unordered list of XRI (extended resource identifiers)
- supported by this printer.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
- )
-
- A list of XRI (extended resource identifiers) supported by this
- printer. Each value of this list should consist of a URI (uniform
- resource identifier) followed by (optional) authentication and
- security fields.
-
- Values of URI should conform to [RFC2396], although URI schemes may
- be defined which do not conform to [RFC2396] (see [RFC2717] and
- [RFC2718]).
-
-
-
-Fleming & McDonald Informational [Page 11]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- Note: LDAP application clients should not attempt to use malformed
- URI values read from this attribute. LDAP administrative clients
- should not write malformed URI values into this attribute.
-
- Note: This attribute is based on 'printer-uri-supported', 'uri-
- authentication-supported', and `'uri-security-supported' (called the
- 'Three Musketeers' because they are parallel ordered attributes)
- defined in IPP/1.1 [RFC2911]. This attribute unfolds those IPP/1.1
- attributes and thus avoids the ordering (and same number of values)
- constraints of the IPP/1.1 separate attributes.
-
- Defined keywords for fields include:
-
- 'uri' (IPP 'printer-uri-supported')
- 'auth' (IPP 'uri-authentication-supported')
- 'sec' (IPP 'uri-security-supported')
-
- A missing 'auth' field should be interpreted to mean 'none'. Per
- IPP/1.1 [RFC2911], defined values of the 'auth' field include:
-
- 'none' (no authentication for this URI)
- 'requesting-user-name' (from operation request)
- 'basic' (HTTP/1.1 Basic [RFC2617])
- 'digest' (HTTP/1.1 Basic, [RFC2617])
- 'certificate' (from certificate)
-
- A missing 'sec' field should be interpreted to mean 'none'. Per
- IPP/1.1 [RFC2911], defined values of the 'sec' field include:
-
- 'none' (no security for this URI)
- 'ssl3' (Netscape SSL3)
- 'tls' (IETF TLS/1.0, [RFC2246])
-
- Each XRI field should be delimited by '<'. For example:
-
- 'uri=ipp://foo.com< auth=digest< sec=tls<'
- 'uri=lpr://bar.com< auth=none< sec=none<'
- 'uri=mailto:printer@foobar.com< auth=none< sec=none<'
-
- Note: The syntax and delimiter for this attribute are aligned with
- the equivalent attribute in the 'service:printer:' v2.0 template
- [SLP-PRT]. Whitespace is permitted after (but not before) the
- delimiter '<'. Note that this delimiter differs from printer-
- resolution-supported.
-
- Note: See Sections 1.1, 1.2, and 1.3 for rationale for design
- choices.
-
-
-
-
-Fleming & McDonald Informational [Page 12]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
-4.3. printer-name
-
- ( 1.3.18.0.2.4.1135
- NAME 'printer-name'
- DESC 'The site-specific administrative name of this printer.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127}
- SINGLE-VALUE
- )
-
- Values of this attribute should be specified in the language
- specified in printer-natural-language-configured (for example, to
- support text-to-speech conversions), although the printer's name may
- be specified in any language. This name may be the last part of the
- printer's URI or it may be completely unrelated. This name may
- contain characters that are not allowed in a conventional URI (see
- [RFC2396]).
-
-4.4. printer-natural-language-configured
-
- ( 1.3.18.0.2.4.1119
- NAME 'printer-natural-language-configured'
- DESC 'The configured natural language in which error and status
- messages will be generated (by default) by this printer.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127}
- SINGLE-VALUE
- )
-
- Also, a possible natural language for printer string attributes set
- by operator, system administrator, or manufacturer. Also, the
- (declared) natural language of the printer-name, printer-location,
- printer-info, and printer-make-and-model attributes of this printer.
-
- Values of language tags should conform to "Tags for the
- Identification of Languages" [RFC3066]. For example:
-
- 'en-us' (English as spoken in the US)
- 'fr-fr' (French as spoken in France)
-
- For consistency with IPP/1.1 [RFC2911], language tags in this
- attribute should be lowercase normalized.
-
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 13]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
-4.5. printer-location
-
- ( 1.3.18.0.2.4.1136
- NAME 'printer-location'
- DESC 'The physical location of this printer.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127}
- SINGLE-VALUE
- )
-
- For example:
-
- 'Room 123A'
- 'Second floor of building XYZ'
-
-4.6. printer-info
-
- ( 1.3.18.0.2.4.1139
- NAME 'printer-info'
- DESC 'Descriptive information about this printer.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127}
- SINGLE-VALUE
- )
-
- For example:
-
- 'This printer can be used for printing color transparencies for
- HR presentations'
- 'Out of courtesy for others, please print only small (1-5 page)
- jobs at this printer'
- 'This printer is going away on July 1, 1997, please find a new
- printer'
-
-4.7. printer-more-info
-
- ( 1.3.18.0.2.4.1134
- NAME 'printer-more-info'
- DESC 'A URI for more information about this specific printer.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
- SINGLE-VALUE
- )
-
-
-
-
-
-Fleming & McDonald Informational [Page 14]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- For example, this could be an HTTP type URI referencing an HTML page
- accessible to a Web Browser. The information obtained from this URI
- is intended for end user consumption.
-
- Values of URI should conform to [RFC2396], although URI schemes may
- be defined which do not conform to [RFC2396] (see [RFC2717] and
- [RFC2718]).
-
- Note: LDAP application clients should not attempt to use malformed
- URI values read from this attribute. LDAP administrative clients
- should not write malformed URI values into this attribute.
-
- Note: See Sections 1.1, 1.2, and 1.3 for rationale for design
- choices.
-
-4.8. printer-make-and-model
-
- ( 1.3.18.0.2.4.1138
- NAME 'printer-make-and-model'
- DESC 'Make and model of this printer.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127}
- SINGLE-VALUE
- )
-
- Note: The printer manufacturer may initially populate this
- attribute.
-
-4.9. printer-ipp-versions-supported
-
- ( 1.3.18.0.2.4.1133
- NAME 'printer-ipp-versions-supported'
- DESC 'IPP protocol version(s) that this printer supports.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127}
- )
-
- The IPP protocol version(s) should include major and minor versions,
- i.e., the exact version numbers for which this Printer implementation
- meets the IPP version-specific conformance requirements.
-
-
-
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 15]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
-4.10. printer-multiple-document-jobs-supported
-
- ( 1.3.18.0.2.4.1132
- NAME 'printer-multiple-document-jobs-supported'
- DESC 'Indicates whether or not this printer supports more than one
- document per job.'
- EQUALITY booleanMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
- SINGLE-VALUE
- )
-
-4.11. printer-charset-configured
-
- ( 1.3.18.0.2.4.1109
- NAME 'printer-charset-configured'
- DESC 'The configured charset in which error and status messages will
- be generated (by default) by this printer.'
- EQUALITY caseIgnoreMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{63}
- SINGLE-VALUE
- )
-
- Also, a possible charset for printer string attributes set by
- operator, system administrator, or manufacturer. For example:
-
- 'utf-8' (ISO 10646/Unicode in UTF-8 transform [RFC2279])
- 'iso-8859-1' (Latin1)
-
- Values of charset tags should be defined in the IANA Registry of
- Coded Character Sets [IANA-CHAR] (see also [RFC2978]) and the
- '(preferred MIME name)' should be used as the charset tag in this
- attribute.
-
- For consistency with IPP/1.1 [RFC2911], charset tags in this
- attribute should be lowercase normalized.
-
-4.12. printer-charset-supported
-
- ( 1.3.18.0.2.4.1131
- NAME 'printer-charset-supported'
- DESC 'Set of charsets supported for the attribute values of syntax
- DirectoryString for this directory entry.'
- EQUALITY caseIgnoreMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{63}
- )
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 16]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- For example:
-
- 'utf-8' (ISO 10646/Unicode in UTF-8 transform [RFC2279])
- 'iso-8859-1' (Latin1)
-
- Values of charset tags should be defined in the IANA Registry of
- Coded Character Sets [IANA-CHAR] (see also [RFC2978]) and the
- '(preferred MIME name)' should be used as the charset tag in this
- attribute.
-
- For consistency with IPP/1.1 [RFC2911], charset tags in this
- attribute should be lowercase normalized.
-
-4.13. printer-generated-natural-language-supported
-
- ( 1.3.18.0.2.4.1137
- NAME 'printer-generated-natural-language-supported'
- DESC 'Natural language(s) supported for this directory entry.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{63}
- )
-
- Values of language tags should conform to "Tags for the
- Identification of Languages" [RFC3066]. For example:
-
- 'en-us' (English as spoken in the US)
- 'fr-fr' (French as spoken in France)
-
- For consistency with IPP/1.1 [RFC2911], language tags in this
- attribute should be lowercase normalized.
-
-4.14. printer-document-format-supported
-
- ( 1.3.18.0.2.4.1130
- NAME 'printer-document-format-supported'
- DESC 'The possible source document formats which may be interpreted
- and printed by this printer.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127}
- )
-
- Values of document formats should be MIME media types defined in the
- IANA Registry of MIME Media Types [IANA-MIME] (see also [RFC2048]).
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 17]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
-4.15. printer-color-supported
-
- ( 1.3.18.0.2.4.1129
- NAME 'printer-color-supported'
- DESC 'Indicates whether this printer is capable of any type of color
- printing at all, including highlight color.'
- EQUALITY booleanMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
- SINGLE-VALUE
- )
-
-4.16. printer-compression-supported
-
- ( 1.3.18.0.2.4.1128
- NAME 'printer-compression-supported'
- DESC 'Compression algorithms supported by this printer.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255}
- )
-
- Values defined in IPP/1.1 [RFC2911] include:
-
- 'none' (no compression is used)
- 'deflate' (public domain ZIP described in [RFC1951])
- 'gzip' (GNU ZIP described in [RFC1952])
- 'compress' (UNIX compression described in [RFC1977])
-
-4.17. printer-pages-per-minute
-
- ( 1.3.18.0.2.4.1127
- NAME 'printer-pages-per-minute'
- DESC 'The nominal number of pages per minute which may be output by
- this printer.'
- EQUALITY integerMatch
- ORDERING integerOrderingMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE
- )
-
- This attribute is informative, not a service guarantee. Typically,
- it is the value used in marketing literature to describe this
- printer. For example, the value for a simplex or black-and-white
- print mode.
-
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 18]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
-4.18. printer-pages-per-minute-color
-
- ( 1.3.18.0.2.4.1126
- NAME 'printer-pages-per-minute-color'
- DESC 'The nominal number of color pages per minute which may be
- output by this printer.'
- EQUALITY integerMatch
- ORDERING integerOrderingMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE
- )
-
- This attribute is informative, not a service guarantee. Typically,
- it is the value used in marketing literature to describe this
- printer.
-
-
-4.19. printer-finishings-supported
-
- ( 1.3.18.0.2.4.1125
- NAME 'printer-finishings-supported'
- DESC 'The possible finishing operations supported by this printer.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255}
- )
-
- Values defined in IPP/1.1 [RFC2911] include: 'none', 'staple',
- 'punch', 'cover', 'bind', 'saddle-stitch', 'edge-stitch',
- 'staple-top-left', 'staple-bottom-left', 'staple-top-right',
- 'staple-bottom-right', 'edge-stitch-left', 'edge-stitch-top',
- 'edge-stitch-right', 'edge-stitch-bottom', 'staple-dual-left',
- 'staple-dual-top', 'staple-dual-right', 'staple-dual-bottom'.
-
- Note: Implementations may support other values.
-
-4.20. printer-number-up-supported
-
- ( 1.3.18.0.2.4.1124
- NAME 'printer-number-up-supported'
- DESC 'The possible numbers of print-stream pages to impose upon a
- single side of an instance of a selected medium.'
- EQUALITY integerMatch
- ORDERING integerOrderingMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- )
-
-
-
-
-
-Fleming & McDonald Informational [Page 19]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- Values defined in IPP/1.1 [RFC2911] include: '1', '2', and '4'.
-
- Note: Implementations may support other values.
-
-4.21. printer-sides-supported
-
- ( 1.3.18.0.2.4.1123
- NAME 'printer-sides-supported'
- DESC 'The number of impression sides (one or two) and the two-sided
- impression rotations supported by this printer.'
- EQUALITY caseIgnoreMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127}
- )
-
- Values defined in IPP/1.1 [RFC2911] include: 'one-sided', 'two-
- sided-long-edge', 'two-sided-short-edge'.'
-
-4.22. printer-media-supported
-
- ( 1.3.18.0.2.4.1122
- NAME 'printer-media-supported'
- DESC 'The standard names/types/sizes (and optional color suffixes) of
- the media supported by this printer.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255}
- )
-
- Values are defined in IPP/1.1 [RFC2911] or any IANA registered
- extensions. For example:
-
- 'iso-a4'
- 'envelope'
- 'na-letter-white'
-
-4.23. printer-media-local-supported
-
- ( 1.3.18.0.2.4.1117
- NAME 'printer-media-local-supported'
- DESC 'Site-specific names of media supported by this printer.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255}
- )
-
- Values should be in the natural language specified by printer-
- natural-language-configured.
-
-
-
-
-Fleming & McDonald Informational [Page 20]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- For example:
-
- 'purchasing-form' (site-specific name)
-
- as opposed to 'na-letter' (standard keyword from IPP/1.1 [RFC2911])
- in the printer-media-supported attribute.
-
-4.24. printer-resolution-supported
-
- ( 1.3.18.0.2.4.1121
- NAME 'printer-resolution-supported'
- DESC 'List of resolutions supported for printing documents by this
- printer.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255}
- )
-
- Each resolution value should be a string containing 3 fields:
- 1) Cross feed direction resolution (positive integer);
- 2) Feed direction resolution (positive integer);
- 3) Unit - 'dpi' (dots per inch) or 'dpcm' (dots per centimeter).
-
- Each resolution field should be delimited by '>'. For example:
-
- '300> 300> dpi>'
- '600> 600> dpi>'
-
- Note: This attribute is based on 'printer-resolution-supported'
- defined in IPP/1.1 [RFC2911] (which has a binary complex encoding)
- derived from 'prtMarkerAddressabilityFeedDir',
- 'prtMarkerAddressabilityXFeedDir', and 'prtMarkerAddressabilityUnit'
- defined in the Printer MIB [RFC1759] (which have integer encodings).
-
- Note: The syntax and delimiter for this attribute are aligned with
- the equivalent attribute in the 'service:printer:' v2.0 template
- [SLP-PRT]. Whitespace is permitted after (but not before) the
- delimiter '>'. Note that this delimiter differs from printer-xri-
- supported.
-
-
-
-
-
-
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 21]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
-4.25. printer-print-quality-supported
-
- ( 1.3.18.0.2.4.1120
- NAME 'printer-print-quality-supported'
- DESC 'List of print qualities supported for printing documents on
- this printer.'
- EQUALITY caseIgnoreMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127}
- )
-
- Values defined in IPP/1.1 [RFC2911] include:
-
- 'unknown'
- 'draft'
- 'normal'
- 'high'
-
-4.26. printer-job-priority-supported
-
- ( 1.3.18.0.2.4.1110
- NAME 'printer-job-priority-supported'
- DESC 'Indicates the number of job priority levels supported by this
- printer.'
- EQUALITY integerMatch
- ORDERING integerOrderingMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE
- )
-
- An IPP/1.1 [RFC2911] conformant Printer, which supports job priority,
- always supports a full range of priorities from '1' to '100' (to
- ensure consistent behavior), therefore this attribute describes the
- 'granularity' of priority supported. Values of this attribute are
- from '1' to '100'.
-
-4.27. printer-copies-supported
-
- ( 1.3.18.0.2.4.1118
- NAME 'printer-copies-supported'
- DESC 'The maximum number of copies of a document that may be printed
- as a single job on this printer.'
- EQUALITY integerMatch
- ORDERING integerOrderingMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE
- )
-
-
-
-
-
-Fleming & McDonald Informational [Page 22]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- A positive value indicates the maximum supported copies. A value of
- '0' indicates no maximum limit. A value of '-1' indicates 'unknown'.
-
- Note: The syntax and values for this attribute are aligned with the
- equivalent attribute in the 'service:printer:' v2.0 template [SLP-
- PRT].
-
-4.28. printer-job-k-octets-supported
-
- ( 1.3.18.0.2.4.1111
- NAME 'printer-job-k-octets-supported'
- DESC 'The maximum size in kilobytes (1,024 octets actually) incoming
- print job that this printer will accept.'
- EQUALITY integerMatch
- ORDERING integerOrderingMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE
- )
-
- A positive value indicates the maximum supported job size. A value
- of '0' indicates no maximum limit. A value of '-1' indicates
- 'unknown'.
-
- Note: The syntax and values for this attribute are aligned with the
- equivalent attribute in the 'service:printer:' v2.0 template [SLP-
- PRT].
-
-4.29. printer-current-operator
-
- ( 1.3.18.0.2.4.1112
- NAME 'printer-current-operator'
- DESC 'The identity of the current human operator responsible for
- operating this printer.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127}
- SINGLE-VALUE
- )
-
- The value of this attribute should include information that would
- enable other humans to reach the operator, such as a telephone
- number.
-
-
-
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 23]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
-4.30. printer-service-person
-
- ( 1.3.18.0.2.4.1113
- NAME 'printer-service-person'
- DESC 'The identity of the current human service person responsible
- for servicing this printer.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127}
- SINGLE-VALUE
- )
-
- The value of this attribute should include information that would
- enable other humans to reach the service person, such as a telephone
- number.
-
-4.31. printer-delivery-orientation-supported
-
- ( 1.3.18.0.2.4.1114
- NAME 'printer-delivery-orientation-supported'
- DESC 'The possible delivery orientations of pages as they are printed
- and ejected from this printer.'
- EQUALITY caseIgnoreMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127}
- )
-
- Values defined include:
-
- 'unknown'
- 'face-up'
- 'face-down'
-
- Note: The syntax and values for this attribute are aligned with the
- equivalent attribute in the 'service:printer:' v2.0 template [SLP-
- PRT].
-
-4.32. printer-stacking-order-supported
-
- ( 1.3.18.0.2.4.1115
- NAME 'printer-stacking-order-supported'
- DESC 'The possible stacking order of pages as they are printed and
- ejected from this printer.'
- EQUALITY caseIgnoreMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127}
- )
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 24]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- Values defined include:
-
- 'unknown'
- 'first-to-last'
- 'last-to-first'
-
- Note: The syntax and values for this attribute are aligned with the
- equivalent attribute in the 'service:printer:' v2.0 template [SLP-
- PRT].
-
-4.33. printer-output-features-supported
-
- ( 1.3.18.0.2.4.1116
- NAME 'printer-output-features-supported'
- DESC 'The possible output features supported by this printer.'
- EQUALITY caseIgnoreMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127}
- )
-
- Values defined include:
-
- 'unknown'
- 'bursting'
- 'decollating'
- 'page-collating'
- 'offset-stacking'
-
- Note: The syntax and values for this attribute are aligned with the
- equivalent attribute in the 'service:printer:' v2.0 template [SLP-
- PRT].
-
- Note: Implementations may support other values.
-
-4.34. printer-aliases
-
- ( 1.3.18.0.2.4.1108
- NAME 'printer-aliases'
- DESC 'List of site-specific administrative names of this printer in
- addition to the value specified for printer-name.'
- EQUALITY caseIgnoreMatch
- SUBSTR caseIgnoreSubstringsMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127}
- )
-
- Values of this attribute should be specified in the language
- specified in printer-natural-language-configured (for example, to
- support text-to-speech conversions), although the printer's alias may
- be specified in any language.
-
-
-
-Fleming & McDonald Informational [Page 25]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
-5. Definition of Syntaxes
-
- No new attribute syntaxes are defined by this document.
-
- The attribute types defined in Section 4 of this document reference
- syntax OIDs defined in Section 6 of [RFC2252], which are summarized
- below:
-
- Syntax OID Syntax Description
- ------------------------------ ------------------
- 1.3.6.1.4.1.1466.115.121.1.7 Boolean
- 1.3.6.1.4.1.1466.115.121.1.15 DirectoryString (UTF-8 [RFC2279])
- 1.3.6.1.4.1.1466.115.121.1.27 Integer
-
-6. Definition of Matching Rules
-
- No new matching rules are defined by this document.
-
- The attribute types defined in Section 4 of this document reference
- matching rules defined in Section 8 of [RFC2252] and/or Section 2 of
- [RFC3698], which are summarized below:
-
- Matching Rule OID Matching Rule Name Usage
- ------------------------------ ------------------ -----
- 2.5.13.13 booleanMatch EQUALITY
- 2.5.13.2 caseIgnoreMatch EQUALITY
- 2.5.13.14 integerMatch EQUALITY
- 2.5.13.15 integerOrderingMatch ORDERING
- 2.5.13.4 caseIgnoreSubstringsMatch SUBSTR
-
-7. IANA Considerations
-
- This document does not define any new syntaxes or matching rules.
-
- This document does define the following Object Identifier
- Descriptors. They have been registered by the IANA:
-
-7.1. Registration of Object Classes
-
- Subject: Request for LDAP Descriptor Registration
-
- Descriptor (short name): see table below
-
- Object Identifier: see table below
-
- Person & email address to contact for further information: see below
-
- Usage: object class
-
-
-
-Fleming & McDonald Informational [Page 26]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- Specification: RFC3712
-
- Author/Change Controller:
-
- Pat Fleming
- IBM
- Highway 52 N
- Rochester, MN 55901
- USA
- Phone: +1 507-253-7583
- EMail: flemingp@us.ibm.com
-
- Comments:
-
- Object Class OID
- ------------------------------------ ---------------------
- slpServicePrinter 1.3.18.0.2.6.254
- printerAbstract 1.3.18.0.2.6.258
- printerService 1.3.18.0.2.6.255
- printerServiceAuxClass 1.3.18.0.2.6.257
- printerIPP 1.3.18.0.2.6.256
- printerLPR 1.3.18.0.2.6.253
-
-7.2. Registration of Attribute Types
-
- Subject: Request for LDAP Descriptor Registration
-
- Descriptor (short name): see table below
-
- Object Identifier: see table below
-
- Person & email address to contact for further information: see below
-
- Usage: attribute type
-
- Specification: RFC3712
-
- Author/Change Controller:
-
- Pat Fleming
- IBM
- Highway 52 N
- Rochester, MN 55901
- USA
- Phone: +1 507-253-7583
- EMail: flemingp@us.ibm.com
-
-
-
-
-
-Fleming & McDonald Informational [Page 27]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- Comments:
-
- Attribute Type OID
- ------------------------------------ ---------------------
- printer-uri 1.3.18.0.2.4.1140
- printer-xri-supported 1.3.18.0.2.4.1107
- printer-name 1.3.18.0.2.4.1135
- printer-natural-language-configured 1.3.18.0.2.4.1119
- printer-location 1.3.18.0.2.4.1136
- printer-info 1.3.18.0.2.4.1139
- printer-more-info 1.3.18.0.2.4.1134
- printer-make-and-model 1.3.18.0.2.4.1138
- printer-ipp-versions-supported 1.3.18.0.2.4.1133
- printer-multiple-document-jobs-supported 1.3.18.0.2.4.1132
- printer-charset-configured 1.3.18.0.2.4.1109
- printer-charset-supported 1.3.18.0.2.4.1131
- printer-generated-natural-language-supported 1.3.18.0.2.4.1137
- printer-document-format-supported 1.3.18.0.2.4.1130
- printer-color-supported 1.3.18.0.2.4.1129
- printer-compression-supported 1.3.18.0.2.4.1128
- printer-pages-per-minute 1.3.18.0.2.4.1127
- printer-pages-per-minute-color 1.3.18.0.2.4.1126
- printer-finishings-supported 1.3.18.0.2.4.1125
- printer-number-up-supported 1.3.18.0.2.4.1124
- printer-sides-supported 1.3.18.0.2.4.1123
- printer-media-supported 1.3.18.0.2.4.1122
- printer-media-local-supported 1.3.18.0.2.4.1117
- printer-resolution-supported 1.3.18.0.2.4.1121
- printer-print-quality-supported 1.3.18.0.2.4.1120
- printer-job-priority-supported 1.3.18.0.2.4.1110
- printer-copies-supported 1.3.18.0.2.4.1118
- printer-job-k-octets-supported 1.3.18.0.2.4.1111
- printer-current-operator 1.3.18.0.2.4.1112
- printer-service-person 1.3.18.0.2.4.1113
- printer-delivery-orientation-supported 1.3.18.0.2.4.1114
- printer-stacking-order-supported 1.3.18.0.2.4.1115
- printer-output-features-supported 1.3.18.0.2.4.1116
- printer-aliases 1.3.18.0.2.4.1108
-
-8. Internationalization Considerations
-
- All text string attributes defined in this document of syntax
- [RFC2279], as required by [RFC2252].
-
- A language tag [RFC3066] for all of the text string attributes
- defined in this document is contained in the printer-natural-
- language-configured attribute.
-
-
-
-
-Fleming & McDonald Informational [Page 28]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- Therefore, all object classes defined in this document conform to the
- "IETF Policy on Character Sets and Languages" [RFC2277].
-
-9. Security Considerations
-
- See [RFC2829] for detailed guidance on authentication methods for
- LDAP. See [RFC2830] for detailed guidance of using TLS/1.0 [RFC2246]
- to supply connection confidentiality and data integrity for LDAP
- sessions.
-
- As with any LDAP schema, it is important to protect specific entries
- and attributes with the appropriate access control. It is
- particularly important that only administrators can modify entries
- defined in this LDAP printer schema. Otherwise, an LDAP client might
- be fooled into diverting print service requests from the original
- printer (or spooler) to a malicious intruder's host system, thus
- exposing the information in printed documents.
-
- For additional security considerations of deploying printers in an
- IPP environment, see Section 8 of [RFC2911].
-
-10. References
-
-10.1. Normative References
-
- [IANA-CHAR] IANA Registry of Character Sets
- http://www.iana.org/assignments/charset-reg/...
-
- [IANA-MIME] IANA Registry of MIME Media Types
- http://www.iana.org/assignments/media-types/...
-
- [LDAP-TS] Hodges, J. and R. Morgan, "Lightweight Directory Access
- Protocol (v3): Technical Specification", RFC 3377,
- September 2002.
-
- [RFC1274] Barker, P. and S. Kille, "The COSINE and Internet X.500
- Schema", RFC 1274, November 1991.
-
- [RFC1759] Smith, R., Wright, F., Hastings, T., Zilles, S. and J.
- Gyllenskog, "Printer MIB", RFC 1759, March 1995.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2252] Wahl, M., Coulbeck, T., Howes, T. and S. Kille,
- "Lightweight Directory Access Protocol (v3): Attribute
- Syntax Definitions", RFC 2252, December 1997.
-
-
-
-
-Fleming & McDonald Informational [Page 29]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- [RFC2396] Berners-Lee. T., Fielding, R. and L. Masinter, "URI
- Generic Syntax", RFC 2396, August 1998.
-
- [RFC2829] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan,
- "Authentication Methods for LDAP", RFC 2829, May 2000.
-
- [RFC2830] Hodges, J., Morgan, R. and M. Wahl, "Lightweight
- Directory Access Protocol (v3): Extension for Transport
- Layer Security", RFC 2830, May 2000.
-
- [RFC2911] Hastings, T., Ed.., Herrito, R., deBry, R., Isaacson, S.
- and P. Powell, "Internet Printing Protocol/1.1: Model and
- Semantics", RFC 2911, September 2000.
-
- [RFC2926] Kempf, J., Moats, R. and P. St. Pierre, "Conversion of
- LDAP Schemas to and from SLP Templates", RFC 2926,
- September 2000.
-
- [RFC3066] Alvestrand, H., "Tags for the Identification of
- Languages", BCP 47, RFC 3066, January 2001.
-
- [RFC3698] Zeilenga, K., Ed., "Lightweight Directory Access Protocol
- (LDAP): Additional Matching Rules", RFC 3698, February
- 2004.
-
-10.2. Informative References
-
- [IANA-SLPT] IANA Registry of SLP Templates
- http://www.iana.org/assignments/svrloc-templates/...
-
- [RFC1179] McLaughlin, L., "Line Printer Daemon Protocol", RFC 1179,
- August 1990.
-
- [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format
- Specification Version 1.3", RFC 1951, May 1996.
-
- [RFC1952] Deutsch, P., "GZIP File Format Specification Version
- 4.3", RFC 1952, May 1996.
-
- [RFC1977] Schryver, V., "PPP BSD Compression Protocol", RFC 1977,
- August 1996.
-
- [RFC2048] Freed, N., Klensin, J. and J. Postel, "Multipurpose
- Internet Mail Extensions (MIME) Part Four: Registration
- Procedures", BCP 13, RFC 2048, November 1996.
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 30]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
- [RFC2079] Smith, M., "Definition of an X.500 Attribute Type and an
- Object Class to Hold Uniform Resource Identifiers
- (URIs)", RFC 2079, January 1997.
-
- [RFC2246] Dierks, T. and C. Allen, "TLS Protocol Version 1.0", RFC
- 2246, January 1999.
-
- [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
- Languages", RFC 2277, January 1998.
-
- [RFC2279] Yergeau, F., "UTF-8, a Transformation Format of ISO
- 10646", RFC 2279, January 1998.
-
- [RFC2608] Guttman, E., Perkins, C., Veizades, J. and M. Day,
- "Service Location Protocol v2", RFC 2608, June 1999.
-
- [RFC2609] Guttman, E., Perkins, C. and J. Kempf, "Service Templates
- and Service: Schemes", RFC 2609, June 1999.
-
- [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence,
- S., Leach, P., Luotonen, A. and L. Stewart, "HTTP
- Authentication: Basic and Digest Access Authentication",
- RFC 2617, June 1999.
-
- [RFC2717] Petke, R. and I. King, "Registration Procedures for URL
- Scheme Names", RFC 2717, November 1999.
-
- [RFC2718] Masinter, L., Alvestrand, H., Zigmond, D. and R. Petke,
- "Guidelines for new URL Schemes", BCP 19, RFC 2718,
- November 1999.
-
- [RFC2978] Freed, N. and J.Postel, "IANA Charset Registration
- Procedures", RFC2978, October 2000.
-
- [SLP-PRT] St. Pierre, Isaacson, McDonald. Definition of the
- Printer Abstract Service Type v2.0, <durable URL below>,
- May 2000. Reviewed and approved by IETF SLP Designated
- Expert, according to Section 5 'IANA Considerations' in
- [RFC2609].
-
- Archived in the IANA Registry of SLP Templates [IANA-
- SLPT] at: http://www.iana.org/assignments/svrloc-
- templates/printer.2.0.en
-
- [W3C-IRI] Duerst, Suignard, "Internationalized Resource Identifiers
- (IRI), Work in Progress.
-
-
-
-
-
-Fleming & McDonald Informational [Page 31]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
-11. Acknowledgments
-
- The editors wish to acknowledge the very significant contributions of
- Ken Jones (Bytemobile) and Harry Lewis (IBM) during the development
- of this document.
-
- Thanks to Patrik Faltstrom (Cisco), Ryan Moats (Lemur Networks),
- Robert Moore (IBM), Lee Rafalow (IBM), Kimberly Reger (IBM), Kurt
- Zeilenga (OpenLDAP), and the members of the IETF IPP Working Group,
- for review comments and help in preparing this document.
-
-12. Authors' Addresses
-
- Please send comments to the authors at the addresses listed below.
-
- Pat Fleming
- IBM
- Highway 52 N
- Rochester, MN 55901
- USA
-
- Phone: +1 507-253-7583
- EMail: flemingp@us.ibm.com
-
-
- Ira McDonald
- High North Inc
- 221 Ridge Ave
- Grand Marais, MI 49839
- USA
-
- Phone: +1 906-494-2434
- Email: imcdonald@sharplabs.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 32]
-\f
-RFC 3712 LDAP Schema for Printer Services February 2004
-
-
-13. Full Copyright Statement
-
- Copyright (C) The Internet Society (2004). This document is subject
- to the rights, licenses and restrictions contained in BCP 78 and
- except as set forth therein, the authors retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE
- REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE
- INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR
- IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
- THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed
- to pertain to the implementation or use of the technology
- described in this document or the extent to which any license
- under such rights might or might not be available; nor does it
- represent that it has made any independent effort to identify any
- such rights. Information on the procedures with respect to
- rights in RFC documents can be found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use
- of such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository
- at http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention
- any copyrights, patents or patent applications, or other
- proprietary rights that may cover technology that may be required
- to implement this standard. Please address the information to the
- IETF at ietf-ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-Fleming & McDonald Informational [Page 33]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group R. Bergman
-Request for Comments: 3805 Hitachi Printing Solutions
-Obsoletes: 1759 H. Lewis
-Category: Standards Track IBM Corporation
- I. McDonald
- High North Inc.
- June 2004
-
-
- Printer MIB v2
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2004).
-
-Abstract
-
- This document provides definitions of models and manageable objects
- for printing environments. The objects included in this MIB apply to
- physical, as well as logical entities within a printing device. This
- document obsoletes RFC 1759.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 1]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-Table of Contents
-
- 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . 4
- 1.1. Network Printing Environment. . . . . . . . . . . . . . 4
- 1.2. Printer Device Overview . . . . . . . . . . . . . . . . 6
- 1.3. Categories of Printer Information . . . . . . . . . . . 6
- 1.3.1. Descriptions. . . . . . . . . . . . . . . . . . 6
- 1.3.2. Status. . . . . . . . . . . . . . . . . . . . . 6
- 1.3.3. Alerts. . . . . . . . . . . . . . . . . . . . . 6
- 1.4. The Internet-Standard Management Framework. . . . . . . 7
- 1.5. Requirement Levels. . . . . . . . . . . . . . . . . . . 7
- 2. Printer Model . . . . . . . . . . . . . . . . . . . . . . . . 8
- 2.1. Overview of the Printer Model . . . . . . . . . . . . . 10
- 2.2. Printer Sub-Units . . . . . . . . . . . . . . . . . . . 10
- 2.2.1. General Printer . . . . . . . . . . . . . . . . 10
- 2.2.1.1. International Considerations. . . . . 10
- 2.2.2. Inputs. . . . . . . . . . . . . . . . . . . . . 11
- 2.2.3. Media . . . . . . . . . . . . . . . . . . . . . 12
- 2.2.4. Outputs . . . . . . . . . . . . . . . . . . . . 12
- 2.2.5. Finishers . . . . . . . . . . . . . . . . . . . 12
- 2.2.6. Markers . . . . . . . . . . . . . . . . . . . . 13
- 2.2.7. Media Paths . . . . . . . . . . . . . . . . . . 13
- 2.2.8. System Controller . . . . . . . . . . . . . . . 14
- 2.2.9. Interfaces. . . . . . . . . . . . . . . . . . . 14
- 2.2.10. Print Job Delivery Channels . . . . . . . . . . 14
- 2.2.11. Interpreters. . . . . . . . . . . . . . . . . . 15
- 2.2.12. Console . . . . . . . . . . . . . . . . . . . . 15
- 2.2.13. Alerts. . . . . . . . . . . . . . . . . . . . . 15
- 2.2.13.1. Status and Alerts . . . . . . . . . . 16
- 2.2.13.2. Overall Printer Status. . . . . . . . 16
- 2.2.13.2.1. Host Resources MIB
- Printer Status. . . . . . 18
- 2.2.13.2.2. Sub-unit Status . . . . . 20
- 2.2.13.3. Alert Tables. . . . . . . . . . . . . 21
- 2.2.13.4. Alert Table Management. . . . . . . . 21
- 2.3. Read-Write Objects. . . . . . . . . . . . . . . . . . . 23
- 2.4. Enumerations. . . . . . . . . . . . . . . . . . . . . . 24
- 2.4.1. Registering Additional Enumerated Values. . . . 25
- 3. Groups from other MIB Specifications. . . . . . . . . . . . . 25
- 3.1. System Group. . . . . . . . . . . . . . . . . . . . . . 25
- 3.2. System Controller . . . . . . . . . . . . . . . . . . . 25
- 3.3. Interface Group objects . . . . . . . . . . . . . . . . 26
- 3.3.1. Interface Types . . . . . . . . . . . . . . . . 26
- 4. Differences from RFC 1759 . . . . . . . . . . . . . . . . . . 26
- 5. The IANA Printer MIB. . . . . . . . . . . . . . . . . . . . . 29
- 6. The Printer MIB . . . . . . . . . . . . . . . . . . . . . . . 56
- -- Textual conventions for this MIB module. . . . . . . . . . 59
- -- The General Printer Group. . . . . . . . . . . . . . . . . 67
-
-
-
-Bergman, et al. Standards Track [Page 2]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- -- The Responsible Party group. . . . . . . . . . . . . . . . 70
- -- The Auxiliary Sheet Group. . . . . . . . . . . . . . . . . 73
- -- Administrative section (The General V2 Group) . . . . . . 74
- -- General alert table section (Alert Table V2 Group). . . . 74
- -- The Cover Table. . . . . . . . . . . . . . . . . . . . . . 75
- -- The Localization Table . . . . . . . . . . . . . . . . . . 76
- -- The System Resources Tables. . . . . . . . . . . . . . . . 78
- -- The Input Group. . . . . . . . . . . . . . . . . . . . . . 81
- -- The Extended Input Group . . . . . . . . . . . . . . . . . 86
- -- The Input Media Group. . . . . . . . . . . . . . . . . . . 87
- -- The Input Switching Group. . . . . . . . . . . . . . . . . 89
- -- The Output Group . . . . . . . . . . . . . . . . . . . . . 90
- -- The Extended Output Group. . . . . . . . . . . . . . . . . 93
- -- The Output Dimensions Group. . . . . . . . . . . . . . . . 95
- -- The Output Features Group. . . . . . . . . . . . . . . . . 97
- -- The Marker Group . . . . . . . . . . . . . . . . . . . . . 98
- -- The Marker Supplies Group. . . . . . . . . . . . . . . . . 104
- -- The Marker Colorant Group. . . . . . . . . . . . . . . . . 107
- -- The Media Path Group . . . . . . . . . . . . . . . . . . . 109
- -- The Print Job Delivery Channel Group . . . . . . . . . . . 113
- -- The Interpreter Group. . . . . . . . . . . . . . . . . . . 115
- -- The Console Group. . . . . . . . . . . . . . . . . . . . . 120
- -- The Alerts Group . . . . . . . . . . . . . . . . . . . . . 125
- -- Conformance Information. . . . . . . . . . . . . . . . . . 129
- 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 147
- 8. Internationalization Considerations . . . . . . . . . . . . . 147
- 9. Security Considerations . . . . . . . . . . . . . . . . . . . 148
- 10. References. . . . . . . . . . . . . . . . . . . . . . . . . . 150
- 10.1. Normative References. . . . . . . . . . . . . . . . . . 150
- 10.2. Informative References. . . . . . . . . . . . . . . . . 151
- Appendix A - Glossary of Terms. . . . . . . . . . . . . . . . . . 153
- Appendix B - Media Size Names . . . . . . . . . . . . . . . . . . 156
- Appendix C - Media Names. . . . . . . . . . . . . . . . . . . . . 158
- Appendix D - Roles of Users . . . . . . . . . . . . . . . . . . . 162
- Appendix E - Overall Printer Status Table . . . . . . . . . . . . 165
- Appendix F - Participants . . . . . . . . . . . . . . . . . . . . 166
- Significant Contributors. . . . . . . . . . . . . . . . . . . . . 168
- Authors' Addresses. . . . . . . . . . . . . . . . . . . . . . . . 170
- Full Copyright Statement. . . . . . . . . . . . . . . . . . . . . 171
-
-
-
-
-
-
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 3]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-1. Introduction
-
-1.1. Network Printing Environment
-
- The management of producing a printed document, in any computer
- environment, is a complex subject. Basically, the task can be
- divided into two overlapping pieces, the management of printing and
- the management of the printer. Printing encompasses the entire
- process of producing a printed document from generation of the file
- to be printed, selection of a printer, choosing printing properties,
- routing, queuing, resource management, scheduling, and final printing
- including notifying the user. Most of the printing process is
- outside the scope of the model presented here; only the management of
- the printer is covered.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 4]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- Figure 1 - One Printer's View of the Network
-
- system printer asset user user user
- manager operator manager
- O O O O O O
- /|\ /|\ /|\ /|\ /|\ /|\
- / \ / \ / \ / \ / \ / \
- | | | | | |
-+---------+ +-------+ +-------+ +-------+ +-----------+ +-----------+
-|configur-| |printer| | asset | |printer| | user | | user |
-|ator | |manager| |manager| |browser| |application| |application|
-+---------+ +-------+ +-------+ +-------+ +-----------+ +-----------+
- ^ ^ ^ ^ | |
- |R/W |R/W |R |R +-----------+ +-----------+
- | | | | | spooler | | spooler |
- | | | | +-----------+ +-----------+
- | | | | | |
- | | | | +-----------+ +-----------+
- | | | | |supervisor | |supervisor |
- | | | | +-----------+ +-----------+
- | | | | ^ ^ ^ ^
- | | | | |R |R/W |R |R/W
- v v | | | | | |
-================================================== | ===== |
- | print| print|
- |SNMP data| data|
- +-----+ +-------+ PCL| PCL|
- | MIB |<------>| agent | PostScript| PostScript|
- +-----+ +-------+ NPAP| NPAP|
- |unspecified etc.| etc.|
- +=============+ +-----------------+ | |
- | |--|channel/interface|<--+ |
- | | +-----------------+ |
- | PRINTER | |
- | | +-----------------+ |
- | |--|channel/interface|<----------------+
- +=============+ +-----------------+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 5]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-1.2. Printer Device Overview
-
- A printer is the physical device that takes media from an input
- source, produces marks on that media according to some page
- description or page control language and puts the result in some
- output destination, possibly with finishing applied. Printers are
- complex devices that consume supplies, produce waste and may have
- mechanical problems. In the management of the physical device the
- description, status and alert information concerning the printer and
- its various subparts has to be made available to the management
- application so that it can be reported to the end user, key operators
- for the replenishment of supplies or the repair or maintenance of the
- device. The information needed in the management of the physical
- printer and the management of a printing job overlap highly and many
- of the tasks in each management area require the same or similar
- information.
-
-1.3. Categories of Printer Information
-
- Information about printers is classified into three basic categories:
- descriptions, status and alerts.
-
-1.3.1. Descriptions
-
- Descriptions convey information about the configuration and
- capabilities of the printer and its various sub-units. This
- information is largely static information and does not generally
- change during the operation of the system but may change as the
- printer is repaired, reconfigured or upgraded. The descriptions are
- one part of the visible state of the printer where state means the
- condition of being of the printer at any point in time.
-
-1.3.2. Status
-
- Status is the information regarding the current operating state of
- the printer and its various sub-units. As an example of the use of
- status, a management application must be able to determine if the
- various sub-units are ready to print or are in some state that
- prevents printing or may prevent printing in the future.
-
-1.3.3. Alerts
-
- An Alert is the representation of a reportable event in the printer.
- An event is a change in the state of the printer. Some of those
- state changes are of interest to a management application and are
- therefore reportable. Typically, these are the events that affect
- the printer's ability to print. Alerts usually occur asynchronously
- to the operation of the computer system(s) to which the printer is
-
-
-
-Bergman, et al. Standards Track [Page 6]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- attached. For convenience below, "alert" will be used for both the
- event caused by a change in the printer's state and for the
- representation of that event.
-
- Alerts can be classified into two basic categories, critical and non-
- critical. A critical alert is one that is triggered by entry into a
- state in which the printer is stopped and printing can not continue
- until the condition that caused the critical alert is eliminated.
- "Out of paper", "toner empty" and "output bin full" are examples of
- critical alerts. Non-critical alerts are triggered by those events
- that enter a state in which printing is not stopped. Such a non-
- critical state may, at some future time, lead to a state in which
- printing may be stopped. Examples of these kinds of non-critical
- alerts are "input media low", "toner low" and "output bin nearly
- full". Or, a non-critical alert may simply provide information, such
- as signaling a configuration changed in the printer.
-
- Description, status and alert information about the printer can be
- thought of as a database describing the printer. The management
- application for a printer will want to view the printer data base
- differently depending on how and for what purposes the information in
- the database is needed.
-
-1.4. The Internet-Standard Management Framework
-
- For a detailed overview of the documents that describe the current
- Internet-Standard Management Framework, please refer to section 7 of
- RFC 3410 [RFC3410].
-
- Managed objects are accessed via a virtual information store, termed
- the Management Information Base or MIB. MIB objects are generally
- accessed through the Simple Network Management Protocol (SNMP).
- Objects in the MIB are defined using the mechanisms defined in the
- Structure of Management Information (SMI). This memo specifies a MIB
- module that is compliant to the SMIv2, which is described in STD 58,
- RFC 2578 [RFC2578], STD 58, RFC 2579 [RFC2579] and STD 58, RFC 2580
- [RFC2580].
-
-1.5. Requirement Levels
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in [RFC2119].
-
- Compliant implementations must follow this specification.
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 7]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-2. Printer Model
-
- In order to accomplish the management of the printer, an abstract
- model of the printer is needed to represent the sub-units from which
- the printer is composed. A printer can be described as consisting of
- 13 types of sub-units. It is important to note that the sub-units of
- a printer do not necessarily relate directly to any physically
- identifiable mechanism. Sub-units can also be a set of definable
- logical processes, such as interpreters for page description
- languages or command processors that set various operating modes of
- the printer.
-
- Figure 2 shows a block diagram of the printer and its basic 13 sub-
- units.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 8]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- Figure 2 - Printer Block Diagram
-
- Physical Connections
- |
- +-----------+
- | |
- +-------------+ |
- | Interface |-+
- | MIB-II |
- +-------------+
- |
- +-----------+
- | |
- +-------------+ | +-----------+
- | Channel |-+ | Operator |
- | | | Console |
- +-------------+ +-----------+
- |
- +-----------+ +---------+
- | | | |
- +-----------+ +-------------+ | +-----------+ |
- | General | | Interpreter |-+ | Alerts |-+
- | Printer | | | | |
- +-----------+ +-------------+ +-----------+
- |
- +-------------------------------+
- | System Controller |
- | HOST-RESOURCES-MIB |
- +-------------------------------+
-
- +------+ +--------+ +--------+
- | | | | | |
-+-------+ | +-------+ +---------+ | +-------+ +--------+ |
-| Input |-+ +--------+| | Marker |-+ +--------+| | Output |-+
-| |===>| |+<==>| |<==>| |+==>| |
-+-------+ +--+ +--+ +---------+ +--+ +--+ +--------+
- \ | || | || \
- \ | || | || \
- \ | || | || \
- +--------+ | |+-------------------------| || +---------+
- | | | +--------------------------+ || | |
-+----------+ | | Media Path |+ +----------+ |
-| Media |-+ +--------------------------------+ | Finisher |-+
-|(optional)| |(optional)|
-+----------+ +----------+
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 9]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-2.1. Overview of the Printer Model
-
- The model has three basic parts: (1) the flow of a print file into an
- interpreter and onto the marker, (2) the flow of media through the
- marker and (3) the auxiliary sub-units that control and facilitate
- the two prior flows. The flow of the print data comes through a
- physical connection on which some form of transport protocol stack is
- running. The data provided by the transport protocol (interface)
- appears on a channel, which is the input to an interpreter. The
- interpreter converts the print data into a form suitable for marking
- on the media.
-
- The media resides in Input sub-units from which the media is selected
- and then transported via a Media Path first to a Marking sub-unit and
- then onto an Output sub-unit with (optionally) some finishing
- operations being performed. The auxiliary sub-units facilitate
- control of the printer, inquiry/control of the operator panel,
- reporting of alerts and the adaptation of the printer to various
- natural languages and characters sets. All the software sub-units
- run on the System Controller that represents the processor, memory
- and storage systems of the Printer. Each of the sub-units is
- discussed in more detail below.
-
- All of the sub-units other than the Alerts report only state
- information, either a description or a status. The Alerts sub-unit
- reports event information.
-
-2.2. Printer Sub-Units
-
- A printer is composed of 13 types of sub-units, called groups. The
- following sections describe the different types of sub-units.
-
-2.2.1. General Printer
-
- The general printer sub-unit is responsible for the overall control
- and status of the printer. There is exactly one general printer sub-
- unit in a printer. The General Printer Group in the model represents
- the general printer sub-unit. In addition to the providing the
- status of the whole printer and allowing the printer to be reset,
- this Group provides information on the status of the packaging of the
- printer, in particular, the covers. The general printer sub-unit is
- usually implemented on the system controller.
-
-2.2.1.1. International Considerations
-
- The localization portion of the general printer sub-unit is
- responsible for identifying the natural language, country, and
- character set in which certain character strings are expressed in
-
-
-
-Bergman, et al. Standards Track [Page 10]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- this MIB. Character sets are identified in this MIB using the
- IANACharset textual convention imported from the IANA Character Set
- MIB [CHARMIB].
-
- There may be one or more localizations supported per printer. The
- available localizations are specified in the Localization table.
- Localization SHOULD only be performed on string objects which are
- named 'xxxDescription' (sub-unit descriptions) or
- 'prtConsoleDisplayBufferText' (local console text).
-
- The agent SHALL return all other character strings in coded character
- sets in which code positions 0-127 (decimal) are US-ASCII [ASCII].
- The agent SHOULD return all other character strings in the UTF-8
- [RFC3629] transform of ISO 10646 [ISO10646], to conform with the IETF
- Policy on Character Sets and Languages [RFC2277]. Control codes
- (code positions 0-31 and 127 decimal) SHALL NOT be used unless
- specifically required in the DESCRIPTION of an object.
-
- The character set portion of the general printer Localization table
- is responsible for identifying the possible character sets for the
- operator console, and network management requests for display
- objects. There may be one or more character sets per printer.
- Default coded character sets for interpreter unit and output octets
- are described in the interpreter sub-unit by
- prtInterpreterDefaultCharSetIn and prtInterpreterDefaultCharSetOut.
- These input/output character sets may be overridden by commands in
- the interpreter language itself.
-
-2.2.2. Inputs
-
- Input sub-units are mechanisms that feed media to be marked on into
- the printer. A printer contains one or more input sub-units. The
- Input Group in the model represents these. The model does not
- distinguish fixed input bins from removable trays, except to report
- when a removable tray has been removed.
-
- There are as many input sub-units as there are distinctly selectable
- input "addresses". For example, if one tray has both a manual and
- auto feeding option, then this is two input sub-units if these two
- sources can be (must be) separately selected. However, the above
- would be considered one input sub-unit if putting a sheet in the
- manual feed slot overrides feeding from the contents of the tray. In
- the second case there is no way to separately select or address the
- manual feed slot.
-
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 11]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-2.2.3. Media
-
- An input sub-unit can hold one or more instances of the media on
- which marking is to be done. Typically, there is a large set of
- possible media that can be associated with an input. The Media Group
- is an extension of the Input Group, which represents media in an
- input sub-unit. The Media Group only describes the current contents
- of each input and not the possible content of the input sub-unit.
-
-2.2.4. Outputs
-
- Output sub-units are mechanisms that receive media that has been
- marked on. The Output Group in the model represents the one or more
- output mechanisms contained by a printer. The model does not
- distinguish fixed output bins from removable output bins, except to
- report when a removable bin has been removed.
-
- There are as many output sub-units as there are distinctly selectable
- output "addresses". Output sub-units can be addressed in two
- different ways: (1) as a set of "mailboxes" which are addressed by a
- specific mailbox selector such as a bin number or a bin name, or (2)
- as a set of "slots" into which multiple copies are collated.
- Sometimes both modes of using the output sub-units can be used on the
- same printer. All that is important from the viewpoint of the model
- is that the output units can be separately selected.
-
-2.2.5. Finishers
-
- A finisher is a sub-unit that performs some operations on the media
- other than marking. The Finisher Group in the model represents the
- finisher sub-units. Some examples of finishing processes are
- stapling, punching, binding, inserting, or folding. Finishing
- processes may have supplies associated with the process. Stapling,
- binding, and punching are examples of processes that have supplies.
- A printer may have more than one finishing sub-unit and each
- finishing sub-unit may be associated with one or more output sub-
- units. Finishers are described in the companion Finisher MIB
- [RFC3806].
-
- The model does not specify the exact interaction and sequencing
- between an output device and its associated finisher. It depends on
- the type of finishing process and the exact implementation of the
- printer system. This standard allows for the logical association of
- a finishing process with an output device but does not put any
- restrictions on the exact sequence or interaction with the associated
- output device. The output and finisher sub-units may or may not be
- separate identifiable physical mechanisms depending on the exact
-
-
-
-
-Bergman, et al. Standards Track [Page 12]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- implementation of a printer. In addition, a single output device may
- be associated with multiple finishing sub-units and a single
- finishing sub-unit may be associated with multiple output devices.
-
-2.2.6. Markers
-
- A marker is the mechanism that produces marks on the print media.
- The Marker Group in the model represents the marker sub-units and
- their associated supplies. A printer can contain one or more marking
- mechanisms. Some examples of multiple marker sub-units are a printer
- with separate markers for normal and magnetic ink or an image setter
- that can output to both a proofing device and final film. Each
- marking device can have its own set of characteristics associated
- with it, such as marking technology and resolution.
-
- In this model the marker sub-unit is viewed as very generalized and
- encompasses all aspects of a marking process. For example, in a
- xerographic process, the marking process as well as the fusing
- process would be included in the generalized concept of the marker.
- With the generalized concept of a marking process, the concept of
- multiple marking supplies associated with a single marking sub-unit
- results. For example, in the xerographic process, there is not only
- a supply of toner, but there can also be other supplies such as a
- fuser supply (e.g., fuser oil) that can be consumed and replaced
- separately. In addition there can be multiple supplies of toner for
- a single marker device, as in a color process.
-
-2.2.7. Media Paths
-
- The media paths encompass the mechanisms in the printer that move the
- media through the printer and connect all other media related sub-
- units: inputs, outputs, markers and finishers. A printer contains
- one or more media paths. The Media Path Group in the model
- represents these. The Media Path group has some objects that apply
- to all paths plus a table of the separate media paths.
-
- In general, the design of the media paths determines the maximum
- speed of the printer as well as the maximum media size that the
- printer can handle. Media paths are complex mechanisms and can
- contain many different identifiable sub-mechanisms such as media
- movement devices, media buffers, duplex units and interlocks. Not
- all of the various sub-mechanisms reside on every media path. For
- example, one media path may provide printing only on one surface of
- the media (a simplex path) and another media path may have a sub-
- mechanism that turns the media over and feeds it a second time
- through the marker sub-unit (a duplex path). The duplex path may
-
-
-
-
-
-Bergman, et al. Standards Track [Page 13]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- even have a buffer sub-mechanism that allows multiple copies of the
- obverse side to be held before the reverse side of all the copies is
- marked.
-
-2.2.8. System Controller
-
- The System Controller is the sub-unit upon which the software
- components of the Printer run. The Host Resources MIB [RFC2790]
- represents the System Controller in the model. The Host Resources
- MIB allows for the specification of the processor(s), memory, disk
- storage, file system and other underlying sub-mechanisms of the
- printer. The controller can range from simple single processor
- systems to multiprocessor systems. In addition, controllers can have
- a full range of resources such as hard disks. The printer is modeled
- to have one system controller even though it may have more than one
- processor and multiple other resources associated with it.
-
-2.2.9. Interfaces
-
- An interface is the communications port and associated protocols that
- are responsible for the transport of data to the printer. A printer
- has one or more interface sub-units. The interfaces are represented
- by the Interfaces Group of MIB-II [RFC1213], [RFC2863]. Some
- examples of interfaces are serial ports (with little or no protocol)
- and Ethernet ports on which one might run Internet IP, Novell IPX,
- etc.
-
-2.2.10. Print Job Delivery Channels
-
- The print job delivery channel sub-units identify the independent
- sources of print data (here print data is the information that is
- used to construct printed pages and may have both data and control
- aspects). A printer may have one or more channels. The channel sub-
- units are represented by the Print Job Delivery Channel Group in the
- Model. The electronic path typically identifies each channel and
- service protocol used to deliver print data to the printer. A
- channel sub-unit may be independently enabled (allowing print data to
- flow) or disabled (stopping the flow of print data). It has a
- current Control Language that can be used to specify which
- interpreter is to be used for the print data and to query and change
- environment variables used by the interpreters (and SNMP). There is
- also a default interpreter that is to be used if an interpreter is
- not explicitly specified using the Control Language. Print Job
- Delivery Channel sub-units can, and usually are, based on an
- underlying interface.
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 14]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-2.2.11. Interpreters
-
- The interpreter sub-units are responsible for the conversion of a
- description of intended print instances into images that are to be
- marked on the media. A printer may have one or more interpreters.
- The Interpreter Group in the Model represents the interpreter sub-
- units. Each interpreter is generally implemented with software
- running on the System Controller sub-unit. The Interpreter Table has
- one entry per interpreter where the interpreters include both Page
- Description Language (PDL) Interpreters and Control Language
- Interpreters.
-
-2.2.12. Console
-
- Many printers have a console on the printer, the operator console
- that is used to display and modify the state of the printer. The
- console can be as simple as a few indicators and switches or as
- complicated as full screen displays and keyboards. There can be at
- most one such console. The Console Group in the model represents
- this console sub-unit. Although most of the information displayed
- there is also available in the state of the printer as represented by
- the various Groups, it is useful to be able to query and modify the
- operator console remotely. For example, a management application
- might like to display to its user the current message on the operator
- console of the remote printer or the management application user
- might like to modify the current message on the operators console of
- the remote printer. As another example, one might have a remote
- application that puts up a pseudo console on a workstation screen.
- Since the rules by which the printer state is mapped onto the console
- and vice versa are not standardized, it is not possible to reproduce
- the console state or the action of console buttons and menus.
- Therefore, the Console Group provides access to the console. The
- operator console is usually implemented on the system controller with
- additional hardware for input and display.
-
-2.2.13. Alerts
-
- The alert sub-unit is responsible for detecting reportable events,
- making an entry in the alert table and, if and only if the event is a
- critical event, initiating a trap. The exception to this rule is
- when the "alertRemovalofBinaryChangeEntry" trap is generated. The
- alert sub-unit is represented by the Alerts Group and, in particular,
- the Alert Table. This table contains information on the severity,
- sub- unit, and detailed location within the sub-unit, alert code and
- description of each alert that is currently active within the
- printer. Each reportable event causes an entry to be made in the
- Alert Table.
-
-
-
-
-Bergman, et al. Standards Track [Page 15]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-2.2.13.1. Status and Alerts
-
- Summary information about the state of the printer is reported at
- three separate levels: (1) The status of the printer as a whole is
- reported in the Host Resources MIB, (2) The status of various sub-
- units is reported in the principle table of the Group that represents
- the sub-unit, and (3) Alert codes are reported in the Alert Table.
-
-2.2.13.2. Overall Printer Status
-
- Of the many states a printer can be in, certain states are more
- "interesting" because of the distinct actions they are likely to
- provoke in the administrator. These states may be applied to the
- printer as a whole, or to a particular sub-unit of the printer.
- These named states are:
-
- Non Critical Alert Active - For the printer this means that one or
- more sub-units have a non-critical alert active. For a sub-unit,
- this means that the sub-unit has a non-critical alert active.
-
- Critical Alert Active - For the printer this means that one or more
- sub-units have a critical alert active. For a sub-unit, this means
- that the sub-unit has a critical alert active.
-
- Unavailable - The printer or sub-unit is unavailable for use (this is
- the same as "broken" or "down" in other terminology). A trained
- service person is typically necessary to make it available.
-
- Moving on-line or off-line - The printer is either off-line, in the
- process of moving off-line or moving back on-line. For example, on
- printers with motorized hoppers, reloading paper involves a
- transition to off-line to open the paper bin, filling the hopper and,
- finally, a transition back to on-line as the paper bin is
- repositioned for printing.
-
- Standby - The printer or sub-unit is not immediately available but
- can accept new instructions.
-
- Available - The printer or subunit is functioning normally.
-
- Idle - The printer or subunit is immediately available.
-
- Active - The printer or subunit is performing its primary function.
-
- Busy - The printer or subunit is performing a function (not
- necessarily its primary function) and is not immediately available
- for its primary function.
-
-
-
-
-Bergman, et al. Standards Track [Page 16]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- The Host Resources MIB [RFC2790] provides three status objects that
- can be used to describe the status of a printer: (1) hrDeviceStatus
- in the entry in the hrDeviceTable; (2) hrPrinterStatus in the
- hrPrinterTable; and (3) hrPrinterDetectedErrorState in the
- hrPrinterTable. These objects describe many of the states that a
- printer can be in. The following table shows how the values of the
- three printer-related objects in the Host Resources MIB relate to the
- states named above:
-
- Printer hrDeviceStatus hrPrinterStatus hrPrinterDetected-
- Status ErrorState
-
- Idle running(2) idle(3) none set
-
- Busy/ running(2) printing(4)
- Active
-
- Non Critical warning(3) idle(3) or could be: lowPaper,
- Alert Active printing(4) lowToner, or
- serviceRequested
-
- Critical down(5) other(1) could be: jammed,
- Alert Active noPaper, noToner,
- coverOpen, or
- serviceRequested
-
- Unavailable down(5) other(1)
-
- Moving off- warning(3) idle(3) or offline
- line printing(4)
- Off-line down(5) other(1) offline
-
- Moving down(5) warmup(5)
- on-line
-
- Standby running(2) other(1)
-
- These named states are only a subset of the possible states - they
- are not an exhaustive list of the possible states. Nevertheless,
- several things should be noted. When using these states, it is not
- possible to detect when both critical and non-critical alerts are
- pending - if both are pending, the Critical Alert Active state will
- prevail. In addition, a printer in the Standby state will be
- represented in the Host Resources MIB with a device status of
- running(2) and a printer status of other(1), a set of states that
- don't uniquely distinguish this important printer state.
-
-
-
-
-
-Bergman, et al. Standards Track [Page 17]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- Detailed status per sub-unit is reported in the sub-unit status
- fields.
-
-2.2.13.2.1. Host Resources MIB Printer Status
-
- For completeness, the definitions of the Printer Status objects of
- the Host Resources MIB [RFC2790] are given below:
-
- hrDeviceStatus OBJECT-TYPE
- SYNTAX INTEGER {
- unknown(1),
- running(2),
- warning(3),
- testing(4),
- down(5)
- }
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "The current operational state of the device
- described by this row of the table. A value
- unknown(1) indicates that the current state of the
- device is unknown. running(2) indicates that the
- device is up and running and that no unusual error
- conditions are known. The warning(3) state
- indicates that agent has been informed of an
- unusual error condition by the operational software
- (e.g., a disk device driver) but that the device
- is still 'operational'. An example would be high
- number of soft errors on a disk. A value of
- testing(4), indicates that the device is not
- available for use because it is in the testing
- state. The state of down(5) is used only when
- the agent has been informed that the device is
- not available for any use."
- ::= { hrDeviceEntry 5 }
-
- hrPrinterStatus OBJECT-TYPE
- SYNTAX INTEGER {
- other(1),
- unknown(2),
- idle(3),
- printing(4),
- warmup(5)
- }
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
-
-
-
-Bergman, et al. Standards Track [Page 18]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- "The current status of this printer device. When in the
- idle(3), printing(4), or warmup(5) state, the corresponding
- hrDeviceStatus should be running(2) or warning(3). When in
- the unknown(2) state, the corresponding hrDeviceStatus
- should be unknown(1)."
- ::= { hrPrinterEntry 1 }
-
- hrPrinterDetectedErrorState OBJECT-TYPE
- SYNTAX OCTET STRING (0..128)
- ACCESS read-only
- STATUS mandatory
- DESCRIPTION
- "This object represents any error conditions detected by the
- printer. The error conditions are encoded as an OCTET STRING
- with the following definitions:
-
- Condition Bit #
-
- lowPaper 0
- noPaper 1
- lowToner 2
- noToner 3
- doorOpen 4
- jammed 5
- offline 6
- serviceRequested 7
-
- inputTrayMissing 8
- outputTrayMissing 9
- markerSupplyMissing 10
- outputNearFull 11
- outputFull 12
- inputTrayEmpty 13
- overduePreventMaint 14
-
- Bit # 15 is not assigned.
-
- If multiple conditions are currently detected and the
- hrDeviceStatus would not otherwise be unknown(1) or
- testing(4), the hrDeviceStatus shall correspond to the worst
- state of those indicated, where down(5) is worse than
- warning(3), which is worse than running(2).
-
- Bits are numbered starting with the most significant bit of
- the first byte being bit 0, the least significant bit of the
- first byte being bit 7, the most significant bit of the
- second byte being bit 8, and so on. A one bit encodes that
- the condition was detected, while a zero bit encodes that
-
-
-
-Bergman, et al. Standards Track [Page 19]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- the condition was not detected.
-
- This object is useful for alerting an operator to specific
- warning or error conditions that may occur, especially those
- requiring human intervention."
- ::= { hrPrinterEntry 2 }
-
-2.2.13.2.2. Sub-unit Status
-
- Sub-unit status is reported in the entries of the principle table in
- the Group that represents the sub-unit. For sub-units that report a
- status, there is a status column in the table and the value of this
- column is always an integer formed in the following way.
-
- The PrtSubUnitStatusTC is an integer that is the sum of 5 distinct
- values, Availability, Non-Critical, Critical, On-line, and
- Transitioning. These values are:
-
- Availability value
-
- Available and Idle 0 000'b
- Available and Standby 2 010'b
- Available and Active 4 100'b
- Available and Busy 6 110'b
- Unavailable and OnRequest 1 001'b
- Unavailable because Broken 3 011'b
- Unknown 5 101'b
-
- Non-Critical
-
- No Non-Critical Alerts 0
- Non-Critical Alerts 8
-
- Critical
-
- No Critical Alerts 0
- Critical Alerts 16
-
- On-Line
-
- State is On-Line 0
- State is Off-Line 32
-
- Transitioning
-
- At intended state 0
- Transitioning to intended state 64
-
-
-
-
-Bergman, et al. Standards Track [Page 20]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- For example, an input (tray) that jammed on the next to the last page
- may show a status of 27 (unavailable because broken (3) + a critical
- state (16), jammed, and a noncritical state (8), low paper).
-
-2.2.13.3. Alert Tables
-
- The Alert Group consists of a single table in which all active alerts
- are represented. This section provides an overview of the table and
- a description of how it is managed. The basic content of the alert
- table is the severity (critical or non-critical) of the alert, the
- Group and entry where a state change caused the alert, additional
- information about the alert (a more detailed location, an alert code,
- and a description), and an indication of the level of training needed
- to service the alert.
-
- The Alert Table contains some information that is redundant, for
- example that an event has occurred, and some information that is only
- represented in the Alert Table, for example the additional
- information. A single table was used because a single entry in a
- group could cause more than one alert, for example paper jams in more
- than one place in a media path. Associating the additional
- information with the entry in the affected group would only allow one
- report where associating the additional information with the alert
- makes multiple reports possible. Every time an alert occurs in the
- printer, the printer makes one or more entries into the Alert Table.
- The printer determines if an event is to be classified as critical or
- non-critical. If the severity of the Alert is "critical", the
- printer sends a trap or event notification to the host indicating
- that the table has changed. Whether or not a trap is sent, the
- management application is expected to poll the printer on a regular
- basis and to read and parse the table to determine what conditions
- have changed, in order to provide reliable information to the
- management application user.
-
-2.2.13.4. Alert Table Management
-
- The alert tables are sparsely populated tables. This means the
- tables will only contain entries of the alerts that are currently
- active and the number of rows, or entries in the table will be
- dynamic. More than one event can be added or removed from the event
- tables at a time depending on the implementation of the printer.
-
- There are basically two kinds of events that produce alerts: binary
- change events and unary change events. Binary change events come in
- pairs: the leading edge event and the trailing edge event. The
- leading edge event enters a state from which there is only one exit;
- for example, going from running to stopped with a paper jam. The
- only exit from this state is fixing the paper jam and it is clear
-
-
-
-Bergman, et al. Standards Track [Page 21]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- when that is accomplished. The trailing edge event exits the state
- that was entered by the leading edge event. In the example above,
- fixing the paper jam is the trailing edge event.
-
- It is relatively straightforward to manage binary change events in
- the Alert Table. Only the leading edge event makes an entry in the
- alert table. This entry persists in the Alert Table until the
- trailing edge event occurs at which point this event is signaled by
- the removal of the leading edge event entry in the Alert Table. That
- is, a trailing edge event does not create an entry; it removes the
- corresponding leading edge event. Removing the leading edge entry
- may cause the unary change event "alertRemovalofBinaryChangeEntry" to
- be added to the table. With binary change events it is possible to
- compute the maximum number that can occur at the same time and
- construct an Alert Table that would hold that many events. There
- would be no possibility of table overflow and no information about
- outstanding events would be lost.
-
- Unfortunately, there are some events that are not binary changes.
- This other category of event, the unary change event, is illustrated
- by the configuration change event. With this kind of event the state
- of the machine has changed, but to a state which is (often) just as
- valid as the state that was left and from which no return is
- necessary. For example, an operator may change the paper that is in
- the primary input source from letter to legal. At some time in the
- future the paper may be changed back to letter, but it might be
- changed to executive instead. This is where the problem occurs. It
- is not obvious how long to keep unary change event entries in the
- Alert Table. If they were never removed, the Alert Table would
- continue to grow indefinitely.
-
- The agent needs to have an algorithm implemented for the management
- of the alert table, especially in the face of combinations of binary
- and unary alerts that would overflow the storage capacity of the
- table. When the table is full and new alerts need to be added, an
- old alert to be deleted should be chosen using the following rules:
-
- 1. Find a non-critical unary alert and delete it. If there are
- multiple non-critical unary alerts, it is suggested that the
- oldest one is chosen. If there are no non-critical unary alerts,
- then,
-
- 2. Find a non-critical binary alert and delete it. If there are
- multiple non-critical binary alerts, it is suggested that the
- oldest one is chosen. If there are no non-critical binary alerts,
- then,
-
-
-
-
-
-Bergman, et al. Standards Track [Page 22]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- 3. Find a critical (binary) alert and delete it. If there are
- multiple critical alerts, it is suggested that the oldest one be
- chosen. Agent implementers are encouraged to provide at least
- enough storage space for the maximum number of critical alerts
- that could occur simultaneously. Note that all critical alerts
- are binary.
-
- In the event that a critical binary alert has been deleted out of the
- alert table; when space allows and the alert condition still exists,
- the alert should be re-added to the alert table even if there was no
- subsequent transition into the associated state. It is recommended
- that this be done for non-critical binary alerts as well. Note that
- the new alert entry will not have the same index as the original
- entry that was moved out of the table.
-
- Note that because the Alert Index is a monotonically increasing
- integer there will be gaps in the values in the table when an alert
- is deleted. The management application may want to re-acquire the
- Printer state and check for state changes that it did not observe in
- the Alert Table if such gaps are detected.
-
-2.3. Read-Write Objects
-
- Some objects in the printer MIB reflect the existence or amount of a
- given resource within the printer. Some examples of such resources
- are the size and number of sheets in a paper tray or the existence of
- certain output options. Some printers have automatic sensors for
- these resources. Most printers lack sensors for every property of
- every resource. The management application is allowed to write into
- objects that hold descriptive or existence values for printers that
- cannot sense these values. The ability to change the value of a
- read- write object may depend on the implementation of the agent.
- Many objects in the MIB are given read-write access, but a printer
- implementation might only permit a management application to change
- the value if the printer can not sense the value itself. Note that
- even though some objects explicitly state the behavior of conditional
- ability to change values, any read-write object may act this way.
-
- Generally, an object is given read-write access in the Printer MIB
- specification if:
-
- 1. The object involves installation of a resource that some printers
- cannot themselves detect. Therefore, external means are needed to
- inform the printer of the installation. (Here external means
- include using the operator console, or remote management
- application) and
-
-
-
-
-
-Bergman, et al. Standards Track [Page 23]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- 2. The printer will behave differently if the installation of the
- resource is reported than the printer would if the installation
- were not reported; that is, the object is not to be used as a
- place to put information not used by the printer, i.e., not a
- "sticky-note". Another way of saying this is that the printer
- believes that information given it and acts as if the information
- were true. For example, on a printer that cannot sense the size,
- if one paper size is loaded, but another size is set into the
- paper size object, then the printer will use the size that was set
- as its current paper size in its imaging and paper handling.
-
- 3. The printer may get hints that it may not know about the existence
- or properties of certain resources. For example, a paper tray may
- be removed and re-inserted. When this removal and insertion
- happens, the printer may either assume that a property, such as
- the size of paper in the tray, has not changed or the printer may
- change the value of the associated object to "unknown", as might
- be done for the amount of paper in the tray. As long as the
- printer acts according to the value in the object either strategy
- is acceptable.
-
- 4. It is an implementation-specific matter as to whether or not MIB
- object values are persistent across power cycles or cold starts.
- It is particularly important that the values of the
- prtMarkerLifeCount object persist throughout the lifetime of the
- printer. Therefore, if the value of any MIB object persists
- across power cycles, then the prtMarkerLifeCount object must also
- persist.
-
-2.4. Enumerations
-
- Enumerations (enums) are sets of symbolic values defined for use with
- one or more objects. Commonly used enumeration sets are assigned a
- symbolic data type name (textual convention), rather than being
- specified in the SYNTAX clause of each individual object definition.
-
- Textual conventions defined in the Printer MIB or the companion IANA
- Printer MIB are extensible by RFC publication or by Designated Expert
- Review (see the 'IANA Considerations' section of this Printer MIB and
- the DESCRIPTION clause in MODULE-IDENTITY of IANA Printer MIB). All
- of these textual conventions are:
-
- a) used more than once in the Printer MIB itself; or
-
- b) imported and used in the companion Finisher MIB; or
-
- c) imported and used in any other, including vendor private, MIB
- modules.
-
-
-
-Bergman, et al. Standards Track [Page 24]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- The Printer MIB has also defined the following special values for use
- with objects of the syntax "Integer32" to define conditions that are
- outside of the normal numeric range: other(-1), unknown(-2), and
- partial(-3). The 'partial' value means that there is some supply
- remaining (but the amount is indeterminate) or there is some capacity
- remaining (but the amount is indeterminate). The Integer32 range
- field indicates in which objects these special values are valid.
-
-2.4.1. Registering Additional Enumerated Values
-
- The Printer MIB and the companion IANA Printer MIB each defines one
- category of textual convention, according to the process employed to
- control the addition of new enumerations:
-
- Type 1 - All of the legal values are defined in the Printer MIB.
- Additional enumerated values require the publication of a new Printer
- MIB.
-
- Type 2 - All of the legal values are registered in the IANA Printer
- MIB. Additional enumerated values require a Designated Expert Review
- defined in "Guidelines for Writing an IANA Considerations Section in
- RFCs" [RFC2434]. The Designated Expert will be selected by the IETF
- Area Director(s) of the Applications Area.
-
-3. Groups from other MIB Specifications
-
- This section identifies the groups from other MIBs that shall be
- supported to supplement and complete a printer MIB implementation.
- The section also describes some of the less obvious characteristics
- of the Printer MIB structure that are related to the inclusion of
- these other MIB groups.
-
-3.1. System Group
-
- All objects in the system group of MIB-II [RFC1213] shall be
- implemented; however, as described in paragraph 2.4, implementers
- should carefully consider what constitutes the "system".
-
-3.2. System Controller
-
- The storage and device groups of the Host Resources MIB [RFC2790]
- shall be implemented to support the printer(s) system controller, and
- any supporting devices. If deemed appropriate by the implementer,
- other groups of the Host Resources MIB (System, Running Software,
- Running Software Performance, and Installed Software) may be
- implemented. Because of the structure of the Host Resources MIB, the
- devices constituting the system controller are at the same level as
- the printer.
-
-
-
-Bergman, et al. Standards Track [Page 25]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-3.3. Interface Group objects
-
- All objects in the Interfaces Group of MIB-II [RFC1213] shall be
- implemented for all print information interfaces to the printer,
- including non-network interfaces.
-
-3.3.1. Interface Types
-
- The interfaces group of RFC 1213 [RFC1213] contains only a partial
- list of interface types that can be specified in the "ifType" object.
- For a complete list of interface types, refer to the IANA registry at
- "ftp://ftp.isi.edu/mib/iana.mib/ianaiftype.mib"
-
-4. Differences from RFC 1759
-
- This document supersedes and replaces RFC 1759. However, a compliant
- implementation of RFC 1759 is also compliant with this document. The
- following changes to RFC 1759 are included: (See the printmib
- REVISION/DESCRIPTION clause for additional details of changes.)
-
- - Minor editorial corrections and changes. Updated the cover page
- and added the "SNMP Management Framework" boilerplate to section
- 1.
-
- - Updated figure 2 to use MIB names instead of RFC numbers.
-
- - Updated Coded Character Set description and IANA registration
- process.
-
- - Change hrPrinterDetectedErrorState "coverOpen" (bit 4) to
- "doorOpen" per RFC 2790.
-
- - Added second octet of hrPrinterDetectedErrorState as partially
- described and assigned in the updated Host Resources MIB (RFC
- 2790).
-
- - Remove fixed association of hrDeviceStatus (warning/down) from
- hrPrinterDetetctedErrorState per RFC 2790.
-
- - Instead of showing bit 15 as "not assigned" in the quote from RFC
- 2790 in the hrPrinterDetectedErrorState object, removed that from
- the tabular form and added it as a sentence, because the RFC
- doesn't show bit 15 in the tabular form.
-
- - Clarified the international considerations.
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 26]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- - Added prtChannelInformation to the Channel Group textual-
- conventions on a per channel basis to clarify the channel
- description and enhance interoperability.
-
- - Deprecated some obsolete channel types.
-
- - Extended the Alert Table and PrtMarkerSuppliesSupplyUnit textual
- conventions to include values from the Finisher MIB.
-
- - Clarified alerts based on unary vs. binary change events.
-
- - Added (optional) unary change event
- alertRemovalOfBinaryChangeEntry(1801).
-
- - Establish a convention for contact information for
- prtGeneralCurrentOperator and prtGeneralServicePerson.
-
- - Added prtAuxiliarySheetStartupPage PresentOnOff
-
- - Added prtAuxiliarySheetBannerPage PresentOnOff
-
- - Added prtGeneralPrinterName OCTET STRING
-
- - Added prtGeneralSerialNumber OCTET STRING
-
- - Added prtInputNextIndex Integer32
-
- - Added the Input Switching Group
-
- - Added prtAlertCriticalEvents Counter32
-
- - Added prtAlertAllEvents Counter32
-
- - Updated PrtAlertCode enums including generic alert codes.
-
- - Created five OBJECT-GROUPs (prtAuxilliarySheetGroup,
- prtInputSwitchingGroup, prtGeneralV2Group, prtAlertTableV2Group,
- prtChannelV2Group). Added the nine new objects to them
- (prtAuxiliarySheetStartupPage, prtAuxiliarySheetBannerPage,
- prtGeneralPrinterName, prtGeneralSerialNumber,
- prtAlertCriticalEvents, prtAlertAllEvents,
- prtInputMediaLoadTimeout, prtInputNextIndex,
- prtChannelInformation). Created one new NOTIFICATION-GROUP
- (prtAlertTrapGroup) to contain printerV2Alert. Included the new
- OBJECT-GROUPs and the NOTIFICATION_GROUP in prtMIBCompliance, all
- in GROUP (not MANDATORY-GROUP) clauses. The nine new objects are
- optional, i.e., this document is backward compatible with RFC
- 1759.
-
-
-
-Bergman, et al. Standards Track [Page 27]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- - prtAlertTime is strongly recommended.
-
- - Deprecated the use of alert codes doorOpen(501) and
- doorClosed(502), in favor of coverOpened(3) and coverClosed(4).
-
- - Added the PrtConsoleDisableTC and PrtMarkerAddressabilityUnitTC
- textual conventions, and changed the PrtConsoleDisable and
- PrtMarkerAddressabilityUnit objects' syntax to use those TCs, and
- changed the PrtGeneralEntry and PrtMarkerColorantEntry SEQUENCEs
- to reflect the new syntax.
-
- - Added textual conventions "PrtLocalizedDescriptionStringTC" and
- "PrtConsoleDescriptionStringTC" and updated several objects to use
- them.
-
- - Changed most enumerations to textual conventions and therefore
- changed the SYNTAX of many objects from RFC 1759 to specify the
- appropriate textual conventions. (28 TCs were added.)
-
- - Changed the TC names "MediaUnit" to "PrtMediaUnitTC",
- "CapacityUnit" to "PrtCapacityUnitTC", and "SubUnitStatus" to
- "PrtSubUnitStatusTC"
-
- - All objects with a MAX-ACCESS of read-write now have a MIN-ACCESS
- of read-only.
-
- - Added 'IANA Considerations' and 'Internationalization
- Considerations' as top level sections, per IETF guidelines.
-
- - Updated Security and Copyright sections.
-
- - Updated references and split into Normative and Informative
- groups.
-
- - Added Appendix E - Overall Printer Status Table.
-
- - Updated participant and contact information.
-
- - Removed CodedCharSet Textual Convention, replaced with an import
- of the IANACharset.
-
- - Removed all comment statements that indicated objects or groups
- are mandatory or optional. Avoids any potential conflicts with
- the conformance section.
-
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 28]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- - Added text to empty description clauses. (prtStorageRefTable,
- prtDeviceRefTable, prtMarkerTable, prtMediaPathTable,
- prtChannelTable, prtInterpreterTable, prtConsoleLightTable, and
- prtAlertTable)
-
- - Added "DEFVAL { unknown }" to prtInterpreterDefaultCharSetIn and
- prtInterpreterDefaultCharSetOut.
-
- - Changed "...values are expected to remain stable..." to "...values
- SHOULD remain stable..." in the description clauses for the index
- object in all tables.
-
- - Added ranges to all objects with a syntax of Integer32.
-
- - Revised the description clause for prtAlertGroupIndex.
-
- - Added additional text to the description clause for
- prtMediaPathEntry, prtChannelEntry, prtInterpreterEntry, and
- printerV2Alert.
-
- - Added text to section 2.4 to explain the usage of textual
- conventions in this MIB and others. Also added a note defining
- the common usage of the enumerations 'other(-1)' and 'unknown(-2)'
-
- - Changed range of prtStorageRefSeqNumber, prtDeviceRefSeqNumber,
- and prtConsoleLightIndex from (0..65535) to (1..65535) since index
- values cannot be zero. (Typo in RFC 1759)
-
- - The PWG Standard for Standardized Media Names is now recommended
- for the objects prtInputMediaName, prtInputMediaColor, and
- prtInputMediaType.
-
- - Added chSMTP(45) to prtChannelTypeTC.
-
-5. The IANA Printer MIB
-
-IANA-PRINTER-MIB DEFINITIONS ::= BEGIN
- -- http://www.iana.org/assignments/ianaprinter-mib
-
-IMPORTS
- MODULE-IDENTITY,
- mib-2
- FROM SNMPv2-SMI -- [RFC2578]
- TEXTUAL-CONVENTION
- FROM SNMPv2-TC; -- [RFC2579]
-
-ianaPrinterMIB MODULE-IDENTITY
- LAST-UPDATED "200406020000Z" -- June 2, 2004
-
-
-
-Bergman, et al. Standards Track [Page 29]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- ORGANIZATION "IANA"
- CONTACT-INFO "Internet Assigned Numbers Authority
- Postal: ICANN
- 4676 Admiralty Way, Suite 330
- Marina del Rey, CA 90292
-
- Tel: +1 310 823 9358
- E-Mail: iana@iana.org"
-
- DESCRIPTION "This MIB module defines a set of printing-related
- TEXTUAL-CONVENTIONs for use in Printer MIB (RFC 3805),
- Finisher MIB (RFC 3806), and other MIBs which need to
- specify printing mechanism details.
-
- Any additions or changes to the contents of this MIB
- module require either publication of an RFC, or
- Designated Expert Review as defined in RFC 2434,
- Guidelines for Writing an IANA Considerations Section
- in RFCs. The Designated Expert will be selected by
- the IESG Area Director(s) of the Applications Area.
-
- Copyright (C) The Internet Society (2004). The
- initial version of this MIB module was published
- in RFC 3805. For full legal notices see the RFC
- itself or see:
- http://www.ietf.org/copyrights/ianamib.html"
-
- REVISION "200406020000Z" -- June 2, 2004
- DESCRIPTION "Original version, published in coordination
- with Printer MIB (RFC 3805)."
- ::= { mib-2 109 }
-
---
--- Generic TEXTUAL-CONVENTIONs
---
-
-PrtCoverStatusTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtCoverStatus in RFC 1759.
- STATUS current
- DESCRIPTION
- "Values for encoding the state of a particular cover or
- access panel on the printer case or enclosure."
- SYNTAX INTEGER {
- other(1),
- coverOpen(3),
- coverClosed(4),
- interlockOpen(5),
- interlockClosed(6)
-
-
-
-Bergman, et al. Standards Track [Page 30]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- }
-
---
--- General Group TEXTUAL-CONVENTIONs
---
-
-PrtGeneralResetTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtGeneralReset in RFC 1759.
- STATUS current
- DESCRIPTION
- "Values for reading and writing the prtGeneralReset object.
-
- If a device does not have NVRAM, the device shall none the
- less respond to a SET with the value resetToNVRAM(5) with a
- sort of warm reset that resets the device to implementation-
- defined state that is preferably under control of the system
- administrator by some means outside the scope of the Printer
- MIB specification."
-
- SYNTAX INTEGER {
- notResetting(3),
- powerCycleReset(4), -- Cold Start
- resetToNVRAM(5), -- Warm Start
- resetToFactoryDefaults(6) -- Reset contents of
- -- NVRAM to factory
- -- defaults
- }
---
--- Channel Group TEXTUAL-CONVENTIONs
---
-
-PrtChannelTypeTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtChannelType in RFC 1759.
- STATUS current
- DESCRIPTION
- "This enumeration indicates the type of channel that is
- receiving jobs."
- SYNTAX INTEGER {
- other(1),
- chSerialPort(3),
- chParallelPort(4),
- chIEEE1284Port(5),
- chSCSIPort(6),
- chAppleTalkPAP(7),
- -- AppleTalk Printer
- -- Access Protocol (PAP)
- --
- -- prtChannelInformation entry:
-
-
-
-Bergman, et al. Standards Track [Page 31]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- --
- -- Printer Name
- -- Keyword: Name
- -- Syntax: Name
- -- Status: Optional
- -- Multiplicity: Single
- -- Description: The name of the printer
- -- within the AppleTalk naming scope
- chLPDServer(8),
- -- prtChannelInformation entry:
- --
- -- Printer queue name
- -- Keyword: Queue
- -- Syntax: Name
- -- Status: Mandatory
- -- Multiplicity: Single
- -- Description: queue name as
- -- defined in [RFC1179].
- chNetwareRPrinter(9),
- -- Novell, Inc.
- -- For each entry of this type, the
- -- prtChannelInformation must have a pair of
- -- keywords. For Netware 3.x channels this must
- -- be a (PServer, Printer) pair. For Netware
- -- 4.x channels and for IntranetWare channels
- -- this must be a (NDSTree, NDSPrinter) pair.
- --
- -- prtChannelInformation entries:
-
- -- Print Server Name
- -- Keyword: PServer
- -- Syntax: Name
- -- Status: Mandatory
- -- Multiplicity: Single
- -- Description: The Pserver's SAP name
- --
- -- Printer Number
- -- Keyword: Printer
- -- Syntax: Integer
- -- Status: Mandatory
- -- Multiplicity: Single
- -- Description: The printer number
- --
- -- NDSTree
- -- Keyword: NDSTree
- -- Syntax: Name
- -- Multiplicity: Single
- -- Description: The tree's SAP name
-
-
-
-Bergman, et al. Standards Track [Page 32]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- --
- -- NDS Printer object
- -- Keyword: NDSPrinter
- -- Syntax: Text (Unicode)
- -- Status: Mandatory
- -- Multiplicity: Single
- -- Description: The fully qualified
- -- name of the Printer
- --
- -- In the Netware 3.x environment, the
- -- client checks the Bindery object
- -- representing the named PServer. The
- -- client then checks for queues which
- -- are associated with the numbered
- -- printer. In the 4.x and IntraNetware
- -- environment, the client looks up the
- -- queues which are associated with the
- -- NDS Printer Object in the named Tree.
- -- Depending on client access rights to
- -- those queues, the client submits jobs
- -- to the appropriate queue.
- chNetwarePServer(10),
- -- Novell,Inc.
- -- For each entry of this type, the
- -- prtChannelInformation must have a pair
- -- of keywords. For Netware 3.x channels
- -- this must be a (Server, PServer) pair.
- -- For Netware 4.x and IntranetWare
- -- channels, this must be a
- -- (NDSTree, NDSPServer) pair.
- --
- -- prtChannelInformation entries:
- --
- -- Server Name
- -- Keyword: Server
- -- Syntax: Name
- -- Status: Mandatory
- -- Multiplicity: Single
- -- Description: The SAP name of the
- -- server for which the PServer is defined.
- --
- -- PServer
- -- Keyword: PServer
- -- Syntax: Name
- -- Status: Mandatory
- -- Multiplicity: Single
- -- Description: The bindery name of
- -- the PServer
-
-
-
-Bergman, et al. Standards Track [Page 33]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- --
- -- NDS Tree
- -- Keyword: NDSTree
- -- Syntax: Name
- -- Status: Mandatory
- -- Multiplicity: Single
- -- Description: The NDS Tree name
- --
- -- PServer
- -- Keyword: NDSPServer
- -- Syntax: Text (Unicode)
- -- Status: Mandatory
- -- Multiplicity: Single
- -- Description: The fully qualified
- -- name of the PServer object in the tree.
- --
- -- In the 3.x environment, the client
- -- checks the bindery object
- -- representing the named PServer on the
- -- named Server. In the 4.x and
- -- IntranetWare environment,
- -- the client checks the NDS object
- -- representing the named PServer in the
- -- named Tree. In either case, the
- -- client then checks for all queues
- -- associated with the Pserver object.
- -- Depending on client access rights
- -- to those queues, the client submits
- -- jobs to the appropriate queue.
- chPort9100(11),
- -- DEPRECATED
- -- (see chPortTCP - 37; chBidirPortTCP - 38)
- chAppSocket(12),
- -- A bi-directional, LPD-like, protocol using
- -- 9101 for control and 9100 for data.
- -- Adobe Systems, Inc.
- chFTP(13), -- [RFC959]
- chTFTP(14), -- [RFC1350]
- chDLCLLCPort(15),
- chIBM3270(16), -- IBM Coax
- chIBM5250(17), -- IBM Twinax
- chFax(18),
- chIEEE1394(19),
- chTransport1(20),
- -- TCP port 35, for reserved TCP port list see
- -- [RFC3232]. This RFC should also be
- -- referenced for other channel
- -- enumerations utilizing TCP port
-
-
-
-Bergman, et al. Standards Track [Page 34]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- -- numbers 0 through 1024.
- chCPAP(21), -- TCP port 170
- -- Digital Equipment Corp.
- chDCERemoteProcCall(22), -- OSF
- -- DEPRECATED
- chONCRemoteProcCall(23), -- SUN Microsystems
- -- DEPRECATED
- chOLE(24), -- Microsoft
- -- DEPRECATED
- chNamedPipe(25),
- chPCPrint(26), -- Banyan
- chServerMessageBlock(27),
- -- File/Print sharing protocol used by
- -- various network operating systems
- -- from IBM 3Com, Microsoft and others
- --
- -- prtChannelInformation entry:
- --
- -- Service Name
- -- Keyword: Name
- -- Syntax: Name
- -- Status: Optional
- -- Multiplicity: Single
- -- Description: The service name of
- -- the printer
- chDPMF(28), -- IBM Infoprint
- chDLLAPI(29), -- Microsoft
- -- DEPRECATED
- chVxDAPI(30), -- Microsoft
- -- DEPRECATED
- chSystemObjectManager(31), -- IBM
- chDECLAT(32),
- -- Digital Equipment Corp.
- --
- -- prtChannelInformation entries:
- --
- -- Port Name
- -- Keyword: Port
- -- Syntax: Name
- -- Status: Conditionally
- -- Mandatory
- -- (see note below)
- -- Multiplicity: Single
- -- Description: LAT port name
- --
- -- Service Name
- -- Keyword: Service
- -- Syntax: Name
-
-
-
-Bergman, et al. Standards Track [Page 35]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- -- Status: Conditionally
- -- Mandatory
- -- Multiplicity: Single
- -- Description: LAT service name
- --
- -- The LAT channel may be
- -- identified by either a port or
- -- service, so either a
- -- Port or Service entry must be
- -- specified, but not both.
- chNPAP(33),
- chUSB(34), -- Not in RFC 1759
- -- Universal Serial Bus
- chIRDA(35), -- Not in RFC 1759
- -- Infrared Data Assoc. Prot.
- chPrintXChange(36), -- Not in RFC 1759
- -- PrintXChange Protocol
- chPortTCP(37), -- Not in RFC 1759
- -- A unidirectional "raw" TCP
- -- channel that uses an administratively
- -- assigned TCP port address.
- --
- -- prtChannelInformation entry:
- --
- -- Port Number
- -- Keyword: Port
- -- Syntax: decimal number
- -- Status: Mandatory
- -- Multiplicity: Single
- -- Description: TCP port number
- chBidirPortTCP(38), -- Not in RFC 1759
- -- A bi-directional version of chPortTCP
- --
- -- prtChannelInformation entries:
- -- (See chPortTCP)
- chUNPP(39), -- Not in RFC 1759
- -- Universal Network Printing
- -- Protocol(UNPP). A bi-directional,
- -- multiport network printing
- -- application protocol available on
- -- multiple transport protocols.
- -- Underscore, Inc.
- -- Contact: info@underscore.com
- chAppleTalkADSP(40), -- Not in RFC 1759
- -- AppleTalk Data Stream Protocol.
- -- ADSP is part of the AppleTalk
- -- suite of protocols.
- -- It is a symmetric, connection-
-
-
-
-Bergman, et al. Standards Track [Page 36]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- -- oriented protocol that makes
- -- possible the establishment
- -- and maintenance of full-duplex
- -- streams of data bytes between
- -- two sockets in an AppleTalk
- -- internet.
- -- See [APPLEMAC].
- chPortSPX(41), -- Not in RFC 1759
- -- Sequenced Packet Exchange (SPX)
- -- socket.
- -- Novell, Inc. Similar to TCP, a
- -- bi-directional data pipe using
- -- Novell SPX as a transport.
- --
- -- prtChannelInformation entries:
- --
- -- Network Number
- -- Keyword: Net
- -- Syntax: HexString
- -- Status: Mandatory
- -- Multiplicity: Single
- -- Description: The network number
- --
- -- Node Number
- -- Keyword: Node
- -- Syntax: HexString
- -- Status: Mandatory
- -- Multiplicity: Single
- -- Description: The node number
- --
- -- Socket Number
- -- Keyword: Socket
- -- Syntax: HexString
- -- Status: Mandatory
- -- Multiplicity: Single
- -- Description: The SPX socket number
- --
- -- There must be exactly one "Net" and
- -- one "Node" and one "Socket" entry. A
- -- HexString is a binary value
- -- represented as a string of
- -- ASCII characters using hexadecimal
- -- notation.
- chPortHTTP(42), -- Not in RFC 1759
- -- Hypertext Transfer Protocol. See [RFC1945]
- -- and [RFC2616].
- chNDPS(43), -- Not in RFC 1759
- -- Novell, Inc.
-
-
-
-Bergman, et al. Standards Track [Page 37]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- --
- -- prtChannelInformation entry:
- --
- -- Printer Agent Name
- -- Keyword: PA
- -- Syntax: Name
- -- Status: Mandatory
- -- Multiplicity: Single
- -- Description: The NDPS Printer
- -- Agent Name
- chIPP(44), -- Not in RFC 1759
- -- Internet Printing Protocol (IPP),
- -- (IPP/1.1 - see [RFC2910] and [RFC2911])
- -- also applies to all future versions of IPP.
- --
- -- IPP Printer URI
- -- Keyword: URI
- -- Syntax: URI (Unicode UTF-8 per
- -- [RFC2396])
- -- Status: Mandatory
- -- Multiplicity: Single
- -- Default: not applicable
- -- Description: URI of this IPP Printer
- -- within Internet naming scope. Unicode
- -- UTF-8 [RFC3629] string with
- -- hexadecimal escapes for any non-ASCII
- -- characters (per [RFC2396]).
- -- Conformance: An IPP Printer shall list all
- -- IPP URI it supports (one per IPP Channel
- -- entry). If a URI contains the 'http:'
- -- scheme it must have an explicit port.
- -- See: [RFC3629], [RFC2396], [RFC2910],
- -- [RFC2911].
- --
- -- IPP Printer Client Authentication
- -- Keyword: Auth
- -- Syntax: Keyword
- -- Status: Optional
- -- Multiplicity: Single
- -- Default: 'none'
- -- Description: A client authentication
- -- mechanism supported for this IPP Printer
- -- URI:
- -- 'none'
- -- no client authentication mechanism
- -- 'requesting-user-name'
- -- authenticated user in 'requesting-
- -- user-name'
-
-
-
-Bergman, et al. Standards Track [Page 38]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- -- 'basic'
- -- authenticated user via HTTP Basic
- -- mechanism
- -- 'digest'
- -- authenticated user via HTTP Digest
- -- mechanism
- -- 'certificate'
- -- authenticated user via certificate
- -- mechanism
- -- Conformance: An IPP Printer should list
- -- all IPP client authentication mechanisms
- -- it supports (one per IPP Channel entry).
- -- See: [RFC2911] and [RFC2910].
- --
- -- IPP Printer Security
- -- Keyword: Security
- -- Syntax: Keyword
- -- Status: Optional
- -- Multiplicity: Single
- -- Default: 'none'
- -- Description: A security mechanism
- -- supported for this IPP Printer URI:
- -- 'none'
- -- no security mechanism
- -- 'ssl3'
- -- SSL3 secure communications channel
- -- protocol
- -- 'tls'
- -- TLS secure communications channel
- -- protocol
- -- Conformance: An IPP Printer should list
- -- all IPP security mechanisms it supports
- -- (one per IPP Channel entry).
- -- See: [RFC2246], [RFC2911].
- --
- -- IPP Printer Protocol Version
- -- Keyword: Version
- -- Syntax: Keyword
- -- Status: Optional
- -- Multiplicity: Multiple
- -- Default: '1.1'
- -- Description: All of the IPP protocol
- -- versions (major.minor) supported for
- -- this IPP Printer URI:
- -- '1.0'
- -- IPP/1.0 conforming Printer
- -- '1.1'
- -- IPP/1.1 conforming Printer
-
-
-
-Bergman, et al. Standards Track [Page 39]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- -- Conformance: An IPP Printer should list
- -- all IPP versions it supports (all listed
- -- in each IPP Channel entry). An IPP
- -- Client should select the highest
- -- numbered version the IPP Client supports
- -- for use in all IPP Requests (for optimum
- -- interworking).
- -- See: [RFC2911].
- chSMTP(45)
- -- Print Job submission via Simple Mail
- -- Transfer Protocol (SMTP) - see [RFC2821]
- --
- -- prtChannelInformation entry:
- --
- -- Keyword: Mailto
- -- Syntax: Name
- -- Status: Mandatory
- -- Multiplicity: Single
- -- Default: not applicable
- -- Description: The SMTP URL of the printer.
-}
-
---
--- Interpreter Group TEXTUAL-CONVENTIONs
---
-
-PrtInterpreterLangFamilyTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtInterpreterLangFamily in RFC 1759.
- STATUS current
- DESCRIPTION
- "This enumeration indicates the type of interpreter that is
- receiving jobs."
- SYNTAX INTEGER {
- other(1),
- unknown(2), -- Not in RFC 1759
- langPCL(3), -- PCL. Starting with PCL version 5,
- -- HP-GL/2 is included as part of the
- -- PCL language.
- -- PCL and HP-GL/2 are registered
- -- trademarks of Hewlett-Packard
- -- Company.
- langHPGL(4), -- Hewlett-Packard Graphics Language.
- -- HP-GL is a registered trademark of
- -- Hewlett-Packard Company.
- langPJL(5), -- Peripheral Job Language. Appears in
- -- the data stream between data intended
- -- for a page description language.
- -- Hewlett-Packard Co.
-
-
-
-Bergman, et al. Standards Track [Page 40]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- langPS(6), -- PostScript (tm) Language
- -- Postscript - a trademark of Adobe
- -- Systems Incorporated which may be
- -- registered in certain jurisdictions
- langIPDS(7), -- Intelligent Printer Data Stream
- -- Bi-directional print data stream for
- -- documents consisting of data objects
- -- (text, image, graphics, bar codes),
- -- resources (fonts, overlays) and page,
- -- form and finishing instructions.
- -- Facilitates system level device
- -- control, document tracking and error
- -- recovery throughout the print
- -- process.
- -- IBM Corporation.
- langPPDS(8), -- IBM Personal Printer Data Stream.
- -- Originally called IBM ASCII, the name
- -- was changed to PPDS when the Laser
- -- Printer was introduced in 1989.
- -- Lexmark International, Inc.
- langEscapeP(9), -- Epson Corp.
- langEpson(10),
- langDDIF(11), -- Digital Document Interchange Format
- -- Digital Equipment Corp., Maynard MA
- langInterpress(12),
- -- Xerox Corp.
- langISO6429(13), -- ISO 6429. Control functions for
- -- Coded Character Sets (has ASCII
- -- control characters, plus additional
- -- controls for
- -- character imaging devices.)
- langLineData(14), -- line-data: Lines of data as
- -- separate ASCII or EBCDIC records
- -- and containing no control functions
- -- (no CR, LF, HT, FF, etc.)
- -- For use with traditional line
- -- printers. May use CR and/or LF to
- -- delimit lines, instead of records.
- -- See ISO 10175 Document Printing
- -- Application (DPA) [ISO10175].
- langMODCA(15), -- Mixed Object Document Content
- -- Architecture
- -- Definitions that allow the
- -- composition, interchange, and
- -- presentation of final form
- -- documents as a collection of data
- -- objects (text, image, graphics, bar
- -- codes), resources (fonts, overlays)
-
-
-
-Bergman, et al. Standards Track [Page 41]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- -- and page, form and finishing
- -- instructions.
- -- IBM Corporation.
- langREGIS(16), -- Remote Graphics Instruction Set,
- -- Digital Equipment Corp., Maynard MA
- langSCS(17), -- SNA Character String
- -- Bi-directional print data stream for
- -- SNA LU-1 mode of communication.
- -- IBM
- langSPDL(18), -- ISO 10180 Standard Page Description
- -- Language
- -- ISO Standard
- langTEK4014(19), -- Tektronix Corp.
- langPDS(20),
- langIGP(21), -- Printronix Corp.
- langCodeV(22), -- Magnum Code-V, Image and printer
- -- control language used to control
- -- impact/dot-matrix printers.
- -- QMS, Inc., Mobile AL
- langDSCDSE(23), -- DSC-DSE: Data Stream Compatible and
- -- Emulation Bi-directional print data
- -- stream for non-SNA (DSC) and SNA LU-3
- -- 3270 controller (DSE) communications
- -- IBM
- langWPS(24), -- Windows Printing System, Resource
- -- based command/data stream used by
- -- Microsoft At Work Peripherals.
- -- Developed by the Microsoft
- -- Corporation.
- langLN03(25), -- Early DEC-PPL3, Digital Equipment
- -- Corp.
- langCCITT(26),
- langQUIC(27), -- QUIC (Quality Information Code), Page
- -- Description Language for laser
- -- printers. Included graphics, printer
- -- control capability and emulation of
- -- other well-known printer.
- -- QMS, Inc.
- langCPAP(28), -- Common Printer Access Protocol
- -- Digital Equipment Corp.
- langDecPPL(29), -- Digital ANSI-Compliant Printing
- -- Protocol
- -- (DEC-PPL)
- -- Digital Equipment Corp.
- langSimpleText(30),
- -- simple-text: character coded data,
- -- including NUL, CR , LF, HT, and FF
- -- control characters. See ISO 10175
-
-
-
-Bergman, et al. Standards Track [Page 42]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- -- Document Printing Application (DPA)
- -- [ISO10175].
- langNPAP(31), -- Network Printer Alliance Protocol
- -- (NPAP). This protocol has been
- -- superseded by the IEEE 1284.1 TIPSI
- -- Std (ref. LangTIPSI(49)).
- langDOC(32), -- Document Option Commands, Appears in
- -- the data stream between data
- -- intended for a page description.
- -- QMS, Inc.
- langimPress(33), -- imPRESS, Page description language
- -- originally developed for the
- -- ImageServer product line. A binary
- -- language providing representations
- -- of text, simple graphics, and some
- -- large forms (simple
- -- bit-map and CCITT group 3/4
- -- encoded).The
- -- language was intended to be sent over
- -- an 8-bit channel and supported early
- -- document preparation languages (e.g.,
- -- TeX and TROFF).
- -- QMS, Inc.
- langPinwriter(34),
- -- 24 wire dot matrix printer for
- -- USA, Europe, and Asia except
- -- Japan.
- -- More widely used in Germany, and
- -- some Asian countries than in US.
- -- NEC
- langNPDL(35), -- Page printer for Japanese market.
- -- NEC
- langNEC201PL(36), -- Serial printer language used in
- -- the Japanese market.
- -- NEC
- langAutomatic(37),
- -- Automatic PDL sensing. Automatic
- -- sensing of the interpreter
- -- language family by the printer
- -- examining the document content.
- -- Which actual interpreter language
- -- families are sensed depends on
- -- the printer implementation.
- langPages(38), -- Page printer Advanced Graphic
- -- Escape Set
- -- IBM Japan
- langLIPS(39), -- LBP Image Processing System
- langTIFF(40), -- Tagged Image File Format (Aldus)
-
-
-
-Bergman, et al. Standards Track [Page 43]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- langDiagnostic(41),
- -- A hex dump of the input to the
- -- interpreter
- langPSPrinter(42),
- -- The PostScript Language used for
- -- control (with any PDLs)
- -- Adobe Systems Incorporated
- langCaPSL(43), -- Canon Print Systems Language
- langEXCL(44), -- Extended Command Language
- -- Talaris Systems Inc.
- langLCDS(45), -- Line Conditioned Data Stream
- -- Xerox Corporation
- langXES(46), -- Xerox Escape Sequences
- -- Xerox Corporation
- langPCLXL(47), -- Not in RFC 1759
- -- Printer Control Language. Extended
- -- language features for printing, and
- -- printer control.
- -- Hewlett-Packard Co.
- langART(48), -- Not in RFC 1759
- -- Advanced Rendering Tools (ART).
- -- Page Description language
- -- originally developed for the Laser
- -- Press printers.
- -- Technical reference manual: "ART IV
- -- Reference Manual", No F33M.
- -- Fuji Xerox Co., Ltd.
- langTIPSI(49), -- Not in RFC 1759
- -- Transport Independent Printer
- -- System Interface (ref. IEEE Std.
- -- 1284.1)
- langPrescribe(50), -- Not in RFC 1759
- -- Page description and printer
- -- control language. It can be
- -- described with ordinary ASCII
- -- Technical reference manual:
- -- "PRESCRIBE II Programming Manual"
- langLinePrinter(51), -- Not in RFC 1759
- -- A simple-text character stream which
- -- supports the control codes LF, VT,
- -- FF, and plus Centronics or
- -- Dataproducts Vertical Format Unit
- -- (VFU) language is commonly used on
- -- many older model line and matrix
- -- printers.
- langIDP(52), -- Not in RFC 1759
- -- Imaging Device Protocol
- -- Apple Computer.
-
-
-
-Bergman, et al. Standards Track [Page 44]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- langXJCL(53), -- Not in RFC 1759
- -- Xerox Job Control Language (JCL).
- -- A Job Control language originally
- -- developed for the LaserPress printers
- -- and is capable of switching PDLs.
- -- Technical reference manual:
- -- "ART IV Reference Manual", No F33M.
- -- Fuji Xerox Co., Ltd.
- langPDF(54), -- Not in RFC 1759
- -- Adobe Portable Document Format
- -- Adobe Systems, Inc.
- langRPDL(55), -- Not in RFC 1759
- -- Ricoh Page Description Language for
- -- printers.
- -- Technical manual "RPDL command
- -- reference" No.307029
- -- RICOH, Co. LTD
- langIntermecIPL(56), -- Not in RFC 1759
- -- Intermec Printer Language for label
- -- printers.
- -- Technical Manual: "IPL Programmers
- -- Reference Manual"
- -- Intermec Corporation
- langUBIFingerprint(57), -- Not in RFC 1759
- -- An intelligent basic-like programming
- -- language for label printers.
- -- Reference Manual: "UBI Fingerprint
- -- 7.1", No. 1-960434-00
- -- United Barcode Industries
- langUBIDirectProtocol(58), -- Not in RFC 1759
- -- An intelligent control language for
- -- label printers.
- -- Programmers guide: " UBI Direct
- -- Protocol", No. 1-960419-00
- -- United Barcode Industries
- langFujitsu(59), -- Not in RFC 1759
- -- Fujitsu Printer Language
- -- Reference Manual:
- -- "FM Printer Sequence" No. 80HP-0770
- -- FUJITSU LIMITED
- langCGM(60), -- Not in RFC 1759
- -- Computer Graphics Metafile
- -- MIME type 'image/cgm'
- langJPEG(61), -- Not in RFC 1759
- -- Joint Photographic Experts Group
- -- MIME type 'image/jpeg'
- langCALS1(62), -- Not in RFC 1759
- -- US DOD CALS1 (see MIL-STD-1840)
-
-
-
-Bergman, et al. Standards Track [Page 45]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- -- MIME type 'application/cals-1840'
- langCALS2(63), -- Not in RFC 1759
- -- US DOD CALS2 (see MIL-STD-1840)
- -- MIME type 'application/cals-1840'
- langNIRS(64), -- Not in RFC 1759
- -- US DOD NIRS (see MIL-STD-1840)
- -- MIME type 'application/cals-1840'
- langC4(65) -- Not in RFC 1759
- -- US DOD C4 (see MIL-STD-1840)
- -- MIME type 'application/cals-1840'
-}
-
---
--- Input/Output Group TEXTUAL-CONVENTIONs
---
-
-PrtInputTypeTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtInputType in RFC 1759.
- STATUS current
- DESCRIPTION
- "The type of technology (discriminated primarily according to
- feeder mechanism type) employed by a specific component or
- components."
- SYNTAX INTEGER {
- other(1),
- unknown(2),
- sheetFeedAutoRemovableTray(3),
- sheetFeedAutoNonRemovableTray(4),
- sheetFeedManual(5),
- continuousRoll(6),
- continuousFanFold(7)
- }
-
-PrtOutputTypeTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtOutputType in RFC 1759.
- STATUS current
- DESCRIPTION
- "The Type of technology supported by this output subunit."
- SYNTAX INTEGER {
- other(1),
- unknown(2),
- removableBin(3),
- unRemovableBin(4),
- continuousRollDevice(5),
- mailBox(6),
- continuousFanFold(7)
- }
-
-
-
-
-Bergman, et al. Standards Track [Page 46]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
---
--- Marker Group TEXTUAL-CONVENTIONs
---
-
-PrtMarkerMarkTechTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtMarkerMarkTech in RFC 1759.
- STATUS current
- DESCRIPTION
- "The type of marking technology used for this marking
- subunit."
- SYNTAX INTEGER {
- other(1),
- unknown(2),
- electrophotographicLED(3),
- electrophotographicLaser(4),
- electrophotographicOther(5),
- impactMovingHeadDotMatrix9pin(6),
- impactMovingHeadDotMatrix24pin(7),
- impactMovingHeadDotMatrixOther(8),
- impactMovingHeadFullyFormed(9),
- impactBand(10),
- impactOther(11),
- inkjetAqueous(12),
- inkjetSolid(13),
- inkjetOther(14),
- pen(15),
- thermalTransfer(16),
- thermalSensitive(17),
- thermalDiffusion(18),
- thermalOther(19),
- electroerosion(20),
- electrostatic(21),
- photographicMicrofiche(22),
- photographicImagesetter(23),
- photographicOther(24),
- ionDeposition(25),
- eBeam(26),
- typesetter(27)
- }
-
-PrtMarkerSuppliesTypeTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtMarkerSuppliesType in RFC 1759.
- STATUS current
- DESCRIPTION
- "The type of this supply."
- SYNTAX INTEGER {
- other(1),
- unknown(2),
-
-
-
-Bergman, et al. Standards Track [Page 47]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- -- Values for Printer MIB
- toner(3),
- wasteToner(4),
- ink(5),
- inkCartridge(6),
- inkRibbon(7),
- wasteInk(8),
- opc(9), -- photo conductor
- developer(10),
- fuserOil(11),
- solidWax(12),
- ribbonWax(13),
- wasteWax(14),
- fuser(15), -- Not in RFC 1759
- coronaWire(16), -- Not in RFC 1759
- fuserOilWick(17), -- Not in RFC 1759
- cleanerUnit(18), -- Not in RFC 1759
- fuserCleaningPad(19), -- Not in RFC 1759
- transferUnit(20), -- Not in RFC 1759
- tonerCartridge(21), -- Not in RFC 1759
- fuserOiler(22), -- Not in RFC 1759
- -- End of values for Printer MIB
- -- Values for Finisher MIB
- water(23), -- Not in RFC 1759
- wasteWater(24), -- Not in RFC 1759
- glueWaterAdditive(25),-- Not in RFC 1759
- wastePaper(26), -- Not in RFC 1759
- bindingSupply(27), -- Not in RFC 1759
- bandingSupply(28), -- Not in RFC 1759
- stitchingWire(29), -- Not in RFC 1759
- shrinkWrap(30), -- Not in RFC 1759
- paperWrap(31), -- Not in RFC 1759
- staples(32), -- Not in RFC 1759
- inserts(33), -- Not in RFC 1759
- covers(34) -- Not in RFC 1759
- -- End of values for Finisher MIB
- }
-
---
--- Media Path TEXTUAL-CONVENTIONs
---
-
-PrtMediaPathTypeTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtMediaPathType in RFC 1759.
- STATUS current
- DESCRIPTION
- "The type of the media path for this media path."
- SYNTAX INTEGER {
-
-
-
-Bergman, et al. Standards Track [Page 48]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- other(1),
- unknown(2),
- longEdgeBindingDuplex(3),
- shortEdgeBindingDuplex(4),
- simplex(5)
- }
-
---
--- Console Group TEXTUAL-CONVENTIONs
---
-
-PrtConsoleColorTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtConsoleColor in RFC 1759.
- STATUS current
- DESCRIPTION
- "The color of this light."
- SYNTAX INTEGER {
- other(1),
- unknown(2),
- white(3),
- red(4),
- green(5),
- blue(6),
- cyan(7),
- magenta(8),
- yellow(9),
- orange(10) -- Not in RFC 1759
- }
-
-PrtConsoleDisableTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtConsoleDisable in RFC 1759.
- STATUS current
- DESCRIPTION
- "This value indicates whether or not input is accepted from
- the operator console. A value of 'enabled' indicates that
- input is accepted from the console, and a value of 'disabled'
- indicates that input is not accepted from the console. "
- SYNTAX INTEGER {
- enabled(3),
- disabled(4)
- }
-
---
--- Alert Group TEXTUAL-CONVENTIONs
---
-
-PrtAlertTrainingLevelTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtAlertTrainingLevel in RFC 1759.
-
-
-
-Bergman, et al. Standards Track [Page 49]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- STATUS current
- DESCRIPTION
- "The level of training required to handle this alert, if
- human intervention is required. The noInterventionRequired
- value should be used if the event does not require any human
- intervention. The training level is an enumeration that is
- determined and assigned by the printer manufacturer based on
- the information or training required to handle this alert.
- The printer will break alerts into these different training
- levels. It is the responsibility of a management application
- in the system to determine how a particular alert is handled
- and how and to whom that alert is routed. The following are
- the four training levels of alerts:
-
- Field Service - Alerts that typically require advanced
- training and technical knowledge of the printer and its
- subunits. An example of a technical person would be a
- manufacturer's Field Service representative, or other
- person formally trained by the manufacturer or similar
- representative.
- Trained - Alerts that require an intermediate or moderate
- knowledge of the printer and its subunits. A typical
- example of such an alert is replacing a toner cartridge.
- Untrained - Alerts that can be fixed without prior
- training either because the action to correct the alert
- is obvious or the printer can help the untrained person
- fix the problem. A typical example of such an alert is
- reloading paper trays or emptying output bins on a low
- end printer.
- Management - Alerts that have to do with overall operation
- of and configuration of the printer. Examples of such
- management events are configuration change of subunits."
- SYNTAX INTEGER {
- other(1),
- unknown(2),
- untrained(3),
- trained(4),
- fieldService(5),
- management(6),
- noInterventionRequired(7) -- Not in RFC 1759
- }
-
-PrtAlertGroupTC ::= TEXTUAL-CONVENTION
- -- Values in the range 1 to 29 must not be IANA-assigned without
- -- re-publishing Printer MIB.
- -- Values of 30 and greater are for use in MIBs that augment
- -- the Printer MIB, such as the Finisher MIB.
- -- This TC extracted from prtAlertGroup in RFC 1759.
-
-
-
-Bergman, et al. Standards Track [Page 50]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- STATUS current
- DESCRIPTION
- "The type of subunit within the printer model that this alert
- is related. Input, output, and markers are examples of
- printer model groups, i.e., examples of types of subunits.
- Wherever possible, the enumerations match the sub-identifier
- that identifies the relevant table in the Printer MIB.
-
- NOTE: Alert type codes have been added for the Host Resources
- MIB storage table and device table. These additional types
- are for situations in which the printer's storage and device
- objects must generate alerts (and possibly traps for critical
- alerts)."
- SYNTAX INTEGER {
- other(1),
- -- (2) is reserved for conformance information
- -- Values for Host Resources MIB
- hostResourcesMIBStorageTable(3),
- hostResourcesMIBDeviceTable(4),
- -- Values for Printer MIB
- generalPrinter(5),
- cover(6),
- localization(7),
- input(8),
- output(9),
- marker(10),
- markerSupplies(11),
- markerColorant(12),
- mediaPath(13),
- channel(14),
- interpreter(15),
- consoleDisplayBuffer(16),
- consoleLights(17),
- alert(18), -- Not in RFC 1759
- -- Values (5) to (29) reserved for Printer MIB
- -- Values for Finisher MIB
- finDevice(30), -- Not in RFC 1759
- finSupply(31), -- Not in RFC 1759
- finSupplyMediaInput(32), -- Not in RFC 1759
- finAttribute(33) -- Not in RFC 1759
- -- Values (30) to (39) reserved for Finisher MIB
- }
-
-PrtAlertCodeTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtAlertCode in RFC 1759.
- STATUS current
- DESCRIPTION
- "The code that describes the type of alert for this entry in
-
-
-
-Bergman, et al. Standards Track [Page 51]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- the table. Binary change event alerts describe states of the
- subunit while unary change event alerts describe a single
- event. The same alert code can be used for a binary change
- event or a unary change event, depending on implementation.
- Also, the same alert code can be used to indicate a critical
- or non-critical (warning) alert, depending on implementation.
- The value of prtAlertSeverityLevel specifies binary vs. unary
- and critical vs. non-critical for each event for the
- implementation.
-
- While there are some specific codes for many subunits, the
- generic codes should be used for most subunit alerts. The
- network management station can then query the subunit
- specified by prtAlertGroup to determine further subunit
- status and other subunit information.
-
- An agent shall not add two entries to the alert table for the
- same event, one containing a generic event code and the other
- containing a specific event code; the agent shall add only
- one entry in the alert table for each event; either generic
- (preferred) or specific, not both.
-
- Implementation of the unary change event
- alertRemovalOfBinaryChangeEntry(1801) is optional. When
- implemented, this alert code shall indicate to network
- management stations that the trailing edge of a binary change
- event has occurred and the corresponding alert entry has been
- removed from the alert table. As with all events, the
- alertRemovalOfBinaryChangeEntry(1801) alert shall be placed
- at the end of the alert table. Such an alert table entry
- shall specify the following information:
-
- prtAlertSeverityLevel warningUnaryChangeEvent(4)
- prtAlertTrainingLevel noInterventionRequired(7)
- prtAlertGroup alert(18)
- prtAlertGroupIndex the index of the row in the
- alert table of the binary
- change event that this event
- has removed.
- prtAlertLocation unknown (-2)
- prtAlertCode alertRemovalOfBinaryChangeEntry(1801)
- prtAlertDescription <description or null string>
- prtAlertTime the value of sysUpTime at
- the time of the removal of the
- binary change event from the
- alert table.
-
- Optionally, the agent may generate a trap coincident with
-
-
-
-Bergman, et al. Standards Track [Page 52]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- removing the binary change event and placing the unary change
- event alertRemovalOfBinaryChangeEntry(1801) in the alert
- table. For such a trap, the prtAlertIndex sent with the above
- trap parameters shall be the index of the
- alertRemovalOfBinaryChangeEvent row that was added to the
- prtAlertTable; not the index of the row that was removed from
- the prtAlertTable."
- SYNTAX INTEGER {
- other(1),
- -- an event that is not represented
- -- by one of the alert codes
- -- specified below.
- unknown(2),
- -- The following generic codes are common to
- -- multiple groups. The NMS may examine the
- -- prtAlertGroup object to determine what group
- -- to query for further information.
- coverOpen(3),
- coverClosed(4),
- interlockOpen(5),
- interlockClosed(6),
- configurationChange(7),
- jam(8),
- subunitMissing(9), -- Not in RFC 1759
- -- The subunit tray, bin, etc.
- -- has been removed.
- subunitLifeAlmostOver(10), -- Not in RFC 1759
- subunitLifeOver(11), -- Not in RFC 1759
- subunitAlmostEmpty(12), -- Not in RFC 1759
- subunitEmpty(13), -- Not in RFC 1759
- subunitAlmostFull(14), -- Not in RFC 1759
- subunitFull(15), -- Not in RFC 1759
- subunitNearLimit(16), -- Not in RFC 1759
- subunitAtLimit(17), -- Not in RFC 1759
- subunitOpened(18), -- Not in RFC 1759
- subunitClosed(19), -- Not in RFC 1759
- subunitTurnedOn(20), -- Not in RFC 1759
- subunitTurnedOff(21), -- Not in RFC 1759
- subunitOffline(22), -- Not in RFC 1759
- subunitPowerSaver(23), -- Not in RFC 1759
- subunitWarmingUp(24), -- Not in RFC 1759
- subunitAdded(25), -- Not in RFC 1759
- subunitRemoved(26), -- Not in RFC 1759
- subunitResourceAdded(27), -- Not in RFC 1759
- subunitResourceRemoved(28), -- Not in RFC 1759
- subunitRecoverableFailure(29),
- -- Not in RFC 1759
- subunitUnrecoverableFailure(30),
-
-
-
-Bergman, et al. Standards Track [Page 53]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- -- Not in RFC 1759
- subunitRecoverableStorageError(31),
- -- Not in RFC 1759
- subunitUnrecoverableStorageError(32),
- -- Not in RFC 1759
- subunitMotorFailure(33), -- Not in RFC 1759
- subunitMemoryExhausted(34), -- Not in RFC 1759
- subunitUnderTemperature(35), -- Not in RFC 1759
- subunitOverTemperature(36), -- Not in RFC 1759
- subunitTimingFailure(37), -- Not in RFC 1759
- subunitThermistorFailure(38), -- Not in RFC 1759
-
- -- General Printer group
- doorOpen(501), -- DEPRECATED
- -- Use coverOpened(3)
- doorClosed(502), -- DEPRECATED
- -- Use coverClosed(4)
- powerUp(503),
- powerDown(504),
- printerNMSReset(505), -- Not in RFC 1759
- -- The printer has been reset by some
- -- network management station(NMS)
- -- writing into 'prtGeneralReset'.
- printerManualReset(506), -- Not in RFC 1759
- -- The printer has been reset manually.
- printerReadyToPrint(507), -- Not in RFC 1759
- -- The printer is ready to print. (i.e.,
- -- not warming up, not in power save
- -- state, not adjusting print quality,
- -- etc.).
-
- -- Input Group
- inputMediaTrayMissing(801),
- inputMediaSizeChange(802),
- inputMediaWeightChange(803),
- inputMediaTypeChange(804),
- inputMediaColorChange(805),
- inputMediaFormPartsChange(806),
- inputMediaSupplyLow(807),
- inputMediaSupplyEmpty(808),
- inputMediaChangeRequest(809), -- Not in RFC 1759
- -- An interpreter has detected that a
- -- different medium is need in this input
- -- tray subunit. The prtAlertDescription may
- -- be used to convey a human readable
- -- description of the medium required to
- -- satisfy the request.
- inputManualInputRequest(810), -- Not in RFC 1759
-
-
-
-Bergman, et al. Standards Track [Page 54]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- -- An interpreter has detected that manual
- -- input is required in this subunit. The
- -- prtAlertDescription may be used to convey
- -- a human readable description of the medium
- -- required to satisfy the request.
- inputTrayPositionFailure(811), -- Not in RFC 1759
- -- The input tray failed to position correctly.
- inputTrayElevationFailure(812),
- -- Not in RFC 1759
- inputCannotFeedSizeSelected(813),
- -- Not in RFC 1759
- -- Output Group
- outputMediaTrayMissing(901),
- outputMediaTrayAlmostFull(902),
- outputMediaTrayFull(903),
- outputMailboxSelectFailure(904),
- -- Not in RFC 1759
- -- Marker group
- markerFuserUnderTemperature(1001),
- markerFuserOverTemperature(1002),
- markerFuserTimingFailure(1003),
- -- Not in RFC 1759
- markerFuserThermistorFailure(1004),
- -- Not in RFC 1759
- markerAdjustingPrintQuality(1005),
- -- Not in RFC 1759
- -- Marker Supplies group
- markerTonerEmpty(1101),
- markerInkEmpty(1102),
- markerPrintRibbonEmpty(1103),
- markerTonerAlmostEmpty(1104),
- markerInkAlmostEmpty(1105),
- markerPrintRibbonAlmostEmpty(1106),
- markerWasteTonerReceptacleAlmostFull(1107),
- markerWasteInkReceptacleAlmostFull(1108),
- markerWasteTonerReceptacleFull(1109),
- markerWasteInkReceptacleFull(1110),
- markerOpcLifeAlmostOver(1111),
- markerOpcLifeOver(1112),
- markerDeveloperAlmostEmpty(1113),
- markerDeveloperEmpty(1114),
- markerTonerCartridgeMissing(1115),
- -- Not in RFC 1759
- -- Media Path Device Group
- mediaPathMediaTrayMissing(1301),
- mediaPathMediaTrayAlmostFull(1302),
- mediaPathMediaTrayFull(1303),
- mediaPathCannotDuplexMediaSelected(1304),
-
-
-
-Bergman, et al. Standards Track [Page 55]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- -- Not in RFC 1759
- -- Interpreter Group
- interpreterMemoryIncrease(1501),
- interpreterMemoryDecrease(1502),
- interpreterCartridgeAdded(1503),
- interpreterCartridgeDeleted(1504),
- interpreterResourceAdded(1505),
- interpreterResourceDeleted(1506),
- interpreterResourceUnavailable(1507),
- interpreterComplexPageEncountered(1509),
- -- Not in RFC 1759
- -- The interpreter has encountered a page
- -- that is too complex for the resources that
- -- are available.
- -- Alert Group
- alertRemovalOfBinaryChangeEntry(1801)
- -- Not in RFC 1759
- -- A binary change event entry has been
- -- removed from the alert table. This unary
- -- change alert table entry is added to the
- -- end of the alert table.
- }
-END
-
-6. The Printer MIB
-
-Printer-MIB DEFINITIONS ::= BEGIN
-
-IMPORTS
- MODULE-IDENTITY, OBJECT-TYPE, Counter32, Integer32, TimeTicks,
- NOTIFICATION-TYPE, OBJECT-IDENTITY,
- mib-2 FROM SNMPv2-SMI -- [RFC2578]
- TEXTUAL-CONVENTION FROM SNMPv2-TC -- [RFC2579]
- MODULE-COMPLIANCE, OBJECT-GROUP, NOTIFICATION-GROUP
- FROM SNMPv2-CONF -- [RFC2580]
- hrDeviceIndex, hrStorageIndex FROM HOST-RESOURCES-MIB -- [RFC2790]
- InterfaceIndexOrZero FROM IF-MIB -- [RFC2863]
- PrtCoverStatusTC, PrtGeneralResetTC, PrtChannelTypeTC,
- PrtInterpreterLangFamilyTC, PrtInputTypeTC, PrtOutputTypeTC,
- PrtMarkerMarkTechTC, PrtMarkerSuppliesTypeTC, PrtConsoleColorTC,
- PrtConsoleDisableTC, PrtMediaPathTypeTC, PrtAlertGroupTC,
- PrtAlertTrainingLevelTC, PrtAlertCodeTC
- FROM IANA-PRINTER-MIB
- IANACharset FROM IANA-CHARSET-MIB;
-
-printmib MODULE-IDENTITY
- LAST-UPDATED "200406020000Z"
- ORGANIZATION "PWG IEEE/ISTO Printer Working Group"
-
-
-
-Bergman, et al. Standards Track [Page 56]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- CONTACT-INFO
- "Harry Lewis
- IBM
- Phone (303) 924-5337
- Email: harryl@us.ibm.com
- http://www.pwg.org/index.html
-
- Send comments to the printmib WG using the Printer MIB
- Project (PMP) Mailing List: pmp@pwg.org
-
- For further information, access the PWG web page under 'Printer
- MIB': http://www.pwg.org/
-
- Implementers of this specification are encouraged to join the
- pmp mailing list in order to participate in discussions on any
- clarifications needed and registration proposals being reviewed
- in order to achieve consensus."
- DESCRIPTION
- "The MIB module for management of printers.
- Copyright (C) The Internet Society (2004). This
- version of this MIB module was published
- in RFC 3805. For full legal notices see the RFC itself."
- REVISION "200406020000Z"
- DESCRIPTION
- "Printer MIB v2.
- Moved all enum groups to be maintained by IANA into new TCs
- within the ianaPrinterMIB, which is contained in this
- document.
- New TCs created from enums defined within RFC 1759 Objects:
- PrtPrintOrientationTC, PrtLocalizedDescriptionStringTC,
- PrtConsoleDescriptionStringTC, PrtChannelStateTC,
- PrtOutputStackingOrderTC, PrtOutputPageDeliveryOrientationTC,
- PrtMarkerCounterUnitTC, PrtMarkerSuppliesSupplyUnitTC,
- PrtMarkerSuppliesClassTC, PrtMarkerAddressabilityUnitTC,
- PrtMarkerColorantRoleTC, PrtMediaPathMaxSpeedPrintUnitTC,
- PrtInterpreterTwoWayTC, and PrtAlertSeverityLevelTC.
- The following four TCs have been deprecated:
- MediaUnit (replaced by PrtMediaUnitTC),
- CapacityUnit (replaced by PrtCapacityUnitTC),
- SubUnitStatus (replaced by PrtSubUnitStatusTC),
- CodedCharSet (replaced by IANACharset in IANA Charset MIB)
- Five new OBJECT-GROUPs: prtAuxilliarySheetGroup,
- prtInputSwitchingGroup, prtGeneralV2Group,
- prtAlertTableV2Group, prtChannelV2Group.
- Nine new objects added to those groups:
- prtAuxiliarySheetStartupPage, prtAuxiliarySheetBannerPage,
- prtGeneralPrinterName, prtGeneralSerialNumber,
- prtAlertCriticalEvents, prtAlertAllEvents,
-
-
-
-Bergman, et al. Standards Track [Page 57]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- prtInputMediaLoadTimeout, prtInputNextIndex,
- prtChannelInformation.
- SYNTAX range changed from (0..65535) to (1..65535) for the
- index objects prtStorageRefSeqNumber, prtDeviceRefSeqNumber,
- and prtConsoleLightIndex.
- SYNTAX range changed from (0..65535) to (0..2147483647) for the
- objects prtStorageRefIndex and prtDeviceRefIndex to agree
- with the Host Resources MIB.
- Defined a range for the objects with a SYNTAX of Integer32:
- prtOutputDefaultIndex, prtInputMediaDimFeedDirDeclared,
- prtInputMediaDimXFeedDirDeclared, prtInputMaxCapacity,
- prtInputCurrentLevel, prtInputMediaDimFeedDirChosen,
- prtInputMediaDimXFeedDirChosen, prtInputMediaWeight,
- prtInputMediaFormParts, prtOutputIndex,
- prtOutputMaxCapacity, prtOutputRemainingCapacity,
- prtOutputMaxDimFeedDir, prtOutputMaxDimXFeedDir,
- prtOutputMinDimFeedDir, prtOutputMinDimXFeedDir,
- prtMarkerAddressibilityFeedDir,
- prtMarkerAddressibilityXFeedDir, prtMarkerNorthMargin,
- prtMarkerSouthMargin, prtMarkerWestMargin,
- prtMarkerEastMargin, prtMarkerSuppliesMaxCapacity,
- prtMarkerSuppliesLevel, prtMarkerColorantTonality,
- prtMediaPathMaxSpeed, prtMediaPathMaxMediaFeedDir,
- prtMediaPathMaxMediaXFeedDir, prtMediaPathMinMediaFeedDir,
- prtMediaPathMinMediaXFeedDir, prtChannelIndex,
- prtChannelCurrentJobCntlLangIndex, prtInterpreterIndex,
- prtChannelDefaultPageDescLangIndex, prtConsoleOnTime,
- prtInterpreterFeedAddressibility, prtConsoleOffTime,
- prtInterpreterXFeedAddressibility, prtAlertIndex,
- prtAlertGroupIndex, prtAlertLocation.
- Changed SYNTAX from Integer32 to InterfaceIndexOrZero for
- prtChannelIfIndex.
- Changed MAX-ACCESS of prtAlertIndex from not-accessible to
- Read-only and added a compliance statement to allow a
- MIN-ACCESS of accessible-for-notify.
- One new NOTIFICATION-GROUP: prtAlertTrapGroup which contains
- printerV2Alert.
- In MODULE-COMPLIANCE prtMIBCompliance, new OBJECT-GROUPs and
- the NOTIFICATION_GROUP, all in GROUP (not MANDATORY-GROUP)
- clauses. The nine new objects are optional, i.e., this
- document is backward compatible with RFC 1759."
- REVISION "199411250000Z"
- DESCRIPTION
- "The original version of this MIB, published as RFC1759."
- ::= { mib-2 43 }
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 58]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
--- TEXTUAL-CONVENTIONs for this MIB module
---
--- Generic unspecific TEXTUAL-CONVENTIONs
---
-
-PrtMediaUnitTC ::= TEXTUAL-CONVENTION
- -- Replaces MediaUnit in RFC 1759.
- STATUS current
- DESCRIPTION
- "Units of measure for media dimensions."
- SYNTAX INTEGER {
- tenThousandthsOfInches(3), -- .0001
- micrometers(4)
- }
-
-MediaUnit ::= TEXTUAL-CONVENTION
- -- Replaced by PrtMediaUnitTC.
- STATUS deprecated
- DESCRIPTION
- "Units of measure for media dimensions."
- SYNTAX INTEGER {
- tenThousandthsOfInches(3), -- .0001
- micrometers(4)
- }
-
-PrtCapacityUnitTC ::= TEXTUAL-CONVENTION
- -- Replaces CapacityUnit in RFC 1759.
- STATUS current
- DESCRIPTION
- "Units of measure for media capacity."
- SYNTAX INTEGER {
- other(1), -- New, not in RFC 1759
- unknown(2), -- New, not in RFC 1759
- tenThousandthsOfInches(3), -- .0001
- micrometers(4),
- sheets(8),
- feet(16),
- meters(17),
- -- Values for Finisher MIB
- items(18), -- New, not in RFC 1759
- percent(19) -- New, not in RFC 1759
- }
-
-CapacityUnit ::= TEXTUAL-CONVENTION
- -- Replaced by PrtCapacityUnitTC.
- STATUS deprecated
- DESCRIPTION
- "Units of measure for media capacity."
-
-
-
-Bergman, et al. Standards Track [Page 59]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- SYNTAX INTEGER {
- tenThousandthsOfInches(3), -- .0001
- micrometers(4),
- sheets(8),
- feet(16),
- meters(17)
- }
-
-PrtPrintOrientationTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtInterpreterDefaultOrientation in
- -- RFC 1759.
- STATUS current
- DESCRIPTION
- "A generic representation for printing orientation on a
- 'page'."
- SYNTAX INTEGER {
- other(1),
- portrait(3),
- landscape(4)
- }
-
-PrtSubUnitStatusTC ::= TEXTUAL-CONVENTION
- -- Replaces SubUnitStatus in RFC 1759.
- STATUS current
- DESCRIPTION
- "Status of a printer sub-unit.
-
- The SubUnitStatus is an integer that is the sum of 5 distinct
- values, Availability, Non-Critical, Critical, On-line, and
- Transitioning. These values are:
-
- Availability Value
-
- Available and Idle 0 0000'b
- Available and Standby 2 0010'b
- Available and Active 4 0100'b
- Available and Busy 6 0110'b
- Unavailable and OnRequest 1 0001'b
- Unavailable because Broken 3 0011'b
- Unknown 5 0101'b
-
- Non-Critical
- No Non-Critical Alerts 0 0000'b
- Non-Critical Alerts 8 1000'b
-
- Critical
-
- No Critical Alerts 0 0000'b
-
-
-
-Bergman, et al. Standards Track [Page 60]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- Critical Alerts 16 1 0000'b
-
- On-Line
-
- State is On-Line 0 0000'b
- State is Off-Line 32 10 0000'b
-
- Transitioning
-
- At intended state 0 0000'b
- Transitioning to intended state 64 100 0000'b"
-
- SYNTAX INTEGER (0..126)
-
-SubUnitStatus ::= TEXTUAL-CONVENTION
- -- Replaced by PrtSubUnitStatusTC.
- STATUS deprecated
- DESCRIPTION
- "Status of a printer sub-unit.
-
- The SubUnitStatus is an integer that is the sum of 5 distinct
- values, Availability, Non-Critical, Critical, On-line, and
- Transitioning. These values are:
-
- Availability Value
- Available and Idle 0 0000'b
- Available and Standby 2 0010'b
- Available and Active 4 0100'b
- Available and Busy 6 0110'b
- Unavailable and OnRequest 1 0001'b
- Unavailable because Broken 3 0011'b
- Unknown 5 0101'b
-
- Non-Critical
- No Non-Critical Alerts 0 0000'b
- Non-Critical Alerts 8 1000'b
-
- Critical
-
- No Critical Alerts 0 0000'b
- Critical Alerts 16 1 0000'b
-
- On-Line
-
- State is On-Line 0 0000'b
- State is Off-Line 32 10 0000'b
-
- Transitioning
-
-
-
-Bergman, et al. Standards Track [Page 61]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- At intended state 0 0000'b
- Transitioning to intended state 64 100 0000'b"
-
- SYNTAX INTEGER (0..126)
-
-PresentOnOff ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "Presence and configuration of a device or feature."
- SYNTAX INTEGER {
- other(1),
- on(3),
- off(4),
- notPresent(5)
- }
-
-PrtLocalizedDescriptionStringTC ::= TEXTUAL-CONVENTION
- -- This TC did not appear in RFC 1759.
- STATUS current
- DESCRIPTION
- "An object MUST use this TEXTUAL-CONVENTION when its
- 'charset' is controlled by the value of
- prtGeneralCurrentLocalization."
- SYNTAX OCTET STRING (SIZE(0..255))
-
-PrtConsoleDescriptionStringTC ::= TEXTUAL-CONVENTION
- -- This TC did not appear in RFC 1759.
- STATUS current
- DESCRIPTION
- "An object MUST use this TEXTUAL-CONVENTION when its
- 'charset' is controlled by the value of
- prtConsoleLocalization."
- SYNTAX OCTET STRING (SIZE(0..255))
-
-CodedCharSet ::= TEXTUAL-CONVENTION
-
- -- Replaced by IANACharset TEXTUAL-CONVENTION in IANA Charset MIB.
- STATUS deprecated
- DESCRIPTION
- "The original description clause from RFC 1759 [RFC1759] was
- technically inaccurate and therefore has been deleted."
- SYNTAX INTEGER {
- other(1) -- used if the designated coded
- -- character set is not currently in
- -- the enumeration
-}
-
---
-
-
-
-Bergman, et al. Standards Track [Page 62]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
--- Channel Group TEXTUAL-CONVENTIONs
---
-
-PrtChannelStateTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtChannelState in RFC 1759.
- STATUS current
- DESCRIPTION
- "The state of this print job delivery channel. The value
- determines whether print data is allowed through this channel."
- SYNTAX INTEGER {
- other(1),
- printDataAccepted(3),
- noDataAccepted(4)
- }
-
---
--- Input/Output Group TEXTUAL-CONVENTIONs
---
-
-PrtOutputStackingOrderTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtOutputStackingOrder in RFC 1759.
- STATUS current
- DESCRIPTION
- "The current state of the stacking order for the associated
- output sub-unit. 'firstToLast' means that as pages are output,
- the front of the next page is placed against the back of the
- previous page. 'lastToFirst' means that as pages are output,
- the back of the next page is placed against the front of the
- previous page."
- SYNTAX INTEGER {
- unknown(2),
- firstToLast(3),
- lastToFirst(4)
- }
-
-PrtOutputPageDeliveryOrientationTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtOutputPageDeliveryOrientation
- -- in RFC 1759.
- STATUS current
- DESCRIPTION
- "The reading surface that will be 'up' when pages are delivered
- to the associated output sub-unit. Values are Face-Up and Face
- Down (Note: interpretation of these values is, in general,
- context-dependent based on locale; presentation of these values
- to an end-user should be normalized to the expectations of the
- user."
- SYNTAX INTEGER {
- faceUp(3),
-
-
-
-Bergman, et al. Standards Track [Page 63]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- faceDown(4)
- }
-
---
--- Marker Group TEXTUAL-CONVENTIONs
---
-
-PrtMarkerCounterUnitTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtMarkerCounterUnit in RFC 1759.
- STATUS current
- DESCRIPTION
- "The unit that will be used by the printer when reporting
- counter values for this marking sub-unit. The
- time units of measure are provided for a device like a
- strip recorder that does not or cannot track the physical
- dimensions of the media and does not use characters,
- lines or sheets."
-
- SYNTAX INTEGER {
- tenThousandthsOfInches(3), -- .0001
- micrometers(4),
- characters(5),
- lines(6),
- impressions(7),
- sheets(8),
- dotRow(9),
- hours(11),
- feet(16),
- meters(17)
- }
-
-PrtMarkerSuppliesSupplyUnitTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtMarkerSuppliesSupplyUnit
- -- in RFC 1759.
- STATUS current
- DESCRIPTION
- "Unit of this marker supply container/receptacle."
- SYNTAX INTEGER {
- other(1), -- New, not in RFC 1759
- unknown(2), -- New, not in RFC 1759
- tenThousandthsOfInches(3), -- .0001
- micrometers(4),
- impressions(7), -- New, not in RFC 1759
- sheets(8), -- New, not in RFC 1759
- hours(11), -- New, not in RFC 1759
- thousandthsOfOunces(12),
- tenthsOfGrams(13),
- hundrethsOfFluidOunces(14),
-
-
-
-Bergman, et al. Standards Track [Page 64]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- tenthsOfMilliliters(15),
- feet(16), -- New, not in RFC 1759
- meters(17), -- New, not in RFC 1759
- -- Values for Finisher MIB
- items(18), -- e.g., #staples. New, not in RFC 1759
- percent(19) -- New, not in RFC 1759
- }
-
-PrtMarkerSuppliesClassTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtMarkerSuppliesClass in RFC 1759.
- STATUS current
- DESCRIPTION
- "Indicates whether this supply entity represents a supply
- that is consumed or a receptacle that is filled."
- SYNTAX INTEGER {
- other(1),
- supplyThatIsConsumed(3),
- receptacleThatIsFilled(4)
- }
-
-PrtMarkerColorantRoleTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtMarkerColorantRole in RFC 1759.
- STATUS current
- DESCRIPTION
- "The role played by this colorant."
- SYNTAX INTEGER { -- Colorant Role
- other(1),
- process(3),
- spot(4)
- }
-
-PrtMarkerAddressabilityUnitTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtMarkerAddressabilityUnit
- -- in RFC 1759.
- STATUS current
- DESCRIPTION
- "The unit of measure of distances, as applied to the marker's
- resolution."
- SYNTAX INTEGER {
- tenThousandthsOfInches(3), -- .0001
- micrometers(4)
- }
-
---
--- Media Path TEXTUAL-CONVENTIONs
---
-
-PrtMediaPathMaxSpeedPrintUnitTC ::= TEXTUAL-CONVENTION
-
-
-
-Bergman, et al. Standards Track [Page 65]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- -- This TC was extracted from prtMediaPathMaxSpeedPrintUnit
- -- in RFC 1759.
- STATUS current
- DESCRIPTION
- "The unit of measure used in specifying the speed of all
- media paths in the printer."
- SYNTAX INTEGER {
- tenThousandthsOfInchesPerHour(3),-- .0001/hour
- micrometersPerHour(4),
- charactersPerHour(5),
- linesPerHour(6),
- impressionsPerHour(7),
- sheetsPerHour(8),
- dotRowPerHour(9),
- feetPerHour(16),
- metersPerHour(17)
- }
-
---
--- Interpreter Group TEXTUAL-CONVENTIONs
---
-
-PrtInterpreterTwoWayTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtInterpreterTwoWay in RFC 1759.
- STATUS current
- DESCRIPTION
- "Indicates whether or not this interpreter returns information
- back to the host."
- SYNTAX INTEGER {
- yes(3),
- no(4)
- }
-
---
--- Alert Group TEXTUAL-CONVENTIONs
---
-
-PrtAlertSeverityLevelTC ::= TEXTUAL-CONVENTION
- -- This TC was extracted from prtAlertSeverityLevel in RFC 1759.
- STATUS current
- DESCRIPTION
- "The level of severity of this alert table entry. The printer
- determines the severity level assigned to each entry in the
- table. A critical alert is binary by nature and definition. A
- warning is defined to be a non-critical alert. The original and
- most common warning is unary. The binary warning was added later
- and given a more distinguished name."
- SYNTAX INTEGER {
-
-
-
-Bergman, et al. Standards Track [Page 66]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- other(1),
- critical(3),
- warning(4),
- warningBinaryChangeEvent(5) -- New, not in RFC 1759
- }
-
--- The General Printer Group
---
--- The general printer sub-unit is responsible for the overall
--- control and status of the printer. There is exactly one
--- general printer sub-unit in a printer.
-
-prtGeneral OBJECT IDENTIFIER ::= { printmib 5 }
-
-prtGeneralTable OBJECT-TYPE
- SYNTAX SEQUENCE OF PrtGeneralEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A table of general information per printer.
- Objects in this table are defined in various
- places in the MIB, nearby the groups to
- which they apply. They are all defined
- here to minimize the number of tables that would
- otherwise need to exist."
- ::= { prtGeneral 1 }
-
-prtGeneralEntry OBJECT-TYPE
- SYNTAX PrtGeneralEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "An entry exists in this table for each device entry in the
- host resources MIB device table with a device type of
- 'printer'.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- INDEX { hrDeviceIndex }
- ::= { prtGeneralTable 1 }
-
-PrtGeneralEntry ::= SEQUENCE {
- -- Note that not all of the objects in this sequence are in
- -- the general printer group. The group to which an
- -- object belongs is tagged with a label "General", "Input"
- -- "Output", etc. after each entry in the following sequence.
- --
- prtGeneralConfigChanges Counter32, -- General
-
-
-
-Bergman, et al. Standards Track [Page 67]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- prtGeneralCurrentLocalization Integer32, -- General
- prtGeneralReset PrtGeneralResetTC,
- -- General
- prtGeneralCurrentOperator OCTET STRING,
- -- Responsible Party
- prtGeneralServicePerson OCTET STRING,
- -- Responsible Party
- prtInputDefaultIndex Integer32, -- Input
- prtOutputDefaultIndex Integer32, -- Output
- prtMarkerDefaultIndex Integer32, -- Marker
- prtMediaPathDefaultIndex Integer32, -- Media Path
- prtConsoleLocalization Integer32, -- Console
- prtConsoleNumberOfDisplayLines Integer32, -- Console
- prtConsoleNumberOfDisplayChars Integer32, -- Console
- prtConsoleDisable PrtConsoleDisableTC,
- -- Console,
- prtAuxiliarySheetStartupPage PresentOnOff,
- -- AuxiliarySheet
- prtAuxiliarySheetBannerPage PresentOnOff,
- -- AuxiliarySheet
- prtGeneralPrinterName OCTET STRING,
- -- General V2
- prtGeneralSerialNumber OCTET STRING,
- -- General V2
- prtAlertCriticalEvents Counter32, -- Alert V2
- prtAlertAllEvents Counter32 -- Alert V2
- }
-
-prtGeneralConfigChanges OBJECT-TYPE
- SYNTAX Counter32
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "Counts configuration changes within the printer. A
- configuration change is defined to be an action that results in
- a change to any MIB object other than those that reflect status
- or level, or those that act as counters or gauges. In addition,
- any action that results in a row being added or deleted from
- any table in the Printer MIB is considered a configuration
- change. Such changes will often affect the capability of the
- printer to service certain types of print jobs. Management
- applications may cache infrequently changed configuration
- information about sub units within the printer. This object
- should be incremented whenever the agent wishes to notify
- management applications that any cached configuration
- information for this device is to be considered 'stale'. At
- this point, the management application should flush any
- configuration information cached about this device and fetch
-
-
-
-Bergman, et al. Standards Track [Page 68]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- new configuration information.
-
- The following are examples of actions that would cause the
- prtGeneralConfigChanges object to be incremented:
-
- - Adding an output bin
- - Changing the media in a sensing input tray
- - Changing the value of prtInputMediaType
-
- Note that the prtGeneralConfigChanges counter would not be
- incremented when an input tray is temporarily removed to load
- additional paper or when the level of an input device changes.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
-
- ::= { prtGeneralEntry 1 }
-
-prtGeneralCurrentLocalization OBJECT-TYPE
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The value of the prtLocalizationIndex corresponding to the
- current language, country, and character set to be used for
- localized string values that are identified as being dependent
- on the value of this object. Note that this object does not
- apply to localized strings in the prtConsole group or to any
- object that is not explicitly identified as being localized
- according to prtGeneralCurrentLocalization. When an object's
- 'charset' is controlled by the value of
- prtGeneralCurrentLocalization, it MUST specify
- PrtLocalizedDescriptionStringTC as its syntax.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtGeneralEntry 2 }
-
-prtGeneralReset OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly defined
- -- by this object.
- SYNTAX PrtGeneralResetTC
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "Setting this value to 'powerCycleReset', 'resetToNVRAM', or
- 'resetToFactoryDefaults' will result in the resetting of the
- printer. When read, this object will always have the value
-
-
-
-Bergman, et al. Standards Track [Page 69]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- 'notResetting(3)', and a SET of the value 'notResetting' shall
- have no effect on the printer. Some of the defined values are
- optional. However, every implementation must support at least
- the values 'notResetting' and 'resetToNVRAM'."
- ::= { prtGeneralEntry 3 }
-
--- The Responsible Party group
-
-prtGeneralCurrentOperator OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..127))
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The name of the person who is responsible for operating
- this printer. It is suggested that this string include
- information that would enable other humans to reach the
- operator, such as a phone number. As a convention to
- facilitate automatic notification of the operator by the
- agent or network management station, the phone number,
- fax number or email address should be indicated by the
- URL schemes 'tel:', 'fax:' and 'mailto:', respectively.
- If either the phone, fax, or email information is not
- available, then a line should not be included for this
- information.
-
- NOTE: For interoperability purposes, it is advisable to
- use email addresses formatted according to [RFC2822]
- requirements.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtGeneralEntry 4 }
-
-prtGeneralServicePerson OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..127))
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The name of the person responsible for servicing this
- printer. It is suggested that this string include
- information that would enable other humans to reach the
- service person, such as a phone number. As a convention
- to facilitate automatic notification of the operator by
- the agent or network management station, the phone
- number, fax number or email address should be indicated
- by the URL schemes 'tel:', 'fax:' and 'mailto:',
- respectively. If either the phone, fax, or email
- information is not available, then a line should not
-
-
-
-Bergman, et al. Standards Track [Page 70]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- be included for this information.
-
- NOTE: For interoperability purposes, it is advisable to use
- email addresses formatted per [RFC2822] requirements.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
-
- ::= { prtGeneralEntry 5 }
-
--- Default indexes section
---
--- The following four objects are used to specify the indexes of
--- certain subunits used as defaults during the printing process.
-
-prtInputDefaultIndex OBJECT-TYPE
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The value of prtInputIndex corresponding to the default input
- sub-unit: that is, this object selects the default source of
- input media."
-::= { prtGeneralEntry 6 }
-
-prtOutputDefaultIndex OBJECT-TYPE
- -- A range has been added to the SYNTAX clause that was not in
- -- RFC 1759. Although this violates SNMP compatibility rules,
- -- it provides a more reasonable guide for SNMP managers.
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The value of prtOutputIndex corresponding to the default
- output sub-unit; that is, this object selects the default
- output destination."
-::= { prtGeneralEntry 7 }
-
-prtMarkerDefaultIndex OBJECT-TYPE
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The value of prtMarkerIndex corresponding to the
- default marker sub-unit; that is, this object selects the
- default marker."
- ::= { prtGeneralEntry 8 }
-
-
-
-
-Bergman, et al. Standards Track [Page 71]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-prtMediaPathDefaultIndex OBJECT-TYPE
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The value of prtMediaPathIndex corresponding to
- the default media path; that is, the selection of the
- default media path."
- ::= { prtGeneralEntry 9 }
-
--- Console general section
---
--- The following four objects describe overall parameters of the
--- printer console subsystem.
-
-prtConsoleLocalization OBJECT-TYPE
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The value of the prtLocalizationIndex corresponding to
- the language, country, and character set to be used for the
- console. This localization applies both to the actual display
- on the console as well as the encoding of these console objects
- in management operations. When an object's 'charset' is
- controlled by the value of prtConsoleLocalization, it MUST
- specify PrtConsoleDescriptionStringTC as its syntax.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtGeneralEntry 10 }
-
-prtConsoleNumberOfDisplayLines OBJECT-TYPE
- SYNTAX Integer32 (0..65535)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The number of lines on the printer's physical
- display. This value is 0 if there are no lines on the
- physical display or if there is no physical display"
- ::= { prtGeneralEntry 11 }
-
-prtConsoleNumberOfDisplayChars OBJECT-TYPE
- SYNTAX Integer32 (0..65535)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The number of characters per line displayed on the physical
-
-
-
-Bergman, et al. Standards Track [Page 72]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- display. This value is 0 if there are no lines on the physical
- display or if there is no physical display"
- ::= { prtGeneralEntry 12 }
-
-prtConsoleDisable OBJECT-TYPE
- -- In RFC 1759, the enumeration values were implicitly defined
- -- by this object.
- SYNTAX PrtConsoleDisableTC
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "This value indicates how input is (or is not) accepted from
- the operator console.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtGeneralEntry 13 }
-
--- The Auxiliary Sheet Group
---
--- The auxiliary sheet group allows the administrator to control
--- the production of auxiliary sheets by the printer. This group
--- contains only the "prtAuxiliarySheetStartupPage" and
--- "prtAuxiliarySheetBannerPage" objects.
-
-prtAuxiliarySheetStartupPage OBJECT-TYPE
- SYNTAX PresentOnOff
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "Used to enable or disable printing a startup page. If enabled,
- a startup page will be printed shortly after power-up, when the
- device is ready. Typical startup pages include test patterns
- and/or printer configuration information."
- ::= { prtGeneralEntry 14 }
-
-prtAuxiliarySheetBannerPage OBJECT-TYPE
- SYNTAX PresentOnOff
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "Used to enable or disable printing banner pages at the
- beginning of jobs. This is a master switch which applies to all
- jobs, regardless of interpreter."
- ::= { prtGeneralEntry 15 }
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 73]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
--- Administrative section (The General V2 Group)
---
--- The following two objects are used to specify administrative
--- information assigned to the printer.
-
-prtGeneralPrinterName OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE (0..127))
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "An administrator-specified name for this printer. Depending
- upon implementation of this printer, the value of this object
- may or may not be same as the value for the MIB-II 'SysName'
- object."
- ::= { prtGeneralEntry 16 }
-
-prtGeneralSerialNumber OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE (0..255))
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "A recorded serial number for this device that indexes some
- type device catalog or inventory. This value is usually set by
- the device manufacturer but the MIB supports the option of
- writing for this object for site-specific administration of
- device inventory or tracking."
- ::= { prtGeneralEntry 17 }
-
--- General alert table section (Alert Table V2 Group)
---
--- The following two objects are used to specify counters
--- associated with the Alert Table.
-
-prtAlertCriticalEvents OBJECT-TYPE
- SYNTAX Counter32
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A running counter of the number of critical alert events that
- have been recorded in the alert table. The value of this object
- is RESET in the event of a power cycle operation (i.e., the
- value is not persistent."
- ::= { prtGeneralEntry 18 }
-
-prtAlertAllEvents OBJECT-TYPE
- SYNTAX Counter32
- MAX-ACCESS read-only
- STATUS current
-
-
-
-Bergman, et al. Standards Track [Page 74]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- DESCRIPTION
- "A running counter of the total number of alert event entries
- (critical and non-critical) that have been recorded in the
- alert table"
- ::= { prtGeneralEntry 19 }
-
--- The Cover Table
---
--- The cover portion of the General print sub-unit describes the
--- covers and interlocks of the printer. The Cover Table has an
--- entry for each cover and interlock.
-
-prtCover OBJECT IDENTIFIER ::= { printmib 6 }
-
-prtCoverTable OBJECT-TYPE
- SYNTAX SEQUENCE OF PrtCoverEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A table of the covers and interlocks of the printer."
- ::= { prtCover 1 }
-
-prtCoverEntry OBJECT-TYPE
- SYNTAX PrtCoverEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "Information about a cover or interlock.
- Entries may exist in the table for each device
- index with a device type of 'printer'.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- INDEX { hrDeviceIndex, prtCoverIndex }
- ::= { prtCoverTable 1 }
-
-PrtCoverEntry ::= SEQUENCE {
- prtCoverIndex Integer32,
- prtCoverDescription PrtLocalizedDescriptionStringTC,
- prtCoverStatus PrtCoverStatusTC
- }
-
-prtCoverIndex OBJECT-TYPE
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A unique value used by the printer to identify this Cover sub
-
-
-
-Bergman, et al. Standards Track [Page 75]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- unit. Although these values may change due to a major
- reconfiguration of the device (e.g., the addition of new cover
- sub-units to the printer), values SHOULD remain stable across
- successive printer power cycles.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtCoverEntry 1 }
-
-prtCoverDescription OBJECT-TYPE
- -- In RFC 1759, the SYNTAX was OCTET STRING. This has been changed
- -- to a TC to better support localization of the object.
- SYNTAX PrtLocalizedDescriptionStringTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The manufacturer provided cover sub-mechanism name in the
- localization specified by prtGeneralCurrentLocalization."
- ::= { prtCoverEntry 2 }
-
-prtCoverStatus OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly defined
- -- by this object and are now defined in the IANA-PRINTER-MIB. The
- -- new TC has defined "coverOpen" and "coverClosed" to replace
- -- "doorOpen" and "doorClosed" in RFC 1759. A name change is not
- -- formally allowed per SMI rules, but was agreed to by the WG group
- -- since a door has a more restrictive meaning than a cover and
- -- Cover group is intended to support doors as a subset of covers.
-
- SYNTAX PrtCoverStatusTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The status of this cover sub-unit."
- ::= { prtCoverEntry 3 }
-
--- The Localization Table
---
--- The localization portion of the General printer sub-unit is
--- responsible for identifying the natural language, country, and
--- character set in which character strings are expressed. There
--- may be one or more localizations supported per printer. The
--- available localizations are represented by the Localization
--- table.
-
-prtLocalization OBJECT IDENTIFIER ::= { printmib 7 }
-
-prtLocalizationTable OBJECT-TYPE
-
-
-
-Bergman, et al. Standards Track [Page 76]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- SYNTAX SEQUENCE OF PrtLocalizationEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The available localizations in this printer."
- ::= { prtLocalization 1 }
-
-prtLocalizationEntry OBJECT-TYPE
- SYNTAX PrtLocalizationEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A description of a localization.
- Entries may exist in the table for each device
- index with a device type of 'printer'.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- INDEX { hrDeviceIndex, prtLocalizationIndex }
- ::= { prtLocalizationTable 1 }
-
-PrtLocalizationEntry ::= SEQUENCE {
- prtLocalizationIndex Integer32,
- prtLocalizationLanguage OCTET STRING,
- prtLocalizationCountry OCTET STRING,
- prtLocalizationCharacterSet IANACharset
- }
-
-prtLocalizationIndex OBJECT-TYPE
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A unique value used by the printer to identify this
- localization entry. Although these values may change due to a
- major reconfiguration of the device (e.g., the addition of new
- localization data to the printer), values SHOULD remain
- stable across successive printer power cycles.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtLocalizationEntry 1 }
-
-prtLocalizationLanguage OBJECT-TYPE
- -- Note: The size is fixed, was incorrectly 0..2 in RFC 1759.
- SYNTAX OCTET STRING (SIZE(2))
- MAX-ACCESS read-only
- STATUS current
-
-
-
-Bergman, et al. Standards Track [Page 77]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- DESCRIPTION
- "A two character language code from ISO 639. Examples en,
- es, fr, de. NOTE: These examples were shown as upper case in
- RFC 1759 and are now shown as lower case to agree with ISO 639."
- ::= { prtLocalizationEntry 2 }
-
-prtLocalizationCountry OBJECT-TYPE
- -- Note: The size is fixed, was incorrectly 0..2 in RFC 1759.
- SYNTAX OCTET STRING (SIZE(2))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A two character country code from ISO 3166, a blank string
- (two space characters) shall indicate that the country is not
- defined. Examples: US, GB, FR, DE, ..."
- ::= { prtLocalizationEntry 3 }
-
-prtLocalizationCharacterSet OBJECT-TYPE
- SYNTAX IANACharset
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The coded character set used for this localization."
- ::= { prtLocalizationEntry 4 }
-
--- The System Resources Tables
---
--- The Printer MIB makes use of the Host Resources MIB to
--- define system resources by referencing the storage
--- and device groups of the print group.
-
-prtStorageRefTable OBJECT-TYPE
- SYNTAX SEQUENCE OF PrtStorageRefEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "This table defines which printer, amongst multiple printers
- serviced by one agent, owns which storage units.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtGeneral 2 }
-
-prtStorageRefEntry OBJECT-TYPE
- SYNTAX PrtStorageRefEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
-
-
-
-Bergman, et al. Standards Track [Page 78]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- "This table will have an entry for each entry in the Host
- Resources MIB storage table that represents storage associated
- with a printer managed by this agent.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- INDEX { hrStorageIndex, prtStorageRefSeqNumber }
- ::= { prtStorageRefTable 1 }
-
-PrtStorageRefEntry ::= SEQUENCE {
- prtStorageRefSeqNumber Integer32,
- prtStorageRefIndex Integer32
- }
-
-prtStorageRefSeqNumber OBJECT-TYPE
- -- NOTE: The range has been changed from RFC 1759, which allowed a
- -- minumum value of zero. This was incorrect, since zero is not a
- -- valid index.
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "This value will be unique amongst all entries with a common
- value of hrStorageIndex. This object allows a storage entry to
- point to the multiple printer devices with which it is
- associated."
- ::= { prtStorageRefEntry 1 }
-
-prtStorageRefIndex OBJECT-TYPE
- -- NOTE: The range has been changed from RFC 1759 to be compatible
- -- with the defined range of hrDeviceIndex.
- SYNTAX Integer32 (0..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The value of the hrDeviceIndex of the printer device that this
- storageEntry is associated with."
- ::= { prtStorageRefEntry 2 }
-
-prtDeviceRefTable OBJECT-TYPE
- SYNTAX SEQUENCE OF PrtDeviceRefEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "This table defines which printer, amongst multiple printers
- serviced by one agent, is associated with which devices.
-
- NOTE: The above description has been modified from RFC 1759
-
-
-
-Bergman, et al. Standards Track [Page 79]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- for clarification."
- ::= { prtGeneral 3 }
-
-prtDeviceRefEntry OBJECT-TYPE
- SYNTAX PrtDeviceRefEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "This table will have an entry for each entry in the Host
- Resources MIB device table that represents a device associated
- with a printer managed by this agent.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- INDEX { hrDeviceIndex, prtDeviceRefSeqNumber }
- ::= { prtDeviceRefTable 1 }
-
-PrtDeviceRefEntry ::= SEQUENCE {
- prtDeviceRefSeqNumber Integer32,
- prtDeviceRefIndex Integer32
- }
-
-prtDeviceRefSeqNumber OBJECT-TYPE
- -- NOTE: The range has been changed from RFC 1759, which allowed a
- -- minumum value of zero. This was incorrect, since zero is not a
- -- valid index.
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "This value will be unique amongst all entries with a common
- value of hrDeviceIndex. This object allows a device entry to
- point to the multiple printer devices with which it is
- associated."
- ::= { prtDeviceRefEntry 1 }
-
-prtDeviceRefIndex OBJECT-TYPE
- -- NOTE: The range has been changed from RFC 1759 to be compatible
- -- with the defined range of hrDeviceIndex.
- SYNTAX Integer32 (0..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The value of the hrDeviceIndex of the printer device that this
- deviceEntry is associated with."
- ::= { prtDeviceRefEntry 2 }
-
-
-
-
-
-Bergman, et al. Standards Track [Page 80]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
--- The Input Group
---
--- Input sub-units are managed as a tabular, indexed collection
--- of possible devices capable of providing media for input to
--- the printing process. Input sub-units typically have a
--- location, a type, an identifier, a set of constraints on
--- possible media sizes and potentially other media
--- characteristics, and may be capable of indicating current
--- status or capacity.
-
-prtInput OBJECT IDENTIFIER ::= { printmib 8 }
-
-prtInputTable OBJECT-TYPE
- SYNTAX SEQUENCE OF PrtInputEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A table of the devices capable of providing media for input to
- the printing process."
- ::= { prtInput 2 }
-
-prtInputEntry OBJECT-TYPE
- SYNTAX PrtInputEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "Attributes of a device capable of providing media for input to
- the printing process. Entries may exist in the table for each
- device index with a device type of 'printer'.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- INDEX { hrDeviceIndex, prtInputIndex }
- ::= { prtInputTable 1 }
-
-PrtInputEntry ::= SEQUENCE {
- prtInputIndex Integer32,
- prtInputType PrtInputTypeTC,
- prtInputDimUnit PrtMediaUnitTC,
- prtInputMediaDimFeedDirDeclared Integer32,
- prtInputMediaDimXFeedDirDeclared Integer32,
- prtInputMediaDimFeedDirChosen Integer32,
- prtInputMediaDimXFeedDirChosen Integer32,
- prtInputCapacityUnit PrtCapacityUnitTC,
- prtInputMaxCapacity Integer32,
- prtInputCurrentLevel Integer32,
- prtInputStatus PrtSubUnitStatusTC,
- prtInputMediaName OCTET STRING,
-
-
-
-Bergman, et al. Standards Track [Page 81]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- prtInputName OCTET STRING,
- prtInputVendorName OCTET STRING,
- prtInputModel OCTET STRING,
- prtInputVersion OCTET STRING,
- prtInputSerialNumber OCTET STRING,
- prtInputDescription PrtLocalizedDescriptionStringTC,
- prtInputSecurity PresentOnOff,
- prtInputMediaWeight Integer32,
- prtInputMediaType OCTET STRING,
- prtInputMediaColor OCTET STRING,
- prtInputMediaFormParts Integer32,
- prtInputMediaLoadTimeout Integer32,
- prtInputNextIndex Integer32
- }
-
-prtInputIndex OBJECT-TYPE
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A unique value used by the printer to identify this input
- sub-unit. Although these values may change due to a major
- reconfiguration of the device (e.g., the addition of new input
- sub-units to the printer), values SHOULD remain stable across
- successive printer power cycles.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtInputEntry 1 }
-
-prtInputType OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtInputTypeTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The type of technology (discriminated primarily according to
- feeder mechanism type) employed by the input sub-unit. Note,
- the Input Class provides for a descriptor field to further
- qualify the other choice."
- ::= { prtInputEntry 2 }
-
-prtInputDimUnit OBJECT-TYPE
- SYNTAX PrtMediaUnitTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
-
-
-
-Bergman, et al. Standards Track [Page 82]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- "The unit of measurement for use calculating and relaying
- dimensional values for this input sub-unit."
- ::= { prtInputEntry 3 }
-
-prtInputMediaDimFeedDirDeclared OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "This object provides the value of the declared dimension, in
- the feed direction, of the media that is (or, if empty, was or
- will be) in this input sub-unit. The feed direction is the
- direction in which the media is fed on this sub-unit. This
- dimension is measured in input sub-unit dimensional units
- (controlled by prtInputDimUnit, which uses PrtMediaUnitTC). If
- this input sub-unit can reliably sense this value, the value is
- sensed by the printer and may not be changed by management
- requests. Otherwise, the value may be changed. The value (-1)
- means other and specifically means that this sub-unit places no
- restriction on this parameter. The value (-2) indicates
- unknown."
- ::= { prtInputEntry 4 }
-
-prtInputMediaDimXFeedDirDeclared OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "This object provides the value of the declared dimension, in
- the cross feed direction, of the media that is (or, if empty,
- was or will be) in this input sub-unit. The cross feed
- direction is ninety degrees relative to the feed direction
- associated with this sub-unit. This dimension is measured in
- input sub-unit dimensional units (controlled by
- prtInputDimUnit,which uses PrtMediaUnitTC). If this input sub-
- unit can reliably sense this value, the value is sensed by the
- printer and may not be changed by management requests.
- Otherwise, the value may be changed. The value (-1) means other
- and specifically means that this sub-unit places no restriction
- on this parameter. The value (-2) indicates unknown."
- ::= { prtInputEntry 5 }
-
-prtInputMediaDimFeedDirChosen OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-only
-
-
-
-Bergman, et al. Standards Track [Page 83]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- STATUS current
- DESCRIPTION
- "The printer will act as if media of the chosen dimension (in
- the feed direction) is present in this input source. Note that
- this value will be used even if the input tray is empty. Feed
- dimension measurements are taken relative to the feed direction
- associated with that sub-unit and are in input sub-unit
- dimensional units (controlled by prtInputDimUnit, which uses
- PrtMediaUnitTC). If the printer supports the declared
- dimension,the granted dimension is the same as the declared
- dimension. If not, the granted dimension is set to the closest
- dimension that the printer supports when the declared dimension
- is set. The value (-1) means other and specifically indicates
- that this sub-unit places no restriction on this parameter. The
- value (-2)indicates unknown."
- ::= { prtInputEntry 6 }
-
-prtInputMediaDimXFeedDirChosen OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The printer will act as if media of the chosen dimension (in
- the cross feed direction) is present in this input source. Note
- that this value will be used even if the input tray is empty.
- The cross feed direction is ninety degrees relative to the feed
- direction associated with this sub-unit. This dimension is
- measured in input sub-unit dimensional units (controlled by
- prtInputDimUnit, which uses PrtMediaUnitTC). If the printer
- supports the declare dimension, the granted dimension is the
- same as the declared dimension. If not, the granted dimension
- is set to the closest dimension that the printer supports when
- the declared dimension is set. The value (-1) means other and
- specifically indicates that this sub-unit places no restriction
- on this parameter. The value (-2) indicates unknown."
- ::= { prtInputEntry 7 }
-
-prtInputCapacityUnit OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtCapacityUnitTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The unit of measurement for use in calculating and relaying
- capacity values for this input sub-unit."
- ::= { prtInputEntry 8 }
-
-
-
-Bergman, et al. Standards Track [Page 84]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-prtInputMaxCapacity OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The maximum capacity of the input sub-unit in input sub-unit
- capacity units (PrtCapacityUnitTC). There is no convention
- associated with the media itself so this value reflects claimed
- capacity. If this input sub-unit can reliably sense this value,
- the value is sensed by the printer and may not be changed by
- management requests; otherwise, the value may be written (by a
- Remote Control Panel or a Management Application). The value
- (-1) means other and specifically indicates that the sub-unit
- places no restrictions on this parameter. The value (-2) means
- unknown."
- ::= { prtInputEntry 9 }
-
-prtInputCurrentLevel OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-3..2147483647) -- in capacity units
- -- (PrtCapacityUnitTC).
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The current capacity of the input sub-unit in input sub-unit
- capacity units (PrtCapacityUnitTC). If this input sub-unit can
- reliably sense this value, the value is sensed by the printer
- and may not be changed by management requests; otherwise, the
- value may be written (by a Remote Control Panel or a Management
- Application). The value (-1) means other and specifically
- indicates that the sub-unit places no restrictions on this
- parameter. The value (-2) means unknown. The value (-3) means
- that the printer knows that at least one unit remains."
- ::= { prtInputEntry 10 }
-
-prtInputStatus OBJECT-TYPE
- SYNTAX PrtSubUnitStatusTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The current status of this input sub-unit."
- ::= { prtInputEntry 11 }
-
-prtInputMediaName OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..63))
- MAX-ACCESS read-write
- STATUS current
-
-
-
-Bergman, et al. Standards Track [Page 85]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- DESCRIPTION
- "A description of the media contained in this input sub-unit;
- This description is to be used by a client to format and
- Localize a string for display to a human operator. This
- description is not processed by the printer. It is used to
- provide information not expressible in terms of the other
- media attributes (e.g., prtInputMediaDimFeedDirChosen,
- prtInputMediaDimXFeedDirChosen, prtInputMediaWeight,
- prtInputMediaType)."
- -- The following reference was not included in RFC 1759.
- REFERENCE
- "The PWG Standardized Media Names specification [PWGMEDIA]
- contains the recommended values for this object. See also
- RFC 3805 Appendix C,'Media Names', which lists the values
- Of standardized media names defined in ISO/IEC 10175."
- ::= { prtInputEntry 12 }
-
--- INPUT MEASUREMENT
---
--- _______ | |
--- ^ | |
--- | | | |
--- | |_ _ _ _ _ _ _ _| _______________ |direction
--- | | | ^ v
--- MaxCapacity | Sheets | |
--- | | left | CurrentLevel
--- | | in | |
--- v | tray | v
--- _______ +_______________+ _______
-
--- The Extended Input Group
-
-prtInputName OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..63))
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The name assigned to this input sub-unit."
- ::= { prtInputEntry 13 }
-
-prtInputVendorName OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..63))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The vendor name of this input sub-unit."
- ::= { prtInputEntry 14 }
-
-
-
-
-Bergman, et al. Standards Track [Page 86]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-prtInputModel OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..63))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The model name of this input sub-unit."
- ::= { prtInputEntry 15 }
-
-prtInputVersion OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..63))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The version of this input sub-unit."
- ::= { prtInputEntry 16 }
-
-prtInputSerialNumber OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..32))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The serial number assigned to this input sub-unit."
- ::= { prtInputEntry 17 }
-
-prtInputDescription OBJECT-TYPE
- -- In RFC 1759, the SYNTAX was OCTET STRING. This has been changed
- -- to a TC to better support localization of the object.
- SYNTAX PrtLocalizedDescriptionStringTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A free-form text description of this input sub-unit in the
- localization specified by prtGeneralCurrentLocalization."
- ::= { prtInputEntry 18 }
-
-prtInputSecurity OBJECT-TYPE
- SYNTAX PresentOnOff
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "Indicates if this input sub-unit has some security associated
- with it."
- ::= { prtInputEntry 19 }
-
--- The Input Media Group
---
--- The Input Media Group supports identification of media
--- installed or available for use on a printing device.
-
-
-
-Bergman, et al. Standards Track [Page 87]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
--- Medium resources are identified by name, and include a
--- collection of characteristic attributes that may further be
--- used for selection and management of them.
--- The Input Media group consists of a set of optional
--- "columns" in the Input Table. In this manner, a minimally
--- conforming implementation may choose to not support reporting
--- of media resources if it cannot do so.
-
-prtInputMediaWeight OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The weight of the medium associated with this input sub-unit
- in grams / per meter squared. The value (-2) means unknown."
- ::= { prtInputEntry 20 }
-
-prtInputMediaType OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..63))
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The name of the type of medium associated with this input sub
- unit. This name need not be processed by the printer; it might
- simply be displayed to an operator.
-
- NOTE: The above description has been modified from RFC 1759."
- -- The following reference was not included in RFC 1759.
- REFERENCE
- "The PWG Standardized Media Names specification [PWGMEDIA],
- section 3 Media Type Names, contains the recommended values for
- this object. Implementers may add additional string values.
- The naming conventions in ISO 9070 are recommended in order to
- avoid potential name clashes."
- ::= { prtInputEntry 21 }
-
-prtInputMediaColor OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..63))
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The name of the color of the medium associated with
- this input sub-unit using standardized string values.
-
- NOTE: The above description has been modified from RFC 1759."
- -- The following reference was not included in RFC 1759.
- REFERENCE
-
-
-
-Bergman, et al. Standards Track [Page 88]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- "The PWG Standardized Media Names specification [PWGMEDIA],
- section 4 Media Color Names, contains the recommended values
- for this object. Implementers may add additional string values.
- The naming conventions in ISO 9070 are recommended in order to
- avoid potential name clashes."
- ::= { prtInputEntry 22 }
-
-prtInputMediaFormParts OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The number of parts associated with the medium
- associated with this input sub-unit if the medium is a
- multi-part form. The value (-1) means other and
- specifically indicates that the device places no
- restrictions on this parameter. The value (-2) means
- unknown."
- ::= { prtInputEntry 23 }
-
--- The Input Switching Group
---
--- The input switching group allows the administrator to set the
--- input subunit time-out for the printer and to control the
--- automatic input subunit switching by the printer when an input
--- subunit becomes empty.
-
-prtInputMediaLoadTimeout OBJECT-TYPE
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "When the printer is not able to print due to a subunit being
- empty or the requested media must be manually loaded, the
- printer will wait for the duration (in seconds) specified by
- this object. Upon expiration of the time-out, the printer will
- take the action specified by prtInputNextIndex.
-
- The event which causes the printer to enter the waiting state
- is product specific. If the printer is not waiting for manually
- fed media, it may switch from an empty subunit to a different
- subunit without waiting for the time-out to expire.
-
- A value of (-1) implies 'other' or 'infinite' which translates
- to 'wait forever'. The action which causes printing to continue
- is product specific. A value of (-2) implies 'unknown'."
- ::= { prtInputEntry 24 }
-
-
-
-Bergman, et al. Standards Track [Page 89]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-prtInputNextIndex OBJECT-TYPE
- SYNTAX Integer32 (-3..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The value of prtInputIndex corresponding to the input subunit
- which will be used when this input subunit is emptied and the
- time-out specified by prtInputMediaLoadTimeout expires. A value
- of zero(0) indicates that auto input switching will not occur
- when this input subunit is emptied. If the time-out specified
- by prtInputLoadMediaTimeout expires and this value is zero(0),
- the job will be aborted. A value of (-1) means other. The
- value (-2)means 'unknown' and specifically indicates that an
- implementation specific method will determine the next input
- subunit to use at the time this subunit is emptied and the time
- out expires. The value(-3) means input switching is not
- supported for this subunit."
- ::= { prtInputEntry 25 }
-
--- The Output Group
---
--- Output sub-units are managed as a tabular, indexed collection
--- of possible devices capable of receiving media delivered from
--- the printing process. Output sub-units typically have a
--- location, a type, an identifier, a set of constraints on
--- possible media sizes and potentially other characteristics,
--- and may be capable of indicating current status or capacity.
-
-prtOutput OBJECT IDENTIFIER ::= { printmib 9 }
-
-prtOutputTable OBJECT-TYPE
- SYNTAX SEQUENCE OF PrtOutputEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A table of the devices capable of receiving media delivered
- from the printing process."
- ::= { prtOutput 2 }
-
-prtOutputEntry OBJECT-TYPE
- SYNTAX PrtOutputEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "Attributes of a device capable of receiving media delivered
- from the printing process. Entries may exist in the table for
- each device index with a device type of 'printer'.
-
-
-
-
-Bergman, et al. Standards Track [Page 90]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- INDEX { hrDeviceIndex, prtOutputIndex }
- ::= { prtOutputTable 1 }
-
-PrtOutputEntry ::= SEQUENCE {
- prtOutputIndex Integer32,
- prtOutputType PrtOutputTypeTC,
- prtOutputCapacityUnit PrtCapacityUnitTC,
- prtOutputMaxCapacity Integer32,
- prtOutputRemainingCapacity Integer32,
- prtOutputStatus PrtSubUnitStatusTC,
- prtOutputName OCTET STRING,
- prtOutputVendorName OCTET STRING,
- prtOutputModel OCTET STRING,
- prtOutputVersion OCTET STRING,
- prtOutputSerialNumber OCTET STRING,
- prtOutputDescription PrtLocalizedDescriptionStringTC,
- prtOutputSecurity PresentOnOff,
- prtOutputDimUnit PrtMediaUnitTC,
- prtOutputMaxDimFeedDir Integer32,
- prtOutputMaxDimXFeedDir Integer32,
- prtOutputMinDimFeedDir Integer32,
- prtOutputMinDimXFeedDir Integer32,
- prtOutputStackingOrder PrtOutputStackingOrderTC,
- prtOutputPageDeliveryOrientation
- PrtOutputPageDeliveryOrientationTC,
- prtOutputBursting PresentOnOff,
- prtOutputDecollating PresentOnOff,
- prtOutputPageCollated PresentOnOff,
- prtOutputOffsetStacking PresentOnOff
- }
-
-prtOutputIndex OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A unique value used by this printer to identify this output
- sub-unit. Although these values may change due to a major
- reconfiguration of the sub-unit (e.g., the addition of new
- output devices to the printer), values SHOULD remain stable
- across successive printer power cycles.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtOutputEntry 1 }
-
-
-
-Bergman, et al. Standards Track [Page 91]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-prtOutputType OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly defined
- -- by this object.
- SYNTAX PrtOutputTypeTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The type of technology supported by this output sub-unit."
- ::= { prtOutputEntry 2 }
-
-prtOutputCapacityUnit OBJECT-TYPE
- SYNTAX PrtCapacityUnitTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The unit of measurement for use in calculating and relaying
- capacity values for this output sub-unit."
- ::= { prtOutputEntry 3 }
-
-prtOutputMaxCapacity OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The maximum capacity of this output sub-unit in output sub-
- unit capacity units (PrtCapacityUnitTC). There is no convention
- associated with the media itself so this value essentially
- reflects claimed capacity. If this output sub-unit can reliably
- sense this value, the value is sensed by the printer and may
- not be changed by management requests; otherwise, the value may
- be written (by a Remote Control Panel or a Management
- Application). The value (-1) means other and specifically
- indicates that the sub-unit places no restrictions on this
- parameter. The value (-2) means unknown."
- ::= { prtOutputEntry 4 }
-
-prtOutputRemainingCapacity OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-3..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The remaining capacity of the possible output sub-unit
- capacity in output sub-unit capacity units
- (PrtCapacityUnitTC)of this output sub-unit. If this output sub-
- unit can reliably sense this value, the value is sensed by the
- printer and may not be modified by management requests;
-
-
-
-Bergman, et al. Standards Track [Page 92]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- otherwise, the value may be written (by a Remote Control Panel
- or a Management Application). The value (-1) means other and
- specifically indicates that the sub-unit places no restrictions
- on this parameter. The value (-2) means unknown. The value
- (-3) means that the printer knows that there remains capacity
- for at least one unit."
- ::= { prtOutputEntry 5 }
-
-prtOutputStatus OBJECT-TYPE
- SYNTAX PrtSubUnitStatusTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The current status of this output sub-unit."
- ::= { prtOutputEntry 6 }
-
--- OUTPUT MEASUREMENT
---
--- _______ | | ________
--- ^ | | ^
--- | | | |
--- | | |RemainingCapacity
--- MaxCapacity| | |
--- | | | v ^
--- | |_ _ _ _ _ _ _ _ | _______________ |direction
--- | | Sheets | |
--- | | in |
--- v | Output |
--- _______ +________________+
-
--- The Extended Output Group
-
-prtOutputName OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..63))
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The name assigned to this output sub-unit."
- ::= { prtOutputEntry 7 }
-
-prtOutputVendorName OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..63))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The vendor name of this output sub-unit."
- ::= { prtOutputEntry 8 }
-
-
-
-
-Bergman, et al. Standards Track [Page 93]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-prtOutputModel OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..63))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The model name assigned to this output sub-unit.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtOutputEntry 9 }
-
-prtOutputVersion OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..63))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The version of this output sub-unit."
- ::= { prtOutputEntry 10 }
-
-prtOutputSerialNumber OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..63))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The serial number assigned to this output sub-unit."
- ::= { prtOutputEntry 11 }
-
-prtOutputDescription OBJECT-TYPE
- -- In RFC 1759, the SYNTAX was OCTET STRING. This has been changed
- -- to a TC to better support localization of the object.
- SYNTAX PrtLocalizedDescriptionStringTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A free-form text description of this output sub-unit in the
- localization specified by prtGeneralCurrentLocalization."
- ::= { prtOutputEntry 12 }
-
-prtOutputSecurity OBJECT-TYPE
- SYNTAX PresentOnOff
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "Indicates if this output sub-unit has some security associated
- with it and if that security is enabled or not."
- ::= { prtOutputEntry 13 }
-
-
-
-
-
-Bergman, et al. Standards Track [Page 94]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
--- The Output Dimensions Group
-
-prtOutputDimUnit OBJECT-TYPE
- SYNTAX PrtMediaUnitTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The unit of measurement for use in calculating and relaying
- dimensional values for this output sub-unit."
- ::= { prtOutputEntry 14 }
-
-prtOutputMaxDimFeedDir OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The maximum dimensions supported by this output sub-unit
- for measurements taken parallel relative to the feed
- direction associated with that sub-unit in output
- sub-unit dimensional units (controlled by prtOutputDimUnit,
- which uses PrtMediaUnitTC). If this output sub-unit can
- reliably sense this value, the value is sensed by the printer
- and may not be changed with management protocol operations.
- The value (-1) means other and specifically indicates that the
- sub-unit places no restrictions on this parameter. The value
- (-2) means unknown.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification and to explain the purpose of (-1) and (-2)."
- ::= { prtOutputEntry 15 }
-
-prtOutputMaxDimXFeedDir OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The maximum dimensions supported by this output sub-unit
- for measurements taken ninety degrees relative to the
- feed direction associated with that sub-unit in output
- sub-unit dimensional units (controlled by prtOutputDimUnit,
- which uses PrtMediaUnitTC). If this output sub-unit can
- reliably sense this value, the value is sensed by the printer
- and may not be changed with management protocol operations.
- The value (-1) means other and specifically indicates that the
- sub-unit places no restrictions on this parameter. The value
- (-2) means unknown.
-
-
-
-Bergman, et al. Standards Track [Page 95]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- NOTE: The above description has been modified from RFC 1759
- for clarification and to explain the purpose of (-1) and (-2)."
- ::= { prtOutputEntry 16 }
-
-prtOutputMinDimFeedDir OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The minimum dimensions supported by this output sub-unit
- for measurements taken parallel relative to the feed
- direction associated with that sub-unit in output
- sub-unit dimensional units (controlled by prtOutputDimUnit,
- which uses PrtMediaUnitTC). If this output sub-unit can
- reliably sense this value, the value is sensed by the printer
- and may not be changed with management protocol operations.
- The value (-1) means other and specifically indicates that the
- sub-unit places no restrictions on this parameter. The value
- (-2) means unknown.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification and to explain the purpose of (-1) and (-2)."
- ::= { prtOutputEntry 17 }
-
-prtOutputMinDimXFeedDir OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The minimum dimensions supported by this output sub-unit
- for measurements taken ninety degrees relative to the
- feed direction associated with that sub-unit in output
- sub-unit dimensional units (controlled by prtOutputDimUnit,
- which uses PrtMediaUnitTC). If this output sub-unit can
- reliably sense this value, the value is sensed by the printer
- and may not be changed with management protocol operations.
- The value (-1) means other and specifically indicates that the
- sub-unit places no restrictions on this parameter. The value
- (-2) means unknown.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification and to explain the purpose of (-1) and (-2)."
- ::= { prtOutputEntry 18 }
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 96]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
--- The Output Features Group
-
-prtOutputStackingOrder OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtOutputStackingOrderTC
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The current state of the stacking order for the
- associated output sub-unit. 'FirstToLast' means
- that as pages are output the front of the next page is
- placed against the back of the previous page.
- 'LasttoFirst' means that as pages are output the back
- of the next page is placed against the front of the
- previous page."
- ::= { prtOutputEntry 19 }
-
-prtOutputPageDeliveryOrientation OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtOutputPageDeliveryOrientationTC
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The reading surface that will be 'up' when pages are
- delivered to the associated output sub-unit. Values are
- faceUp and faceDown. (Note: interpretation of these
- values is in general context-dependent based on locale;
- presentation of these values to an end-user should be
- normalized to the expectations of the user)."
- ::= { prtOutputEntry 20 }
-
-prtOutputBursting OBJECT-TYPE
- SYNTAX PresentOnOff
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "This object indicates that the outputting sub-unit supports
- bursting, and if so, whether the feature is enabled. Bursting
- is the process by which continuous media is separated into
- individual sheets, typically by bursting along pre-formed
- perforations."
- ::= { prtOutputEntry 21 }
-
-prtOutputDecollating OBJECT-TYPE
- SYNTAX PresentOnOff
- MAX-ACCESS read-write
-
-
-
-Bergman, et al. Standards Track [Page 97]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- STATUS current
- DESCRIPTION
- "This object indicates that the output supports decollating,
- and if so, whether the feature is enabled. Decollating is the
- process by which the individual parts within a multi-part form
- are separated and sorted into separate stacks for each part."
- ::= { prtOutputEntry 22 }
-
-prtOutputPageCollated OBJECT-TYPE
- SYNTAX PresentOnOff
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "This object indicates that the output sub-unit supports page
- collation, and if so, whether the feature is enabled. See RFC
- 3805 Appendix A, Glossary Of Terms, for definition of how this
- document defines collation.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtOutputEntry 23 }
-
-prtOutputOffsetStacking OBJECT-TYPE
- SYNTAX PresentOnOff
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "This object indicates that the output supports offset
- stacking,and if so, whether the feature is enabled. See RFC
- 3805 Appendix A, Glossary Of Terms, for how Offset Stacking is
- defined by this document.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtOutputEntry 24 }
-
--- The Marker Group
---
--- A marker is the mechanism that produces marks on the print
--- media. The marker sub-units and their associated supplies are
--- represented by the Marker Group in the model. A printer can
--- contain one or more marking mechanisms. Some examples of
--- multiple marker sub-units are: a printer
--- with separate markers for normal and magnetic ink or an
--- imagesetter that can output to both a proofing device and
--- final film. Each marking device can have its own set of
--- characteristics associated with it, such as marking technology
--- and resolution.
-
-
-
-Bergman, et al. Standards Track [Page 98]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-prtMarker OBJECT IDENTIFIER ::= { printmib 10 }
-
--- The printable area margins as listed below define an area of
--- the print media which is guaranteed to be printable for all
--- combinations of input, media paths, and interpreters for this
--- marker.
-
-prtMarkerTable OBJECT-TYPE
- SYNTAX SEQUENCE OF PrtMarkerEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The marker table provides a description of each marker
- sub-unit contained within the printer.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMarker 2 }
-
-prtMarkerEntry OBJECT-TYPE
- SYNTAX PrtMarkerEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "Entries in this table define the characteristics and status
- of each marker sub-unit in the printer.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- INDEX { hrDeviceIndex, prtMarkerIndex }
- ::= { prtMarkerTable 1 }
-
-PrtMarkerEntry ::= SEQUENCE {
- prtMarkerIndex Integer32,
- prtMarkerMarkTech PrtMarkerMarkTechTC,
- prtMarkerCounterUnit PrtMarkerCounterUnitTC,
- prtMarkerLifeCount Counter32,
- prtMarkerPowerOnCount Counter32,
- prtMarkerProcessColorants Integer32,
- prtMarkerSpotColorants Integer32,
- prtMarkerAddressabilityUnit PrtMarkerAddressabilityUnitTC,
- prtMarkerAddressabilityFeedDir Integer32,
- prtMarkerAddressabilityXFeedDir Integer32,
- prtMarkerNorthMargin Integer32,
- prtMarkerSouthMargin Integer32,
- prtMarkerWestMargin Integer32,
- prtMarkerEastMargin Integer32,
- prtMarkerStatus PrtSubUnitStatusTC
-
-
-
-Bergman, et al. Standards Track [Page 99]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- }
-
-prtMarkerIndex OBJECT-TYPE
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A unique value used by the printer to identify this marking
- SubUnit. Although these values may change due to a major
- reconfiguration of the device (e.g., the addition of new marking
- sub-units to the printer), values SHOULD remain stable across
- successive printer power cycles.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMarkerEntry 1 }
-
-prtMarkerMarkTech OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtMarkerMarkTechTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The type of marking technology used for this marking
- sub-unit."
- ::= { prtMarkerEntry 2 }
-
-prtMarkerCounterUnit OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtMarkerCounterUnitTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The unit that will be used by the printer when reporting
- counter values for this marking sub-unit. The time units of
- measure are provided for a device like a strip recorder that
- does not or cannot track the physical dimensions of the media
- and does not use characters, lines or sheets."
- ::= { prtMarkerEntry 3 }
-
-prtMarkerLifeCount OBJECT-TYPE
- SYNTAX Counter32
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The count of the number of units of measure counted during the
-
-
-
-Bergman, et al. Standards Track [Page 100]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- life of printer using units of measure as specified by
- prtMarkerCounterUnit.
-
- Note: This object should be implemented as a persistent object
- with a reliable value throughout the lifetime of the printer."
- ::= { prtMarkerEntry 4 }
-
-prtMarkerPowerOnCount OBJECT-TYPE
- SYNTAX Counter32
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The count of the number of units of measure counted since the
- equipment was most recently powered on using units of measure
- as specified by prtMarkerCounterUnit."
- ::= { prtMarkerEntry 5 }
-
-prtMarkerProcessColorants OBJECT-TYPE
- SYNTAX Integer32 (0..65535)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The number of process colors supported by this marker. A
- process color of 1 implies monochrome. The value of this
- object and prtMarkerSpotColorants cannot both be 0. The value
- of prtMarkerProcessColorants must be 0 or greater.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMarkerEntry 6 }
-
-prtMarkerSpotColorants OBJECT-TYPE
- SYNTAX Integer32 (0..65535)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The number of spot colors supported by this marker. The value
- of this object and prtMarkerProcessColorants cannot both be 0.
- Must be 0 or greater.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMarkerEntry 7 }
-
-prtMarkerAddressabilityUnit OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtMarkerAddressabilityUnitTC
-
-
-
-Bergman, et al. Standards Track [Page 101]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The unit of measure of distances, as applied to the marker's
- resolution.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMarkerEntry 8 }
-
-prtMarkerAddressabilityFeedDir OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The maximum number of addressable marking positions in the
- feed direction per 10000 units of measure specified by
- prtMarkerAddressabilityUnit. A value of (-1) implies 'other'
- or 'infinite' while a value of (-2) implies 'unknown'.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMarkerEntry 9 }
-
-prtMarkerAddressabilityXFeedDir OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The maximum number of addressable marking positions in the
- cross feed direction in 10000 units of measure specified by
- prtMarkerAddressabilityUnit. A value of (-1) implies 'other'
- or 'infinite' while a value of (-2) implies 'unknown'.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMarkerEntry 10 }
-
-prtMarkerNorthMargin OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The margin, in units identified by prtMarkerAddressabilityUnit,
- from the leading edge of the medium as the medium flows through
-
-
-
-Bergman, et al. Standards Track [Page 102]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- the marking engine with the side to be imaged facing the
- observer. The leading edge is the North edge and the other
- edges are defined by the normal compass layout of directions
- with the compass facing the observer. Printing within the area
- bounded by all four margins is guaranteed for all interpreters.
- The value (-2) means unknown."
- ::= { prtMarkerEntry 11 }
-
-prtMarkerSouthMargin OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The margin from the South edge (see prtMarkerNorthMargin) of
- the medium in units identified by prtMarkerAddressabilityUnit.
- Printing within the area bounded by all four margins is
- guaranteed for all interpreters. The value (-2) means unknown."
- ::= { prtMarkerEntry 12 }
-
-prtMarkerWestMargin OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The margin from the West edge (see prtMarkerNorthMargin) of
- the medium in units identified by prtMarkerAddressabilityUnit.
- Printing within the area bounded by all four margins is
- guaranteed for all interpreters. The value (-2) means unknown."
- ::= { prtMarkerEntry 13 }
-
-prtMarkerEastMargin OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The margin from the East edge (see prtMarkerNorthMargin) of
- the medium in units identified by prtMarkerAddressabilityUnit.
- Printing within the area bounded by all four margins is
- guaranteed for all interpreters. The value (-2) means unknown."
- ::= { prtMarkerEntry 14 }
-
-prtMarkerStatus OBJECT-TYPE
- SYNTAX PrtSubUnitStatusTC
- MAX-ACCESS read-only
- STATUS current
-
-
-
-Bergman, et al. Standards Track [Page 103]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- DESCRIPTION
- "The current status of this marker sub-unit."
- ::= { prtMarkerEntry 15 }
-
--- The Marker Supplies Group
-
-prtMarkerSupplies OBJECT IDENTIFIER ::= { printmib 11 }
-
-prtMarkerSuppliesTable OBJECT-TYPE
- SYNTAX SEQUENCE OF PrtMarkerSuppliesEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A table of the marker supplies available on this printer."
- ::= { prtMarkerSupplies 1 }
-
-prtMarkerSuppliesEntry OBJECT-TYPE
- SYNTAX PrtMarkerSuppliesEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "Attributes of a marker supply. Entries may exist in the table
- for each device index with a device type of 'printer'.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- INDEX { hrDeviceIndex, prtMarkerSuppliesIndex }
- ::= { prtMarkerSuppliesTable 1 }
-PrtMarkerSuppliesEntry ::= SEQUENCE {
- prtMarkerSuppliesIndex Integer32,
- prtMarkerSuppliesMarkerIndex Integer32,
- prtMarkerSuppliesColorantIndex Integer32,
- prtMarkerSuppliesClass PrtMarkerSuppliesClassTC,
- prtMarkerSuppliesType PrtMarkerSuppliesTypeTC,
- prtMarkerSuppliesDescription PrtLocalizedDescriptionStringTC,
- prtMarkerSuppliesSupplyUnit PrtMarkerSuppliesSupplyUnitTC,
- prtMarkerSuppliesMaxCapacity Integer32,
- prtMarkerSuppliesLevel Integer32
- }
-
-prtMarkerSuppliesIndex OBJECT-TYPE
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A unique value used by the printer to identify this marker
- supply. Although these values may change due to a major
- reconfiguration of the device (e.g., the addition of new marker
-
-
-
-Bergman, et al. Standards Track [Page 104]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- supplies to the printer), values SHOULD remain stable across
- successive printer power cycles.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMarkerSuppliesEntry 1 }
-
-prtMarkerSuppliesMarkerIndex OBJECT-TYPE
- SYNTAX Integer32 (0..65535)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The value of prtMarkerIndex corresponding to the marking sub
- unit with which this marker supply sub-unit is associated."
- ::= { prtMarkerSuppliesEntry 2 }
-
-prtMarkerSuppliesColorantIndex OBJECT-TYPE
- SYNTAX Integer32 (0..65535)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The value of prtMarkerColorantIndex corresponding to the
- colorant with which this marker supply sub-unit is associated.
- This value shall be 0 if there is no colorant table or if this
- supply does not depend on a single specified colorant.
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMarkerSuppliesEntry 3 }
-
-prtMarkerSuppliesClass OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtMarkerSuppliesClassTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "Indicates whether this supply entity represents a supply that
- is consumed or a receptacle that is filled.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMarkerSuppliesEntry 4 }
-
-prtMarkerSuppliesType OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtMarkerSuppliesTypeTC
- MAX-ACCESS read-only
-
-
-
-Bergman, et al. Standards Track [Page 105]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- STATUS current
- DESCRIPTION
- "The type of this supply."
- ::= { prtMarkerSuppliesEntry 5 }
-
-prtMarkerSuppliesDescription OBJECT-TYPE
- -- In RFC 1759, the SYNTAX was OCTET STRING. This has been changed
- -- to a TC to better support localization of the object.
- SYNTAX PrtLocalizedDescriptionStringTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The description of this supply container/receptacle in the
- localization specified by prtGeneralCurrentLocalization."
- ::= { prtMarkerSuppliesEntry 6 }
-
-prtMarkerSuppliesSupplyUnit OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtMarkerSuppliesSupplyUnitTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "Unit of measure of this marker supply container/receptacle.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMarkerSuppliesEntry 7 }
-
-prtMarkerSuppliesMaxCapacity OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The maximum capacity of this supply container/receptacle
- expressed in prtMarkerSuppliesSupplyUnit. If this supply
- container/receptacle can reliably sense this value, the value
- is reported by the printer and is read-only; otherwise, the
- value may be written (by a Remote Control Panel or a Management
- Application). The value (-1) means other and specifically
- indicates that the sub-unit places no restrictions on this
- parameter. The value (-2) means unknown."
- ::= { prtMarkerSuppliesEntry 8 }
-
-prtMarkerSuppliesLevel OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-3..2147483647)
-
-
-
-Bergman, et al. Standards Track [Page 106]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The current level if this supply is a container; the remaining
- space if this supply is a receptacle. If this supply
- container/receptacle can reliably sense this value, the value
- is reported by the printer and is read-only; otherwise, the
- value may be written (by a Remote Control Panel or a Management
- Application). The value (-1) means other and specifically
- indicates that the sub-unit places no restrictions on this
- parameter. The value (-2) means unknown. A value of (-3) means
- that the printer knows that there is some supply/remaining
- space, respectively."
- ::= { prtMarkerSuppliesEntry 9 }
-
--- The Marker Colorant Group
-
-prtMarkerColorant OBJECT IDENTIFIER ::= { printmib 12 }
-
-prtMarkerColorantTable OBJECT-TYPE
- SYNTAX SEQUENCE OF PrtMarkerColorantEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A table of all of the colorants available on the printer."
- ::= { prtMarkerColorant 1 }
-
-prtMarkerColorantEntry OBJECT-TYPE
- SYNTAX PrtMarkerColorantEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "Attributes of a colorant available on the printer. Entries may
- exist in the table for each device index with a device type of
- 'printer'.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- INDEX { hrDeviceIndex, prtMarkerColorantIndex }
- ::= { prtMarkerColorantTable 1 }
-
-PrtMarkerColorantEntry ::= SEQUENCE {
- prtMarkerColorantIndex Integer32,
- prtMarkerColorantMarkerIndex Integer32,
- prtMarkerColorantRole PrtMarkerColorantRoleTC,
- prtMarkerColorantValue OCTET STRING,
- prtMarkerColorantTonality Integer32
- }
-
-
-
-Bergman, et al. Standards Track [Page 107]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-prtMarkerColorantIndex OBJECT-TYPE
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A unique value used by the printer to identify this colorant.
- Although these values may change due to a major reconfiguration
- of the device (e.g., the addition of new colorants to the
- printer) , values SHOULD remain stable across successive
- printer power cycles.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMarkerColorantEntry 1 }
-
-prtMarkerColorantMarkerIndex OBJECT-TYPE
- SYNTAX Integer32 (0..65535)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The value of prtMarkerIndex corresponding to the marker sub
- unit with which this colorant entry is associated."
- ::= { prtMarkerColorantEntry 2 }
-
-prtMarkerColorantRole OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtMarkerColorantRoleTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The role played by this colorant."
- ::= { prtMarkerColorantEntry 3 }
-
-prtMarkerColorantValue OBJECT-TYPE
- -- NOTE: The string length range has been increased from RFC 1759.
- SYNTAX OCTET STRING (SIZE(0..255))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The name of the color of this colorant using standardized
- string names from ISO 10175 (DPA) and ISO 10180 (SPDL) such as:
- other
- unknown
- white
- red
- green
- blue
-
-
-
-Bergman, et al. Standards Track [Page 108]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- cyan
- magenta
- yellow
- black
- Implementers may add additional string values. The naming
- conventions in ISO 9070 are recommended in order to avoid
- potential name clashes"
- ::= { prtMarkerColorantEntry 4 }
-
-prtMarkerColorantTonality OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (2..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The distinct levels of tonality realizable by a marking sub
- unit when using this colorant. This value does not include the
- number of levels of tonal difference that an interpreter can
- obtain by techniques such as half toning. This value must be at
- least 2."
- ::= { prtMarkerColorantEntry 5 }
-
--- The Media Path Group
---
--- The media paths encompass the mechanisms in the printer that
--- move the media through the printer and connect all other media
--- related sub-units: inputs, outputs, markers and finishers. A
--- printer contains one or more media paths. These are
--- represented by the Media Path Group in the model.
-
-prtMediaPath OBJECT IDENTIFIER ::= { printmib 13 }
-
-prtMediaPathTable OBJECT-TYPE
- SYNTAX SEQUENCE OF PrtMediaPathEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The media path table includes both physical and logical paths
- within the printer.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMediaPath 4 }
-
-prtMediaPathEntry OBJECT-TYPE
- SYNTAX PrtMediaPathEntry
- MAX-ACCESS not-accessible
- STATUS current
-
-
-
-Bergman, et al. Standards Track [Page 109]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- DESCRIPTION
- "Entries may exist in the table for each device index with a
- device type of 'printer' Each entry defines the physical
- characteristics of and the status of the media path. The data
- provided indicates the maximum throughput and the media
- size limitations of these subunits.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- INDEX { hrDeviceIndex, prtMediaPathIndex }
- ::= { prtMediaPathTable 1 }
-
-PrtMediaPathEntry ::= SEQUENCE {
- prtMediaPathIndex Integer32,
- prtMediaPathMaxSpeedPrintUnit PrtMediaPathMaxSpeedPrintUnitTC,
- prtMediaPathMediaSizeUnit PrtMediaUnitTC,
- prtMediaPathMaxSpeed Integer32,
- prtMediaPathMaxMediaFeedDir Integer32,
- prtMediaPathMaxMediaXFeedDir Integer32,
- prtMediaPathMinMediaFeedDir Integer32,
- prtMediaPathMinMediaXFeedDir Integer32,
- prtMediaPathType PrtMediaPathTypeTC,
- prtMediaPathDescription PrtLocalizedDescriptionStringTC,
- prtMediaPathStatus PrtSubUnitStatusTC
- }
-
-prtMediaPathIndex OBJECT-TYPE
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A unique value used by the printer to identify this media
- path. Although these values may change due to a major
- reconfiguration of the device (e.g., the addition of new media
- paths to the printer), values SHOULD remain stable across
- successive printer power cycles.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMediaPathEntry 1 }
-
-prtMediaPathMaxSpeedPrintUnit OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtMediaPathMaxSpeedPrintUnitTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
-
-
-
-Bergman, et al. Standards Track [Page 110]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- "The unit of measure used in specifying the speed of all media
- paths in the printer."
- ::= { prtMediaPathEntry 2 }
-
-prtMediaPathMediaSizeUnit OBJECT-TYPE
- SYNTAX PrtMediaUnitTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The units of measure of media size for use in calculating and
- relaying dimensional values for all media paths in the
- printer."
- ::= { prtMediaPathEntry 3 }
-
-prtMediaPathMaxSpeed OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The maximum printing speed of this media path expressed in
- prtMediaPathMaxSpeedUnit's. A value of (-1) implies 'other'."
- ::= { prtMediaPathEntry 4 }
-
-prtMediaPathMaxMediaFeedDir OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The maximum physical media size in the feed direction of this
- media path expressed in units of measure specified by
- PrtMediaPathMediaSizeUnit. A value of (-1) implies 'unlimited'
- a value of (-2) implies 'unknown'.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMediaPathEntry 5 }
-
-prtMediaPathMaxMediaXFeedDir OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The maximum physical media size across the feed direction of
- this media path expressed in units of measure specified by
- prtMediaPathMediaSizeUnit. A value of (-2) implies 'unknown'.
-
-
-
-Bergman, et al. Standards Track [Page 111]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMediaPathEntry 6 }
-
-prtMediaPathMinMediaFeedDir OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The minimum physical media size in the feed direction of this
- media path expressed in units of measure specified by
- prtMediaPathMediaSizeUnit. A value of (-2) implies 'unknown'.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMediaPathEntry 7 }
-
-prtMediaPathMinMediaXFeedDir OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The minimum physical media size across the feed direction of
- this media path expressed in units of measure specified by
- prtMediaPathMediaSizeUnit. A value of (-2) implies 'unknown'.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtMediaPathEntry 8 }
-
-prtMediaPathType OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtMediaPathTypeTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The type of the media path for this media path."
- ::= { prtMediaPathEntry 9 }
-
-prtMediaPathDescription OBJECT-TYPE
- -- In RFC 1759, the SYNTAX was OCTET STRING. This has been changed
- -- to a TC to better support localization of the object.
- SYNTAX PrtLocalizedDescriptionStringTC
- MAX-ACCESS read-only
- STATUS current
-
-
-
-Bergman, et al. Standards Track [Page 112]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- DESCRIPTION
- "The manufacturer-provided description of this media path in
- the localization specified by prtGeneralCurrentLocalization."
- ::= { prtMediaPathEntry 10 }
-
-prtMediaPathStatus OBJECT-TYPE
- SYNTAX PrtSubUnitStatusTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The current status of this media path."
- ::= { prtMediaPathEntry 11 }
-
--- The Print Job Delivery Channel Group
---
--- Print Job Delivery Channels are independent sources of print
--- data. Here, print data is the term used for the information
--- that is used to construct printed pages and may have both data
--- and control aspects. The output of a channel is in a form
--- suitable for input to one of the interpreters as a
--- stream. A channel may be independently enabled (allowing
--- print data to flow) or disabled (stopping the flow of
--- print data). A printer may have one or more channels.
---
--- The Print Job Delivery Channel table describes the
--- capabilities of the printer and not what is currently being
--- performed by the printer
---
--- Basically, the print job delivery channel abstraction
--- describes the final processing step of getting the print data
--- to an interpreter. It might include some level of
--- decompression or decoding of print stream data.
--- channel. All of these aspects are hidden in the channel
--- abstraction.
---
--- There are many kinds of print job delivery channels; some of
--- which are based on networks and others which are not. For
--- example, a channel can be a serial (or parallel) connection;
--- it can be a service, such as the UNIX Line Printer Daemon
--- (LPD), offering services over a network connection; or
--- it could be a disk drive into which a floppy disk with
--- the print data is inserted. Each print job delivery channel is
--- identified by the electronic path and/or service protocol
--- used to deliver print data to a print data interpreter.
---
--- Channel example Implementation
---
--- serial port channel bi-directional data channel
-
-
-
-Bergman, et al. Standards Track [Page 113]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
--- parallel port channel often uni-directional channel
--- IEEE 1284 port channel bi-directional channel
--- SCSI port channel bi-directional
--- Apple PAP channel may be based on LocalTalk,
--- Ethernet or Tokentalk
--- LPD Server channel TCP/IP based, port 515
--- Netware Remote Printer SPX/IPX based channel
--- Netware Print Server SPX/IPX based channel
---
--- It is easy to note that this is a mixed bag. There are
--- some physical connections over which no (or very meager)
--- protocols are run (e.g., the serial or old parallel ports)
--- and there are services which often have elaborate
--- protocols that run over a number of protocol stacks. In
--- the end, what is important is the delivery of print data
--- through the channel.
---
--- The print job delivery channel sub-units are represented by
--- the Print Job Delivery Channel Group in the Model. It has a
--- current print job control language, which can be used to
--- specify which interpreter is to be used for the print data and
--- to query and change environment variables used by the
--- interpreters (and Management Applications). There is also a
--- default interpreter that is to be used if an interpreter is
--- not explicitly specified using the Control Language.
-
--- The first seven items in the Print Job Delivery Channel Table
--- define the "channel" itself. A channel typically depends on
--- other protocols and interfaces to provide the data that flows
--- through the channel.
---
--- Control of a print job delivery channel is largely limited to
--- enabling or disabling the entire channel itself. It is likely
--- that more control of the process of accessing print data
--- will be needed over time. Thus, the ChannelType will
--- allow type-specific data to be associated with each
--- channel (using ChannelType specific groups in a fashion
--- analogous to the media specific MIBs that are associated
--- with the IANAIfType in the Interfaces Table). As a first
--- step in this direction, each channel will identify the
--- underlying Interface on which it is based. This is the
--- eighth object in each row of the table.
-
-
-
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 114]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
--- The Print Job Delivery Channel Table
-
-prtChannel OBJECT IDENTIFIER ::= { printmib 14 }
-
-prtChannelTable OBJECT-TYPE
- SYNTAX SEQUENCE OF PrtChannelEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The channel table represents the set of input data sources
- which can provide print data to one or more of the
- interpreters available on a printer.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtChannel 1 }
-
-prtChannelEntry OBJECT-TYPE
- SYNTAX PrtChannelEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "Entries may exist in the table for each device index with a
- device type of 'printer'. Each channel table entry is
- characterized by a unique protocol stack and/or addressing.
- The channel may also have printer dependent features that are
- associated with a printing language.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- INDEX { hrDeviceIndex, prtChannelIndex }
- ::= { prtChannelTable 1 }
-
-PrtChannelEntry ::= SEQUENCE {
- prtChannelIndex Integer32,
- prtChannelType PrtChannelTypeTC,
- prtChannelProtocolVersion OCTET STRING,
- prtChannelCurrentJobCntlLangIndex Integer32,
- prtChannelDefaultPageDescLangIndex Integer32,
- prtChannelState PrtChannelStateTC,
- prtChannelIfIndex InterfaceIndexOrZero,
- prtChannelStatus PrtSubUnitStatusTC,
- prtChannelInformation OCTET STRING
- }
-
-prtChannelIndex OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (1..65535)
-
-
-
-Bergman, et al. Standards Track [Page 115]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A unique value used by the printer to identify this data
- channel. Although these values may change due to a major
- reconfiguration of the device (e.g., the addition of new data
- channels to the printer), values SHOULD remain stable across
- successive printer power cycles.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtChannelEntry 1 }
-
-prtChannelType OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtChannelTypeTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The type of this print data channel. This object provides the
- linkage to ChannelType-specific groups that may (conceptually)
- extend the prtChannelTable with additional details about that
- channel."
- ::= { prtChannelEntry 2 }
-
-prtChannelProtocolVersion OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..63))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The version of the protocol used on this channel. The format
- used for version numbering depends on prtChannelType."
- ::= { prtChannelEntry 3 }
-
-prtChannelCurrentJobCntlLangIndex OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (0..65535)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The value of prtInterpreterIndex corresponding to the Control
- Language Interpreter for this channel. This interpreter defines
- the syntax used for control functions, such as querying or
- changing environment variables and identifying job boundaries
- (e.g., PJL, PostScript, NPAP). A value of zero indicates that
- there is no current Job Control Language Interpreter for this
- channel.
-
-
-
-Bergman, et al. Standards Track [Page 116]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtChannelEntry 4 }
-
-prtChannelDefaultPageDescLangIndex OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (0..65535)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The value of prtInterpreterIndex corresponding to the Page
- Description Language Interpreter for this channel. This
- interpreter defines the default Page Description Language
- interpreter to be used for the print data unless the Control
- Language is used to select a specific interpreter (e.g., PCL,
- PostScript Language, auto-sense). A value of zero indicates
- that there is no default page description language interpreter
- for this channel.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtChannelEntry 5 }
-
-prtChannelState OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtChannelStateTC
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The state of this print data channel. The value determines
- whether control information and print data is allowed through
- this channel or not."
- ::= { prtChannelEntry 6 }
-
-prtChannelIfIndex OBJECT-TYPE
- SYNTAX InterfaceIndexOrZero -- Was Integer32 in RFC 1759.
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The value of ifIndex in the ifTable; see the Interfaces Group
- MIB [RFC2863] which corresponds to this channel.
- When more than one row of the ifTable is relevant, this is the
- index of the row representing the topmost layer in the
- interface hierarchy. A value of zero indicates that no
- interface is associated with this channel.
-
- NOTE: The above description has been modified from RFC 1759
-
-
-
-Bergman, et al. Standards Track [Page 117]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- for clarification."
- ::= { prtChannelEntry 7 }
-
-prtChannelStatus OBJECT-TYPE
- SYNTAX PrtSubUnitStatusTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The current status of the channel."
- ::= { prtChannelEntry 8 }
-
-prtChannelInformation OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE (0..255))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "Auxiliary information to allow a printing application to use
- the channel for data submission to the printer. An application
- capable of using a specific PrtChannelType should be able to
- use the combined information from the prtChannelInformation and
- other channel and interface group objects to 'bootstrap' its
- use of the channel. prtChannelInformation is not intended to
- provide a general channel description, nor to provide
- information that is available once the channel is in use.
-
- The encoding and interpretation of the prtChannelInformation
- object is specific to channel type. The description of each
- PrtChannelType enum value for which prtChannelInformation is
- defined specifies the appropriate encoding and interpretation,
- including interaction with other objects. For channel types
- that do not specify a prtChannelInformation value, its value
- shall be null (0 length).
-
- When a new PrtChannelType enumeration value is registered, its
- accompanying description must specify the encoding and
- interpretation of the prtChannelInformation value for the
- channel type. prtChannelInformation semantics for an existing
- PrtChannelType may be added or amended in the same manner as
- described in section 2.4.1 for type 2 enumeration values.
-
- The prtChannelInformation specifies values for a collection of
- channel attributes, represented as text according to the
- following rules:
-
- 1. The prtChannelInformation is not affected by localization.
-
- 2. The prtChannelInformation is a list of entries representing
- the attribute values. Each entry consists of the following
-
-
-
-Bergman, et al. Standards Track [Page 118]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- items, in order:
-
- a. A keyword, composed of alphabetic characters (A-Z, a-z)
- represented by their NVT ASCII [RFC854] codes, that
- identifies a channel attribute,
-
- b. The NVT ASCII code for an Equals Sign (=) (code 61) to
- delimit the keyword,
-
- c. A data value encoded using rules specific to the
- PrtChannelType to with the prtChannelInformation applies which
- must in no case allow an octet with value 10 (the NVT ASCII
- Line Feed code),
-
- d. the NVT ASCII code for a Line Feed character (code 10) to
- delimit the data value.
-
- No other octets shall be present.
-
- Keywords are case-sensitive. Conventionally, keywords are
- capitalized (including each word of a multi-word keyword) and
- since they occupy space in the prtChannelInformation, they are
- kept short.
-
- 3. If a channel attribute has multiple values, it is
- represented by multiple entries with the same keyword, each
- specifying one value. Otherwise, there shall be at most one
- entry for each attribute.
-
- 4. By default, entries may appear in any order. If there are
- ordering constraints for particular entries, these must be
- specified in their definitions.
-
- 5. The prtChannelInformation value by default consists of text
- represented by NVT ASCII graphics character codes. However,
- other representations may be specified:
-
- a. In cases where the prtChannelInformation value contains
- information not normally coded in textual form, whatever
- symbolic representation is conventionally used for the
- information should be used for encoding the
- prtChannelInformation value. (For instance, a binary port value
- might be represented as a decimal number using NVT ASCII
- codes.) Such encoding must be specified in the definition of
- the value.
-
- b. The value may contain textual information in a character set
- other than NVT ASCII graphics characters. (For instance, an
-
-
-
-Bergman, et al. Standards Track [Page 119]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- identifier might consist of ISO 10646 text encoded using the
- UTF-8 encoding scheme.) Such a character set and its encoding
- must be specified in the definition of the value.
-
- 6. For each PrtChannelType for which prtChannelInformation
- entries are defined, the descriptive text associated with the
- PrtChannelType enumeration value shall specify the following
- information for each entry:
-
- Title: Brief description phrase, e.g.: 'Port name',
- 'Service Name', etc.
-
- Keyword: The keyword value, e.g.: 'Port' or 'Service'
-
- Syntax: The encoding of the entry value if it cannot be
- directly represented by NVT ASCII.
-
- Status: 'Mandatory', 'Optional', or 'Conditionally
- Mandatory'
-
- Multiplicity: 'Single' or 'Multiple' to indicate whether the
- entry may be present multiple times.
-
- Description: Description of the use of the entry, other
- information required to complete the definition
- (e.g.: ordering constraints, interactions between
- entries).
-
- Applications that interpret prtChannelInformation should ignore
- unrecognized entries, so they are not affected if new entry
- types are added."
-
- ::= { prtChannelEntry 9 }
-
--- The Interpreter Group
---
--- The interpreter sub-units are responsible for the conversion
--- of a description of intended print instances into images that
--- are to be marked on the media. A printer may have one or more
--- interpreters. The interpreter sub-units are represented by the
--- Interpreter Group in the Model. Each interpreter is generally
--- implemented with software running on the System Controller
--- sub-unit. The Interpreter Table has one entry per interpreter
--- where the interpreters include both Page Description Language
--- (PDL) Interpreters and Control Language Interpreters.
-
-prtInterpreter OBJECT IDENTIFIER ::= { printmib 15 }
-
-
-
-
-Bergman, et al. Standards Track [Page 120]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
--- Interpreter Table
-
-prtInterpreterTable OBJECT-TYPE
- SYNTAX SEQUENCE OF PrtInterpreterEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The interpreter table is a table representing the
- interpreters in the printer. An entry shall be placed in the
- interpreter table for each interpreter on the printer.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtInterpreter 1 }
-
-prtInterpreterEntry OBJECT-TYPE
- SYNTAX PrtInterpreterEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "Entries may exist in the table for each device index with a
- device type of 'printer'. Each table entry provides a complete
- description of the interpreter, including version information,
- rendering resolutions, default character sets, output
- orientation, and communication capabilities.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- INDEX { hrDeviceIndex, prtInterpreterIndex }
- ::= { prtInterpreterTable 1 }
-
-PrtInterpreterEntry ::= SEQUENCE {
- prtInterpreterIndex Integer32,
- prtInterpreterLangFamily PrtInterpreterLangFamilyTC,
- prtInterpreterLangLevel OCTET STRING,
- prtInterpreterLangVersion OCTET STRING,
- prtInterpreterDescription PrtLocalizedDescriptionStringTC,
- prtInterpreterVersion OCTET STRING,
- prtInterpreterDefaultOrientation PrtPrintOrientationTC,
- prtInterpreterFeedAddressability Integer32,
- prtInterpreterXFeedAddressability Integer32,
- prtInterpreterDefaultCharSetIn IANACharset,
- prtInterpreterDefaultCharSetOut IANACharset,
- prtInterpreterTwoWay PrtInterpreterTwoWayTC
- }
-
-prtInterpreterIndex OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
-
-
-
-Bergman, et al. Standards Track [Page 121]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A unique value for each PDL or control language for which
- there exists an interpreter or emulator in the printer. The
- value is used to identify this interpreter. Although these
- values may change due to a major reconfiguration of the device
- (e.g., the addition of new interpreters to the printer), values
- SHOULD remain stable across successive printer power cycles.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtInterpreterEntry 1 }
-
-prtInterpreterLangFamily OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtInterpreterLangFamilyTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The family name of a Page Description Language (PDL) or
- control language which this interpreter in the printer can
- interpret or emulate.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtInterpreterEntry 2 }
-
-prtInterpreterLangLevel OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..31))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The level of the language which this interpreter is
- interpreting or emulating. This might contain a value like
- '5e'for an interpreter which is emulating level 5e of the PCL
- language. It might contain '2' for an interpreter which is
- emulating level 2 of the PostScript language. Similarly it
- might contain '2' for an interpreter which is emulating level 2
- of the HPGL language."
- ::= { prtInterpreterEntry 3 }
-
-prtInterpreterLangVersion OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..31))
- MAX-ACCESS read-only
- STATUS current
-
-
-
-Bergman, et al. Standards Track [Page 122]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- DESCRIPTION
- "The date code or version of the language which this
- interpreter is interpreting or emulating."
- ::= { prtInterpreterEntry 4 }
-
-prtInterpreterDescription OBJECT-TYPE
- -- In RFC 1759, the SYNTAX was OCTET STRING. This has been changed
- -- to a TC to better support localization of the object.
- SYNTAX PrtLocalizedDescriptionStringTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A string to identify this interpreter in the localization
- specified by prtGeneralCurrentLocalization as opposed to the
- language which is being interpreted. It is anticipated that
- this string will allow manufacturers to unambiguously identify
- their interpreters."
- ::= { prtInterpreterEntry 5 }
-
-prtInterpreterVersion OBJECT-TYPE
- SYNTAX OCTET STRING (SIZE(0..31))
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The date code, version number, or other product specific
- information tied to this interpreter. This value is associated
- with the interpreter, rather than with the version of the
- language which is being interpreted or emulated."
- ::= { prtInterpreterEntry 6 }
-
-prtInterpreterDefaultOrientation OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtPrintOrientationTC
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The current orientation default for this interpreter. This
- value may be overridden for a particular job (e.g., by a
- command in the input data stream)."
- ::= { prtInterpreterEntry 7 }
-
-prtInterpreterFeedAddressability OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
-
-
-
-Bergman, et al. Standards Track [Page 123]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- "The maximum interpreter addressability in the feed
- direction in 10000 prtMarkerAddressabilityUnits (as specified
- by prtMarkerDefaultIndex) for this interpreter. The
- value (-1) means other and specifically indicates that the
- sub-unit places no restrictions on this parameter. The value
- (-2) means unknown.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtInterpreterEntry 8 }
-
-prtInterpreterXFeedAddressability OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The maximum interpreter addressability in the cross feed
- direction in 10000 prtMarkerAddressabilityUnits (as specified
- by prtMarkerDefaultIndex) for this interpreter. The
- value (-1) means other and specifically indicates that the
- sub-unit places no restrictions on this parameter. The value
- (-2) means unknown.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtInterpreterEntry 9 }
-
-prtInterpreterDefaultCharSetIn OBJECT-TYPE
- SYNTAX IANACharset
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The default coded character set for input octets encountered
- outside a context in which the Page Description Language
- established the interpretation of the octets. (Input octets are
- presented to the interpreter through a path defined in the
- channel group.)"
- ::= { prtInterpreterEntry 10 }
-
-prtInterpreterDefaultCharSetOut OBJECT-TYPE
- SYNTAX IANACharset
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The default character set for data coming from this
- interpreter through the printer's output channel (i.e. the
- 'backchannel')."
-
-
-
-Bergman, et al. Standards Track [Page 124]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- ::= { prtInterpreterEntry 11 }
-
-prtInterpreterTwoWay OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtInterpreterTwoWayTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "Indicates whether or not this interpreter returns information
- back to the host."
- ::= { prtInterpreterEntry 12 }
-
--- The Console Group
---
--- Many printers have a console on the printer, the operator
--- console, that is used to display and modify the state of the
--- printer. The console can be as simple as a few indicators and
--- switches or as complicated as full screen displays and
--- keyboards. There can be at most one such console.
-
--- The Display Buffer Table
-
-prtConsoleDisplayBuffer OBJECT IDENTIFIER ::= { printmib 16 }
-
-prtConsoleDisplayBufferTable OBJECT-TYPE
- SYNTAX SEQUENCE OF PrtConsoleDisplayBufferEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "Physical display buffer for printer console display or
- operator panel
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtConsoleDisplayBuffer 5 }
-
-prtConsoleDisplayBufferEntry OBJECT-TYPE
- SYNTAX PrtConsoleDisplayBufferEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "This table contains one entry for each physical line on
- the display. Lines cannot be added or deleted. Entries may
- exist in the table for each device index with a device type of
- 'printer'.
-
- NOTE: The above description has been modified from RFC 1759
-
-
-
-Bergman, et al. Standards Track [Page 125]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- for clarification."
- INDEX { hrDeviceIndex, prtConsoleDisplayBufferIndex }
- ::= { prtConsoleDisplayBufferTable 1 }
-
-PrtConsoleDisplayBufferEntry ::= SEQUENCE {
- prtConsoleDisplayBufferIndex Integer32,
- prtConsoleDisplayBufferText PrtConsoleDescriptionStringTC
- }
-
-prtConsoleDisplayBufferIndex OBJECT-TYPE
- SYNTAX Integer32 (1..65535)
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A unique value for each console line in the printer. The value
- is used to identify this console line. Although these values
- may change due to a major reconfiguration of the device (e.g.,
- the addition of new console lines to the printer). Values
- SHOULD remain stable across successive printer power cycles.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtConsoleDisplayBufferEntry 1 }
-
-prtConsoleDisplayBufferText OBJECT-TYPE
- -- In RFC 1759, the SYNTAX was OCTET STRING. This has been changed
- -- to a TC to better support localization of the object.
- SYNTAX PrtConsoleDescriptionStringTC
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "The content of a line in the logical display buffer of
- the operator's console of the printer. When a write
- operation occurs, normally a critical message, to one of
- the LineText strings, the agent should make that line
- displayable if a physical display is present. Writing a zero
- length string clears the line. It is an implementation-
- specific matter as to whether the agent allows a line to be
- overwritten before it has been cleared. Printer generated
- strings shall be in the localization specified by
- prtConsoleLocalization.Management Application generated strings
- should be localized by the Management Application."
- ::= { prtConsoleDisplayBufferEntry 2 }
-
--- The Console Light Table
-
-prtConsoleLights OBJECT IDENTIFIER ::= { printmib 17 }
-
-
-
-
-Bergman, et al. Standards Track [Page 126]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-prtConsoleLightTable OBJECT-TYPE
- SYNTAX SEQUENCE OF PrtConsoleLightEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The console light table provides a description and state
- information for each light present on the printer console.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtConsoleLights 6 }
-
-prtConsoleLightEntry OBJECT-TYPE
- SYNTAX PrtConsoleLightEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "Entries may exist in the table for each device index with a
- device type of 'printer'.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- INDEX { hrDeviceIndex, prtConsoleLightIndex }
- ::= { prtConsoleLightTable 1 }
-
-PrtConsoleLightEntry ::= SEQUENCE {
- prtConsoleLightIndex Integer32,
- prtConsoleOnTime Integer32,
- prtConsoleOffTime Integer32,
- prtConsoleColor PrtConsoleColorTC,
- prtConsoleDescription PrtConsoleDescriptionStringTC
- }
-
-prtConsoleLightIndex OBJECT-TYPE
- SYNTAX Integer32 (1..65535) -- Lower limit invalid in RFC 1759
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A unique value used by the printer to identify this light.
- Although these values may change due to a major
- reconfiguration of the device (e.g., the addition of new lights
- to the printer). Values SHOULD remain stable across successive
- printer power cycles.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtConsoleLightEntry 1 }
-
-
-
-
-Bergman, et al. Standards Track [Page 127]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-prtConsoleOnTime OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (0..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "This object, in conjunction with prtConsoleOffTime, defines
- the current status of the light. If both prtConsoleOnTime and
- prtConsoleOffTime are non-zero, the lamp is blinking and the
- values presented define the on time and off time, respectively,
- in milliseconds. If prtConsoleOnTime is zero and
- prtConsoleOffTime is non-zero, the lamp is off. If
- prtConsoleOffTime is zero and prtConsoleOnTime is non-zero, the
- lamp is on. If both values are zero the lamp is off.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtConsoleLightEntry 2 }
-
-prtConsoleOffTime OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (0..2147483647)
- MAX-ACCESS read-write
- STATUS current
- DESCRIPTION
- "This object, in conjunction with prtConsoleOnTime, defines the
- current status of the light. If both prtConsoleOnTime and
- prtConsoleOffTime are non-zero, the lamp is blinking and the
- values presented define the on time and off time, respectively,
- in milliseconds. If prtConsoleOnTime is zero and
- prtConsoleOffTime is non-zero, the lamp is off. If
- prtConsoleOffTime is zero and prtConsoleOnTime is non-zero, the
- lamp is on. If both values are zero the lamp is off.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtConsoleLightEntry 3 }
-
-prtConsoleColor OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtConsoleColorTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The color of this light."
- ::= { prtConsoleLightEntry 4 }
-
-
-
-
-Bergman, et al. Standards Track [Page 128]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-prtConsoleDescription OBJECT-TYPE
- -- In RFC 1759, the SYNTAX was OCTET STRING. This has been changed
- -- to a TC to better support localization of the object.
- SYNTAX PrtConsoleDescriptionStringTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The vendor description or label of this light in the
- localization specified by prtConsoleLocalization."
- ::= { prtConsoleLightEntry 5 }
-
--- The Alerts Group
---
--- The table contains information on the severity, component,
--- detail location within the component, alert code and
--- description of each critical alert that is currently active
--- within the printer. See 2.2.13 for a more complete
--- description of the alerts table and its management.
---
--- Each parameter in the Trap PDU is a full OID which itself is
--- indexed by the host resources MIB "hrDeviceIndex" object. In
--- order for a management station to obtain the correct
--- "hrDeviceIndex" associated with a particular Trap PDU, the
--- "hrDeviceIndex" value can be extracted from the returned OID
--- value in the Trap PDU when the PDU is received by the
--- Management station.
-
-prtAlert OBJECT IDENTIFIER ::= { printmib 18 }
-
-prtAlertTable OBJECT-TYPE
- SYNTAX SEQUENCE OF PrtAlertEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The prtAlertTable lists all the critical and non-critical
- alerts currently active in the printer. A critical alert is
- one that stops the printer from printing immediately and
- printing can not continue until the critical alert condition
- is eliminated. Non-critical alerts are those items that do
- not stop printing but may at some future time.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtAlert 1 }
-
-prtAlertEntry OBJECT-TYPE
- SYNTAX PrtAlertEntry
- MAX-ACCESS not-accessible
-
-
-
-Bergman, et al. Standards Track [Page 129]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- STATUS current
- DESCRIPTION
- "Entries may exist in the table for each device
- index with a device type of 'printer'.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- INDEX { hrDeviceIndex, prtAlertIndex }
- ::= { prtAlertTable 1 }
-
-PrtAlertEntry ::= SEQUENCE {
- prtAlertIndex Integer32,
- prtAlertSeverityLevel PrtAlertSeverityLevelTC,
- prtAlertTrainingLevel PrtAlertTrainingLevelTC,
- prtAlertGroup PrtAlertGroupTC,
- prtAlertGroupIndex Integer32,
- prtAlertLocation Integer32,
- prtAlertCode PrtAlertCodeTC,
- prtAlertDescription PrtLocalizedDescriptionStringTC,
- prtAlertTime TimeTicks
- }
-
-prtAlertIndex OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined. The MAX-ACCESS has
- -- been changed from not accessible to allow the object to be
- -- included (as originally in RFC 1759) in the trap bindings.
-
- SYNTAX Integer32 (1..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The index value used to determine which alerts have been added
- or removed from the alert table. This is an incrementing
- integer initialized to 1 when the printer is reset. (i.e., The
- first event placed in the alert table after a reset of the
- printer shall have an index value of 1.) When the printer adds
- an alert to the table, that alert is assigned the next higher
- integer value from the last item entered into the table. If
- the index value reaches its maximum value, the next index value
- used must be 1.
-
- NOTE: The management application will read the alert table when
- a trap or event notification occurs or at a periodic rate and
- then parse the table to determine if any new entries were added
- by comparing the last known index value with the current
- highest index value. The management application will then
- update its copy of the alert table. When the printer discovers
- that an alert is no longer active, the printer shall remove the
-
-
-
-Bergman, et al. Standards Track [Page 130]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- row for that alert from the table and shall reduce the number
- of rows in the table. The printer may add or delete any number
- of rows from the table at any time. The management station can
- detect when binary change alerts have been deleted by
- requesting an attribute of each alert, and noting alerts as
- deleted when that retrieval is not possible. The objects
- 'prtAlertCriticalEvents'and 'prtAlertAllEvents' in the
- 'prtGeneralTable' reduce the need for management applications
- to scan the 'prtAlertTable'.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtAlertEntry 1 }
-
-prtAlertSeverityLevel OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtAlertSeverityLevelTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The level of severity of this alert table entry. The printer
- determines the severity level assigned to each entry into the
- table."
- ::= { prtAlertEntry 2 }
-
-prtAlertTrainingLevel OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtAlertTrainingLevelTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "See TEXTUAL-CONVENTION PrtAlertTrainingLevelTC.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtAlertEntry 3 }
-
-prtAlertGroup OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtAlertGroupTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The type of sub-unit within the printer model that this alert
- is related. Input, output, and markers are examples of printer
-
-
-
-Bergman, et al. Standards Track [Page 131]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- model groups, i.e., examples of types of sub-units. Wherever
- possible, these enumerations match the sub-identifier that
- identifies the relevant table in the printmib."
- ::= { prtAlertEntry 4 }
-
-prtAlertGroupIndex OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-1..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The low-order index of the row within the table identified
- by prtAlertGroup that represents the sub-unit of the printer
- that caused this alert, or -1 if not applicable. The
- combination of the prtAlertGroup and the prtAlertGroupIndex
- defines exactly which printer sub-unit caused the alert; for
- example, Input #3, Output#2, and Marker #1. Every object in
- this MIB is indexed with hrDeviceIndex and optionally, another
- index variable. If this other index variable is present in the
- table that generated the alert, it will be used as the value
- for this object. Otherwise, this value shall be -1.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtAlertEntry 5 }
-
-prtAlertLocation OBJECT-TYPE
- -- NOTE: In RFC 1759, the range was not defined.
- SYNTAX Integer32 (-2..2147483647)
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The sub-unit location that is defined by the printer
- manufacturer to further refine the location of this alert
- within the designated sub-unit. The location is used in
- conjunction with the Group and GroupIndex values; for example,
- there is an alert in Input #2 at location number 7. The value
- (-2) indicates unknown.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtAlertEntry 6 }
-
-prtAlertCode OBJECT-TYPE
- -- NOTE: In RFC 1759, the enumeration values were implicitly
- -- defined by this object.
- SYNTAX PrtAlertCodeTC
- MAX-ACCESS read-only
-
-
-
-Bergman, et al. Standards Track [Page 132]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- STATUS current
- DESCRIPTION
- "See associated TEXTUAL-CONVENTION PrtAlertCodeTC.
-
- NOTE: The above description has been modified from RFC 1759
- for clarification."
- ::= { prtAlertEntry 7 }
-
-prtAlertDescription OBJECT-TYPE
- -- In RFC 1759, the SYNTAX was OCTET STRING. This has been changed
- -- to a TC to better support localization of the object.
- SYNTAX PrtLocalizedDescriptionStringTC
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "A description of this alert entry in the localization
- specified by prtGeneralCurrentLocalization. The description is
- provided by the printer to further elaborate on the enumerated
- alert or provide information in the case where the code is
- classified as 'other' or 'unknown'. The printer is required to
- return a description string but the string may be a null
- string."
- ::= { prtAlertEntry 8 }
-
-prtAlertTime OBJECT-TYPE
- SYNTAX TimeTicks
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The value of sysUpTime at the time that this alert was
- generated."
- ::= { prtAlertEntry 9 }
-
-printerV1Alert OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
- "The value of the enterprise-specific OID in an SNMPv1 trap
- sent signaling a critical event in the prtAlertTable."
- ::= { prtAlert 2 }
-
-printerV2AlertPrefix OBJECT IDENTIFIER ::= { printerV1Alert 0 }
-
-printerV2Alert NOTIFICATION-TYPE
- OBJECTS { prtAlertIndex, prtAlertSeverityLevel, prtAlertGroup,
- prtAlertGroupIndex, prtAlertLocation, prtAlertCode }
- STATUS current
- DESCRIPTION
- "This trap is sent whenever a critical event is added to the
-
-
-
-Bergman, et al. Standards Track [Page 133]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- prtAlertTable.
-
- NOTE: The prtAlertIndex object was redundantly included in the
- bindings of the 'printerV2Alert' notification in RFC 1759, even
- though the value exists in the instance qualifier of all the
- other bindings. This object has been retained to provide
- compatiblity with existing RFC 1759 implementaions."
- ::= { printerV2AlertPrefix 1 }
-
--- Note that the SNMPv2 to SNMPv1 translation rules dictate that
--- the preceding structure will result in SNMPv1 traps of the
--- following form:
---
--- printerAlert TRAP-TYPE
--- ENTERPRISE printerV1Alert
--- VARIABLES { prtAlertIndex, prtAlertSeverityLevel,
--- prtAlertGroup, prtAlertGroupIndex,
--- prtAlertLocation, prtAlertCode }
--- DESCRIPTION
--- "This trap is sent whenever a critical event is added
--- to the prtAlertTable."
--- ::= 1
-
--- Conformance Information
-
-prtMIBConformance OBJECT IDENTIFIER ::= { printmib 2 }
-
--- compliance statements
-
-prtMIBCompliance MODULE-COMPLIANCE
-
- STATUS current
- DESCRIPTION
- "The compliance statement for agents that implement the
- printer MIB as defined by RFC 1759."
- MODULE -- this module
- MANDATORY-GROUPS { prtGeneralGroup, prtInputGroup,
- prtOutputGroup,
- prtMarkerGroup, prtMediaPathGroup,
- prtChannelGroup, prtInterpreterGroup,
- prtConsoleGroup, prtAlertTableGroup }
- OBJECT prtGeneralReset
- SYNTAX INTEGER {
- notResetting(3),
- resetToNVRAM(5)
- }
- DESCRIPTION
- "It is conformant to implement just these two states in this
-
-
-
-Bergman, et al. Standards Track [Page 134]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- object. Any additional states are optional."
-
- OBJECT prtConsoleOnTime
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtConsoleOffTime
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
- ::= { prtMIBConformance 1 }
-
-prtMIB2Compliance MODULE-COMPLIANCE
- STATUS current
- DESCRIPTION
- "The compliance statement for agents that implement the
- printer MIB V2."
- -- The changes from RFC 1759 fall into 2 categories:
- -- 1. New objects plus existing objects with a MIN-ACCESS of
- -- read-only are included. Existing objects have been added
- -- to this category due to feedback from implementers and
- -- interoperability testing. This allows products to be
- -- be designed with a higher degree of SNMP security.
- -- 2. New object groups have been added to include all new
- -- objects in this MIB. All new object groups are optional.
- -- Any MIB that is compliant with RFC 1759 will also be
- -- compliant with this version of the MIB.
- MODULE -- this module
- MANDATORY-GROUPS { prtGeneralGroup, prtInputGroup,
- prtOutputGroup,
- prtMarkerGroup, prtMediaPathGroup,
- prtChannelGroup, prtInterpreterGroup,
- prtConsoleGroup, prtAlertTableGroup }
- OBJECT prtGeneralReset
- SYNTAX INTEGER {
- notResetting(3),
- resetToNVRAM(5)
- }
- DESCRIPTION
- "It is conformant to implement just these two states in this
- object. Any additional states are optional."
-
- OBJECT prtGeneralCurrentLocalization
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
-
-
-
-Bergman, et al. Standards Track [Page 135]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- OBJECT prtGeneralCurrentOperator
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtGeneralServicePerson
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtGeneralPrinterName
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtGeneralSerialNumber
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtInputDefaultIndex
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtInputMediaDimFeedDirDeclared
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtInputMaxCapacity
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtInputCurrentLevel
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtInputMediaName
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtInputName
- MIN-ACCESS read-only
- DESCRIPTION
-
-
-
-Bergman, et al. Standards Track [Page 136]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- "It is conformant to implement this object as read-only"
-
- OBJECT prtInputSecurity
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtInputMediaWeight
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtInputMediaType
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtInputMediaColor
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtInputMediaFormParts
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtOutputDefaultIndex
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtOutputMaxCapacity
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtOutputRemainingCapacity
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtOutputName
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtOutputSecurity
-
-
-
-Bergman, et al. Standards Track [Page 137]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtOutputMaxDimFeedDir
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtOutputMaxDimXFeedDir
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtOutputMinDimFeedDir
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtOutputMinDimXFeedDir
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtOutputStackingOrder
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtOutputPageDeliveryOrientation
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtOutputBursting
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtOutputDecollating
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtOutputPageCollated
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
-
-
-Bergman, et al. Standards Track [Page 138]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- OBJECT prtOutputOffsetStacking
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtMarkerDefaultIndex
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtMarkerSuppliesMaxCapacity
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtMarkerSuppliesLevel
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtMediaPathDefaultIndex
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtChannelCurrentJobCntlLangIndex
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtChannelDefaultPageDescLangIndex
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtChannelState
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtChannelIfIndex
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtInterpreterDefaultOrientation
- MIN-ACCESS read-only
- DESCRIPTION
-
-
-
-Bergman, et al. Standards Track [Page 139]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- "It is conformant to implement this object as read-only"
-
- OBJECT prtInterpreterDefaultCharSetIn
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtInterpreterDefaultCharSetOut
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtConsoleLocalization
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtConsoleDisable
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtConsoleDisplayBufferText
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtConsoleOnTime
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtConsoleOffTime
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtAlertIndex
- MIN-ACCESS accessible-for-notify
- DESCRIPTION
- "It is conformant to implement this object as
- accessible-for-notify "
-
- GROUP prtResponsiblePartyGroup
- DESCRIPTION
- "This group is unconditionally optional."
-
- GROUP prtExtendedInputGroup
-
-
-
-Bergman, et al. Standards Track [Page 140]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- DESCRIPTION
- "This group is unconditionally optional."
-
- GROUP prtInputMediaGroup
- DESCRIPTION
- "This group is unconditionally optional."
-
- GROUP prtExtendedOutputGroup
- DESCRIPTION
- "This group is unconditionally optional."
-
- GROUP prtOutputDimensionsGroup
- DESCRIPTION
- "This group is unconditionally optional."
-
- GROUP prtOutputFeaturesGroup
- DESCRIPTION
- "This group is unconditionally optional."
-
- GROUP prtMarkerSuppliesGroup
- DESCRIPTION
- "This group is unconditionally optional."
-
- GROUP prtMarkerColorantGroup
- DESCRIPTION
- "This group is unconditionally optional."
-
- GROUP prtAlertTimeGroup
- DESCRIPTION
- "This group is unconditionally optional."
-
- -- the prtResponsiblePartyGroup, prtExtendedInputGroup,
- -- prtInputMediaGroup, prtExtendedOutputGroup,
- -- prtOutputDimensionsGroup, prtOutputFeaturesGroup,
- -- prtMarkerSuppliesGroup, prtMarkerColorantGroup, and the
- -- prtAlertTimeGroup are completely optional. However, it is
- -- strongly RECOMMENDED that the prtAlertTimeGroup be implemented.
-
- -- New to version 2 of this printer MIB:
- OBJECT prtAuxiliarySheetStartupPage
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtAuxiliarySheetBannerPage
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
-
-
-Bergman, et al. Standards Track [Page 141]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- OBJECT prtInputMediaLoadTimeout
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- OBJECT prtInputNextIndex
- MIN-ACCESS read-only
- DESCRIPTION
- "It is conformant to implement this object as read-only"
-
- GROUP prtAuxiliarySheetGroup
- DESCRIPTION
- "This group is unconditionally optional."
-
- GROUP prtInputSwitchingGroup
- DESCRIPTION
- "This group is unconditionally optional."
-
- GROUP prtGeneralV2Group
- DESCRIPTION
- "This group is unconditionally optional."
-
- GROUP prtAlertTableV2Group
- DESCRIPTION
- "This group is unconditionally optional."
-
- GROUP prtChannelV2Group
- DESCRIPTION
- "This group is unconditionally optional."
-
- GROUP prtAlertTrapGroup
- DESCRIPTION
- "This group is unconditionally optional."
- ::= { prtMIBConformance 3 }
-
-prtMIBGroups OBJECT IDENTIFIER ::= { prtMIBConformance 2 }
--- These groups are from RFC 1759 and are applicable to Printer MIB V2
-
-prtGeneralGroup OBJECT-GROUP
- OBJECTS { prtGeneralConfigChanges,
- prtGeneralCurrentLocalization,
- prtGeneralReset, prtCoverDescription,
- prtCoverStatus,
- prtLocalizationLanguage, prtLocalizationCountry,
- prtLocalizationCharacterSet, prtStorageRefIndex,
- prtDeviceRefIndex }
- STATUS current
- DESCRIPTION
-
-
-
-Bergman, et al. Standards Track [Page 142]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- "The general printer group."
- ::= { prtMIBGroups 1 }
-
-prtResponsiblePartyGroup OBJECT-GROUP
- OBJECTS { prtGeneralCurrentOperator, prtGeneralServicePerson }
- STATUS current
- DESCRIPTION
- "The responsible party group contains contact information for
- humans responsible for the printer."
- ::= { prtMIBGroups 2 }
-
-prtInputGroup OBJECT-GROUP
- OBJECTS { prtInputDefaultIndex, prtInputType, prtInputDimUnit,
- prtInputMediaDimFeedDirDeclared,
- prtInputMediaDimXFeedDirDeclared,
- prtInputMediaDimFeedDirChosen,
- prtInputMediaDimXFeedDirChosen, prtInputCapacityUnit,
- prtInputMaxCapacity, prtInputCurrentLevel, prtInputStatus,
- prtInputMediaName }
- STATUS current
- DESCRIPTION
- "The input group."
- ::= { prtMIBGroups 3 }
-
-prtExtendedInputGroup OBJECT-GROUP
- OBJECTS { prtInputName, prtInputVendorName, prtInputModel,
- prtInputVersion, prtInputSerialNumber,
- prtInputDescription, prtInputSecurity }
- STATUS current
- DESCRIPTION
- "The extended input group."
- ::= { prtMIBGroups 4 }
-
-prtInputMediaGroup OBJECT-GROUP
- OBJECTS { prtInputMediaWeight, prtInputMediaType,
- prtInputMediaColor, prtInputMediaFormParts }
- STATUS current
- DESCRIPTION
- "The input media group."
- ::= { prtMIBGroups 5 }
-
-prtOutputGroup OBJECT-GROUP
- OBJECTS { prtOutputDefaultIndex, prtOutputType,
- prtOutputCapacityUnit, prtOutputMaxCapacity,
- prtOutputRemainingCapacity, prtOutputStatus }
- STATUS current
- DESCRIPTION
- "The output group."
-
-
-
-Bergman, et al. Standards Track [Page 143]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- ::= { prtMIBGroups 6 }
-
-prtExtendedOutputGroup OBJECT-GROUP
- OBJECTS { prtOutputName, prtOutputVendorName, prtOutputModel,
- prtOutputVersion, prtOutputSerialNumber,
- prtOutputDescription, prtOutputSecurity }
- STATUS current
- DESCRIPTION
- "The extended output group."
- ::= { prtMIBGroups 7 }
-
-prtOutputDimensionsGroup OBJECT-GROUP
- OBJECTS { prtOutputDimUnit, prtOutputMaxDimFeedDir,
- prtOutputMaxDimXFeedDir, prtOutputMinDimFeedDir,
- prtOutputMinDimXFeedDir }
- STATUS current
- DESCRIPTION
- "The output dimensions group"
- ::= { prtMIBGroups 8 }
-
-prtOutputFeaturesGroup OBJECT-GROUP
- OBJECTS { prtOutputStackingOrder,
- prtOutputPageDeliveryOrientation, prtOutputBursting,
- prtOutputDecollating, prtOutputPageCollated,
- prtOutputOffsetStacking }
- STATUS current
- DESCRIPTION
- "The output features group."
- ::= { prtMIBGroups 9 }
-
-prtMarkerGroup OBJECT-GROUP
- OBJECTS { prtMarkerDefaultIndex, prtMarkerMarkTech,
- prtMarkerCounterUnit, prtMarkerLifeCount,
- prtMarkerPowerOnCount, prtMarkerProcessColorants,
- prtMarkerSpotColorants, prtMarkerAddressabilityUnit,
- prtMarkerAddressabilityFeedDir,
- prtMarkerAddressabilityXFeedDir, prtMarkerNorthMargin,
- prtMarkerSouthMargin, prtMarkerWestMargin,
- prtMarkerEastMargin, prtMarkerStatus }
- STATUS current
- DESCRIPTION
- "The marker group."
- ::= { prtMIBGroups 10 }
-
-prtMarkerSuppliesGroup OBJECT-GROUP
- OBJECTS { prtMarkerSuppliesMarkerIndex,
- prtMarkerSuppliesColorantIndex, prtMarkerSuppliesClass,
- prtMarkerSuppliesType, prtMarkerSuppliesDescription,
-
-
-
-Bergman, et al. Standards Track [Page 144]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- prtMarkerSuppliesSupplyUnit,
- prtMarkerSuppliesMaxCapacity, prtMarkerSuppliesLevel }
- STATUS current
- DESCRIPTION
- "The marker supplies group."
- ::= { prtMIBGroups 11 }
-
-prtMarkerColorantGroup OBJECT-GROUP
- OBJECTS { prtMarkerColorantMarkerIndex, prtMarkerColorantRole,
- prtMarkerColorantValue, prtMarkerColorantTonality }
- STATUS current
- DESCRIPTION
- "The marker colorant group."
- ::= { prtMIBGroups 12 }
-
-prtMediaPathGroup OBJECT-GROUP
- OBJECTS { prtMediaPathDefaultIndex, prtMediaPathMaxSpeedPrintUnit,
- prtMediaPathMediaSizeUnit, prtMediaPathMaxSpeed,
- prtMediaPathMaxMediaFeedDir,
- prtMediaPathMaxMediaXFeedDir,
- prtMediaPathMinMediaFeedDir,
- prtMediaPathMinMediaXFeedDir, prtMediaPathType,
- prtMediaPathDescription, prtMediaPathStatus}
- STATUS current
- DESCRIPTION
- "The media path group."
- ::= { prtMIBGroups 13 }
-
-prtChannelGroup OBJECT-GROUP
- OBJECTS { prtChannelType, prtChannelProtocolVersion,
- prtChannelCurrentJobCntlLangIndex,
- prtChannelDefaultPageDescLangIndex, prtChannelState,
- prtChannelIfIndex, prtChannelStatus
- }
- STATUS current
- DESCRIPTION
- "The channel group."
- ::= { prtMIBGroups 14 }
-
-prtInterpreterGroup OBJECT-GROUP
- OBJECTS { prtInterpreterLangFamily, prtInterpreterLangLevel,
- prtInterpreterLangVersion, prtInterpreterDescription,
- prtInterpreterVersion, prtInterpreterDefaultOrientation,
- prtInterpreterFeedAddressability,
- prtInterpreterXFeedAddressability,
- prtInterpreterDefaultCharSetIn,
- prtInterpreterDefaultCharSetOut, prtInterpreterTwoWay }
- STATUS current
-
-
-
-Bergman, et al. Standards Track [Page 145]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- DESCRIPTION
- "The interpreter group."
- ::= { prtMIBGroups 15 }
-
-prtConsoleGroup OBJECT-GROUP
- OBJECTS { prtConsoleLocalization, prtConsoleNumberOfDisplayLines,
- prtConsoleNumberOfDisplayChars, prtConsoleDisable,
- prtConsoleDisplayBufferText, prtConsoleOnTime,
- prtConsoleOffTime, prtConsoleColor,
- prtConsoleDescription }
- STATUS current
- DESCRIPTION
- "The console group."
- ::= { prtMIBGroups 16 }
-
-prtAlertTableGroup OBJECT-GROUP
- OBJECTS { prtAlertSeverityLevel, prtAlertTrainingLevel,
- prtAlertGroup, prtAlertGroupIndex, prtAlertLocation,
- prtAlertCode, prtAlertDescription }
- STATUS current
- DESCRIPTION
- "The alert table group."
- ::= { prtMIBGroups 17 }
-
-prtAlertTimeGroup OBJECT-GROUP
- OBJECTS { prtAlertTime }
- STATUS current
- DESCRIPTION
- "The alert time group. Implementation of prtAlertTime is
- strongly RECOMMENDED."
- ::= { prtMIBGroups 18 }
-
-prtMIB2Groups OBJECT IDENTIFIER ::= { prtMIBConformance 4 }
--- These groups are unique to Printer MIB V2
-
-prtAuxiliarySheetGroup OBJECT-GROUP
- OBJECTS { prtAuxiliarySheetStartupPage,
- prtAuxiliarySheetBannerPage }
- STATUS current
- DESCRIPTION
- "The auxiliary sheet group."
- ::= { prtMIBGroups 19 }
-
-prtInputSwitchingGroup OBJECT-GROUP
- OBJECTS { prtInputMediaLoadTimeout, prtInputNextIndex }
- STATUS current
- DESCRIPTION
- "The input switching group."
-
-
-
-Bergman, et al. Standards Track [Page 146]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- ::= { prtMIBGroups 20 }
-
-prtGeneralV2Group OBJECT-GROUP
- OBJECTS { prtGeneralPrinterName, prtGeneralSerialNumber }
- STATUS current
- DESCRIPTION
- "The general printer group with new v2 objects."
- ::= { prtMIBGroups 21 }
-
-prtAlertTableV2Group OBJECT-GROUP
- OBJECTS { prtAlertIndex, prtAlertCriticalEvents, prtAlertAllEvents }
- STATUS current
- DESCRIPTION
- "The alert table group with new v2 objects and prtAlertIndex
- changed to MAX-ACCESS of 'read-only' for inclusion in the trap
- bindings (as originally defined in RFC 1759)."
-
- ::= { prtMIBGroups 22 }
-
-prtChannelV2Group OBJECT-GROUP
- OBJECTS { prtChannelInformation }
- STATUS current
- DESCRIPTION
- "The channel group with a new v2 object."
- ::= { prtMIBGroups 23 }
-
-prtAlertTrapGroup NOTIFICATION-GROUP
- NOTIFICATIONS { printerV2Alert }
- STATUS current
- DESCRIPTION
- "The alert trap group."
- ::= { prtMIBGroups 24 }
-
-END
-
-7. IANA Considerations
-
- The initial version the IANA Printer MIB defined in section 5 of this
- document is to be archived by IANA and subsequently maintained
- according to the Process specified in section 2.4.1 of this document.
- The most current and authoritative version of the IANA Printer MIB is
- available at:
-
- http://www.iana.org/assignments/ianaprinter-mib
-
-8. Internationalization Considerations
-
- See section 2.2.1.1, 'International Considerations'.
-
-
-
-Bergman, et al. Standards Track [Page 147]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-9. Security Considerations
-
- There are a number of management objects defined in this MIB module
- with a MAX-ACCESS clause of read-write and/or read-create. Such
- objects may be considered sensitive or vulnerable in some network
- environments. The support for SET operations in a non-secure
- environment without proper protection can have a negative effect on
- network operations. These are the tables and objects and their
- sensitivity/vulnerability:
-
- prtGeneralTable:
- prtGeneralCurrentLocalization - Possible data loss
- prtGeneralReset - Possible data loss
- prtGeneralCurrentOperator - Possible severe inconvenience
- prtGeneralServicePerson - Possible severe inconvenience
- prtInputDefaultIndex - Possible data loss
- prtOutputDefaultIndex - Possible minor inconvenience
- prtMarkerDefaultIndex - Possible minor inconvenience
- prtMediaPathDefaultIndex - Possible minor inconvenience
- prtConsoleLocalization - Possible severe inconvenience
- prtConsoleDisable - Possible severe inconvenience
- prtAuxiliarySheetStartupPage - Possible minor inconvenience
- prtAuxiliarySheetBannerPage - Possible minor inconvenience
- prtGeneralPrinterName - Possible severe inconvenience
- prtGeneralSerialNumber - Possible severe inconvenience
- prtInputTable:
- prtInputMediaDimFeedDirDeclared - Possible data loss
- prtInputMediaDimXFeedDirDeclared - Possible data loss
- prtInputMaxCapacity - Possible minor inconvenience
- prtInputCurrentLevel - Possible minor inconvenience
- prtInputMediaName - Possible minor inconvenience
- prtInputName - Possible minor inconvenience
- prtInputSecurity - Possible minor inconvenience
- prtInputMediaWeight - Possible minor inconvenience
- prtInputMediaType - Possible minor inconvenience
- prtInputMediaColor - Possible minor inconvenience
- prtInputMediaFormParts - Possible minor inconvenience
- prtInputMediaLoadTimeout - Possible minor inconvenience
- prtInputNextIndex - Possible minor inconvenience
- prtOutputTable
- prtOutputMaxCapacity - Possible minor inconvenience
- prtOutputRemainingCapacity - Possible minor inconvenience
- prtOutputName - Possible minor inconvenience
- prtOutputSecurity - Possible minor inconvenience
- prtOutputMaxDimFeedDir - Possible minor inconvenience
- prtOutputMaxDimXFeedDir - Possible minor inconvenience
- prtOutputMinDimFeedDir - Possible minor inconvenience
- prtOutputMinDimXFeedDir - Possible minor inconvenience
-
-
-
-Bergman, et al. Standards Track [Page 148]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- prtOutputStackingOrder - Possible minor inconvenience
- prtOutputPageDeliveryOrientation - Possible minor inconvenience
- prtOutputBursting - Possible minor inconvenience
- prtOutputDecollating - Possible minor inconvenience
- prtOutputPageCollated - Possible minor inconvenience
- prtOutputOffsetStacking - Possible minor inconvenience
- prtMarkerSuppliesTable
- prtMarkerSuppliesMaxCapacity - Possible minor inconvenience
- prtMarkerSuppliesLevel - Possible minor inconvenience
- prtChannelTable
- prtChannelCurrentJobCntlLangIndex - Possible data loss
- prtChannelDefaultPageDescLangIndex - Possible data loss
- prtChannelState - Possible minor inconvenience
- prtChannelIfIndex - Possible minor inconvenience
- prtInterpreterTable
- prtInterpreterDefaultOrientation - Possible data loss
- prtInterpreterDefaultCharSetIn - Possible data loss
- prtInterpreterDefaultCharSetOut - Possible minor inconvenience
- prtConsoleDisplayBufferTable
- prtConsoleDisplayBufferText - Possible minor inconvenience
- prtConsoleLightTable
- prtConsoleOnTime - Possible minor inconvenience
- prtConsoleOffTime - Possible minor inconvenience
-
- SNMP versions prior to SNMPv3 did not include adequate security.
- Even if the network itself is secure (for example by using IPSec),
- even then, there is no control as to who on the secure network is
- allowed to access and GET/SET (read/change/create/delete) the objects
- in this MIB module.
-
- It is RECOMMENDED that implementers consider the security features as
- provided by the SNMPv3 framework (see [RFC3410], section 8),
- including full support for the SNMPv3 cryptographic mechanisms (for
- authentication and privacy).
-
- Further, deployment of SNMP versions prior to SNMPv3 is NOT
- RECOMMENDED. Instead, it is RECOMMENDED to deploy SNMPv3 and to
- enable cryptographic security. It is then a customer/operator
- responsibility to ensure that the SNMP entity giving access to an
- instance of this MIB module is properly configured to give access to
- the objects only to those principals (users) that have legitimate
- rights to indeed GET or SET (change/create/delete) them.
-
- Where the operational capability of the printing device are
- especially vulnerable or difficult to administer, certain objects
- within this MIB have been tagged as READ-ONLY, preventing
- modification. Further, for all READ-WRITE objects within the MIB,
- the working group has included specific conformance guidelines
-
-
-
-Bergman, et al. Standards Track [Page 149]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- stating that vendors are free to implement these objects as READ-
- ONLY. This conformance allowance should cover cases where specific
- vendor vulnerabilities may differ from product to product. (See
- conformance section with regards to MIN-ACCESS clauses).
-
-10. References
-
-10.1. Normative References
-
- [ASCII] ANSI, "Coded Character Set - 7-bit American Standard Code
- for Information Interchange", ANSI X3.4-1986.
-
- [CHARSET] IANA Character Set Registry:
- http://www.iana.org/assignments/character-sets
-
- [CHARMIB] IANA Character Set MIB:
- http://www.iana.org/assignments/ianacharset-mib
-
- [ISO10175] ISO, "Document Printing Application (DPA)", ISO 10175,
- 1996.
-
- [ISO10646] ISO, "Universal Multiple-Octet Coded Character Set (UCS) -
- Part 1: Architecture and Basic Multilingual Plane", ISO
- 10646-1, September 2000. ISO, "Universal Multiple-Octet
- Coded Character Set (UCS) - Part 2: Supplemental Planes",
- ISO 10646-2, January 2001.
-
- [PWGMEDIA] IEEE-ISTO PWG "The Printer Working Group Standard for
- Media Standardized Names", IEEE-ISTO PWG 5101.1-2002.
-
- [RFC1213] McCloghrie, K. and M. Rose, "Management Information Base
- for Network Management of TCP/IP-based internets: MIB-II",
- STD 17, RFC 1213, March 1991.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
- Languages", BCP 18, RFC 2277, January 1998.
-
- [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
- 10646", RFC 3629, November 2003.
-
-
-
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 150]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an
- IANA Considerations Section in RFCs", BCP 26, RFC 2434,
- October 1998.
-
- [RFC2578] McCloghrie, K., Perkins, D., and J. Schoenwaelder,
- "Structure of Management Information Version 2 (SMIv2)",
- STD 58, RFC 2578, April 1999.
-
- [RFC2579] McCloghrie, K., Perkins, D., and J. Schoenwaelder,
- "Textual Conventions for SMIv2", STD 58, RFC 2579, April
- 1999.
-
- [RFC2580] McCloghrie, K., Perkins, D., and J. Schoenwaelder,
- "Conformance Statements for SMIv2", STD 58, RFC 2580,
- April 1999.
-
- [RFC2790] Waldbusser, S. and P. Grillo, "Host Resources MIB", RFC
- 2790, March 2000.
-
- [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group
- MIB", RFC 2863, June 2000.
-
- [RFC3806] Bergman, R., Lewis, H., and I. McDonald, "Printer
- Finishing MIB", RFC 3806, June 2004.
-
-10.2. Informative References
-
- [APPLEMAC] Apple staff, "Inside MacIntosh: Networking", 1994.
-
- [RFC854] Postel, J. and J. Reynolds, "Telnet Protocol
- Specification", STD 8, RFC 854, May 1983.
-
- [RFC959] Postel, J. and J. Reynolds, "File Transfer Protocol", STD
- 9, RFC 959, October 1985.
-
- [RFC1179] McLaughlin, L., "Line printer daemon protocol", RFC 1179,
- August 1990.
-
- [RFC1350] Sollins, K., "The TFTP Protocol (Revision 2)", STD 33, RFC
- 1350, July 1992.
-
- [RFC1945] Berners-Lee, T., Fielding, R., and H. Frystyk, "Hypertext
- Transfer Protocol - HTTP/1.0", RFC 1945, May 1996.
-
- [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
- RFC 2246, 1999.
-
-
-
-
-
-Bergman, et al. Standards Track [Page 151]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
- Resource Identifiers (URI): Generic Syntax", RFC 2396,
- August 1998.
-
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
- Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
- Transfer Protocol - HTTP/1.1", RFC 2616, June 1999.
-
- [RFC2821] Klensin, J., Ed., "Simple Mail Transfer Protocol", RFC
- 2821, April 2001.
-
- [RFC2822] Resnick, P., Ed., "Internet Message Format", RFC 2822,
- April 2001.
-
- [RFC2910] Herriot, R., Ed., Butler, S., Moore, P., Turner, R., and
- J. Wenn, "Internet Printing Protocol/1.1: Encoding and
- Transport", RFC 2910, September 2000.
-
- [RFC2911] Hastings, T., Ed., Herriot, R., deBry, R., Isaacson, S.,
- and P. Powell, "Internet Printing Protocol/1.1: Model and
- Semantics", RFC 2911, September 2000.
-
- [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration
- Procedures", BCP 19, RFC 2978, October 2000.
-
- [RFC3232] Reynolds, J., Ed., "Assigned Numbers: RFC 1700 is
- Replaced by an On-line Database", RFC 3232, January 2002.
-
- [RFC3285] Gahrns, M. and T. Hain, "Using Microsoft Word to create
- Internet Drafts and RFCs", RFC 3285, May 2002.
-
- [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart,
- "Introduction and Applicability Statements for Internet-
- Standard Management Framework", RFC 3410, December 2002.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 152]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-Appendix A - Glossary of Terms
-
- Addressability - On the marker, the number of distinct marking units
- (pels) per unit of addressability unit that can be set; for example,
- 300 dots per inch is expressed as 300 per 1000 Thousandths Of Inches
- and 4 dots per millimeter is 4 per 1000 Micrometers. Addressability
- is not resolution because marks that are one addressability position
- apart may not be independently resolvable by the eye due to factors
- such as gain in the area of marks so they overlap or nearly touch.
-
- Alert - A reportable event for which there is an entry in the alert
- table.
-
- Bin - An output sub-unit which may or may not be removable.
-
- Binary Change Event - An event which comes in pairs; the leading edge
- event and the trailing edge event. The leading edge event enters a
- state from which there is only one exit. A binary change event may
- be critical or non-critical. See unary change event.
-
- Bursting - The process by which continuous media is separated into
- individual sheets, typically by bursting along pre-formed
- perforations.
-
- Channel - A term used to describe a single source of data which is
- presented to a printer. The model that we use in describing a
- printer allows for an arbitrary number of channels. Multiple
- channels can exist on the same physical port. This is commonly done
- over Ethernet ports where EtherTalk, TCP/IP, and SPX/IPX protocols
- can be supplying different data streams simultaneously to a single
- printer on the same physical port.
-
- Collation - In multiple copy output, placing the pages from separate
- copies into separate ordered sets, ready for binding.
-
- Control Language - A data syntax or language for controlling the
- printer through the print data channel.
-
- Critical Alert - An alert triggered by an event which leads to a
- state in which printing is no longer possible; the printer is
- stopped.
-
- Decollating - The process by which the individual parts within a
- multi-part form are separated and sorted into separate stacks for
- each part.
-
- Description - Information about the configuration and capabilities of
- the printer and its various sub-units.
-
-
-
-Bergman, et al. Standards Track [Page 153]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- DPA - ISO 10175 Document Printing Application standard. A standard
- for a client server protocol for a print system, including (1)
- submitting print jobs to and (2) managing print jobs in a spooler.
-
- Event - A state change in the printer.
-
- Group - A collection of objects that represent a type of sub-unit of
- the printer.
-
- Host Resources MIB - See [RFC2790].
-
- IANA - Internet Assigned Numbers Authority. See [RFC3232].
-
- Idempotent - Idempotence is the property of an operation that results
- in the same state no matter how many times it is executed (at least
- once). This is a property that is shared by true databases in which
- operations on data items only change the state of the data item and
- do not have other side effects. Because the SNMP data model is that
- of operations on a database, SNMP MIB objects should be assumed to be
- idempotent. If a MIB object is defined in a non-idempotent way, the
- this data model can break in subtle ways when faced with packet loss,
- multiple managers, and other common conditions.
-
- In order to fulfill the common need for actions to result from
- SNMP Set operations, SNMP MIB objects can be modeled such that the
- change in state from one state to another has the side effect of
- causing an action. It is important to note that with this model,
- an SNMP operation that sets a value equal to its current value
- will cause no action. This retains the idempotence of a single
- command, while allowing actions to be initiated by SNMP SET
- requests.
-
- Input - A tray or bin from which instances of the media are obtained
- and fed into the Media Path.
-
- Interpreter - The embodiment of an algorithm that processes a data
- stream consisting of a Page Description Language (PDL) and/or a
- Control Language.
-
- Localization - The specification of human language, country, and
- character set needed to present information to people in their native
- languages.
-
- Management Application (a.k.a. Manager) - A program which queries and
- controls one or more managed nodes.
-
- Management Station - A physical computer on which one or more
- management applications can run.
-
-
-
-Bergman, et al. Standards Track [Page 154]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- Media Path - The mechanisms that transport instances of the media
- from an input, through the marker, possibly through media buffers and
- duplex pathways, out to the output with optional finishing applied.
- The inputs and outputs are not part of the Media Path.
-
- Non-critical Alert - An alert triggered by a reportable event which
- does not lead to a state in which printing is no longer possible;
- such an alert may lead to a state from which printing may no longer
- be possible in the future, such as the low toner state or the alert
- may be pure informational, such as a configuration change at the
- printer.
-
- Output - A bin or stacker which accepts instances of media that have
- been processed by a printer.
-
- Page Description Language (PDL) - A data syntax or language for the
- electronic representation of a document as a sequence of page images.
-
- Printer - A physical device that takes media from an input source,
- produces marks on that media according to some page description or
- page control language and puts the result in some output destination,
- possibly with finishing applied.
-
- Printing - The entire process of producing a printed document from
- generation of the file to be printed, choosing printing properties,
- selection of a printer, routing, queuing, resource management,
- scheduling, and finally printing including notifying the user.
-
- Reportable event - An event that is deemed of interest to a
- management station watching the printer.
-
- Status - Information regarding the current operating state of the
- printer and its various sub-units. This is an abstraction of the
- exact physical condition of the printer.
-
- Sub-mechanism - A distinguishable part of a sub-unit.
-
- Sub-unit - A part of the printer which may be a physical part, such
- as one of the input sources or a logical part such as an interpreter.
-
- Tray - An input sub-unit which is typically removable.
-
- Unary Change Event - An event that indicates a change of state of the
- printer, but to a state which is (often) just as valid as the state
- that was left, and from which no return is necessary. See binary
- change event.
-
-
-
-
-
-Bergman, et al. Standards Track [Page 155]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- Visible state - The portion of the state of the printer that can be
- examined by a management application.
-
- Warning - A non-critical alert. See non-critical alert.
-
-Appendix B - Media Size Names
-
- The PWG Standardized Media Names specification [PWGMEDIA], section 5
- Self Describing Names, contains the currently recommended media size
- names. This appendix lists the standardized media size names from
- ISO/IEC 10175 Document Printing Application (DPA), [ISO10175] as
- presented in RFC 1759. Management applications are encouraged to use
- the names from the PWG standard. However, many legacy systems exist
- that use the DPA names and they are presented here for the
- convenience of developers.
-
- A printer implementing the Printer MIB has no knowledge of these
- names, however; all media sizes in the MIB are given in terms of
- media dimensions as the values of prtInputMediaDimFeedDirChosen and
- prtInputMediaDimXFeedDirChosen.
-
- String name Description
-
- other
-
- unknown
- na-letter or letter North American letter size: 8.5 by 11 inches
- na-legal or legal North American legal size: 8.5 by 14 inches
- na-10x13-envelope North American 10x13 envelope
- size: 10 by 13 inches
- na-9x12-envelope North American 9x12 envelope
- size: 9 by 12 inches
- na-number-10-envelope North American number 10 business envelope
- size: 4.125 by 9.5 inches
- na-7x9-envelope North American 7x9 size: 7 by 9 inches
- na-9x11-envelope North American 9x11 size: 9 by 11 inches
- na-10x14-envelope North American 10x14 envelope
- size: 10 by 14 inches
- na-number-9-envelope North American number 9 business envelope
- size: 3.875 by 8.875 inches
- na-6x9-envelope North American 6x9 envelope
- size: 6 by 9 inches
- na-10x15-envelope North American 10x15 envelope
- size: 10 by 15 inches
- a engineering A size 8.5 inches by 11 inches
- b engineering B size 11 inches by 17 inches
- c engineering C size 17 inches by 22 inches
- d engineering D size 22 inches by 34 inches
-
-
-
-Bergman, et al. Standards Track [Page 156]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- e engineering E size 34 inches by 44 inches
- iso-a0 ISO A0 size: 841 mm by 1189 mm
- iso-a1 ISO A1 size: 594 mm by 841 mm
- iso-a2 ISO A2 size: 420 mm by 594 mm
- iso-a3 ISO A3 size: 297 mm by 420 mm
- iso-a4 ISO A4 size: 210 mm by 297 mm
- iso-a5 ISO A5 size: 148 mm by 210 mm
- iso-a6 ISO A6 size: 105 mm by 148 mm
- iso-a7 ISO A7 size: 74 mm by 105 mm
- iso-a8 ISO A8 size: 52 mm by 74 mm
- iso-a9 ISO A9 size: 37 mm by 52 mm
- iso-a10 ISO A10 size: 26 mm by 37 mm
- iso-b0 ISO B0 size: 1000 mm by 1414 mm
- iso-b1 ISO B1 size: 707 mm by 1000 mm
- iso-b2 ISO B2 size: 500 mm by 707 mm
- iso-b3 ISO B3 size: 353 mm by 500 mm
- iso-b4 ISO B4 size: 250 mm by 353 mm
- iso-b5 ISO B5 size: 176 mm by 250 mm
- iso-b6 ISO B6 size: 125 mm by 176 mm
- iso-b7 ISO B7 size: 88 mm by 125 mm
- iso-b8 ISO B8 size: 62 mm by 88 mm
- iso-b9 ISO B9 size: 44 mm by 62 mm
- iso-b10 ISO B10 size: 31 mm by 44 mm
- iso-c0 ISO C0 size: 917 mm by 1297 mm
- iso-c1 ISO C1 size: 648 mm by 917 mm
- iso-c2 ISO C2 size: 458 mm by 648 mm
- iso-c3 ISO C3 size: 324 mm by 458 mm
- iso-c4 ISO C4 size: 229 mm by 324 mm
- iso-c5 ISO C5 size: 162 mm by 229 mm
- iso-c6 ISO C6 size: 114 mm by 162 mm
- iso-c7 ISO C7 size: 81 mm by 114 mm
- iso-c8 ISO C8 size: 57 mm by 81 mm
- iso-designated ISO Designated Long
- size: 110 mm by 220 mm
- jis-b0 JIS B0 size 1030 mm by 1456 mm
- jis-b1 JIS B1 size 728 mm by 1030 mm
- jis-b2 JIS B2 size 515 mm by 728 mm
- jis-b3 JIS B3 size 364 mm by 515 mm
- jis-b4 JIS B4 size 257 mm by 364 mm
- jis-b5 JIS B5 size 182 mm by 257 mm
- jis-b6 JIS B6 size 128 mm by 182 mm
- jis-b7 JIS B7 size 91 mm by 128 mm
- jis-b8 JIS B8 size 64 mm by 91 mm
- jis-b9 JIS B9 size 45 mm by 64 mm
- jis-b10 JIS B10 size 32 mm by 45 mm
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 157]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-Appendix C - Media Names
-
- For the convenience of management application developers, this
- appendix lists the standardized media names from ISO/IEC 10175
- Document Printing Application (DPA), [ISO10175]. Management
- applications that present a dialogue for choosing media may wish to
- use these names as an alternative to separately specifying, size,
- color, and/or type. New names may also be created using this format
- and the names defined in the PWG Standardized Media Names
- specification [PWGMEDIA].
-
- Using standard media names will mean that a single management
- application dealing with printers from different vendors and under
- different system mangers will tend to use the same names for the same
- media. If selection of media by name is used, the attributes (size,
- type or color) implied by the name must be explicitly mapped to the
- appropriate object (prtInputMediaDimFeedDirDeclared,
- prtInputMediaDimXFeedDirDeclared, prtInputMediaType and
- prtInputMediaColor) in the MIB. The object prtInputMediaName is
- intended for display to an operator and is purely descriptive. The
- value in prtInputMediaName is not interpreted by the printer so using
- a standard name for this value will not change any of the other media
- attributes nor will it cause an alert if the media in the input sub-
- unit does not match the name.
-
- Simple Name Descriptor Text
-
- other
- unknown
- iso-a4-white Specifies the ISO A4 white medium with
- size: 210 mm by 297 mm as defined in ISO 216
- iso-a4-coloured Specifies the ISO A4 colored medium with
- size: 210 mm by 297 mm as defined in ISO 216
- iso-a4-transparent Specifies the ISO A4 transparent medium with
- size: 210 mm by 297 mm as defined in ISO 216
- iso-a3-white Specifies the ISO A3 white medium with
- size: 297 mm by 420 mm as defined in ISO 216
- iso-a3-coloured Specifies the ISO A3 colored medium with
- size: 297 mm by 420 mm as defined in ISO 216
- iso-a5-white Specifies the ISO A5 white medium with
- size: 148 mm by 210 mm as defined in ISO 216
- iso-a5-coloured Specifies the ISO A5 colored medium with
- size: 148 mm by 210 mm as defined in ISO 216
- iso-b4-white Specifies the ISO B4 white medium with
- size: 250 mm by 353 mm as defined in ISO 216
- iso-b4-coloured Specifies the ISO B4 colored medium with
- size: 250 mm by 353 mm as defined in ISO 216
-
-
-
-
-Bergman, et al. Standards Track [Page 158]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- iso-b5-white Specifies the ISO B5 white medium with
- size: 176 mm by 250 mm as defined in ISO 216
- iso-b5-coloured Specifies the ISO B5 colored medium with
- size: 176 mm by 250 mm as defined in ISO 216
- jis-b4-white Specifies the JIS B4 white medium with
- size: 257 mm by 364 mm as defined in JIS P0138
- jis-b4-coloured Specifies the JIS B4 colored medium with
- size: 257 mm by 364 mm as defined in JIS P0138
- jis-b5-white Specifies the JIS B5 white medium with
- size: 182 mm by 257 mm as defined in JIS P0138
- jis-b5-coloured Specifies the JIS B5 colored medium with
- size: 182 mm by 257 mm as defined in JIS P0138
-
- The following standard values are defined for North American media:
-
- na-letter-white Specifies the North American letter white
- medium with size: 8.5 inches by 11 inches
- na-letter-coloured Specifies the North American letter colored
- medium with size: 8.5 inches by 11 inches
- na-letter-transparent
- Specifies the North American letter
- transparent medium with size: 8.5 inches
- by 11 inches
- na-legal-white Specifies the North American legal white
- medium with size: 8.5 inches by 14 inches
- na-legal-coloured Specifies the North American legal colored
- medium with size: 8.5 inches by 14 inches
-
- The following standard values are defined for envelopes:
-
- iso-b5-envelope Specifies the ISO B5 envelope medium
- with size: 176 mm by 250 mm
- as defined in ISO 216 and ISO 269
- iso-b4-envelope Specifies the ISO B4 envelope medium
- with size: 250 mm by 353 mm
- as defined in ISO 216
- iso-c4-envelope Specifies the ISO C4 envelope medium
- with size: 229 mm by 324 mm
- as defined in ISO 216 and ISO 269
- iso-c5-envelope Specifies the ISO C5 envelope medium
- with size: 162 mm by 229 mm
- as defined in ISO 269
- iso-designated-long-envelope
- Specifies the ISO Designated Long envelope
- medium with size: 110 mm by 220 mm
- as defined in ISO 269
-
-
-
-
-
-Bergman, et al. Standards Track [Page 159]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- na-10x13-envelope Specifies the North American 10x13 envelope
- medium with size: 10 inches by 13 inches
- na-9x12-envelope Specifies the North American 9x12 envelope
- medium with size: 9 inches by 12 inches
- na-number-10-envelope
- Specifies the North American number 10
- business envelope medium with size: 4.125
- inches by 9.5 inches
- na-7x9-envelope Specifies the North American 7x9 inch envelope
-
- na-9x11-envelope Specifies the North American 9x11 inch envelope
-
- na-10x14-envelope Specifies the North American 10x14 inch envelope
-
- na-number-9-envelope
- Specifies the North American number 9
- business envelope 3.875 by 8.875 inches
- na-6x9-envelope Specifies the North American 6x9 inch envelope
-
- na-10x15-envelope Specifies the North American 10x15 inch envelope
-
- The following standard values are defined for the less commonly
- used media (white-only):
-
- iso-a0-white Specifies the ISO A0 white medium
- with size: 841 mm by 1189 mm
- as defined in ISO 216
- iso-a1-white Specifies the ISO A1 white medium
- with size: 594 mm by 841 mm
- as defined in ISO 216
- iso-a2-white Specifies the ISO A2 white medium
- with size: 420 mm by 594 mm
- as defined in ISO 216
- iso-a6-white Specifies the ISO A6 white medium
- with size: 105 mm by 148 mm
- as defined in ISO 216
- iso-a7-white Specifies the ISO A7 white medium
- with size: 74 mm by 105 mm
- as defined in ISO 216
- iso-a8-white Specifies the ISO A8 white medium
- with size: 52 mm by 74 mm
- as defined in ISO 216
- iso-a9-white Specifies the ISO A9 white medium
- with size: 39 mm by 52 mm
- as defined in ISO 216
- iso-a10-white Specifies the ISO A10 white medium
- with size: 26 mm by 37 mm
- as defined in ISO 216
-
-
-
-Bergman, et al. Standards Track [Page 160]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- iso-b0-white Specifies the ISO B0 white medium
- with size: 1000 mm by 1414 mm
- as defined in ISO 216
- iso-b1-white Specifies the ISO B1 white medium
- with size: 707 mm by 1000 mm
- as defined in ISO 216
- iso-b2-white Specifies the ISO B2 white medium
- with size: 500 mm by 707 mm
- as defined in ISO 216
- iso-b3-white Specifies the ISO B3 white medium
- with size: 353 mm by 500 mm
- as defined in ISO 216
- iso-b6-white Specifies the ISO B6 white medium
- with size: 125 mm by 176 mm i
- as defined in ISO 216
- iso-b7-white Specifies the ISO B7 white medium
- with size: 88 mm by 125 mm
- as defined in ISO 216
- iso-b8-white Specifies the ISO B8 white medium
- with size: 62 mm by 88 mm
- as defined in ISO 216
- iso-b9-white Specifies the ISO B9 white medium
- with size: 44 mm by 62 mm
- as defined in ISO 216
- iso-b10-white Specifies the ISO B10 white medium
- with size: 31 mm by 44 mm
- as defined in ISO 216
- jis-b0-white Specifies the JIS B0 white medium with size:
- 1030 mm by 1456 mm
- jis-b1-white Specifies the JIS B1 white medium with size:
- 728 mm by 1030 mm
- jis-b2-white Specifies the JIS B2 white medium with size:
- 515 mm by 728 mm
- jis-b3-white Specifies the JIS B3 white medium with size:
- 364 mm by 515 mm
- jis-b6-white Specifies the JIS B6 white medium with size:
- 257 mm by 364 mm
- jis-b7-white Specifies the JIS B7 white medium with size:
- 182 mm by 257 mm
- jis-b8-white Specifies the JIS B8 white medium with size:
- 128 mm by 182 mm
- jis-b9-white Specifies the JIS B9 white medium with size:
- 91 mm by 128 mm
- jis-b10-white Specifies the JIS B10 white medium with size:
- 64 mm by 91 mm
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 161]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- The following standard values are defined for engineering media:
- a Specifies the engineering A size medium with
- size: 8.5 inches by 11 inches
- b Specifies the engineering B size medium with
- size: 11 inches by 17 inches
- c Specifies the engineering C size medium with
- size: 17 inches by 22 inches
- d Specifies the engineering D size medium with
- size: 22 inches by 34 inches
- e Specifies the engineering E size medium with
- size: 34 inches by 44 inches
-
-Appendix D - Roles of Users
-
- Background
-
- The need for "Role Models" stemmed in large part from the need to
- understand the importance of any given proposed object for the MIB.
- Many times the real world need for a proposed object would be debated
- within the group; the debate would typically result in the need to
- describe the potential usage of the object in terms of a "live"
- person performing some type of printing-related task.
-
- Determining the value of a proposed object through identification of
- the associated human users was found to be so common that a more
- formalized model was required for consistent analysis. The model
- describing categories of human-oriented tasks is called "Role Models"
- in this document.
-
- In developing the Role Models it was necessary to identify the
- common, primary tasks that humans typically face when interacting
- with a printer and its related printing system(s). It was expected
- that certain kinds of tasks would serve to identify the various Role
- Models.
-
- In presenting the set of Role Models, the set of "Common Print System
- Tasks" are first presented, followed by the set of Role Model
- definitions. Finally, a simple matrix is presented in which Role
- Models and Tasks are cross-compared.
-
- Common Print System Tasks
-
- Upon researching the many tasks encountered by humans in dealing with
- printers and printing systems, the following were found to be
- pervasive within any operating environment:
-
- Printer job state - Determine the status of a job without a printer.
-
-
-
-
-Bergman, et al. Standards Track [Page 162]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- Printer capabilities - Determine the current capabilities of a
- printer, for example, the available media sizes, two-sided printing,
- a particular type of interpreter, etc.
-
- Printer job submission - Submit a print job to a printer.
-
- Printer job removal - Remove a job from a printer.
-
- Notification of events - Receive notification of the existence of a
- defined printer event. An event can be of many types, including
- warnings, errors, job stage completion (e.g., "job done"), etc.
-
- Printer configuration - Query the current configuration of a printer.
-
- Printer consumables - Determine the current state of any and all
- consumables within a printer.
-
- Print job identification - Determine the identification of a job
- within a printer.
-
- Internal printer status - Determine the current status of the
- printer.
-
- Printer identification - Determine the identity of a printer.
- Printer location - Determine the physical location of a printer.
-
- Local system configuration - Determine various aspects of the current
- configuration of the local system involved with the operation of a
- printer.
-
- These "tasks" cover a large spectrum of requirements surrounding the
- operation of a printer in a network environment. This list serves as
- the basis for defining the various Role Models described below.
-
- Proposed Role Models
-
- Following is the list of "Role Models" used to evaluate the
- requirements for any given Printer MIB object. Note that the keyword
- enclosed in parentheses represents an abbreviation for the particular
- Role Model in the matrix described later in this document.
-
- User (USER) - A person or application that submits print jobs to the
- printer; typically viewed as the "end user" within the overall
- printing environment.
-
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 163]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- Operator (OP) - A person responsible for maintaining a printer on a
- day-to-day basis, including such tasks as filling empty media trays,
- emptying full output trays, replacing toner cartridges, clearing
- simple paper jams, etc.
-
- Technician (TECH) - A person responsible for repairing a
- malfunctioning printer, performing routine preventive maintenance,
- and other tasks that typically require advanced training on the
- printer internals. An example of a "technician" would be a
- manufacturer's Field Service representative, or other person formally
- trained by the manufacturer or similar representative.
-
- System Manager (MGR) - A person responsible for configuration and
- troubleshooting of components involved in the overall printing
- environment, including printers, print queues and network
- connectivity issues. This person is typically responsible for
- ensuring the overall operational integrity of the print system
- components, and is typically viewed as the central point of
- coordination among all other Role Models.
-
- Help Desk (HELP) - A person responsible for supporting Users in
- their printing needs, including training Users and troubleshooting
- Users' printing problems.
-
- Asset Manager (AM) - A person responsible for managing an
- organization's printing system assets (primarily printers). Such a
- person needs to be able to identify and track the location of
- printing assets on an ongoing basis.
-
- Capacity Planner (CP) - A person responsible for tracking the usage
- of printing resources on an ongoing basis for the purpose of planning
- printer acquisitions and/or placement of printers based on usage
- trends.
-
- Installer (INST) - A person or application responsible for
- installing or configuring printing system components on a local
- system.
-
- Accountant (ACCT) - A person responsible for tracking the usage of
- printing resources on an ongoing basis for the purpose of charging
- Users for resources used.
-
- Matrix of Common Print System Tasks and Role Models
-
- To better understand the relationship between the set of defined
- "Common Print System Tasks" and the various "Role Models," the
- following matrix is provided.
-
-
-
-
-Bergman, et al. Standards Track [Page 164]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- It is important to recognize that many of the tasks will appear to be
- applicable to many of the Role Models. However, when considering the
- actual context of a task, it is very important to realize that often
- the actual context of a task is such that the Role Model can change.
-
- For example, it is obvious that a "System Manager" must be able to
- submit print jobs to a printer; however, when submitting a print job,
- a person identified as a "System Manager" is actually operating in
- the context of a "User" in this case; hence, the requirement to
- submit a print job is not listed as a requirement for a System
- Manager.
-
- Conversely, while a "User" must be able to remove a job previously
- submitted to a printer, an "Operator" is often expected to be able to
- remove any print job from any printer; hence, print job removal is a
- (subtly different) requirement for both the "User" and "Operator"
- Role Models.
-
- Role Models
- -----------
-
- Requirement Area USER OP TECH MGR HELP AM CP INST ACCT
- Print job status xx xx xx xx xx
- Printer capabilities xx xx xx
- Print job submission xx
- Print job removal xx xx
- Notification of events xx xx
- Printer configuration xx xx
- Printer consumables xx xx xx
- Print job identification xx xx xx xx xx
- Internal printer status xx xx xx
- Printer identification xx xx xx xx xx xx xx
- Printer location xx
- Local system configuration xx xx
-
-Appendix E - Overall Printer Status Table
-
- The Status Table establishes a convention for the top 25 printer
- errors. The table defines a suggested relationship between various
- printer states and the variables Printer hrDeviceStatus,
- hrPrinterStatus, hrPrinterDetectedErrorState, prtAlertGroup,
- prtAlertCode and various sub-unit status variables (prtInputStatus,
- prtOutputStatus, prtMarkerStatus, prtMediaPathStatus and
- prtChannelStatus). This table is the recommended implementation of
- these variables. It is provided to guide implementors of this MIB
- and users of the MIB by providing a sample set of states and the
- variable values that are expected to be produced as result of that
- state. This information supplements that provided in Section
-
-
-
-Bergman, et al. Standards Track [Page 165]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- 2.2.13.2 "Overall Printer Status". This is not an exhaustive list
- rather it is a guideline.
-
- The definition of PrtSubUnitStatusTC specifies that SubUnitStatus is
- an integer that is the sum of 5 distinct values/states: Availability,
- Critical, Non-Critical, On-line and Transitioning. Thus when a non-
- critical alert or alerts are present the values for Availability,
- On-Line and Transitioning will be summed with the Non- Critical
- Alerts (8) value.
-
- The table was generated in landscape format and is located at
- ftp://ftp.pwg.org/pub/pwg/pmp/contributions/Top25Errors.pdf.
-
-Appendix F - Participants
-
- The Printer MIB Working Group would like to extend a special thank
- you to the following individuals that put forth a significant effort
- to review this document and provide numerous suggestions for
- improvement.
-
- David Harrington - Enterasys Networks
- Juergen Schoenwaelder - TU Braunschweig
- Bert Wijnen - Lucent Technologies and IETF Op & Mngmt, Area Director
-
- This version of the Printer MIB would not be possible without the
- previous work that resulted in RFC 1759. The authors of the Printer
- MIB version 2 would like to acknowledge the following individuals for
- their efforts in developing the base for this document. A special
- recognition is also extended to Steve Waldbusser, who provided
- significant technical guidance in the development of the architecture
- of the Printer MIB.
-
- Joel Gyllenskog - Microworks
- Tom Hastings - Xerox
- Jay Martin - Underscore, Inc.
- Ron Smith - Texas Instruments
- Steve Waldbusser - Lucent Technologies
- Don Wright - Lexmark
- Steve Zilles - Adobe
-
- The following people attended at least one meeting of the Printer MIB
- Working Group for version 2; many attended most meetings.
-
- Ron Bergman - Hitachi Printing Solutions
- Luis Cubero - Hewlett-Packard
- Jay Cummings - Novell
- Andy Davidson - Tektronix
- Lee Farrell - Canon
-
-
-
-Bergman, et al. Standards Track [Page 166]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- Tom Hastings - Xerox
- Scott Isaacson - Novell
- Binnur Al-Kazily - Hewlett-Packard
- Rick Landau - Digital Equipment Corporation
- David Kellerman - Northlake Software
- Harry Lewis - IBM
- Pete Loya - Hewlett-Packard
- Jay Martin - Underscore, Inc.
- Bob Pentecost - Hewlett-Packard
- Dave Roach - Unisys
- Stuart Rowley - Kyocera
- Bob Setterbo - Adobe
- Mike Timperman - Lexmark
- Randy Turner - 2Wire, Inc.
- Bill Wagner - NETsilicon, Inc.
- Chris Wellens - Interworking Labs
- Craig Whittle - Sharp Labs
- Don Wright - Lexmark
- Lloyd Young - Lexmark
- Atsushi Yuki - Kyocera
- Steve Zilles - Adobe
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 167]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-Significant Contributors
-
- Ray Casterline
- Lighthouse Solutions, LLC
-
- Phone: (716) 218-9910
- EMail: RayCasterline@lhsolutions.com
-
- Gary Gocek
-
- Phone: (585) 223-3826
- EMail: gary@gocek.org
-
- Thomas N. Hastings
- Xerox Corporation
-
- Phone: (310) 333-6413
- EMail: hastings@cp10.es.xerox.com
-
- Scott Isaacson
- Novell
-
- Phone: (801) 861-7366
- EMail: sisaacson@novell.com
-
- Binnur Al-Kazily
- Hewlett-Packard, Inc.
-
- Phone: (208) 396-6372
- EMail: binnur_al-kazily@hp.com
-
- David Kellerman
- Northlake Software
-
- Phone: (503) 228-3383
- EMail: kellerman@nls.com
-
- Matt King
- Lexmark International
-
- Phone: (859) 232-6907
- EMail: emking@lexmark.com
-
- Jay Martin
- Underscore, Inc.
-
- Phone: (603) 889-7000
- EMail: jkm@underscore.com
-
-
-
-Bergman, et al. Standards Track [Page 168]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-
- Mike McKay
- Novell, Inc.
-
- Bob Pentecost
- Hewlett-Packard
-
- Phone: (208) 396-3312
- EMail: bpenteco@boi.hp.com
-
- Stuart Rowley
- Kyocera
-
- Phone: (510) 299-7206
- EMail: stuart.rowley@kyocera.com
-
- Gail Songer
- Peerless Systems Networking
-
- Phone: (650) 569-4414
- EMail: gsonger@peerless.com
-
- Randy Turner
- 2Wire, Inc.
-
- Phone (408) 895-1216
- EMail: rturner@2wire.com
-
- William Wagner
- NETsilicon, Inc.
-
- Phone: (781) 398-4588
- EMail: WWagner@NetSilicon.com
-
- Chris Wellens
- Interworking Labs
-
- Phone: (408) 685-3190
- EMail: chrisw@iwl.com
-
- F.D. Wright
- Lexmark International
-
- Phone: (859) 232-4808
- EMail: don@lexmark.com
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 169]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
- Lloyd Young
- Lexmark International
-
- Phone: (859) 232-5150
- EMail: lpyoung@lexmark.com
-
- Stephen N. Zilles
- Adobe Systems, Inc.
-
- Phone: (415) 962-4766
- EMail: szilles@adobe.com
-
-Authors' Addresses
-
- Ron Bergman (Chairman)
- Hitachi Printing Solutions America
- 2635 Park Center Drive
- Simi Valley, CA 93065-6209
-
- Phone: (805) 578-4421
- EMail: Ron.Bergman@hitachi-ps.us
-
-
- Harry Lewis
- IBM
- 6300 Diagonal Hwy.
- Boulder, CO 80301
-
- Phone (303) 924-5337
- EMail: harryl@us.ibm.com
-
-
- Ira McDonald
- High North Inc
- P.O. Box 221
- Grand Marais, MI 49839
-
- Phone: (906) 494-2434 or (906) 494-2697
- EMail: imcdonald@sharplabs.com
-
-
-
-
-
-
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 170]
-\f
-RFC 3805 Printer MIB v2 June 2004
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2004). This document is subject
- to the rights, licenses and restrictions contained in BCP 78, and
- except as set forth therein, the authors retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at ietf-
- ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-Bergman, et al. Standards Track [Page 171]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group I. McDonald
-Request for Comments: 3808 High North
-Category: Informational June 2004
-
-
- IANA Charset MIB
-
-Status of this Memo
-
- This memo provides information for the Internet community. It does
- not specify an Internet standard of any kind. Distribution of this
- memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2004).
-
-Abstract
-
- This memo defines a portion of the Management Information Base (MIB)
- for use with network management protocols in the Internet community.
- This IANA Charset MIB is now an IANA registry. In particular, a
- single textual convention 'IANACharset' is defined that may be used
- to specify charset labels in MIB objects. 'IANACharset' was
- extracted from Printer MIB v2 (RFC 3805). 'IANACharset' was
- originally defined (and mis-named) as 'CodedCharSet' in Printer MIB
- v1 (RFC 1759). A tool has been written in C, that may be used by
- IANA to regenerate this IANA Charset MIB, when future charsets are
- registered in accordance with the IANA Charset Registration
- Procedures (RFC 2978).
-
-Table of Contents
-
- 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . 2
- 1.1. Conformance Terminology . . . . . . . . . . . . . . . . 2
- 1.2. Charset Terminology . . . . . . . . . . . . . . . . . . 2
- 2. The Internet-Standard Management Framework. . . . . . . . . . 2
- 3. Generation of IANA Charset MIB. . . . . . . . . . . . . . . . 3
- 4. Definition of IANA Charset MIB. . . . . . . . . . . . . . . . 3
- 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
- 6. Internationalization Considerations . . . . . . . . . . . . . 10
- 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11
- 8. Acknowledgements. . . . . . . . . . . . . . . . . . . . . . . 11
- 9. References. . . . . . . . . . . . . . . . . . . . . . . . . . 11
- 9.1. Normative References. . . . . . . . . . . . . . . . . . 11
- 9.2. Informative References. . . . . . . . . . . . . . . . . 12
- 10. Authors' Addresses. . . . . . . . . . . . . . . . . . . . . . 13
- 11. Full Copyright Statement. . . . . . . . . . . . . . . . . . . 14
-
-
-
-McDonald Informational [Page 1]
-\f
-RFC 3808 IANA Charset MIB June 2004
-
-
-1. Introduction
-
- This IANA Charset MIB [CHARMIB] module defines the single textual
- convention 'IANACharset'. Once adopted, all future versions of the
- IANA Charset MIB [CHARMIB] may be machine-generated whenever the IANA
- Charset Registry [CHARSET] is updated by IANA staff according to the
- procedures defined in [RFC2978], using the utility [CHARGEN]
- described in section 3 of this document or any other machine-
- generation method.
-
- It is strongly recommended that future updates to the IANA Charset
- MIB [CHARMIB] be machine-generated (rather than hand-edited) to avoid
- asynchrony between the IANA Charset Registry [CHARSET] and the IANA
- Charset MIB [CHARMIB].
-
- Note: Questions and comments on this IANA Charset MIB [CHARMIB]
- should be sent to the editor (imcdonald@sharplabs.com) and IANA
- (iana@iana.org) with a copy to the IETF Charsets mailing list (ietf-
- charset@iana.org).
-
-1.1. Conformance Terminology
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in BCP 14, RFC 2119
- [RFC2119].
-
-1.2. Charset Terminology
-
- The following terms are used in this specification, exactly as
- defined in section 1 'Definitions and Notation' of the IANA Charset
- Registration Procedures [RFC2978]: "character", "charset", "coded
- character set (CCS)", and "character encoding scheme (CES)".
-
-2. The Internet-Standard Management Framework
-
- For a detailed overview of the documents that describe the current
- Internet-Standard Management Framework, please refer to section 7 of
- RFC 3410 [RFC3410].
-
- Managed objects are accessed via a virtual information store, termed
- the Management Information Base or MIB. MIB objects are generally
- accessed through the Simple Network Management Protocol (SNMP).
- Objects in the MIB are defined using the mechanisms defined in the
- Structure of Management Information (SMI). This memo specifies a MIB
- module that is compliant to the SMIv2, which is described in STD 58,
- RFC 2578 [RFC2578], STD 58, RFC 2579 [RFC2579], and STD 58, RFC 2580
- [RFC2580].
-
-
-
-McDonald Informational [Page 2]
-\f
-RFC 3808 IANA Charset MIB June 2004
-
-
-3. Generation of IANA Charset MIB
-
- Intellectual Property: The C language utility 'ianachar.c' [CHARGEN]
- and the IANA Charset MIB template file [CHARTEMP] are hereby donated
- by the author (Ira McDonald) to IANA, in perpetuity, free of license
- or any other restraint.
-
- The [CHARGEN] utility may be used to generate an updated version of
- the 'IANACharset' textual convention by reading and parsing the
- (currently plaintext) IANA Charset Registry [CHARSET].
-
- This utility parses each charset registration, finding (in order):
-
- 1) The 'Name' field (which is saved for a fallback - see below);
-
- 2) The 'MIBenum' field (which contains the IANA-assigned positive
- decimal enum value); and
-
- 3) The (usually present) 'Alias' field that begins with 'cs' (that
- contains the IANA-assigned enum label). If an 'Alias' field is
- not found, the utility constructs one from the 'Name' field by:
-
- - Beginning the enum label with a lowercase 'cs' prefix;
-
- - Copying _only_ alpha/numeric characters from the 'Name' field
- to the enum label (ignoring punctuation, whitespace, etc.).
-
-4. Definition of IANA Charset MIB
-
-IANA-CHARSET-MIB DEFINITIONS ::= BEGIN
--- http://www.iana.org/assignments/ianacharset-mib
-
-IMPORTS
- MODULE-IDENTITY,
- mib-2
- FROM SNMPv2-SMI -- [RFC2578]
- TEXTUAL-CONVENTION
- FROM SNMPv2-TC; -- [RFC2579]
-
-ianaCharsetMIB MODULE-IDENTITY
- LAST-UPDATED "200406080000Z"
- ORGANIZATION "IANA"
- CONTACT-INFO " Internet Assigned Numbers Authority
-
- Postal: ICANN
- 4676 Admiralty Way, Suite 330
- Marina del Rey, CA 90292
-
-
-
-
-McDonald Informational [Page 3]
-\f
-RFC 3808 IANA Charset MIB June 2004
-
-
- Tel: +1 310 823 9358
- E-Mail: iana@iana.org"
-
- DESCRIPTION "This MIB module defines the IANACharset
- TEXTUAL-CONVENTION. The IANACharset TC is used to
- specify the encoding of string objects defined in
- a MIB.
-
- Each version of this MIB will be released based on
- the IANA Charset Registry file (see RFC 2978) at
- http://www.iana.org/assignments/character-sets.
-
- Note: The IANACharset TC, originally defined in
- RFC 1759, was inaccurately named CodedCharSet.
-
- Note: Best practice is to define new MIB string
- objects with invariant UTF-8 (RFC 3629) syntax
- using the SnmpAdminString TC (defined in RFC 3411)
- in accordance with IETF Policy on Character Sets and
- Languages (RFC 2277).
-
- Copyright (C) The Internet Society (2004). The
- initial version of this MIB module was published
- in RFC 3808; for full legal notices see the RFC
- itself. Supplementary information may be
- available on
- http://www.ietf.org/copyrights/ianamib.html."
-
- -- revision history
-
- REVISION "200406080000Z"
- DESCRIPTION "Original version transferred from Printer MIB,
- generated from the IANA maintained assignments
- http://www.iana.org/assignments/character-sets."
-
- ::= { mib-2 106 }
-
-IANACharset ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "Specifies an IANA registered 'charset' - coded character set
- (CCS) plus optional character encoding scheme (CES) - terms
- defined in 'IANA Charset Registration Procedures' (RFC 2978).
-
- Objects of this syntax are used to specify the encoding for
- string objects defined in one or more MIBs. For example, the
- prtLocalizationCharacterSet, prtInterpreterDefaultCharSetIn, and
- prtInterpreterDefaultCharSetOut objects defined in Printer MIB.
-
-
-
-McDonald Informational [Page 4]
-\f
-RFC 3808 IANA Charset MIB June 2004
-
-
- The current list of 'charset' names and enumerated values
- is contained in the IANA Character Set Registry at:
-
- http://www.iana.org/assignments/character-sets
-
- Enum names are derived from the IANA Charset Registry 'Alias'
- fields that begin with 'cs' (for character set).
- Enum values are derived from the parallel 'MIBenum' fields."
- SYNTAX INTEGER {
- other(1), -- used if the designated
- -- character set is not currently
- -- registered by IANA
- unknown(2), -- used as a default value
- csASCII(3),
- csISOLatin1(4),
- csISOLatin2(5),
- csISOLatin3(6),
- csISOLatin4(7),
- csISOLatinCyrillic(8),
- csISOLatinArabic(9),
- csISOLatinGreek(10),
- csISOLatinHebrew(11),
- csISOLatin5(12),
- csISOLatin6(13),
- csISOTextComm(14),
- csHalfWidthKatakana(15),
- csJISEncoding(16),
- csShiftJIS(17),
- csEUCPkdFmtJapanese(18),
- csEUCFixWidJapanese(19),
- csISO4UnitedKingdom(20),
- csISO11SwedishForNames(21),
- csISO15Italian(22),
- csISO17Spanish(23),
- csISO21German(24),
- csISO60DanishNorwegian(25),
- csISO69French(26),
- csISO10646UTF1(27),
- csISO646basic1983(28),
- csINVARIANT(29),
- csISO2IntlRefVersion(30),
- csNATSSEFI(31),
- csNATSSEFIADD(32),
- csNATSDANO(33),
- csNATSDANOADD(34),
- csISO10Swedish(35),
- csKSC56011987(36),
- csISO2022KR(37),
-
-
-
-McDonald Informational [Page 5]
-\f
-RFC 3808 IANA Charset MIB June 2004
-
-
- csEUCKR(38),
- csISO2022JP(39),
- csISO2022JP2(40),
- csISO13JISC6220jp(41),
- csISO14JISC6220ro(42),
- csISO16Portuguese(43),
- csISO18Greek7Old(44),
- csISO19LatinGreek(45),
- csISO25French(46),
- csISO27LatinGreek1(47),
- csISO5427Cyrillic(48),
- csISO42JISC62261978(49),
- csISO47BSViewdata(50),
- csISO49INIS(51),
- csISO50INIS8(52),
- csISO51INISCyrillic(53),
- csISO54271981(54),
- csISO5428Greek(55),
- csISO57GB1988(56),
- csISO58GB231280(57),
- csISO61Norwegian2(58),
- csISO70VideotexSupp1(59),
- csISO84Portuguese2(60),
- csISO85Spanish2(61),
- csISO86Hungarian(62),
- csISO87JISX0208(63),
- csISO88Greek7(64),
- csISO89ASMO449(65),
- csISO90(66),
- csISO91JISC62291984a(67),
- csISO92JISC62991984b(68),
- csISO93JIS62291984badd(69),
- csISO94JIS62291984hand(70),
- csISO95JIS62291984handadd(71),
- csISO96JISC62291984kana(72),
- csISO2033(73),
- csISO99NAPLPS(74),
- csISO102T617bit(75),
- csISO103T618bit(76),
- csISO111ECMACyrillic(77),
- csa71(78),
- csa72(79),
- csISO123CSAZ24341985gr(80),
- csISO88596E(81),
- csISO88596I(82),
- csISO128T101G2(83),
- csISO88598E(84),
- csISO88598I(85),
-
-
-
-McDonald Informational [Page 6]
-\f
-RFC 3808 IANA Charset MIB June 2004
-
-
- csISO139CSN369103(86),
- csISO141JUSIB1002(87),
- csISO143IECP271(88),
- csISO146Serbian(89),
- csISO147Macedonian(90),
- csISO150(91),
- csISO151Cuba(92),
- csISO6937Add(93),
- csISO153GOST1976874(94),
- csISO8859Supp(95),
- csISO10367Box(96),
- csISO158Lap(97),
- csISO159JISX02121990(98),
- csISO646Danish(99),
- csUSDK(100),
- csDKUS(101),
- csKSC5636(102),
- csUnicode11UTF7(103),
- csISO2022CN(104),
- csISO2022CNEXT(105),
- csUTF8(106),
- csISO885913(109),
- csISO885914(110),
- csISO885915(111),
- csISO885916(112),
- csGBK(113),
- csGB18030(114),
- csOSDEBCDICDF0415(115),
- csOSDEBCDICDF03IRV(116),
- csOSDEBCDICDF041(117),
- csUnicode(1000),
- csUCS4(1001),
- csUnicodeASCII(1002),
- csUnicodeLatin1(1003),
- csUnicodeIBM1261(1005),
- csUnicodeIBM1268(1006),
- csUnicodeIBM1276(1007),
- csUnicodeIBM1264(1008),
- csUnicodeIBM1265(1009),
- csUnicode11(1010),
- csSCSU(1011),
- csUTF7(1012),
- csUTF16BE(1013),
- csUTF16LE(1014),
- csUTF16(1015),
- csCESU8(1016),
- csUTF32(1017),
- csUTF32BE(1018),
-
-
-
-McDonald Informational [Page 7]
-\f
-RFC 3808 IANA Charset MIB June 2004
-
-
- csUTF32LE(1019),
- csBOCU1(1020),
- csWindows30Latin1(2000),
- csWindows31Latin1(2001),
- csWindows31Latin2(2002),
- csWindows31Latin5(2003),
- csHPRoman8(2004),
- csAdobeStandardEncoding(2005),
- csVenturaUS(2006),
- csVenturaInternational(2007),
- csDECMCS(2008),
- csPC850Multilingual(2009),
- csPCp852(2010),
- csPC8CodePage437(2011),
- csPC8DanishNorwegian(2012),
- csPC862LatinHebrew(2013),
- csPC8Turkish(2014),
- csIBMSymbols(2015),
- csIBMThai(2016),
- csHPLegal(2017),
- csHPPiFont(2018),
- csHPMath8(2019),
- csHPPSMath(2020),
- csHPDesktop(2021),
- csVenturaMath(2022),
- csMicrosoftPublishing(2023),
- csWindows31J(2024),
- csGB2312(2025),
- csBig5(2026),
- csMacintosh(2027),
- csIBM037(2028),
- csIBM038(2029),
- csIBM273(2030),
- csIBM274(2031),
- csIBM275(2032),
- csIBM277(2033),
- csIBM278(2034),
- csIBM280(2035),
- csIBM281(2036),
- csIBM284(2037),
- csIBM285(2038),
- csIBM290(2039),
- csIBM297(2040),
- csIBM420(2041),
- csIBM423(2042),
- csIBM424(2043),
- csIBM500(2044),
- csIBM851(2045),
-
-
-
-McDonald Informational [Page 8]
-\f
-RFC 3808 IANA Charset MIB June 2004
-
-
- csIBM855(2046),
- csIBM857(2047),
- csIBM860(2048),
- csIBM861(2049),
- csIBM863(2050),
- csIBM864(2051),
- csIBM865(2052),
- csIBM868(2053),
- csIBM869(2054),
- csIBM870(2055),
- csIBM871(2056),
- csIBM880(2057),
- csIBM891(2058),
- csIBM903(2059),
- csIBBM904(2060),
- csIBM905(2061),
- csIBM918(2062),
- csIBM1026(2063),
- csIBMEBCDICATDE(2064),
- csEBCDICATDEA(2065),
- csEBCDICCAFR(2066),
- csEBCDICDKNO(2067),
- csEBCDICDKNOA(2068),
- csEBCDICFISE(2069),
- csEBCDICFISEA(2070),
- csEBCDICFR(2071),
- csEBCDICIT(2072),
- csEBCDICPT(2073),
- csEBCDICES(2074),
- csEBCDICESA(2075),
- csEBCDICESS(2076),
- csEBCDICUK(2077),
- csEBCDICUS(2078),
- csUnknown8BiT(2079),
- csMnemonic(2080),
- csMnem(2081),
- csVISCII(2082),
- csVIQR(2083),
- csKOI8R(2084),
- csHZGB2312(2085),
- csIBM866(2086),
- csPC775Baltic(2087),
- csKOI8U(2088),
- csIBM00858(2089),
- csIBM00924(2090),
- csIBM01140(2091),
- csIBM01141(2092),
- csIBM01142(2093),
-
-
-
-McDonald Informational [Page 9]
-\f
-RFC 3808 IANA Charset MIB June 2004
-
-
- csIBM01143(2094),
- csIBM01144(2095),
- csIBM01145(2096),
- csIBM01146(2097),
- csIBM01147(2098),
- csIBM01148(2099),
- csIBM01149(2100),
- csBig5HKSCS(2101),
- csIBM1047(2102),
- csPTCP154(2103),
- csAmiga1251(2104),
- csKOI7switched(2105),
- cswindows1250(2250),
- cswindows1251(2251),
- cswindows1252(2252),
- cswindows1253(2253),
- cswindows1254(2254),
- cswindows1255(2255),
- cswindows1256(2256),
- cswindows1257(2257),
- cswindows1258(2258),
- csTIS620(2259),
- reserved(3000)
- }
-END
-
-5. IANA Considerations
-
- IANA has assigned a base arc in the 'mgmt' (standards track) OID tree
- for the 'ianaCharset' MODULE-IDENTITY defined in the IANA Charset MIB
- [CHARMIB].
-
- Whenever any 'charset' is added to the IANA Charset Registry
- [CHARSET], a new version of the IANA Charset MIB [CHARMIB] may be
- machine-generated using the C language utility [CHARGEN], described
- in section 3 of this document or some other utility.
-
-6. Internationalization Considerations
-
- The IANA Charset MIB [CHARMIB] defines the 'IANACharset' textual
- convention that may be used in a given MIB module to supply explicit
- character set labels for one or more text string objects defined in
- that MIB module.
-
- For example, the Printer MIB [RFC1759] defines the three character
- set label objects 'prtLocalizationCharacterSet' (for description and
- console strings), 'prtInterpreterDefaultCharSetIn' (for received
-
-
-
-
-McDonald Informational [Page 10]
-\f
-RFC 3808 IANA Charset MIB June 2004
-
-
- print job input data), and 'prtIntpreterDefaultCharSetOut' (for
- processed print job output data).
-
- The IANA Charset MIB [CHARMIB] supports implementation of the best
- practices specified in "IETF Policy on Character Sets and Languages"
- [RFC2277].
-
- Note: The use of the 'SnmpAdminString' textual convention defined in
- [RFC3411], which has a fixed character set of UTF-8 [RFC3629], is
- STRONGLY RECOMMENDED in defining new MIB modules. The IANA Charset
- MIB [CHARMIB] supports locale-specific MIB objects with variable
- character sets.
-
-7. Security Considerations
-
- This MIB module does not define any management objects. Instead, it
- defines a (set of) textual convention(s) which may be used by other
- MIB modules to define management objects.
-
- Meaningful security considerations can only be written in the MIB
- modules that define management objects. Therefore, this document has
- no impact on the security of the Internet.
-
-8. Acknowledgements
-
- The editor would like to thank: Bert Wijnen (Lucent) for his
- original suggestion that the 'IANACharset' textual convention should
- be extracted from Printer MIB v2 [RFC3805]; Ron Bergman (Hitachi
- Printing Solutions) and Harry Lewis (IBM) for their many years of
- effort as editors of Printer MIB v2 [RFC3805].
-
-9. References
-
-9.1. Normative References
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
- Languages", RFC 2277, January 1998.
-
- [RFC2578] McCloghrie, K., Perkins, D., and J. Schoenwaelder,
- "Structure of Management Information Version 2 (SMIv2)",
- STD 58, RFC 2578, April 1999.
-
- [RFC2579] McCloghrie, K., Perkins, D., and J. Schoenwaelder,
- "Textual Conventions for SMIv2", STD 58, RFC 2579, April
- 1999.
-
-
-
-McDonald Informational [Page 11]
-\f
-RFC 3808 IANA Charset MIB June 2004
-
-
- [RFC2580] McCloghrie, K., Perkins, D., and J. Schoenwaelder,
- "Conformance Statements for SMIv2", STD 58, RFC 2580,
- April 1999.
-
- [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration
- Procedures", BCP 19, RFC 2978, October 2000.
-
- [RFC3411] Harrington, D., Presuhn, R., and B. Wijnen, "An
- Architecture for Describing SNMP Network Management
- Frameworks", STD 62, RFC 3411, December 2002.
-
- [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
- 10646", RFC 3629, November 2003.
-
-9.2. Informative References
-
- [CHARGEN] IANA Charset MIB Generation Utility (archived at):
- ftp://www.pwg.org/pub/pwg/pmp/tools/ianachar.c
-
- [CHARMIB] IANA Charset MIB (in the future, to be archived at):
- http://www.iana.org/assignments/ianacharset-mib
-
- [CHARSET] IANA Charset Registry (archived at):
- http://www.iana.org/assignments/character-sets
-
- [CHARTEMP] IANA Charset MIB template file (archived at):
- ftp://www.pwg.org/pub/pwg/pmp/tools/ianachar.dat
-
- [RFC1759] Smith, R., Wright, F., Hastings, T., Zilles, S., and J.
- Gyllenskog. "Printer MIB", RFC 1759, March 1995.
-
- [RFC3805] Bergman, R., Lewis, H., and I. McDonald, "Printer MIB
- v2", RFC 3805, June 2004.
-
- [RFC3410] Case, J., Mundy, P., Partain, D., and B. Stewart,
- "Introduction and Applicability Statements for
- Internet-Standard Network Management Framework", RFC
- 3410, December 2002.
-
-
-
-
-
-
-
-
-
-
-
-
-
-McDonald Informational [Page 12]
-\f
-RFC 3808 IANA Charset MIB June 2004
-
-
-10. Authors' Addresses
-
- Ira McDonald
- High North Inc
- 221 Ridge Ave
- Grand Marais, MI 49839
- USA
-
- Phone: +1 906 494 2434
- EMail: imcdonald@sharplabs.com
-
-
- Internet Assigned Numbers Authority (IANA)
- ICANN
- 4676 Admiralty Way, Suite 330
- Marina del Rey, CA 90292
- USA
-
- Phone: +1 310 823 9358
- EMail: iana@iana.org
-
- Note: Questions and comments on this IANA Charset MIB [CHARMIB]
- should be sent to the editor (imcdonald@sharplabs.com) and IANA
- (iana@iana.org) with a copy to the IETF Charsets mailing list
- (ietf-charset@iana.org).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-McDonald Informational [Page 13]
-\f
-RFC 3808 IANA Charset MIB June 2004
-
-
-11. Full Copyright Statement
-
- Copyright (C) The Internet Society (2004). This document is subject
- to the rights, licenses and restrictions contained in BCP 78, and
- except as set forth therein, the authors retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at ietf-
- ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-McDonald Informational [Page 14]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group D. Robinson
-Request for Comments: 3875 K. Coar
-Category: Informational The Apache Software Foundation
- October 2004
-
-
- The Common Gateway Interface (CGI) Version 1.1
-
-Status of this Memo
-
- This memo provides information for the Internet community. It does
- not specify an Internet standard of any kind. Distribution of this
- memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2004).
-
-IESG Note
-
- This document is not a candidate for any level of Internet Standard.
- The IETF disclaims any knowledge of the fitness of this document for
- any purpose, and in particular notes that it has not had IETF review
- for such things as security, congestion control or inappropriate
- interaction with deployed protocols. The RFC Editor has chosen to
- publish this document at its discretion. Readers of this document
- should exercise caution in evaluating its value for implementation
- and deployment.
-
-Abstract
-
- The Common Gateway Interface (CGI) is a simple interface for running
- external programs, software or gateways under an information server
- in a platform-independent manner. Currently, the supported
- information servers are HTTP servers.
-
- The interface has been in use by the World-Wide Web (WWW) since 1993.
- This specification defines the 'current practice' parameters of the
- 'CGI/1.1' interface developed and documented at the U.S. National
- Centre for Supercomputing Applications. This document also defines
- the use of the CGI/1.1 interface on UNIX(R) and other, similar
- systems.
-
-
-
-
-
-
-
-
-
-Robinson & Coar Informational [Page 1]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
-Table of Contents
-
- 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . 4
- 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . 4
- 1.2. Requirements . . . . . . . . . . . . . . . . . . . . . . 4
- 1.3. Specifications . . . . . . . . . . . . . . . . . . . . . 4
- 1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . 5
-
- 2. Notational Conventions and Generic Grammar. . . . . . . . . . 5
- 2.1. Augmented BNF . . . . . . . . . . . . . . . . . . . . . 5
- 2.2. Basic Rules . . . . . . . . . . . . . . . . . . . . . . 6
- 2.3. URL Encoding . . . . . . . . . . . . . . . . . . . . . . 7
-
- 3. Invoking the Script . . . . . . . . . . . . . . . . . . . . . 8
- 3.1. Server Responsibilities . . . . . . . . . . . . . . . . 8
- 3.2. Script Selection . . . . . . . . . . . . . . . . . . . . 9
- 3.3. The Script-URI . . . . . . . . . . . . . . . . . . . . . 9
- 3.4. Execution . . . . . . . . . . . . . . . . . . . . . . . 10
-
- 4. The CGI Request . . . . . . . . . . . . . . . . . . . . . . . 10
- 4.1. Request Meta-Variables . . . . . . . . . . . . . . . . . 10
- 4.1.1. AUTH_TYPE. . . . . . . . . . . . . . . . . . . . 11
- 4.1.2. CONTENT_LENGTH . . . . . . . . . . . . . . . . . 12
- 4.1.3. CONTENT_TYPE . . . . . . . . . . . . . . . . . . 12
- 4.1.4. GATEWAY_INTERFACE. . . . . . . . . . . . . . . . 13
- 4.1.5. PATH_INFO. . . . . . . . . . . . . . . . . . . . 13
- 4.1.6. PATH_TRANSLATED. . . . . . . . . . . . . . . . . 14
- 4.1.7. QUERY_STRING . . . . . . . . . . . . . . . . . . 15
- 4.1.8. REMOTE_ADDR. . . . . . . . . . . . . . . . . . . 15
- 4.1.9. REMOTE_HOST. . . . . . . . . . . . . . . . . . . 16
- 4.1.10. REMOTE_IDENT . . . . . . . . . . . . . . . . . . 16
- 4.1.11. REMOTE_USER. . . . . . . . . . . . . . . . . . . 16
- 4.1.12. REQUEST_METHOD . . . . . . . . . . . . . . . . . 17
- 4.1.13. SCRIPT_NAME. . . . . . . . . . . . . . . . . . . 17
- 4.1.14. SERVER_NAME. . . . . . . . . . . . . . . . . . . 17
- 4.1.15. SERVER_PORT. . . . . . . . . . . . . . . . . . . 18
- 4.1.16. SERVER_PROTOCOL. . . . . . . . . . . . . . . . . 18
- 4.1.17. SERVER_SOFTWARE. . . . . . . . . . . . . . . . . 19
- 4.1.18. Protocol-Specific Meta-Variables . . . . . . . . 19
- 4.2. Request Message-Body . . . . . . . . . . . . . . . . . . 20
- 4.3. Request Methods . . . . . . . . . . . . . . . . . . . . 20
- 4.3.1. GET. . . . . . . . . . . . . . . . . . . . . . . 20
- 4.3.2. POST . . . . . . . . . . . . . . . . . . . . . . 21
- 4.3.3. HEAD . . . . . . . . . . . . . . . . . . . . . . 21
- 4.3.4. Protocol-Specific Methods. . . . . . . . . . . . 21
- 4.4. The Script Command Line. . . . . . . . . . . . . . . . . 21
-
-
-
-
-
-Robinson & Coar Informational [Page 2]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- 5. NPH Scripts . . . . . . . . . . . . . . . . . . . . . . . . . 22
- 5.1. Identification . . . . . . . . . . . . . . . . . . . . . 22
- 5.2. NPH Response . . . . . . . . . . . . . . . . . . . . . . 22
-
- 6. CGI Response. . . . . . . . . . . . . . . . . . . . . . . . . 23
- 6.1. Response Handling. . . . . . . . . . . . . . . . . . . . 23
- 6.2. Response Types . . . . . . . . . . . . . . . . . . . . . 23
- 6.2.1. Document Response. . . . . . . . . . . . . . . . 23
- 6.2.2. Local Redirect Response. . . . . . . . . . . . . 24
- 6.2.3. Client Redirect Response . . . . . . . . . . . . 24
- 6.2.4. Client Redirect Response with Document . . . . . 24
- 6.3. Response Header Fields . . . . . . . . . . . . . . . . . 25
- 6.3.1. Content-Type . . . . . . . . . . . . . . . . . . 25
- 6.3.2. Location . . . . . . . . . . . . . . . . . . . . 26
- 6.3.3. Status . . . . . . . . . . . . . . . . . . . . . 26
- 6.3.4. Protocol-Specific Header Fields. . . . . . . . . 27
- 6.3.5. Extension Header Fields. . . . . . . . . . . . . 27
- 6.4. Response Message-Body. . . . . . . . . . . . . . . . . . 28
-
- 7. System Specifications . . . . . . . . . . . . . . . . . . . . 28
- 7.1. AmigaDOS . . . . . . . . . . . . . . . . . . . . . . . . 28
- 7.2. UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . 28
- 7.3. EBCDIC/POSIX . . . . . . . . . . . . . . . . . . . . . . 29
-
- 8. Implementation. . . . . . . . . . . . . . . . . . . . . . . . 29
- 8.1. Recommendations for Servers. . . . . . . . . . . . . . . 29
- 8.2. Recommendations for Scripts. . . . . . . . . . . . . . . 30
-
- 9. Security Considerations . . . . . . . . . . . . . . . . . . . 30
- 9.1. Safe Methods . . . . . . . . . . . . . . . . . . . . . . 30
- 9.2. Header Fields Containing Sensitive Information . . . . . 31
- 9.3. Data Privacy . . . . . . . . . . . . . . . . . . . . . . 31
- 9.4. Information Security Model . . . . . . . . . . . . . . . 31
- 9.5. Script Interference with the Server. . . . . . . . . . . 31
- 9.6. Data Length and Buffering Considerations . . . . . . . . 32
- 9.7. Stateless Processing . . . . . . . . . . . . . . . . . . 32
- 9.8. Relative Paths . . . . . . . . . . . . . . . . . . . . . 33
- 9.9. Non-parsed Header Output . . . . . . . . . . . . . . . . 33
-
- 10. Acknowledgements. . . . . . . . . . . . . . . . . . . . . . . 33
-
- 11. References. . . . . . . . . . . . . . . . . . . . . . . . . . 33
- 11.1. Normative References. . . . . . . . . . . . . . . . . . 33
- 11.2. Informative References. . . . . . . . . . . . . . . . . 34
-
- 12. Authors' Addresses. . . . . . . . . . . . . . . . . . . . . . 35
-
- 13. Full Copyright Statement. . . . . . . . . . . . . . . . . . . 36
-
-
-
-Robinson & Coar Informational [Page 3]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
-1. Introduction
-
-1.1. Purpose
-
- The Common Gateway Interface (CGI) [22] allows an HTTP [1], [4]
- server and a CGI script to share responsibility for responding to
- client requests. The client request comprises a Uniform Resource
- Identifier (URI) [11], a request method and various ancillary
- information about the request provided by the transport protocol.
-
- The CGI defines the abstract parameters, known as meta-variables,
- which describe a client's request. Together with a concrete
- programmer interface this specifies a platform-independent interface
- between the script and the HTTP server.
-
- The server is responsible for managing connection, data transfer,
- transport and network issues related to the client request, whereas
- the CGI script handles the application issues, such as data access
- and document processing.
-
-1.2. Requirements
-
- The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT',
- 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY' and 'OPTIONAL' in this
- document are to be interpreted as described in BCP 14, RFC 2119 [3].
-
- An implementation is not compliant if it fails to satisfy one or more
- of the 'must' requirements for the protocols it implements. An
- implementation that satisfies all of the 'must' and all of the
- 'should' requirements for its features is said to be 'unconditionally
- compliant'; one that satisfies all of the 'must' requirements but not
- all of the 'should' requirements for its features is said to be
- 'conditionally compliant'.
-
-1.3. Specifications
-
- Not all of the functions and features of the CGI are defined in the
- main part of this specification. The following phrases are used to
- describe the features that are not specified:
-
- 'system-defined'
- The feature may differ between systems, but must be the same for
- different implementations using the same system. A system will
- usually identify a class of operating systems. Some systems are
- defined in section 7 of this document. New systems may be defined
- by new specifications without revision of this document.
-
-
-
-
-
-Robinson & Coar Informational [Page 4]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- 'implementation-defined'
- The behaviour of the feature may vary from implementation to
- implementation; a particular implementation must document its
- behaviour.
-
-1.4. Terminology
-
- This specification uses many terms defined in the HTTP/1.1
- specification [4]; however, the following terms are used here in a
- sense which may not accord with their definitions in that document,
- or with their common meaning.
-
- 'meta-variable'
- A named parameter which carries information from the server to the
- script. It is not necessarily a variable in the operating
- system's environment, although that is the most common
- implementation.
-
- 'script'
- The software that is invoked by the server according to this
- interface. It need not be a standalone program, but could be a
- dynamically-loaded or shared library, or even a subroutine in the
- server. It might be a set of statements interpreted at run-time,
- as the term 'script' is frequently understood, but that is not a
- requirement and within the context of this specification the term
- has the broader definition stated.
-
- 'server'
- The application program that invokes the script in order to
- service requests from the client.
-
-2. Notational Conventions and Generic Grammar
-
-2.1. Augmented BNF
-
- All of the mechanisms specified in this document are described in
- both prose and an augmented Backus-Naur Form (BNF) similar to that
- used by RFC 822 [13]. Unless stated otherwise, the elements are
- case-sensitive. This augmented BNF contains the following
- constructs:
-
- name = definition
- The name of a rule and its definition are separated by the equals
- character ('='). Whitespace is only significant in that
- continuation lines of a definition are indented.
-
-
-
-
-
-
-Robinson & Coar Informational [Page 5]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- "literal"
- Double quotation marks (") surround literal text, except for a
- literal quotation mark, which is surrounded by angle-brackets ('<'
- and '>').
-
- rule1 | rule2
- Alternative rules are separated by a vertical bar ('|').
-
- (rule1 rule2 rule3)
- Elements enclosed in parentheses are treated as a single element.
-
- *rule
- A rule preceded by an asterisk ('*') may have zero or more
- occurrences. The full form is 'n*m rule' indicating at least n
- and at most m occurrences of the rule. n and m are optional
- decimal values with default values of 0 and infinity respectively.
-
- [rule]
- An element enclosed in square brackets ('[' and ']') is optional,
- and is equivalent to '*1 rule'.
-
- N rule
- A rule preceded by a decimal number represents exactly N
- occurrences of the rule. It is equivalent to 'N*N rule'.
-
-2.2. Basic Rules
-
- This specification uses a BNF-like grammar defined in terms of
- characters. Unlike many specifications which define the bytes
- allowed by a protocol, here each literal in the grammar corresponds
- to the character it represents. How these characters are represented
- in terms of bits and bytes within a system are either system-defined
- or specified in the particular context. The single exception is the
- rule 'OCTET', defined below.
-
- The following rules are used throughout this specification to
- describe basic parsing constructs.
-
- alpha = lowalpha | hialpha
- lowalpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" |
- "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" |
- "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" |
- "y" | "z"
- hialpha = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" |
- "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" |
- "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" |
- "Y" | "Z"
-
-
-
-
-Robinson & Coar Informational [Page 6]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" |
- "8" | "9"
- alphanum = alpha | digit
- OCTET = <any 8-bit byte>
- CHAR = alpha | digit | separator | "!" | "#" | "$" |
- "%" | "&" | "'" | "*" | "+" | "-" | "." | "`" |
- "^" | "_" | "{" | "|" | "}" | "~" | CTL
- CTL = <any control character>
- SP = <space character>
- HT = <horizontal tab character>
- NL = <newline>
- LWSP = SP | HT | NL
- separator = "(" | ")" | "<" | ">" | "@" | "," | ";" | ":" |
- "\" | <"> | "/" | "[" | "]" | "?" | "=" | "{" |
- "}" | SP | HT
- token = 1*<any CHAR except CTLs or separators>
- quoted-string = <"> *qdtext <">
- qdtext = <any CHAR except <"> and CTLs but including LWSP>
- TEXT = <any printable character>
-
- Note that newline (NL) need not be a single control character, but
- can be a sequence of control characters. A system MAY define TEXT to
- be a larger set of characters than <any CHAR excluding CTLs but
- including LWSP>.
-
-2.3. URL Encoding
-
- Some variables and constructs used here are described as being
- 'URL-encoded'. This encoding is described in section 2 of RFC 2396
- [2]. In a URL-encoded string an escape sequence consists of a
- percent character ("%") followed by two hexadecimal digits, where the
- two hexadecimal digits form an octet. An escape sequence represents
- the graphic character that has the octet as its code within the
- US-ASCII [9] coded character set, if it exists. Currently there is
- no provision within the URI syntax to identify which character set
- non-ASCII codes represent, so CGI handles this issue on an ad-hoc
- basis.
-
- Note that some unsafe (reserved) characters may have different
- semantics when encoded. The definition of which characters are
- unsafe depends on the context; see section 2 of RFC 2396 [2], updated
- by RFC 2732 [7], for an authoritative treatment. These reserved
- characters are generally used to provide syntactic structure to the
- character string, for example as field separators. In all cases, the
- string is first processed with regard to any reserved characters
- present, and then the resulting data can be URL-decoded by replacing
- "%" escape sequences by their character values.
-
-
-
-
-Robinson & Coar Informational [Page 7]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- To encode a character string, all reserved and forbidden characters
- are replaced by the corresponding "%" escape sequences. The string
- can then be used in assembling a URI. The reserved characters will
- vary from context to context, but will always be drawn from this set:
-
- reserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" | "$" |
- "," | "[" | "]"
-
- The last two characters were added by RFC 2732 [7]. In any
- particular context, a sub-set of these characters will be reserved;
- the other characters from this set MUST NOT be encoded when a string
- is URL-encoded in that context. Other basic rules used to describe
- URI syntax are:
-
- hex = digit | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b"
- | "c" | "d" | "e" | "f"
- escaped = "%" hex hex
- unreserved = alpha | digit | mark
- mark = "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")"
-
-3. Invoking the Script
-
-3.1. Server Responsibilities
-
- The server acts as an application gateway. It receives the request
- from the client, selects a CGI script to handle the request, converts
- the client request to a CGI request, executes the script and converts
- the CGI response into a response for the client. When processing the
- client request, it is responsible for implementing any protocol or
- transport level authentication and security. The server MAY also
- function in a 'non-transparent' manner, modifying the request or
- response in order to provide some additional service, such as media
- type transformation or protocol reduction.
-
- The server MUST perform translations and protocol conversions on the
- client request data required by this specification. Furthermore, the
- server retains its responsibility to the client to conform to the
- relevant network protocol even if the CGI script fails to conform to
- this specification.
-
- If the server is applying authentication to the request, then it MUST
- NOT execute the script unless the request passes all defined access
- controls.
-
-
-
-
-
-
-
-
-Robinson & Coar Informational [Page 8]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
-3.2. Script Selection
-
- The server determines which CGI is script to be executed based on a
- generic-form URI supplied by the client. This URI includes a
- hierarchical path with components separated by "/". For any
- particular request, the server will identify all or a leading part of
- this path with an individual script, thus placing the script at a
- particular point in the path hierarchy. The remainder of the path,
- if any, is a resource or sub-resource identifier to be interpreted by
- the script.
-
- Information about this split of the path is available to the script
- in the meta-variables, described below. Support for non-hierarchical
- URI schemes is outside the scope of this specification.
-
-3.3. The Script-URI
-
- The mapping from client request URI to choice of script is defined by
- the particular server implementation and its configuration. The
- server may allow the script to be identified with a set of several
- different URI path hierarchies, and therefore is permitted to replace
- the URI by other members of this set during processing and generation
- of the meta-variables. The server
-
- 1. MAY preserve the URI in the particular client request; or
-
- 2. it MAY select a canonical URI from the set of possible values
- for each script; or
-
- 3. it can implement any other selection of URI from the set.
-
- From the meta-variables thus generated, a URI, the 'Script-URI', can
- be constructed. This MUST have the property that if the client had
- accessed this URI instead, then the script would have been executed
- with the same values for the SCRIPT_NAME, PATH_INFO and QUERY_STRING
- meta-variables. The Script-URI has the structure of a generic URI as
- defined in section 3 of RFC 2396 [2], with the exception that object
- parameters and fragment identifiers are not permitted. The various
- components of the Script-URI are defined by some of the
- meta-variables (see below);
-
- script-URI = <scheme> "://" <server-name> ":" <server-port>
- <script-path> <extra-path> "?" <query-string>
-
- where <scheme> is found from SERVER_PROTOCOL, <server-name>,
- <server-port> and <query-string> are the values of the respective
- meta-variables. The SCRIPT_NAME and PATH_INFO values, URL-encoded
- with ";", "=" and "?" reserved, give <script-path> and <extra-path>.
-
-
-
-Robinson & Coar Informational [Page 9]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- See section 4.1.5 for more information about the PATH_INFO
- meta-variable.
-
- The scheme and the protocol are not identical as the scheme
- identifies the access method in addition to the application protocol.
- For example, a resource accessed using Transport Layer Security (TLS)
- [14] would have a request URI with a scheme of https when using the
- HTTP protocol [19]. CGI/1.1 provides no generic means for the script
- to reconstruct this, and therefore the Script-URI as defined includes
- the base protocol used. However, a script MAY make use of
- scheme-specific meta-variables to better deduce the URI scheme.
-
- Note that this definition also allows URIs to be constructed which
- would invoke the script with any permitted values for the path-info
- or query-string, by modifying the appropriate components.
-
-3.4. Execution
-
- The script is invoked in a system-defined manner. Unless specified
- otherwise, the file containing the script will be invoked as an
- executable program. The server prepares the CGI request as described
- in section 4; this comprises the request meta-variables (immediately
- available to the script on execution) and request message data. The
- request data need not be immediately available to the script; the
- script can be executed before all this data has been received by the
- server from the client. The response from the script is returned to
- the server as described in sections 5 and 6.
-
- In the event of an error condition, the server can interrupt or
- terminate script execution at any time and without warning. That
- could occur, for example, in the event of a transport failure between
- the server and the client; so the script SHOULD be prepared to handle
- abnormal termination.
-
-4. The CGI Request
-
- Information about a request comes from two different sources; the
- request meta-variables and any associated message-body.
-
-4.1. Request Meta-Variables
-
- Meta-variables contain data about the request passed from the server
- to the script, and are accessed by the script in a system-defined
- manner. Meta-variables are identified by case-insensitive names;
- there cannot be two different variables whose names differ in case
- only. Here they are shown using a canonical representation of
- capitals plus underscore ("_"). A particular system can define a
- different representation.
-
-
-
-Robinson & Coar Informational [Page 10]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- meta-variable-name = "AUTH_TYPE" | "CONTENT_LENGTH" |
- "CONTENT_TYPE" | "GATEWAY_INTERFACE" |
- "PATH_INFO" | "PATH_TRANSLATED" |
- "QUERY_STRING" | "REMOTE_ADDR" |
- "REMOTE_HOST" | "REMOTE_IDENT" |
- "REMOTE_USER" | "REQUEST_METHOD" |
- "SCRIPT_NAME" | "SERVER_NAME" |
- "SERVER_PORT" | "SERVER_PROTOCOL" |
- "SERVER_SOFTWARE" | scheme |
- protocol-var-name | extension-var-name
- protocol-var-name = ( protocol | scheme ) "_" var-name
- scheme = alpha *( alpha | digit | "+" | "-" | "." )
- var-name = token
- extension-var-name = token
-
- Meta-variables with the same name as a scheme, and names beginning
- with the name of a protocol or scheme (e.g., HTTP_ACCEPT) are also
- defined. The number and meaning of these variables may change
- independently of this specification. (See also section 4.1.18.)
-
- The server MAY set additional implementation-defined extension meta-
- variables, whose names SHOULD be prefixed with "X_".
-
- This specification does not distinguish between zero-length (NULL)
- values and missing values. For example, a script cannot distinguish
- between the two requests http://host/script and http://host/script?
- as in both cases the QUERY_STRING meta-variable would be NULL.
-
- meta-variable-value = "" | 1*<TEXT, CHAR or tokens of value>
-
- An optional meta-variable may be omitted (left unset) if its value is
- NULL. Meta-variable values MUST be considered case-sensitive except
- as noted otherwise. The representation of the characters in the
- meta-variables is system-defined; the server MUST convert values to
- that representation.
-
-4.1.1. AUTH_TYPE
-
- The AUTH_TYPE variable identifies any mechanism used by the server to
- authenticate the user. It contains a case-insensitive value defined
- by the client protocol or server implementation.
-
- For HTTP, if the client request required authentication for external
- access, then the server MUST set the value of this variable from the
- 'auth-scheme' token in the request Authorization header field.
-
-
-
-
-
-
-Robinson & Coar Informational [Page 11]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- AUTH_TYPE = "" | auth-scheme
- auth-scheme = "Basic" | "Digest" | extension-auth
- extension-auth = token
-
- HTTP access authentication schemes are described in RFC 2617 [5].
-
-4.1.2. CONTENT_LENGTH
-
- The CONTENT_LENGTH variable contains the size of the message-body
- attached to the request, if any, in decimal number of octets. If no
- data is attached, then NULL (or unset).
-
- CONTENT_LENGTH = "" | 1*digit
-
- The server MUST set this meta-variable if and only if the request is
- accompanied by a message-body entity. The CONTENT_LENGTH value must
- reflect the length of the message-body after the server has removed
- any transfer-codings or content-codings.
-
-4.1.3. CONTENT_TYPE
-
- If the request includes a message-body, the CONTENT_TYPE variable is
- set to the Internet Media Type [6] of the message-body.
-
- CONTENT_TYPE = "" | media-type
- media-type = type "/" subtype *( ";" parameter )
- type = token
- subtype = token
- parameter = attribute "=" value
- attribute = token
- value = token | quoted-string
-
- The type, subtype and parameter attribute names are not
- case-sensitive. Parameter values may be case sensitive. Media types
- and their use in HTTP are described section 3.7 of the HTTP/1.1
- specification [4].
-
- There is no default value for this variable. If and only if it is
- unset, then the script MAY attempt to determine the media type from
- the data received. If the type remains unknown, then the script MAY
- choose to assume a type of application/octet-stream or it may reject
- the request with an error (as described in section 6.3.3).
-
- Each media-type defines a set of optional and mandatory parameters.
- This may include a charset parameter with a case-insensitive value
- defining the coded character set for the message-body. If the
-
-
-
-
-
-Robinson & Coar Informational [Page 12]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- charset parameter is omitted, then the default value should be
- derived according to whichever of the following rules is the first to
- apply:
-
- 1. There MAY be a system-defined default charset for some
- media-types.
-
- 2. The default for media-types of type "text" is ISO-8859-1 [4].
-
- 3. Any default defined in the media-type specification.
-
- 4. The default is US-ASCII.
-
- The server MUST set this meta-variable if an HTTP Content-Type field
- is present in the client request header. If the server receives a
- request with an attached entity but no Content-Type header field, it
- MAY attempt to determine the correct content type, otherwise it
- should omit this meta-variable.
-
-4.1.4. GATEWAY_INTERFACE
-
- The GATEWAY_INTERFACE variable MUST be set to the dialect of CGI
- being used by the server to communicate with the script. Syntax:
-
- GATEWAY_INTERFACE = "CGI" "/" 1*digit "." 1*digit
-
- Note that the major and minor numbers are treated as separate
- integers and hence each may be incremented higher than a single
- digit. Thus CGI/2.4 is a lower version than CGI/2.13 which in turn
- is lower than CGI/12.3. Leading zeros MUST be ignored by the script
- and MUST NOT be generated by the server.
-
- This document defines the 1.1 version of the CGI interface.
-
-4.1.5. PATH_INFO
-
- The PATH_INFO variable specifies a path to be interpreted by the CGI
- script. It identifies the resource or sub-resource to be returned by
- the CGI script, and is derived from the portion of the URI path
- hierarchy following the part that identifies the script itself.
- Unlike a URI path, the PATH_INFO is not URL-encoded, and cannot
- contain path-segment parameters. A PATH_INFO of "/" represents a
- single void path segment.
-
- PATH_INFO = "" | ( "/" path )
- path = lsegment *( "/" lsegment )
- lsegment = *lchar
- lchar = <any TEXT or CTL except "/">
-
-
-
-Robinson & Coar Informational [Page 13]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- The value is considered case-sensitive and the server MUST preserve
- the case of the path as presented in the request URI. The server MAY
- impose restrictions and limitations on what values it permits for
- PATH_INFO, and MAY reject the request with an error if it encounters
- any values considered objectionable. That MAY include any requests
- that would result in an encoded "/" being decoded into PATH_INFO, as
- this might represent a loss of information to the script. Similarly,
- treatment of non US-ASCII characters in the path is system-defined.
-
- URL-encoded, the PATH_INFO string forms the extra-path component of
- the Script-URI (see section 3.3) which follows the SCRIPT_NAME part
- of that path.
-
-4.1.6. PATH_TRANSLATED
-
- The PATH_TRANSLATED variable is derived by taking the PATH_INFO
- value, parsing it as a local URI in its own right, and performing any
- virtual-to-physical translation appropriate to map it onto the
- server's document repository structure. The set of characters
- permitted in the result is system-defined.
-
- PATH_TRANSLATED = *<any character>
-
- This is the file location that would be accessed by a request for
-
- <scheme> "://" <server-name> ":" <server-port> <extra-path>
-
- where <scheme> is the scheme for the original client request and
- <extra-path> is a URL-encoded version of PATH_INFO, with ";", "=" and
- "?" reserved. For example, a request such as the following:
-
- http://somehost.com/cgi-bin/somescript/this%2eis%2epath%3binfo
-
- would result in a PATH_INFO value of
-
- /this.is.the.path;info
-
- An internal URI is constructed from the scheme, server location and
- the URL-encoded PATH_INFO:
-
- http://somehost.com/this.is.the.path%3binfo
-
- This would then be translated to a location in the server's document
- repository, perhaps a filesystem path something like this:
-
- /usr/local/www/htdocs/this.is.the.path;info
-
- The value of PATH_TRANSLATED is the result of the translation.
-
-
-
-Robinson & Coar Informational [Page 14]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- The value is derived in this way irrespective of whether it maps to a
- valid repository location. The server MUST preserve the case of the
- extra-path segment unless the underlying repository supports case-
- insensitive names. If the repository is only case-aware, case-
- preserving, or case-blind with regard to document names, the server
- is not required to preserve the case of the original segment through
- the translation.
-
- The translation algorithm the server uses to derive PATH_TRANSLATED
- is implementation-defined; CGI scripts which use this variable may
- suffer limited portability.
-
- The server SHOULD set this meta-variable if the request URI includes
- a path-info component. If PATH_INFO is NULL, then the
- PATH_TRANSLATED variable MUST be set to NULL (or unset).
-
-4.1.7. QUERY_STRING
-
- The QUERY_STRING variable contains a URL-encoded search or parameter
- string; it provides information to the CGI script to affect or refine
- the document to be returned by the script.
-
- The URL syntax for a search string is described in section 3 of RFC
- 2396 [2]. The QUERY_STRING value is case-sensitive.
-
- QUERY_STRING = query-string
- query-string = *uric
- uric = reserved | unreserved | escaped
-
- When parsing and decoding the query string, the details of the
- parsing, reserved characters and support for non US-ASCII characters
- depends on the context. For example, form submission from an HTML
- document [18] uses application/x-www-form-urlencoded encoding, in
- which the characters "+", "&" and "=" are reserved, and the ISO
- 8859-1 encoding may be used for non US-ASCII characters.
-
- The QUERY_STRING value provides the query-string part of the
- Script-URI. (See section 3.3).
-
- The server MUST set this variable; if the Script-URI does not include
- a query component, the QUERY_STRING MUST be defined as an empty
- string ("").
-
-4.1.8. REMOTE_ADDR
-
- The REMOTE_ADDR variable MUST be set to the network address of the
- client sending the request to the server.
-
-
-
-
-Robinson & Coar Informational [Page 15]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- REMOTE_ADDR = hostnumber
- hostnumber = ipv4-address | ipv6-address
- ipv4-address = 1*3digit "." 1*3digit "." 1*3digit "." 1*3digit
- ipv6-address = hexpart [ ":" ipv4-address ]
- hexpart = hexseq | ( [ hexseq ] "::" [ hexseq ] )
- hexseq = 1*4hex *( ":" 1*4hex )
-
- The format of an IPv6 address is described in RFC 3513 [15].
-
-4.1.9. REMOTE_HOST
-
- The REMOTE_HOST variable contains the fully qualified domain name of
- the client sending the request to the server, if available, otherwise
- NULL. Fully qualified domain names take the form as described in
- section 3.5 of RFC 1034 [17] and section 2.1 of RFC 1123 [12].
- Domain names are not case sensitive.
-
- REMOTE_HOST = "" | hostname | hostnumber
- hostname = *( domainlabel "." ) toplabel [ "." ]
- domainlabel = alphanum [ *alphahypdigit alphanum ]
- toplabel = alpha [ *alphahypdigit alphanum ]
- alphahypdigit = alphanum | "-"
-
- The server SHOULD set this variable. If the hostname is not
- available for performance reasons or otherwise, the server MAY
- substitute the REMOTE_ADDR value.
-
-4.1.10. REMOTE_IDENT
-
- The REMOTE_IDENT variable MAY be used to provide identity information
- reported about the connection by an RFC 1413 [20] request to the
- remote agent, if available. The server may choose not to support
- this feature, or not to request the data for efficiency reasons, or
- not to return available identity data.
-
- REMOTE_IDENT = *TEXT
-
- The data returned may be used for authentication purposes, but the
- level of trust reposed in it should be minimal.
-
-4.1.11. REMOTE_USER
-
- The REMOTE_USER variable provides a user identification string
- supplied by client as part of user authentication.
-
- REMOTE_USER = *TEXT
-
-
-
-
-
-Robinson & Coar Informational [Page 16]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- If the client request required HTTP Authentication [5] (e.g., the
- AUTH_TYPE meta-variable is set to "Basic" or "Digest"), then the
- value of the REMOTE_USER meta-variable MUST be set to the user-ID
- supplied.
-
-4.1.12. REQUEST_METHOD
-
- The REQUEST_METHOD meta-variable MUST be set to the method which
- should be used by the script to process the request, as described in
- section 4.3.
-
- REQUEST_METHOD = method
- method = "GET" | "POST" | "HEAD" | extension-method
- extension-method = "PUT" | "DELETE" | token
-
- The method is case sensitive. The HTTP methods are described in
- section 5.1.1 of the HTTP/1.0 specification [1] and section 5.1.1 of
- the HTTP/1.1 specification [4].
-
-4.1.13. SCRIPT_NAME
-
- The SCRIPT_NAME variable MUST be set to a URI path (not URL-encoded)
- which could identify the CGI script (rather than the script's
- output). The syntax is the same as for PATH_INFO (section 4.1.5)
-
- SCRIPT_NAME = "" | ( "/" path )
-
- The leading "/" is not part of the path. It is optional if the path
- is NULL; however, the variable MUST still be set in that case.
-
- The SCRIPT_NAME string forms some leading part of the path component
- of the Script-URI derived in some implementation-defined manner. No
- PATH_INFO segment (see section 4.1.5) is included in the SCRIPT_NAME
- value.
-
-4.1.14. SERVER_NAME
-
- The SERVER_NAME variable MUST be set to the name of the server host
- to which the client request is directed. It is a case-insensitive
- hostname or network address. It forms the host part of the
- Script-URI.
-
- SERVER_NAME = server-name
- server-name = hostname | ipv4-address | ( "[" ipv6-address "]" )
-
-
-
-
-
-
-
-Robinson & Coar Informational [Page 17]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- A deployed server can have more than one possible value for this
- variable, where several HTTP virtual hosts share the same IP address.
- In that case, the server would use the contents of the request's Host
- header field to select the correct virtual host.
-
-4.1.15. SERVER_PORT
-
- The SERVER_PORT variable MUST be set to the TCP/IP port number on
- which this request is received from the client. This value is used
- in the port part of the Script-URI.
-
- SERVER_PORT = server-port
- server-port = 1*digit
-
- Note that this variable MUST be set, even if the port is the default
- port for the scheme and could otherwise be omitted from a URI.
-
-4.1.16. SERVER_PROTOCOL
-
- The SERVER_PROTOCOL variable MUST be set to the name and version of
- the application protocol used for this CGI request. This MAY differ
- from the protocol version used by the server in its communication
- with the client.
-
- SERVER_PROTOCOL = HTTP-Version | "INCLUDED" | extension-version
- HTTP-Version = "HTTP" "/" 1*digit "." 1*digit
- extension-version = protocol [ "/" 1*digit "." 1*digit ]
- protocol = token
-
- Here, 'protocol' defines the syntax of some of the information
- passing between the server and the script (the 'protocol-specific'
- features). It is not case sensitive and is usually presented in
- upper case. The protocol is not the same as the scheme part of the
- script URI, which defines the overall access mechanism used by the
- client to communicate with the server. For example, a request that
- reaches the script with a protocol of "HTTP" may have used an "https"
- scheme.
-
- A well-known value for SERVER_PROTOCOL which the server MAY use is
- "INCLUDED", which signals that the current document is being included
- as part of a composite document, rather than being the direct target
- of the client request. The script should treat this as an HTTP/1.0
- request.
-
-
-
-
-
-
-
-
-Robinson & Coar Informational [Page 18]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
-4.1.17. SERVER_SOFTWARE
-
- The SERVER_SOFTWARE meta-variable MUST be set to the name and version
- of the information server software making the CGI request (and
- running the gateway). It SHOULD be the same as the server
- description reported to the client, if any.
-
- SERVER_SOFTWARE = 1*( product | comment )
- product = token [ "/" product-version ]
- product-version = token
- comment = "(" *( ctext | comment ) ")"
- ctext = <any TEXT excluding "(" and ")">
-
-4.1.18. Protocol-Specific Meta-Variables
-
- The server SHOULD set meta-variables specific to the protocol and
- scheme for the request. Interpretation of protocol-specific
- variables depends on the protocol version in SERVER_PROTOCOL. The
- server MAY set a meta-variable with the name of the scheme to a
- non-NULL value if the scheme is not the same as the protocol. The
- presence of such a variable indicates to a script which scheme is
- used by the request.
-
- Meta-variables with names beginning with "HTTP_" contain values read
- from the client request header fields, if the protocol used is HTTP.
- The HTTP header field name is converted to upper case, has all
- occurrences of "-" replaced with "_" and has "HTTP_" prepended to
- give the meta-variable name. The header data can be presented as
- sent by the client, or can be rewritten in ways which do not change
- its semantics. If multiple header fields with the same field-name
- are received then the server MUST rewrite them as a single value
- having the same semantics. Similarly, a header field that spans
- multiple lines MUST be merged onto a single line. The server MUST,
- if necessary, change the representation of the data (for example, the
- character set) to be appropriate for a CGI meta-variable.
-
- The server is not required to create meta-variables for all the
- header fields that it receives. In particular, it SHOULD remove any
- header fields carrying authentication information, such as
- 'Authorization'; or that are available to the script in other
- variables, such as 'Content-Length' and 'Content-Type'. The server
- MAY remove header fields that relate solely to client-side
- communication issues, such as 'Connection'.
-
-
-
-
-
-
-
-
-Robinson & Coar Informational [Page 19]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
-4.2. Request Message-Body
-
- Request data is accessed by the script in a system-defined method;
- unless defined otherwise, this will be by reading the 'standard
- input' file descriptor or file handle.
-
- Request-Data = [ request-body ] [ extension-data ]
- request-body = <CONTENT_LENGTH>OCTET
- extension-data = *OCTET
-
- A request-body is supplied with the request if the CONTENT_LENGTH is
- not NULL. The server MUST make at least that many bytes available
- for the script to read. The server MAY signal an end-of-file
- condition after CONTENT_LENGTH bytes have been read or it MAY supply
- extension data. Therefore, the script MUST NOT attempt to read more
- than CONTENT_LENGTH bytes, even if more data is available. However,
- it is not obliged to read any of the data.
-
- For non-parsed header (NPH) scripts (section 5), the server SHOULD
- attempt to ensure that the data supplied to the script is precisely
- as supplied by the client and is unaltered by the server.
-
- As transfer-codings are not supported on the request-body, the server
- MUST remove any such codings from the message-body, and recalculate
- the CONTENT_LENGTH. If this is not possible (for example, because of
- large buffering requirements), the server SHOULD reject the client
- request. It MAY also remove content-codings from the message-body.
-
-4.3. Request Methods
-
- The Request Method, as supplied in the REQUEST_METHOD meta-variable,
- identifies the processing method to be applied by the script in
- producing a response. The script author can choose to implement the
- methods most appropriate for the particular application. If the
- script receives a request with a method it does not support it SHOULD
- reject it with an error (see section 6.3.3).
-
-4.3.1. GET
-
- The GET method indicates that the script should produce a document
- based on the meta-variable values. By convention, the GET method is
- 'safe' and 'idempotent' and SHOULD NOT have the significance of
- taking an action other than producing a document.
-
- The meaning of the GET method may be modified and refined by
- protocol-specific meta-variables.
-
-
-
-
-
-Robinson & Coar Informational [Page 20]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
-4.3.2. POST
-
- The POST method is used to request the script perform processing and
- produce a document based on the data in the request message-body, in
- addition to meta-variable values. A common use is form submission in
- HTML [18], intended to initiate processing by the script that has a
- permanent affect, such a change in a database.
-
- The script MUST check the value of the CONTENT_LENGTH variable before
- reading the attached message-body, and SHOULD check the CONTENT_TYPE
- value before processing it.
-
-4.3.3. HEAD
-
- The HEAD method requests the script to do sufficient processing to
- return the response header fields, without providing a response
- message-body. The script MUST NOT provide a response message-body
- for a HEAD request. If it does, then the server MUST discard the
- message-body when reading the response from the script.
-
-4.3.4. Protocol-Specific Methods
-
- The script MAY implement any protocol-specific method, such as
- HTTP/1.1 PUT and DELETE; it SHOULD check the value of SERVER_PROTOCOL
- when doing so.
-
- The server MAY decide that some methods are not appropriate or
- permitted for a script, and may handle the methods itself or return
- an error to the client.
-
-4.4. The Script Command Line
-
- Some systems support a method for supplying an array of strings to
- the CGI script. This is only used in the case of an 'indexed' HTTP
- query, which is identified by a 'GET' or 'HEAD' request with a URI
- query string that does not contain any unencoded "=" characters. For
- such a request, the server SHOULD treat the query-string as a
- search-string and parse it into words, using the rules
-
- search-string = search-word *( "+" search-word )
- search-word = 1*schar
- schar = unreserved | escaped | xreserved
- xreserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "," |
- "$"
-
- After parsing, each search-word is URL-decoded, optionally encoded in
- a system-defined manner and then added to the command line argument
- list.
-
-
-
-Robinson & Coar Informational [Page 21]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- If the server cannot create any part of the argument list, then the
- server MUST NOT generate any command line information. For example,
- the number of arguments may be greater than operating system or
- server limits, or one of the words may not be representable as an
- argument.
-
- The script SHOULD check to see if the QUERY_STRING value contains an
- unencoded "=" character, and SHOULD NOT use the command line
- arguments if it does.
-
-5. NPH Scripts
-
-5.1. Identification
-
- The server MAY support NPH (Non-Parsed Header) scripts; these are
- scripts to which the server passes all responsibility for response
- processing.
-
- This specification provides no mechanism for an NPH script to be
- identified on the basis of its output data alone. By convention,
- therefore, any particular script can only ever provide output of one
- type (NPH or CGI) and hence the script itself is described as an 'NPH
- script'. A server with NPH support MUST provide an implementation-
- defined mechanism for identifying NPH scripts, perhaps based on the
- name or location of the script.
-
-5.2. NPH Response
-
- There MUST be a system-defined method for the script to send data
- back to the server or client; a script MUST always return some data.
- Unless defined otherwise, this will be the same as for conventional
- CGI scripts.
-
- Currently, NPH scripts are only defined for HTTP client requests. An
- (HTTP) NPH script MUST return a complete HTTP response message,
- currently described in section 6 of the HTTP specifications [1], [4].
- The script MUST use the SERVER_PROTOCOL variable to determine the
- appropriate format for a response. It MUST also take account of any
- generic or protocol-specific meta-variables in the request as might
- be mandated by the particular protocol specification.
-
- The server MUST ensure that the script output is sent to the client
- unmodified. Note that this requires the script to use the correct
- character set (US-ASCII [9] and ISO 8859-1 [10] for HTTP) in the
- header fields. The server SHOULD attempt to ensure that the script
- output is sent directly to the client, with minimal internal and no
- transport-visible buffering.
-
-
-
-
-Robinson & Coar Informational [Page 22]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- Unless the implementation defines otherwise, the script MUST NOT
- indicate in its response that the client can send further requests
- over the same connection.
-
-6. CGI Response
-
-6.1. Response Handling
-
- A script MUST always provide a non-empty response, and so there is a
- system-defined method for it to send this data back to the server.
- Unless defined otherwise, this will be via the 'standard output' file
- descriptor.
-
- The script MUST check the REQUEST_METHOD variable when processing the
- request and preparing its response.
-
- The server MAY implement a timeout period within which data must be
- received from the script. If a server implementation defines such a
- timeout and receives no data from a script within the timeout period,
- the server MAY terminate the script process.
-
-6.2. Response Types
-
- The response comprises a message-header and a message-body, separated
- by a blank line. The message-header contains one or more header
- fields. The body may be NULL.
-
- generic-response = 1*header-field NL [ response-body ]
-
- The script MUST return one of either a document response, a local
- redirect response or a client redirect (with optional document)
- response. In the response definitions below, the order of header
- fields in a response is not significant (despite appearing so in the
- BNF). The header fields are defined in section 6.3.
-
- CGI-Response = document-response | local-redir-response |
- client-redir-response | client-redirdoc-response
-
-6.2.1. Document Response
-
- The CGI script can return a document to the user in a document
- response, with an optional error code indicating the success status
- of the response.
-
- document-response = Content-Type [ Status ] *other-field NL
- response-body
-
-
-
-
-
-Robinson & Coar Informational [Page 23]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- The script MUST return a Content-Type header field. A Status header
- field is optional, and status 200 'OK' is assumed if it is omitted.
- The server MUST make any appropriate modifications to the script's
- output to ensure that the response to the client complies with the
- response protocol version.
-
-6.2.2. Local Redirect Response
-
- The CGI script can return a URI path and query-string
- ('local-pathquery') for a local resource in a Location header field.
- This indicates to the server that it should reprocess the request
- using the path specified.
-
- local-redir-response = local-Location NL
-
- The script MUST NOT return any other header fields or a message-body,
- and the server MUST generate the response that it would have produced
- in response to a request containing the URL
-
- scheme "://" server-name ":" server-port local-pathquery
-
-6.2.3. Client Redirect Response
-
- The CGI script can return an absolute URI path in a Location header
- field, to indicate to the client that it should reprocess the request
- using the URI specified.
-
- client-redir-response = client-Location *extension-field NL
-
- The script MUST not provide any other header fields, except for
- server-defined CGI extension fields. For an HTTP client request, the
- server MUST generate a 302 'Found' HTTP response message.
-
-6.2.4. Client Redirect Response with Document
-
- The CGI script can return an absolute URI path in a Location header
- field together with an attached document, to indicate to the client
- that it should reprocess the request using the URI specified.
-
- client-redirdoc-response = client-Location Status Content-Type
- *other-field NL response-body
-
- The Status header field MUST be supplied and MUST contain a status
- value of 302 'Found', or it MAY contain an extension-code, that is,
- another valid status code that means client redirection. The server
- MUST make any appropriate modifications to the script's output to
- ensure that the response to the client complies with the response
- protocol version.
-
-
-
-Robinson & Coar Informational [Page 24]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
-6.3. Response Header Fields
-
- The response header fields are either CGI or extension header fields
- to be interpreted by the server, or protocol-specific header fields
- to be included in the response returned to the client. At least one
- CGI field MUST be supplied; each CGI field MUST NOT appear more than
- once in the response. The response header fields have the syntax:
-
- header-field = CGI-field | other-field
- CGI-field = Content-Type | Location | Status
- other-field = protocol-field | extension-field
- protocol-field = generic-field
- extension-field = generic-field
- generic-field = field-name ":" [ field-value ] NL
- field-name = token
- field-value = *( field-content | LWSP )
- field-content = *( token | separator | quoted-string )
-
- The field-name is not case sensitive. A NULL field value is
- equivalent to a field not being sent. Note that each header field in
- a CGI-Response MUST be specified on a single line; CGI/1.1 does not
- support continuation lines. Whitespace is permitted between the ":"
- and the field-value (but not between the field-name and the ":"), and
- also between tokens in the field-value.
-
-6.3.1. Content-Type
-
- The Content-Type response field sets the Internet Media Type [6] of
- the entity body.
-
- Content-Type = "Content-Type:" media-type NL
-
- If an entity body is returned, the script MUST supply a Content-Type
- field in the response. If it fails to do so, the server SHOULD NOT
- attempt to determine the correct content type. The value SHOULD be
- sent unmodified to the client, except for any charset parameter
- changes.
-
- Unless it is otherwise system-defined, the default charset assumed by
- the client for text media-types is ISO-8859-1 if the protocol is HTTP
- and US-ASCII otherwise. Hence the script SHOULD include a charset
- parameter. See section 3.4.1 of the HTTP/1.1 specification [4] for a
- discussion of this issue.
-
-
-
-
-
-
-
-
-Robinson & Coar Informational [Page 25]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
-6.3.2. Location
-
- The Location header field is used to specify to the server that the
- script is returning a reference to a document rather than an actual
- document (see sections 6.2.3 and 6.2.4). It is either an absolute
- URI (optionally with a fragment identifier), indicating that the
- client is to fetch the referenced document, or a local URI path
- (optionally with a query string), indicating that the server is to
- fetch the referenced document and return it to the client as the
- response.
-
- Location = local-Location | client-Location
- client-Location = "Location:" fragment-URI NL
- local-Location = "Location:" local-pathquery NL
- fragment-URI = absoluteURI [ "#" fragment ]
- fragment = *uric
- local-pathquery = abs-path [ "?" query-string ]
- abs-path = "/" path-segments
- path-segments = segment *( "/" segment )
- segment = *pchar
- pchar = unreserved | escaped | extra
- extra = ":" | "@" | "&" | "=" | "+" | "$" | ","
-
- The syntax of an absoluteURI is incorporated into this document from
- that specified in RFC 2396 [2] and RFC 2732 [7]. A valid absoluteURI
- always starts with the name of scheme followed by ":"; scheme names
- start with a letter and continue with alphanumerics, "+", "-" or ".".
- The local URI path and query must be an absolute path, and not a
- relative path or NULL, and hence must start with a "/".
-
- Note that any message-body attached to the request (such as for a
- POST request) may not be available to the resource that is the target
- of the redirect.
-
-6.3.3. Status
-
- The Status header field contains a 3-digit integer result code that
- indicates the level of success of the script's attempt to handle the
- request.
-
- Status = "Status:" status-code SP reason-phrase NL
- status-code = "200" | "302" | "400" | "501" | extension-code
- extension-code = 3digit
- reason-phrase = *TEXT
-
- Status code 200 'OK' indicates success, and is the default value
- assumed for a document response. Status code 302 'Found' is used
- with a Location header field and response message-body. Status code
-
-
-
-Robinson & Coar Informational [Page 26]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- 400 'Bad Request' may be used for an unknown request format, such as
- a missing CONTENT_TYPE. Status code 501 'Not Implemented' may be
- returned by a script if it receives an unsupported REQUEST_METHOD.
-
- Other valid status codes are listed in section 6.1.1 of the HTTP
- specifications [1], [4], and also the IANA HTTP Status Code Registry
- [8] and MAY be used in addition to or instead of the ones listed
- above. The script SHOULD check the value of SERVER_PROTOCOL before
- using HTTP/1.1 status codes. The script MAY reject with error 405
- 'Method Not Allowed' HTTP/1.1 requests made using a method it does
- not support.
-
- Note that returning an error status code does not have to mean an
- error condition with the script itself. For example, a script that
- is invoked as an error handler by the server should return the code
- appropriate to the server's error condition.
-
- The reason-phrase is a textual description of the error to be
- returned to the client for human consumption.
-
-6.3.4. Protocol-Specific Header Fields
-
- The script MAY return any other header fields that relate to the
- response message defined by the specification for the SERVER_PROTOCOL
- (HTTP/1.0 [1] or HTTP/1.1 [4]). The server MUST translate the header
- data from the CGI header syntax to the HTTP header syntax if these
- differ. For example, the character sequence for newline (such as
- UNIX's US-ASCII LF) used by CGI scripts may not be the same as that
- used by HTTP (US-ASCII CR followed by LF).
-
- The script MUST NOT return any header fields that relate to
- client-side communication issues and could affect the server's
- ability to send the response to the client. The server MAY remove
- any such header fields returned by the client. It SHOULD resolve any
- conflicts between header fields returned by the script and header
- fields that it would otherwise send itself.
-
-6.3.5. Extension Header Fields
-
- There may be additional implementation-defined CGI header fields,
- whose field names SHOULD begin with "X-CGI-". The server MAY ignore
- (and delete) any unrecognised header fields with names beginning "X-
- CGI-" that are received from the script.
-
-
-
-
-
-
-
-
-Robinson & Coar Informational [Page 27]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
-6.4. Response Message-Body
-
- The response message-body is an attached document to be returned to
- the client by the server. The server MUST read all the data provided
- by the script, until the script signals the end of the message-body
- by way of an end-of-file condition. The message-body SHOULD be sent
- unmodified to the client, except for HEAD requests or any required
- transfer-codings, content-codings or charset conversions.
-
- response-body = *OCTET
-
-7. System Specifications
-
-7.1. AmigaDOS
-
- Meta-Variables
- Meta-variables are passed to the script in identically named
- environment variables. These are accessed by the DOS library
- routine GetVar(). The flags argument SHOULD be 0. Case is
- ignored, but upper case is recommended for compatibility with
- case-sensitive systems.
-
- The current working directory
- The current working directory for the script is set to the
- directory containing the script.
-
- Character set
- The US-ASCII character set [9] is used for the definition of
- meta-variables, header fields and values; the newline (NL)
- sequence is LF; servers SHOULD also accept CR LF as a newline.
-
-7.2. UNIX
-
- For UNIX compatible operating systems, the following are defined:
-
- Meta-Variables
- Meta-variables are passed to the script in identically named
- environment variables. These are accessed by the C library
- routine getenv() or variable environ.
-
- The command line
- This is accessed using the argc and argv arguments to main(). The
- words have any characters which are 'active' in the Bourne shell
- escaped with a backslash.
-
- The current working directory
- The current working directory for the script SHOULD be set to the
- directory containing the script.
-
-
-
-Robinson & Coar Informational [Page 28]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- Character set
- The US-ASCII character set [9], excluding NUL, is used for the
- definition of meta-variables, header fields and CHAR values; TEXT
- values use ISO-8859-1. The PATH_TRANSLATED value can contain any
- 8-bit byte except NUL. The newline (NL) sequence is LF; servers
- should also accept CR LF as a newline.
-
-7.3. EBCDIC/POSIX
-
- For POSIX compatible operating systems using the EBCDIC character
- set, the following are defined:
-
- Meta-Variables
- Meta-variables are passed to the script in identically named
- environment variables. These are accessed by the C library
- routine getenv().
-
- The command line
- This is accessed using the argc and argv arguments to main(). The
- words have any characters which are 'active' in the Bourne shell
- escaped with a backslash.
-
- The current working directory
- The current working directory for the script SHOULD be set to the
- directory containing the script.
-
- Character set
- The IBM1047 character set [21], excluding NUL, is used for the
- definition of meta-variables, header fields, values, TEXT strings
- and the PATH_TRANSLATED value. The newline (NL) sequence is LF;
- servers should also accept CR LF as a newline.
-
- media-type charset default
- The default charset value for text (and other implementation-
- defined) media types is IBM1047.
-
-8. Implementation
-
-8.1. Recommendations for Servers
-
- Although the server and the CGI script need not be consistent in
- their handling of URL paths (client URLs and the PATH_INFO data,
- respectively), server authors may wish to impose consistency. So the
- server implementation should specify its behaviour for the following
- cases:
-
- 1. define any restrictions on allowed path segments, in particular
- whether non-terminal NULL segments are permitted;
-
-
-
-Robinson & Coar Informational [Page 29]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- 2. define the behaviour for "." or ".." path segments; i.e.,
- whether they are prohibited, treated as ordinary path segments
- or interpreted in accordance with the relative URL
- specification [2];
-
- 3. define any limits of the implementation, including limits on
- path or search string lengths, and limits on the volume of
- header fields the server will parse.
-
-8.2. Recommendations for Scripts
-
- If the script does not intend processing the PATH_INFO data, then it
- should reject the request with 404 Not Found if PATH_INFO is not
- NULL.
-
- If the output of a form is being processed, check that CONTENT_TYPE
- is "application/x-www-form-urlencoded" [18] or "multipart/form-data"
- [16]. If CONTENT_TYPE is blank, the script can reject the request
- with a 415 'Unsupported Media Type' error, where supported by the
- protocol.
-
- When parsing PATH_INFO, PATH_TRANSLATED or SCRIPT_NAME the script
- should be careful of void path segments ("//") and special path
- segments ("." and ".."). They should either be removed from the path
- before use in OS system calls, or the request should be rejected with
- 404 'Not Found'.
-
- When returning header fields, the script should try to send the CGI
- header fields as soon as possible, and should send them before any
- HTTP header fields. This may help reduce the server's memory
- requirements.
-
- Script authors should be aware that the REMOTE_ADDR and REMOTE_HOST
- meta-variables (see sections 4.1.8 and 4.1.9) may not identify the
- ultimate source of the request. They identify the client for the
- immediate request to the server; that client may be a proxy, gateway,
- or other intermediary acting on behalf of the actual source client.
-
-9. Security Considerations
-
-9.1. Safe Methods
-
- As discussed in the security considerations of the HTTP
- specifications [1], [4], the convention has been established that the
- GET and HEAD methods should be 'safe' and 'idempotent' (repeated
- requests have the same effect as a single request). See section 9.1
- of RFC 2616 [4] for a full discussion.
-
-
-
-
-Robinson & Coar Informational [Page 30]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
-9.2. Header Fields Containing Sensitive Information
-
- Some HTTP header fields may carry sensitive information which the
- server should not pass on to the script unless explicitly configured
- to do so. For example, if the server protects the script by using
- the Basic authentication scheme, then the client will send an
- Authorization header field containing a username and password. The
- server validates this information and so it should not pass on the
- password via the HTTP_AUTHORIZATION meta-variable without careful
- consideration. This also applies to the Proxy-Authorization header
- field and the corresponding HTTP_PROXY_AUTHORIZATION meta-variable.
-
-9.3. Data Privacy
-
- Confidential data in a request should be placed in a message-body as
- part of a POST request, and not placed in the URI or message headers.
- On some systems, the environment used to pass meta-variables to a
- script may be visible to other scripts or users. In addition, many
- existing servers, proxies and clients will permanently record the URI
- where it might be visible to third parties.
-
-9.4. Information Security Model
-
- For a client connection using TLS, the security model applies between
- the client and the server, and not between the client and the script.
- It is the server's responsibility to handle the TLS session, and thus
- it is the server which is authenticated to the client, not the CGI
- script.
-
- This specification provides no mechanism for the script to
- authenticate the server which invoked it. There is no enforced
- integrity on the CGI request and response messages.
-
-9.5. Script Interference with the Server
-
- The most common implementation of CGI invokes the script as a child
- process using the same user and group as the server process. It
- should therefore be ensured that the script cannot interfere with the
- server process, its configuration, documents or log files.
-
- If the script is executed by calling a function linked in to the
- server software (either at compile-time or run-time) then precautions
- should be taken to protect the core memory of the server, or to
- ensure that untrusted code cannot be executed.
-
-
-
-
-
-
-
-Robinson & Coar Informational [Page 31]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
-9.6. Data Length and Buffering Considerations
-
- This specification places no limits on the length of the message-body
- presented to the script. The script should not assume that
- statically allocated buffers of any size are sufficient to contain
- the entire submission at one time. Use of a fixed length buffer
- without careful overflow checking may result in an attacker
- exploiting 'stack-smashing' or 'stack-overflow' vulnerabilities of
- the operating system. The script may spool large submissions to disk
- or other buffering media, but a rapid succession of large submissions
- may result in denial of service conditions. If the CONTENT_LENGTH of
- a message-body is larger than resource considerations allow, scripts
- should respond with an error status appropriate for the protocol
- version; potentially applicable status codes include 503 'Service
- Unavailable' (HTTP/1.0 and HTTP/1.1), 413 'Request Entity Too Large'
- (HTTP/1.1), and 414 'Request-URI Too Large' (HTTP/1.1).
-
- Similar considerations apply to the server's handling of the CGI
- response from the script. There is no limit on the length of the
- header or message-body returned by the script; the server should not
- assume that statically allocated buffers of any size are sufficient
- to contain the entire response.
-
-9.7. Stateless Processing
-
- The stateless nature of the Web makes each script execution and
- resource retrieval independent of all others even when multiple
- requests constitute a single conceptual Web transaction. Because of
- this, a script should not make any assumptions about the context of
- the user-agent submitting a request. In particular, scripts should
- examine data obtained from the client and verify that they are valid,
- both in form and content, before allowing them to be used for
- sensitive purposes such as input to other applications, commands, or
- operating system services. These uses include (but are not limited
- to) system call arguments, database writes, dynamically evaluated
- source code, and input to billing or other secure processes. It is
- important that applications be protected from invalid input
- regardless of whether the invalidity is the result of user error,
- logic error, or malicious action.
-
- Authors of scripts involved in multi-request transactions should be
- particularly cautious about validating the state information;
- undesirable effects may result from the substitution of dangerous
- values for portions of the submission which might otherwise be
- presumed safe. Subversion of this type occurs when alterations are
- made to data from a prior stage of the transaction that were not
- meant to be controlled by the client (e.g., hidden HTML form
- elements, cookies, embedded URLs, etc.).
-
-
-
-Robinson & Coar Informational [Page 32]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
-9.8. Relative Paths
-
- The server should be careful of ".." path segments in the request
- URI. These should be removed or resolved in the request URI before
- it is split into the script-path and extra-path. Alternatively, when
- the extra-path is used to find the PATH_TRANSLATED, care should be
- taken to avoid the path resolution from providing translated paths
- outside an expected path hierarchy.
-
-9.9. Non-parsed Header Output
-
- If a script returns a non-parsed header output, to be interpreted by
- the client in its native protocol, then the script must address all
- security considerations relating to that protocol.
-
-10. Acknowledgements
-
- This work is based on the original CGI interface that arose out of
- discussions on the 'www-talk' mailing list. In particular, Rob
- McCool, John Franks, Ari Luotonen, George Phillips and Tony Sanders
- deserve special recognition for their efforts in defining and
- implementing the early versions of this interface.
-
- This document has also greatly benefited from the comments and
- suggestions made Chris Adie, Dave Kristol and Mike Meyer; also David
- Morris, Jeremy Madea, Patrick McManus, Adam Donahue, Ross Patterson
- and Harald Alvestrand.
-
-11. References
-
-11.1 Normative References
-
- [1] Berners-Lee, T., Fielding, R. and H. Frystyk, "Hypertext
- Transfer Protocol -- HTTP/1.0", RFC 1945, May 1996.
-
- [2] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource
- Identifiers (URI) : Generic Syntax", RFC 2396, August 1998.
-
- [3] Bradner, S., "Key words for use in RFCs to Indicate Requirements
- Levels", BCP 14, RFC 2119, March 1997.
-
- [4] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L.,
- Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol --
- HTTP/1.1", RFC 2616, June 1999.
-
- [5] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
- Leach, P., Luotonen, A., and L. Stewart, "HTTP Authentication:
- Basic and Digest Access Authentication", RFC 2617, June 1999.
-
-
-
-Robinson & Coar Informational [Page 33]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- [6] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part Two: Media Types", RFC 2046, November
- 1996.
-
- [7] Hinden, R., Carpenter, B., and L. Masinter, "Format for Literal
- IPv6 Addresses in URL's", RFC 2732, December 1999.
-
- [8] "HTTP Status Code Registry",
- http://www.iana.org/assignments/http-status-codes, IANA.
-
- [9] "Information Systems -- Coded Character Sets -- 7-bit American
- Standard Code for Information Interchange (7-Bit ASCII)", ANSI
- INCITS.4-1986 (R2002).
-
- [10] "Information technology -- 8-bit single-byte coded graphic
- character sets -- Part 1: Latin alphabet No. 1", ISO/IEC
- 8859-1:1998.
-
-11.2. Informative References
-
- [11] Berners-Lee, T., "Universal Resource Identifiers in WWW: A
- Unifying Syntax for the Expression of Names and Addresses of
- Objects on the Network as used in the World-Wide Web", RFC 1630,
- June 1994.
-
- [12] Braden, R., Ed., "Requirements for Internet Hosts -- Application
- and Support", STD 3, RFC 1123, October 1989.
-
- [13] Crocker, D., "Standard for the Format of ARPA Internet Text
- Messages", STD 11, RFC 822, August 1982.
-
- [14] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC
- 2246, January 1999.
-
- [15] Hinden R. and S. Deering, "Internet Protocol Version 6 (IPv6)
- Addressing Architecture", RFC 3513, April 2003.
-
- [16] Masinter, L., "Returning Values from Forms:
- multipart/form-data", RFC 2388, August 1998.
-
- [17] Mockapetris, P., "Domain Names - Concepts and Facilities", STD
- 13, RFC 1034, November 1987.
-
- [18] Raggett, D., Le Hors, A., and I. Jacobs, Eds., "HTML 4.01
- Specification", W3C Recommendation December 1999,
- http://www.w3.org/TR/html401/.
-
- [19] Rescola, E. "HTTP Over TLS", RFC 2818, May 2000.
-
-
-
-Robinson & Coar Informational [Page 34]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
- [20] St. Johns, M., "Identification Protocol", RFC 1413, February
- 1993.
-
- [21] IBM National Language Support Reference Manual Volume 2,
- SE09-8002-01, March 1990.
-
- [22] "The Common Gateway Interface",
- http://hoohoo.ncsa.uiuc.edu/cgi/, NCSA, University of Illinois.
-
-12. Authors' Addresses
-
- David Robinson
- The Apache Software Foundation
-
- EMail: drtr@apache.org
-
-
- Ken A. L. Coar
- The Apache Software Foundation
-
- EMail: coar@apache.org
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Robinson & Coar Informational [Page 35]
-\f
-RFC 3875 CGI Version 1.1 October 2004
-
-
-13. Full Copyright Statement
-
- Copyright (C) The Internet Society (2004). This document is subject
- to the rights, licenses and restrictions contained in BCP 78 and at
- www.rfc-editor.org, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
- Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the ISOC's procedures with respect to rights in ISOC Documents can
- be found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at ietf-
- ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-Robinson & Coar Informational [Page 36]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group T. Berners-Lee
-Request for Comments: 3986 W3C/MIT
-STD: 66 R. Fielding
-Updates: 1738 Day Software
-Obsoletes: 2732, 2396, 1808 L. Masinter
-Category: Standards Track Adobe Systems
- January 2005
-
-
- Uniform Resource Identifier (URI): Generic Syntax
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2005).
-
-Abstract
-
- A Uniform Resource Identifier (URI) is a compact sequence of
- characters that identifies an abstract or physical resource. This
- specification defines the generic URI syntax and a process for
- resolving URI references that might be in relative form, along with
- guidelines and security considerations for the use of URIs on the
- Internet. The URI syntax defines a grammar that is a superset of all
- valid URIs, allowing an implementation to parse the common components
- of a URI reference without knowing the scheme-specific requirements
- of every possible identifier. This specification does not define a
- generative grammar for URIs; that task is performed by the individual
- specifications of each URI scheme.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 1]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
- 1.1. Overview of URIs . . . . . . . . . . . . . . . . . . . . 4
- 1.1.1. Generic Syntax . . . . . . . . . . . . . . . . . 6
- 1.1.2. Examples . . . . . . . . . . . . . . . . . . . . 7
- 1.1.3. URI, URL, and URN . . . . . . . . . . . . . . . 7
- 1.2. Design Considerations . . . . . . . . . . . . . . . . . 8
- 1.2.1. Transcription . . . . . . . . . . . . . . . . . 8
- 1.2.2. Separating Identification from Interaction . . . 9
- 1.2.3. Hierarchical Identifiers . . . . . . . . . . . . 10
- 1.3. Syntax Notation . . . . . . . . . . . . . . . . . . . . 11
- 2. Characters . . . . . . . . . . . . . . . . . . . . . . . . . . 11
- 2.1. Percent-Encoding . . . . . . . . . . . . . . . . . . . . 12
- 2.2. Reserved Characters . . . . . . . . . . . . . . . . . . 12
- 2.3. Unreserved Characters . . . . . . . . . . . . . . . . . 13
- 2.4. When to Encode or Decode . . . . . . . . . . . . . . . . 14
- 2.5. Identifying Data . . . . . . . . . . . . . . . . . . . . 14
- 3. Syntax Components . . . . . . . . . . . . . . . . . . . . . . 16
- 3.1. Scheme . . . . . . . . . . . . . . . . . . . . . . . . . 17
- 3.2. Authority . . . . . . . . . . . . . . . . . . . . . . . 17
- 3.2.1. User Information . . . . . . . . . . . . . . . . 18
- 3.2.2. Host . . . . . . . . . . . . . . . . . . . . . . 18
- 3.2.3. Port . . . . . . . . . . . . . . . . . . . . . . 22
- 3.3. Path . . . . . . . . . . . . . . . . . . . . . . . . . . 22
- 3.4. Query . . . . . . . . . . . . . . . . . . . . . . . . . 23
- 3.5. Fragment . . . . . . . . . . . . . . . . . . . . . . . . 24
- 4. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
- 4.1. URI Reference . . . . . . . . . . . . . . . . . . . . . 25
- 4.2. Relative Reference . . . . . . . . . . . . . . . . . . . 26
- 4.3. Absolute URI . . . . . . . . . . . . . . . . . . . . . . 27
- 4.4. Same-Document Reference . . . . . . . . . . . . . . . . 27
- 4.5. Suffix Reference . . . . . . . . . . . . . . . . . . . . 27
- 5. Reference Resolution . . . . . . . . . . . . . . . . . . . . . 28
- 5.1. Establishing a Base URI . . . . . . . . . . . . . . . . 28
- 5.1.1. Base URI Embedded in Content . . . . . . . . . . 29
- 5.1.2. Base URI from the Encapsulating Entity . . . . . 29
- 5.1.3. Base URI from the Retrieval URI . . . . . . . . 30
- 5.1.4. Default Base URI . . . . . . . . . . . . . . . . 30
- 5.2. Relative Resolution . . . . . . . . . . . . . . . . . . 30
- 5.2.1. Pre-parse the Base URI . . . . . . . . . . . . . 31
- 5.2.2. Transform References . . . . . . . . . . . . . . 31
- 5.2.3. Merge Paths . . . . . . . . . . . . . . . . . . 32
- 5.2.4. Remove Dot Segments . . . . . . . . . . . . . . 33
- 5.3. Component Recomposition . . . . . . . . . . . . . . . . 35
- 5.4. Reference Resolution Examples . . . . . . . . . . . . . 35
- 5.4.1. Normal Examples . . . . . . . . . . . . . . . . 36
- 5.4.2. Abnormal Examples . . . . . . . . . . . . . . . 36
-
-
-
-Berners-Lee, et al. Standards Track [Page 2]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- 6. Normalization and Comparison . . . . . . . . . . . . . . . . . 38
- 6.1. Equivalence . . . . . . . . . . . . . . . . . . . . . . 38
- 6.2. Comparison Ladder . . . . . . . . . . . . . . . . . . . 39
- 6.2.1. Simple String Comparison . . . . . . . . . . . . 39
- 6.2.2. Syntax-Based Normalization . . . . . . . . . . . 40
- 6.2.3. Scheme-Based Normalization . . . . . . . . . . . 41
- 6.2.4. Protocol-Based Normalization . . . . . . . . . . 42
- 7. Security Considerations . . . . . . . . . . . . . . . . . . . 43
- 7.1. Reliability and Consistency . . . . . . . . . . . . . . 43
- 7.2. Malicious Construction . . . . . . . . . . . . . . . . . 43
- 7.3. Back-End Transcoding . . . . . . . . . . . . . . . . . . 44
- 7.4. Rare IP Address Formats . . . . . . . . . . . . . . . . 45
- 7.5. Sensitive Information . . . . . . . . . . . . . . . . . 45
- 7.6. Semantic Attacks . . . . . . . . . . . . . . . . . . . . 45
- 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46
- 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 46
- 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 46
- 10.1. Normative References . . . . . . . . . . . . . . . . . . 46
- 10.2. Informative References . . . . . . . . . . . . . . . . . 47
- A. Collected ABNF for URI . . . . . . . . . . . . . . . . . . . . 49
- B. Parsing a URI Reference with a Regular Expression . . . . . . 50
- C. Delimiting a URI in Context . . . . . . . . . . . . . . . . . 51
- D. Changes from RFC 2396 . . . . . . . . . . . . . . . . . . . . 53
- D.1. Additions . . . . . . . . . . . . . . . . . . . . . . . 53
- D.2. Modifications . . . . . . . . . . . . . . . . . . . . . 53
- Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
- Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 60
- Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 61
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 3]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-1. Introduction
-
- A Uniform Resource Identifier (URI) provides a simple and extensible
- means for identifying a resource. This specification of URI syntax
- and semantics is derived from concepts introduced by the World Wide
- Web global information initiative, whose use of these identifiers
- dates from 1990 and is described in "Universal Resource Identifiers
- in WWW" [RFC1630]. The syntax is designed to meet the
- recommendations laid out in "Functional Recommendations for Internet
- Resource Locators" [RFC1736] and "Functional Requirements for Uniform
- Resource Names" [RFC1737].
-
- This document obsoletes [RFC2396], which merged "Uniform Resource
- Locators" [RFC1738] and "Relative Uniform Resource Locators"
- [RFC1808] in order to define a single, generic syntax for all URIs.
- It obsoletes [RFC2732], which introduced syntax for an IPv6 address.
- It excludes portions of RFC 1738 that defined the specific syntax of
- individual URI schemes; those portions will be updated as separate
- documents. The process for registration of new URI schemes is
- defined separately by [BCP35]. Advice for designers of new URI
- schemes can be found in [RFC2718]. All significant changes from RFC
- 2396 are noted in Appendix D.
-
- This specification uses the terms "character" and "coded character
- set" in accordance with the definitions provided in [BCP19], and
- "character encoding" in place of what [BCP19] refers to as a
- "charset".
-
-1.1. Overview of URIs
-
- URIs are characterized as follows:
-
- Uniform
-
- Uniformity provides several benefits. It allows different types
- of resource identifiers to be used in the same context, even when
- the mechanisms used to access those resources may differ. It
- allows uniform semantic interpretation of common syntactic
- conventions across different types of resource identifiers. It
- allows introduction of new types of resource identifiers without
- interfering with the way that existing identifiers are used. It
- allows the identifiers to be reused in many different contexts,
- thus permitting new applications or protocols to leverage a pre-
- existing, large, and widely used set of resource identifiers.
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 4]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- Resource
-
- This specification does not limit the scope of what might be a
- resource; rather, the term "resource" is used in a general sense
- for whatever might be identified by a URI. Familiar examples
- include an electronic document, an image, a source of information
- with a consistent purpose (e.g., "today's weather report for Los
- Angeles"), a service (e.g., an HTTP-to-SMS gateway), and a
- collection of other resources. A resource is not necessarily
- accessible via the Internet; e.g., human beings, corporations, and
- bound books in a library can also be resources. Likewise,
- abstract concepts can be resources, such as the operators and
- operands of a mathematical equation, the types of a relationship
- (e.g., "parent" or "employee"), or numeric values (e.g., zero,
- one, and infinity).
-
- Identifier
-
- An identifier embodies the information required to distinguish
- what is being identified from all other things within its scope of
- identification. Our use of the terms "identify" and "identifying"
- refer to this purpose of distinguishing one resource from all
- other resources, regardless of how that purpose is accomplished
- (e.g., by name, address, or context). These terms should not be
- mistaken as an assumption that an identifier defines or embodies
- the identity of what is referenced, though that may be the case
- for some identifiers. Nor should it be assumed that a system
- using URIs will access the resource identified: in many cases,
- URIs are used to denote resources without any intention that they
- be accessed. Likewise, the "one" resource identified might not be
- singular in nature (e.g., a resource might be a named set or a
- mapping that varies over time).
-
- A URI is an identifier consisting of a sequence of characters
- matching the syntax rule named <URI> in Section 3. It enables
- uniform identification of resources via a separately defined
- extensible set of naming schemes (Section 3.1). How that
- identification is accomplished, assigned, or enabled is delegated to
- each scheme specification.
-
- This specification does not place any limits on the nature of a
- resource, the reasons why an application might seek to refer to a
- resource, or the kinds of systems that might use URIs for the sake of
- identifying resources. This specification does not require that a
- URI persists in identifying the same resource over time, though that
- is a common goal of all URI schemes. Nevertheless, nothing in this
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 5]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- specification prevents an application from limiting itself to
- particular types of resources, or to a subset of URIs that maintains
- characteristics desired by that application.
-
- URIs have a global scope and are interpreted consistently regardless
- of context, though the result of that interpretation may be in
- relation to the end-user's context. For example, "http://localhost/"
- has the same interpretation for every user of that reference, even
- though the network interface corresponding to "localhost" may be
- different for each end-user: interpretation is independent of access.
- However, an action made on the basis of that reference will take
- place in relation to the end-user's context, which implies that an
- action intended to refer to a globally unique thing must use a URI
- that distinguishes that resource from all other things. URIs that
- identify in relation to the end-user's local context should only be
- used when the context itself is a defining aspect of the resource,
- such as when an on-line help manual refers to a file on the end-
- user's file system (e.g., "file:///etc/hosts").
-
-1.1.1. Generic Syntax
-
- Each URI begins with a scheme name, as defined in Section 3.1, that
- refers to a specification for assigning identifiers within that
- scheme. As such, the URI syntax is a federated and extensible naming
- system wherein each scheme's specification may further restrict the
- syntax and semantics of identifiers using that scheme.
-
- This specification defines those elements of the URI syntax that are
- required of all URI schemes or are common to many URI schemes. It
- thus defines the syntax and semantics needed to implement a scheme-
- independent parsing mechanism for URI references, by which the
- scheme-dependent handling of a URI can be postponed until the
- scheme-dependent semantics are needed. Likewise, protocols and data
- formats that make use of URI references can refer to this
- specification as a definition for the range of syntax allowed for all
- URIs, including those schemes that have yet to be defined. This
- decouples the evolution of identification schemes from the evolution
- of protocols, data formats, and implementations that make use of
- URIs.
-
- A parser of the generic URI syntax can parse any URI reference into
- its major components. Once the scheme is determined, further
- scheme-specific parsing can be performed on the components. In other
- words, the URI generic syntax is a superset of the syntax of all URI
- schemes.
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 6]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-1.1.2. Examples
-
- The following example URIs illustrate several URI schemes and
- variations in their common syntax components:
-
- ftp://ftp.is.co.za/rfc/rfc1808.txt
-
- http://www.ietf.org/rfc/rfc2396.txt
-
- ldap://[2001:db8::7]/c=GB?objectClass?one
-
- mailto:John.Doe@example.com
-
- news:comp.infosystems.www.servers.unix
-
- tel:+1-816-555-1212
-
- telnet://192.0.2.16:80/
-
- urn:oasis:names:specification:docbook:dtd:xml:4.1.2
-
-
-1.1.3. URI, URL, and URN
-
- A URI can be further classified as a locator, a name, or both. The
- term "Uniform Resource Locator" (URL) refers to the subset of URIs
- that, in addition to identifying a resource, provide a means of
- locating the resource by describing its primary access mechanism
- (e.g., its network "location"). The term "Uniform Resource Name"
- (URN) has been used historically to refer to both URIs under the
- "urn" scheme [RFC2141], which are required to remain globally unique
- and persistent even when the resource ceases to exist or becomes
- unavailable, and to any other URI with the properties of a name.
-
- An individual scheme does not have to be classified as being just one
- of "name" or "locator". Instances of URIs from any given scheme may
- have the characteristics of names or locators or both, often
- depending on the persistence and care in the assignment of
- identifiers by the naming authority, rather than on any quality of
- the scheme. Future specifications and related documentation should
- use the general term "URI" rather than the more restrictive terms
- "URL" and "URN" [RFC3305].
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 7]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-1.2. Design Considerations
-
-1.2.1. Transcription
-
- The URI syntax has been designed with global transcription as one of
- its main considerations. A URI is a sequence of characters from a
- very limited set: the letters of the basic Latin alphabet, digits,
- and a few special characters. A URI may be represented in a variety
- of ways; e.g., ink on paper, pixels on a screen, or a sequence of
- character encoding octets. The interpretation of a URI depends only
- on the characters used and not on how those characters are
- represented in a network protocol.
-
- The goal of transcription can be described by a simple scenario.
- Imagine two colleagues, Sam and Kim, sitting in a pub at an
- international conference and exchanging research ideas. Sam asks Kim
- for a location to get more information, so Kim writes the URI for the
- research site on a napkin. Upon returning home, Sam takes out the
- napkin and types the URI into a computer, which then retrieves the
- information to which Kim referred.
-
- There are several design considerations revealed by the scenario:
-
- o A URI is a sequence of characters that is not always represented
- as a sequence of octets.
-
- o A URI might be transcribed from a non-network source and thus
- should consist of characters that are most likely able to be
- entered into a computer, within the constraints imposed by
- keyboards (and related input devices) across languages and
- locales.
-
- o A URI often has to be remembered by people, and it is easier for
- people to remember a URI when it consists of meaningful or
- familiar components.
-
- These design considerations are not always in alignment. For
- example, it is often the case that the most meaningful name for a URI
- component would require characters that cannot be typed into some
- systems. The ability to transcribe a resource identifier from one
- medium to another has been considered more important than having a
- URI consist of the most meaningful of components.
-
- In local or regional contexts and with improving technology, users
- might benefit from being able to use a wider range of characters;
- such use is not defined by this specification. Percent-encoded
- octets (Section 2.1) may be used within a URI to represent characters
- outside the range of the US-ASCII coded character set if this
-
-
-
-Berners-Lee, et al. Standards Track [Page 8]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- representation is allowed by the scheme or by the protocol element in
- which the URI is referenced. Such a definition should specify the
- character encoding used to map those characters to octets prior to
- being percent-encoded for the URI.
-
-1.2.2. Separating Identification from Interaction
-
- A common misunderstanding of URIs is that they are only used to refer
- to accessible resources. The URI itself only provides
- identification; access to the resource is neither guaranteed nor
- implied by the presence of a URI. Instead, any operation associated
- with a URI reference is defined by the protocol element, data format
- attribute, or natural language text in which it appears.
-
- Given a URI, a system may attempt to perform a variety of operations
- on the resource, as might be characterized by words such as "access",
- "update", "replace", or "find attributes". Such operations are
- defined by the protocols that make use of URIs, not by this
- specification. However, we do use a few general terms for describing
- common operations on URIs. URI "resolution" is the process of
- determining an access mechanism and the appropriate parameters
- necessary to dereference a URI; this resolution may require several
- iterations. To use that access mechanism to perform an action on the
- URI's resource is to "dereference" the URI.
-
- When URIs are used within information retrieval systems to identify
- sources of information, the most common form of URI dereference is
- "retrieval": making use of a URI in order to retrieve a
- representation of its associated resource. A "representation" is a
- sequence of octets, along with representation metadata describing
- those octets, that constitutes a record of the state of the resource
- at the time when the representation is generated. Retrieval is
- achieved by a process that might include using the URI as a cache key
- to check for a locally cached representation, resolution of the URI
- to determine an appropriate access mechanism (if any), and
- dereference of the URI for the sake of applying a retrieval
- operation. Depending on the protocols used to perform the retrieval,
- additional information might be supplied about the resource (resource
- metadata) and its relation to other resources.
-
- URI references in information retrieval systems are designed to be
- late-binding: the result of an access is generally determined when it
- is accessed and may vary over time or due to other aspects of the
- interaction. These references are created in order to be used in the
- future: what is being identified is not some specific result that was
- obtained in the past, but rather some characteristic that is expected
- to be true for future results. In such cases, the resource referred
- to by the URI is actually a sameness of characteristics as observed
-
-
-
-Berners-Lee, et al. Standards Track [Page 9]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- over time, perhaps elucidated by additional comments or assertions
- made by the resource provider.
-
- Although many URI schemes are named after protocols, this does not
- imply that use of these URIs will result in access to the resource
- via the named protocol. URIs are often used simply for the sake of
- identification. Even when a URI is used to retrieve a representation
- of a resource, that access might be through gateways, proxies,
- caches, and name resolution services that are independent of the
- protocol associated with the scheme name. The resolution of some
- URIs may require the use of more than one protocol (e.g., both DNS
- and HTTP are typically used to access an "http" URI's origin server
- when a representation isn't found in a local cache).
-
-1.2.3. Hierarchical Identifiers
-
- The URI syntax is organized hierarchically, with components listed in
- order of decreasing significance from left to right. For some URI
- schemes, the visible hierarchy is limited to the scheme itself:
- everything after the scheme component delimiter (":") is considered
- opaque to URI processing. Other URI schemes make the hierarchy
- explicit and visible to generic parsing algorithms.
-
- The generic syntax uses the slash ("/"), question mark ("?"), and
- number sign ("#") characters to delimit components that are
- significant to the generic parser's hierarchical interpretation of an
- identifier. In addition to aiding the readability of such
- identifiers through the consistent use of familiar syntax, this
- uniform representation of hierarchy across naming schemes allows
- scheme-independent references to be made relative to that hierarchy.
-
- It is often the case that a group or "tree" of documents has been
- constructed to serve a common purpose, wherein the vast majority of
- URI references in these documents point to resources within the tree
- rather than outside it. Similarly, documents located at a particular
- site are much more likely to refer to other resources at that site
- than to resources at remote sites. Relative referencing of URIs
- allows document trees to be partially independent of their location
- and access scheme. For instance, it is possible for a single set of
- hypertext documents to be simultaneously accessible and traversable
- via each of the "file", "http", and "ftp" schemes if the documents
- refer to each other with relative references. Furthermore, such
- document trees can be moved, as a whole, without changing any of the
- relative references.
-
- A relative reference (Section 4.2) refers to a resource by describing
- the difference within a hierarchical name space between the reference
- context and the target URI. The reference resolution algorithm,
-
-
-
-Berners-Lee, et al. Standards Track [Page 10]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- presented in Section 5, defines how such a reference is transformed
- to the target URI. As relative references can only be used within
- the context of a hierarchical URI, designers of new URI schemes
- should use a syntax consistent with the generic syntax's hierarchical
- components unless there are compelling reasons to forbid relative
- referencing within that scheme.
-
- NOTE: Previous specifications used the terms "partial URI" and
- "relative URI" to denote a relative reference to a URI. As some
- readers misunderstood those terms to mean that relative URIs are a
- subset of URIs rather than a method of referencing URIs, this
- specification simply refers to them as relative references.
-
- All URI references are parsed by generic syntax parsers when used.
- However, because hierarchical processing has no effect on an absolute
- URI used in a reference unless it contains one or more dot-segments
- (complete path segments of "." or "..", as described in Section 3.3),
- URI scheme specifications can define opaque identifiers by
- disallowing use of slash characters, question mark characters, and
- the URIs "scheme:." and "scheme:..".
-
-1.3. Syntax Notation
-
- This specification uses the Augmented Backus-Naur Form (ABNF)
- notation of [RFC2234], including the following core ABNF syntax rules
- defined by that specification: ALPHA (letters), CR (carriage return),
- DIGIT (decimal digits), DQUOTE (double quote), HEXDIG (hexadecimal
- digits), LF (line feed), and SP (space). The complete URI syntax is
- collected in Appendix A.
-
-2. Characters
-
- The URI syntax provides a method of encoding data, presumably for the
- sake of identifying a resource, as a sequence of characters. The URI
- characters are, in turn, frequently encoded as octets for transport
- or presentation. This specification does not mandate any particular
- character encoding for mapping between URI characters and the octets
- used to store or transmit those characters. When a URI appears in a
- protocol element, the character encoding is defined by that protocol;
- without such a definition, a URI is assumed to be in the same
- character encoding as the surrounding text.
-
- The ABNF notation defines its terminal values to be non-negative
- integers (codepoints) based on the US-ASCII coded character set
- [ASCII]. Because a URI is a sequence of characters, we must invert
- that relation in order to understand the URI syntax. Therefore, the
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 11]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- integer values used by the ABNF must be mapped back to their
- corresponding characters via US-ASCII in order to complete the syntax
- rules.
-
- A URI is composed from a limited set of characters consisting of
- digits, letters, and a few graphic symbols. A reserved subset of
- those characters may be used to delimit syntax components within a
- URI while the remaining characters, including both the unreserved set
- and those reserved characters not acting as delimiters, define each
- component's identifying data.
-
-2.1. Percent-Encoding
-
- A percent-encoding mechanism is used to represent a data octet in a
- component when that octet's corresponding character is outside the
- allowed set or is being used as a delimiter of, or within, the
- component. A percent-encoded octet is encoded as a character
- triplet, consisting of the percent character "%" followed by the two
- hexadecimal digits representing that octet's numeric value. For
- example, "%20" is the percent-encoding for the binary octet
- "00100000" (ABNF: %x20), which in US-ASCII corresponds to the space
- character (SP). Section 2.4 describes when percent-encoding and
- decoding is applied.
-
- pct-encoded = "%" HEXDIG HEXDIG
-
- The uppercase hexadecimal digits 'A' through 'F' are equivalent to
- the lowercase digits 'a' through 'f', respectively. If two URIs
- differ only in the case of hexadecimal digits used in percent-encoded
- octets, they are equivalent. For consistency, URI producers and
- normalizers should use uppercase hexadecimal digits for all percent-
- encodings.
-
-2.2. Reserved Characters
-
- URIs include components and subcomponents that are delimited by
- characters in the "reserved" set. These characters are called
- "reserved" because they may (or may not) be defined as delimiters by
- the generic syntax, by each scheme-specific syntax, or by the
- implementation-specific syntax of a URI's dereferencing algorithm.
- If data for a URI component would conflict with a reserved
- character's purpose as a delimiter, then the conflicting data must be
- percent-encoded before the URI is formed.
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 12]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- reserved = gen-delims / sub-delims
-
- gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@"
-
- sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
- / "*" / "+" / "," / ";" / "="
-
- The purpose of reserved characters is to provide a set of delimiting
- characters that are distinguishable from other data within a URI.
- URIs that differ in the replacement of a reserved character with its
- corresponding percent-encoded octet are not equivalent. Percent-
- encoding a reserved character, or decoding a percent-encoded octet
- that corresponds to a reserved character, will change how the URI is
- interpreted by most applications. Thus, characters in the reserved
- set are protected from normalization and are therefore safe to be
- used by scheme-specific and producer-specific algorithms for
- delimiting data subcomponents within a URI.
-
- A subset of the reserved characters (gen-delims) is used as
- delimiters of the generic URI components described in Section 3. A
- component's ABNF syntax rule will not use the reserved or gen-delims
- rule names directly; instead, each syntax rule lists the characters
- allowed within that component (i.e., not delimiting it), and any of
- those characters that are also in the reserved set are "reserved" for
- use as subcomponent delimiters within the component. Only the most
- common subcomponents are defined by this specification; other
- subcomponents may be defined by a URI scheme's specification, or by
- the implementation-specific syntax of a URI's dereferencing
- algorithm, provided that such subcomponents are delimited by
- characters in the reserved set allowed within that component.
-
- URI producing applications should percent-encode data octets that
- correspond to characters in the reserved set unless these characters
- are specifically allowed by the URI scheme to represent data in that
- component. If a reserved character is found in a URI component and
- no delimiting role is known for that character, then it must be
- interpreted as representing the data octet corresponding to that
- character's encoding in US-ASCII.
-
-2.3. Unreserved Characters
-
- Characters that are allowed in a URI but do not have a reserved
- purpose are called unreserved. These include uppercase and lowercase
- letters, decimal digits, hyphen, period, underscore, and tilde.
-
- unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 13]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- URIs that differ in the replacement of an unreserved character with
- its corresponding percent-encoded US-ASCII octet are equivalent: they
- identify the same resource. However, URI comparison implementations
- do not always perform normalization prior to comparison (see Section
- 6). For consistency, percent-encoded octets in the ranges of ALPHA
- (%41-%5A and %61-%7A), DIGIT (%30-%39), hyphen (%2D), period (%2E),
- underscore (%5F), or tilde (%7E) should not be created by URI
- producers and, when found in a URI, should be decoded to their
- corresponding unreserved characters by URI normalizers.
-
-2.4. When to Encode or Decode
-
- Under normal circumstances, the only time when octets within a URI
- are percent-encoded is during the process of producing the URI from
- its component parts. This is when an implementation determines which
- of the reserved characters are to be used as subcomponent delimiters
- and which can be safely used as data. Once produced, a URI is always
- in its percent-encoded form.
-
- When a URI is dereferenced, the components and subcomponents
- significant to the scheme-specific dereferencing process (if any)
- must be parsed and separated before the percent-encoded octets within
- those components can be safely decoded, as otherwise the data may be
- mistaken for component delimiters. The only exception is for
- percent-encoded octets corresponding to characters in the unreserved
- set, which can be decoded at any time. For example, the octet
- corresponding to the tilde ("~") character is often encoded as "%7E"
- by older URI processing implementations; the "%7E" can be replaced by
- "~" without changing its interpretation.
-
- Because the percent ("%") character serves as the indicator for
- percent-encoded octets, it must be percent-encoded as "%25" for that
- octet to be used as data within a URI. Implementations must not
- percent-encode or decode the same string more than once, as decoding
- an already decoded string might lead to misinterpreting a percent
- data octet as the beginning of a percent-encoding, or vice versa in
- the case of percent-encoding an already percent-encoded string.
-
-2.5. Identifying Data
-
- URI characters provide identifying data for each of the URI
- components, serving as an external interface for identification
- between systems. Although the presence and nature of the URI
- production interface is hidden from clients that use its URIs (and is
- thus beyond the scope of the interoperability requirements defined by
- this specification), it is a frequent source of confusion and errors
- in the interpretation of URI character issues. Implementers have to
- be aware that there are multiple character encodings involved in the
-
-
-
-Berners-Lee, et al. Standards Track [Page 14]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- production and transmission of URIs: local name and data encoding,
- public interface encoding, URI character encoding, data format
- encoding, and protocol encoding.
-
- Local names, such as file system names, are stored with a local
- character encoding. URI producing applications (e.g., origin
- servers) will typically use the local encoding as the basis for
- producing meaningful names. The URI producer will transform the
- local encoding to one that is suitable for a public interface and
- then transform the public interface encoding into the restricted set
- of URI characters (reserved, unreserved, and percent-encodings).
- Those characters are, in turn, encoded as octets to be used as a
- reference within a data format (e.g., a document charset), and such
- data formats are often subsequently encoded for transmission over
- Internet protocols.
-
- For most systems, an unreserved character appearing within a URI
- component is interpreted as representing the data octet corresponding
- to that character's encoding in US-ASCII. Consumers of URIs assume
- that the letter "X" corresponds to the octet "01011000", and even
- when that assumption is incorrect, there is no harm in making it. A
- system that internally provides identifiers in the form of a
- different character encoding, such as EBCDIC, will generally perform
- character translation of textual identifiers to UTF-8 [STD63] (or
- some other superset of the US-ASCII character encoding) at an
- internal interface, thereby providing more meaningful identifiers
- than those resulting from simply percent-encoding the original
- octets.
-
- For example, consider an information service that provides data,
- stored locally using an EBCDIC-based file system, to clients on the
- Internet through an HTTP server. When an author creates a file with
- the name "Laguna Beach" on that file system, the "http" URI
- corresponding to that resource is expected to contain the meaningful
- string "Laguna%20Beach". If, however, that server produces URIs by
- using an overly simplistic raw octet mapping, then the result would
- be a URI containing "%D3%81%87%A4%95%81@%C2%85%81%83%88". An
- internal transcoding interface fixes this problem by transcoding the
- local name to a superset of US-ASCII prior to producing the URI.
- Naturally, proper interpretation of an incoming URI on such an
- interface requires that percent-encoded octets be decoded (e.g.,
- "%20" to SP) before the reverse transcoding is applied to obtain the
- local name.
-
- In some cases, the internal interface between a URI component and the
- identifying data that it has been crafted to represent is much less
- direct than a character encoding translation. For example, portions
- of a URI might reflect a query on non-ASCII data, or numeric
-
-
-
-Berners-Lee, et al. Standards Track [Page 15]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- coordinates on a map. Likewise, a URI scheme may define components
- with additional encoding requirements that are applied prior to
- forming the component and producing the URI.
-
- When a new URI scheme defines a component that represents textual
- data consisting of characters from the Universal Character Set [UCS],
- the data should first be encoded as octets according to the UTF-8
- character encoding [STD63]; then only those octets that do not
- correspond to characters in the unreserved set should be percent-
- encoded. For example, the character A would be represented as "A",
- the character LATIN CAPITAL LETTER A WITH GRAVE would be represented
- as "%C3%80", and the character KATAKANA LETTER A would be represented
- as "%E3%82%A2".
-
-3. Syntax Components
-
- The generic URI syntax consists of a hierarchical sequence of
- components referred to as the scheme, authority, path, query, and
- fragment.
-
- URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
-
- hier-part = "//" authority path-abempty
- / path-absolute
- / path-rootless
- / path-empty
-
- The scheme and path components are required, though the path may be
- empty (no characters). When authority is present, the path must
- either be empty or begin with a slash ("/") character. When
- authority is not present, the path cannot begin with two slash
- characters ("//"). These restrictions result in five different ABNF
- rules for a path (Section 3.3), only one of which will match any
- given URI reference.
-
- The following are two example URIs and their component parts:
-
- foo://example.com:8042/over/there?name=ferret#nose
- \_/ \______________/\_________/ \_________/ \__/
- | | | | |
- scheme authority path query fragment
- | _____________________|__
- / \ / \
- urn:example:animal:ferret:nose
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 16]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-3.1. Scheme
-
- Each URI begins with a scheme name that refers to a specification for
- assigning identifiers within that scheme. As such, the URI syntax is
- a federated and extensible naming system wherein each scheme's
- specification may further restrict the syntax and semantics of
- identifiers using that scheme.
-
- Scheme names consist of a sequence of characters beginning with a
- letter and followed by any combination of letters, digits, plus
- ("+"), period ("."), or hyphen ("-"). Although schemes are case-
- insensitive, the canonical form is lowercase and documents that
- specify schemes must do so with lowercase letters. An implementation
- should accept uppercase letters as equivalent to lowercase in scheme
- names (e.g., allow "HTTP" as well as "http") for the sake of
- robustness but should only produce lowercase scheme names for
- consistency.
-
- scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
-
- Individual schemes are not specified by this document. The process
- for registration of new URI schemes is defined separately by [BCP35].
- The scheme registry maintains the mapping between scheme names and
- their specifications. Advice for designers of new URI schemes can be
- found in [RFC2718]. URI scheme specifications must define their own
- syntax so that all strings matching their scheme-specific syntax will
- also match the <absolute-URI> grammar, as described in Section 4.3.
-
- When presented with a URI that violates one or more scheme-specific
- restrictions, the scheme-specific resolution process should flag the
- reference as an error rather than ignore the unused parts; doing so
- reduces the number of equivalent URIs and helps detect abuses of the
- generic syntax, which might indicate that the URI has been
- constructed to mislead the user (Section 7.6).
-
-3.2. Authority
-
- Many URI schemes include a hierarchical element for a naming
- authority so that governance of the name space defined by the
- remainder of the URI is delegated to that authority (which may, in
- turn, delegate it further). The generic syntax provides a common
- means for distinguishing an authority based on a registered name or
- server address, along with optional port and user information.
-
- The authority component is preceded by a double slash ("//") and is
- terminated by the next slash ("/"), question mark ("?"), or number
- sign ("#") character, or by the end of the URI.
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 17]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- authority = [ userinfo "@" ] host [ ":" port ]
-
- URI producers and normalizers should omit the ":" delimiter that
- separates host from port if the port component is empty. Some
- schemes do not allow the userinfo and/or port subcomponents.
-
- If a URI contains an authority component, then the path component
- must either be empty or begin with a slash ("/") character. Non-
- validating parsers (those that merely separate a URI reference into
- its major components) will often ignore the subcomponent structure of
- authority, treating it as an opaque string from the double-slash to
- the first terminating delimiter, until such time as the URI is
- dereferenced.
-
-3.2.1. User Information
-
- The userinfo subcomponent may consist of a user name and, optionally,
- scheme-specific information about how to gain authorization to access
- the resource. The user information, if present, is followed by a
- commercial at-sign ("@") that delimits it from the host.
-
- userinfo = *( unreserved / pct-encoded / sub-delims / ":" )
-
- Use of the format "user:password" in the userinfo field is
- deprecated. Applications should not render as clear text any data
- after the first colon (":") character found within a userinfo
- subcomponent unless the data after the colon is the empty string
- (indicating no password). Applications may choose to ignore or
- reject such data when it is received as part of a reference and
- should reject the storage of such data in unencrypted form. The
- passing of authentication information in clear text has proven to be
- a security risk in almost every case where it has been used.
-
- Applications that render a URI for the sake of user feedback, such as
- in graphical hypertext browsing, should render userinfo in a way that
- is distinguished from the rest of a URI, when feasible. Such
- rendering will assist the user in cases where the userinfo has been
- misleadingly crafted to look like a trusted domain name
- (Section 7.6).
-
-3.2.2. Host
-
- The host subcomponent of authority is identified by an IP literal
- encapsulated within square brackets, an IPv4 address in dotted-
- decimal form, or a registered name. The host subcomponent is case-
- insensitive. The presence of a host subcomponent within a URI does
- not imply that the scheme requires access to the given host on the
- Internet. In many cases, the host syntax is used only for the sake
-
-
-
-Berners-Lee, et al. Standards Track [Page 18]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- of reusing the existing registration process created and deployed for
- DNS, thus obtaining a globally unique name without the cost of
- deploying another registry. However, such use comes with its own
- costs: domain name ownership may change over time for reasons not
- anticipated by the URI producer. In other cases, the data within the
- host component identifies a registered name that has nothing to do
- with an Internet host. We use the name "host" for the ABNF rule
- because that is its most common purpose, not its only purpose.
-
- host = IP-literal / IPv4address / reg-name
-
- The syntax rule for host is ambiguous because it does not completely
- distinguish between an IPv4address and a reg-name. In order to
- disambiguate the syntax, we apply the "first-match-wins" algorithm:
- If host matches the rule for IPv4address, then it should be
- considered an IPv4 address literal and not a reg-name. Although host
- is case-insensitive, producers and normalizers should use lowercase
- for registered names and hexadecimal addresses for the sake of
- uniformity, while only using uppercase letters for percent-encodings.
-
- A host identified by an Internet Protocol literal address, version 6
- [RFC3513] or later, is distinguished by enclosing the IP literal
- within square brackets ("[" and "]"). This is the only place where
- square bracket characters are allowed in the URI syntax. In
- anticipation of future, as-yet-undefined IP literal address formats,
- an implementation may use an optional version flag to indicate such a
- format explicitly rather than rely on heuristic determination.
-
- IP-literal = "[" ( IPv6address / IPvFuture ) "]"
-
- IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )
-
- The version flag does not indicate the IP version; rather, it
- indicates future versions of the literal format. As such,
- implementations must not provide the version flag for the existing
- IPv4 and IPv6 literal address forms described below. If a URI
- containing an IP-literal that starts with "v" (case-insensitive),
- indicating that the version flag is present, is dereferenced by an
- application that does not know the meaning of that version flag, then
- the application should return an appropriate error for "address
- mechanism not supported".
-
- A host identified by an IPv6 literal address is represented inside
- the square brackets without a preceding version flag. The ABNF
- provided here is a translation of the text definition of an IPv6
- literal address provided in [RFC3513]. This syntax does not support
- IPv6 scoped addressing zone identifiers.
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 19]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- A 128-bit IPv6 address is divided into eight 16-bit pieces. Each
- piece is represented numerically in case-insensitive hexadecimal,
- using one to four hexadecimal digits (leading zeroes are permitted).
- The eight encoded pieces are given most-significant first, separated
- by colon characters. Optionally, the least-significant two pieces
- may instead be represented in IPv4 address textual format. A
- sequence of one or more consecutive zero-valued 16-bit pieces within
- the address may be elided, omitting all their digits and leaving
- exactly two consecutive colons in their place to mark the elision.
-
- IPv6address = 6( h16 ":" ) ls32
- / "::" 5( h16 ":" ) ls32
- / [ h16 ] "::" 4( h16 ":" ) ls32
- / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
- / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
- / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32
- / [ *4( h16 ":" ) h16 ] "::" ls32
- / [ *5( h16 ":" ) h16 ] "::" h16
- / [ *6( h16 ":" ) h16 ] "::"
-
- ls32 = ( h16 ":" h16 ) / IPv4address
- ; least-significant 32 bits of address
-
- h16 = 1*4HEXDIG
- ; 16 bits of address represented in hexadecimal
-
- A host identified by an IPv4 literal address is represented in
- dotted-decimal notation (a sequence of four decimal numbers in the
- range 0 to 255, separated by "."), as described in [RFC1123] by
- reference to [RFC0952]. Note that other forms of dotted notation may
- be interpreted on some platforms, as described in Section 7.4, but
- only the dotted-decimal form of four octets is allowed by this
- grammar.
-
- IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet
-
- dec-octet = DIGIT ; 0-9
- / %x31-39 DIGIT ; 10-99
- / "1" 2DIGIT ; 100-199
- / "2" %x30-34 DIGIT ; 200-249
- / "25" %x30-35 ; 250-255
-
- A host identified by a registered name is a sequence of characters
- usually intended for lookup within a locally defined host or service
- name registry, though the URI's scheme-specific semantics may require
- that a specific registry (or fixed name table) be used instead. The
- most common name registry mechanism is the Domain Name System (DNS).
- A registered name intended for lookup in the DNS uses the syntax
-
-
-
-Berners-Lee, et al. Standards Track [Page 20]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- defined in Section 3.5 of [RFC1034] and Section 2.1 of [RFC1123].
- Such a name consists of a sequence of domain labels separated by ".",
- each domain label starting and ending with an alphanumeric character
- and possibly also containing "-" characters. The rightmost domain
- label of a fully qualified domain name in DNS may be followed by a
- single "." and should be if it is necessary to distinguish between
- the complete domain name and some local domain.
-
- reg-name = *( unreserved / pct-encoded / sub-delims )
-
- If the URI scheme defines a default for host, then that default
- applies when the host subcomponent is undefined or when the
- registered name is empty (zero length). For example, the "file" URI
- scheme is defined so that no authority, an empty host, and
- "localhost" all mean the end-user's machine, whereas the "http"
- scheme considers a missing authority or empty host invalid.
-
- This specification does not mandate a particular registered name
- lookup technology and therefore does not restrict the syntax of reg-
- name beyond what is necessary for interoperability. Instead, it
- delegates the issue of registered name syntax conformance to the
- operating system of each application performing URI resolution, and
- that operating system decides what it will allow for the purpose of
- host identification. A URI resolution implementation might use DNS,
- host tables, yellow pages, NetInfo, WINS, or any other system for
- lookup of registered names. However, a globally scoped naming
- system, such as DNS fully qualified domain names, is necessary for
- URIs intended to have global scope. URI producers should use names
- that conform to the DNS syntax, even when use of DNS is not
- immediately apparent, and should limit these names to no more than
- 255 characters in length.
-
- The reg-name syntax allows percent-encoded octets in order to
- represent non-ASCII registered names in a uniform way that is
- independent of the underlying name resolution technology. Non-ASCII
- characters must first be encoded according to UTF-8 [STD63], and then
- each octet of the corresponding UTF-8 sequence must be percent-
- encoded to be represented as URI characters. URI producing
- applications must not use percent-encoding in host unless it is used
- to represent a UTF-8 character sequence. When a non-ASCII registered
- name represents an internationalized domain name intended for
- resolution via the DNS, the name must be transformed to the IDNA
- encoding [RFC3490] prior to name lookup. URI producers should
- provide these registered names in the IDNA encoding, rather than a
- percent-encoding, if they wish to maximize interoperability with
- legacy URI resolvers.
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 21]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-3.2.3. Port
-
- The port subcomponent of authority is designated by an optional port
- number in decimal following the host and delimited from it by a
- single colon (":") character.
-
- port = *DIGIT
-
- A scheme may define a default port. For example, the "http" scheme
- defines a default port of "80", corresponding to its reserved TCP
- port number. The type of port designated by the port number (e.g.,
- TCP, UDP, SCTP) is defined by the URI scheme. URI producers and
- normalizers should omit the port component and its ":" delimiter if
- port is empty or if its value would be the same as that of the
- scheme's default.
-
-3.3. Path
-
- The path component contains data, usually organized in hierarchical
- form, that, along with data in the non-hierarchical query component
- (Section 3.4), serves to identify a resource within the scope of the
- URI's scheme and naming authority (if any). The path is terminated
- by the first question mark ("?") or number sign ("#") character, or
- by the end of the URI.
-
- If a URI contains an authority component, then the path component
- must either be empty or begin with a slash ("/") character. If a URI
- does not contain an authority component, then the path cannot begin
- with two slash characters ("//"). In addition, a URI reference
- (Section 4.1) may be a relative-path reference, in which case the
- first path segment cannot contain a colon (":") character. The ABNF
- requires five separate rules to disambiguate these cases, only one of
- which will match the path substring within a given URI reference. We
- use the generic term "path component" to describe the URI substring
- matched by the parser to one of these rules.
-
- path = path-abempty ; begins with "/" or is empty
- / path-absolute ; begins with "/" but not "//"
- / path-noscheme ; begins with a non-colon segment
- / path-rootless ; begins with a segment
- / path-empty ; zero characters
-
- path-abempty = *( "/" segment )
- path-absolute = "/" [ segment-nz *( "/" segment ) ]
- path-noscheme = segment-nz-nc *( "/" segment )
- path-rootless = segment-nz *( "/" segment )
- path-empty = 0<pchar>
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 22]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- segment = *pchar
- segment-nz = 1*pchar
- segment-nz-nc = 1*( unreserved / pct-encoded / sub-delims / "@" )
- ; non-zero-length segment without any colon ":"
-
- pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
-
- A path consists of a sequence of path segments separated by a slash
- ("/") character. A path is always defined for a URI, though the
- defined path may be empty (zero length). Use of the slash character
- to indicate hierarchy is only required when a URI will be used as the
- context for relative references. For example, the URI
- <mailto:fred@example.com> has a path of "fred@example.com", whereas
- the URI <foo://info.example.com?fred> has an empty path.
-
- The path segments "." and "..", also known as dot-segments, are
- defined for relative reference within the path name hierarchy. They
- are intended for use at the beginning of a relative-path reference
- (Section 4.2) to indicate relative position within the hierarchical
- tree of names. This is similar to their role within some operating
- systems' file directory structures to indicate the current directory
- and parent directory, respectively. However, unlike in a file
- system, these dot-segments are only interpreted within the URI path
- hierarchy and are removed as part of the resolution process (Section
- 5.2).
-
- Aside from dot-segments in hierarchical paths, a path segment is
- considered opaque by the generic syntax. URI producing applications
- often use the reserved characters allowed in a segment to delimit
- scheme-specific or dereference-handler-specific subcomponents. For
- example, the semicolon (";") and equals ("=") reserved characters are
- often used to delimit parameters and parameter values applicable to
- that segment. The comma (",") reserved character is often used for
- similar purposes. For example, one URI producer might use a segment
- such as "name;v=1.1" to indicate a reference to version 1.1 of
- "name", whereas another might use a segment such as "name,1.1" to
- indicate the same. Parameter types may be defined by scheme-specific
- semantics, but in most cases the syntax of a parameter is specific to
- the implementation of the URI's dereferencing algorithm.
-
-3.4. Query
-
- The query component contains non-hierarchical data that, along with
- data in the path component (Section 3.3), serves to identify a
- resource within the scope of the URI's scheme and naming authority
- (if any). The query component is indicated by the first question
- mark ("?") character and terminated by a number sign ("#") character
- or by the end of the URI.
-
-
-
-Berners-Lee, et al. Standards Track [Page 23]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- query = *( pchar / "/" / "?" )
-
- The characters slash ("/") and question mark ("?") may represent data
- within the query component. Beware that some older, erroneous
- implementations may not handle such data correctly when it is used as
- the base URI for relative references (Section 5.1), apparently
- because they fail to distinguish query data from path data when
- looking for hierarchical separators. However, as query components
- are often used to carry identifying information in the form of
- "key=value" pairs and one frequently used value is a reference to
- another URI, it is sometimes better for usability to avoid percent-
- encoding those characters.
-
-3.5. Fragment
-
- The fragment identifier component of a URI allows indirect
- identification of a secondary resource by reference to a primary
- resource and additional identifying information. The identified
- secondary resource may be some portion or subset of the primary
- resource, some view on representations of the primary resource, or
- some other resource defined or described by those representations. A
- fragment identifier component is indicated by the presence of a
- number sign ("#") character and terminated by the end of the URI.
-
- fragment = *( pchar / "/" / "?" )
-
- The semantics of a fragment identifier are defined by the set of
- representations that might result from a retrieval action on the
- primary resource. The fragment's format and resolution is therefore
- dependent on the media type [RFC2046] of a potentially retrieved
- representation, even though such a retrieval is only performed if the
- URI is dereferenced. If no such representation exists, then the
- semantics of the fragment are considered unknown and are effectively
- unconstrained. Fragment identifier semantics are independent of the
- URI scheme and thus cannot be redefined by scheme specifications.
-
- Individual media types may define their own restrictions on or
- structures within the fragment identifier syntax for specifying
- different types of subsets, views, or external references that are
- identifiable as secondary resources by that media type. If the
- primary resource has multiple representations, as is often the case
- for resources whose representation is selected based on attributes of
- the retrieval request (a.k.a., content negotiation), then whatever is
- identified by the fragment should be consistent across all of those
- representations. Each representation should either define the
- fragment so that it corresponds to the same secondary resource,
- regardless of how it is represented, or should leave the fragment
- undefined (i.e., not found).
-
-
-
-Berners-Lee, et al. Standards Track [Page 24]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- As with any URI, use of a fragment identifier component does not
- imply that a retrieval action will take place. A URI with a fragment
- identifier may be used to refer to the secondary resource without any
- implication that the primary resource is accessible or will ever be
- accessed.
-
- Fragment identifiers have a special role in information retrieval
- systems as the primary form of client-side indirect referencing,
- allowing an author to specifically identify aspects of an existing
- resource that are only indirectly provided by the resource owner. As
- such, the fragment identifier is not used in the scheme-specific
- processing of a URI; instead, the fragment identifier is separated
- from the rest of the URI prior to a dereference, and thus the
- identifying information within the fragment itself is dereferenced
- solely by the user agent, regardless of the URI scheme. Although
- this separate handling is often perceived to be a loss of
- information, particularly for accurate redirection of references as
- resources move over time, it also serves to prevent information
- providers from denying reference authors the right to refer to
- information within a resource selectively. Indirect referencing also
- provides additional flexibility and extensibility to systems that use
- URIs, as new media types are easier to define and deploy than new
- schemes of identification.
-
- The characters slash ("/") and question mark ("?") are allowed to
- represent data within the fragment identifier. Beware that some
- older, erroneous implementations may not handle this data correctly
- when it is used as the base URI for relative references (Section
- 5.1).
-
-4. Usage
-
- When applications make reference to a URI, they do not always use the
- full form of reference defined by the "URI" syntax rule. To save
- space and take advantage of hierarchical locality, many Internet
- protocol elements and media type formats allow an abbreviation of a
- URI, whereas others restrict the syntax to a particular form of URI.
- We define the most common forms of reference syntax in this
- specification because they impact and depend upon the design of the
- generic syntax, requiring a uniform parsing algorithm in order to be
- interpreted consistently.
-
-4.1. URI Reference
-
- URI-reference is used to denote the most common usage of a resource
- identifier.
-
- URI-reference = URI / relative-ref
-
-
-
-Berners-Lee, et al. Standards Track [Page 25]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- A URI-reference is either a URI or a relative reference. If the
- URI-reference's prefix does not match the syntax of a scheme followed
- by its colon separator, then the URI-reference is a relative
- reference.
-
- A URI-reference is typically parsed first into the five URI
- components, in order to determine what components are present and
- whether the reference is relative. Then, each component is parsed
- for its subparts and their validation. The ABNF of URI-reference,
- along with the "first-match-wins" disambiguation rule, is sufficient
- to define a validating parser for the generic syntax. Readers
- familiar with regular expressions should see Appendix B for an
- example of a non-validating URI-reference parser that will take any
- given string and extract the URI components.
-
-4.2. Relative Reference
-
- A relative reference takes advantage of the hierarchical syntax
- (Section 1.2.3) to express a URI reference relative to the name space
- of another hierarchical URI.
-
- relative-ref = relative-part [ "?" query ] [ "#" fragment ]
-
- relative-part = "//" authority path-abempty
- / path-absolute
- / path-noscheme
- / path-empty
-
- The URI referred to by a relative reference, also known as the target
- URI, is obtained by applying the reference resolution algorithm of
- Section 5.
-
- A relative reference that begins with two slash characters is termed
- a network-path reference; such references are rarely used. A
- relative reference that begins with a single slash character is
- termed an absolute-path reference. A relative reference that does
- not begin with a slash character is termed a relative-path reference.
-
- A path segment that contains a colon character (e.g., "this:that")
- cannot be used as the first segment of a relative-path reference, as
- it would be mistaken for a scheme name. Such a segment must be
- preceded by a dot-segment (e.g., "./this:that") to make a relative-
- path reference.
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 26]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-4.3. Absolute URI
-
- Some protocol elements allow only the absolute form of a URI without
- a fragment identifier. For example, defining a base URI for later
- use by relative references calls for an absolute-URI syntax rule that
- does not allow a fragment.
-
- absolute-URI = scheme ":" hier-part [ "?" query ]
-
- URI scheme specifications must define their own syntax so that all
- strings matching their scheme-specific syntax will also match the
- <absolute-URI> grammar. Scheme specifications will not define
- fragment identifier syntax or usage, regardless of its applicability
- to resources identifiable via that scheme, as fragment identification
- is orthogonal to scheme definition. However, scheme specifications
- are encouraged to include a wide range of examples, including
- examples that show use of the scheme's URIs with fragment identifiers
- when such usage is appropriate.
-
-4.4. Same-Document Reference
-
- When a URI reference refers to a URI that is, aside from its fragment
- component (if any), identical to the base URI (Section 5.1), that
- reference is called a "same-document" reference. The most frequent
- examples of same-document references are relative references that are
- empty or include only the number sign ("#") separator followed by a
- fragment identifier.
-
- When a same-document reference is dereferenced for a retrieval
- action, the target of that reference is defined to be within the same
- entity (representation, document, or message) as the reference;
- therefore, a dereference should not result in a new retrieval action.
-
- Normalization of the base and target URIs prior to their comparison,
- as described in Sections 6.2.2 and 6.2.3, is allowed but rarely
- performed in practice. Normalization may increase the set of same-
- document references, which may be of benefit to some caching
- applications. As such, reference authors should not assume that a
- slightly different, though equivalent, reference URI will (or will
- not) be interpreted as a same-document reference by any given
- application.
-
-4.5. Suffix Reference
-
- The URI syntax is designed for unambiguous reference to resources and
- extensibility via the URI scheme. However, as URI identification and
- usage have become commonplace, traditional media (television, radio,
- newspapers, billboards, etc.) have increasingly used a suffix of the
-
-
-
-Berners-Lee, et al. Standards Track [Page 27]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- URI as a reference, consisting of only the authority and path
- portions of the URI, such as
-
- www.w3.org/Addressing/
-
- or simply a DNS registered name on its own. Such references are
- primarily intended for human interpretation rather than for machines,
- with the assumption that context-based heuristics are sufficient to
- complete the URI (e.g., most registered names beginning with "www"
- are likely to have a URI prefix of "http://"). Although there is no
- standard set of heuristics for disambiguating a URI suffix, many
- client implementations allow them to be entered by the user and
- heuristically resolved.
-
- Although this practice of using suffix references is common, it
- should be avoided whenever possible and should never be used in
- situations where long-term references are expected. The heuristics
- noted above will change over time, particularly when a new URI scheme
- becomes popular, and are often incorrect when used out of context.
- Furthermore, they can lead to security issues along the lines of
- those described in [RFC1535].
-
- As a URI suffix has the same syntax as a relative-path reference, a
- suffix reference cannot be used in contexts where a relative
- reference is expected. As a result, suffix references are limited to
- places where there is no defined base URI, such as dialog boxes and
- off-line advertisements.
-
-5. Reference Resolution
-
- This section defines the process of resolving a URI reference within
- a context that allows relative references so that the result is a
- string matching the <URI> syntax rule of Section 3.
-
-5.1. Establishing a Base URI
-
- The term "relative" implies that a "base URI" exists against which
- the relative reference is applied. Aside from fragment-only
- references (Section 4.4), relative references are only usable when a
- base URI is known. A base URI must be established by the parser
- prior to parsing URI references that might be relative. A base URI
- must conform to the <absolute-URI> syntax rule (Section 4.3). If the
- base URI is obtained from a URI reference, then that reference must
- be converted to absolute form and stripped of any fragment component
- prior to its use as a base URI.
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 28]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- The base URI of a reference can be established in one of four ways,
- discussed below in order of precedence. The order of precedence can
- be thought of in terms of layers, where the innermost defined base
- URI has the highest precedence. This can be visualized graphically
- as follows:
-
- .----------------------------------------------------------.
- | .----------------------------------------------------. |
- | | .----------------------------------------------. | |
- | | | .----------------------------------------. | | |
- | | | | .----------------------------------. | | | |
- | | | | | <relative-reference> | | | | |
- | | | | `----------------------------------' | | | |
- | | | | (5.1.1) Base URI embedded in content | | | |
- | | | `----------------------------------------' | | |
- | | | (5.1.2) Base URI of the encapsulating entity | | |
- | | | (message, representation, or none) | | |
- | | `----------------------------------------------' | |
- | | (5.1.3) URI used to retrieve the entity | |
- | `----------------------------------------------------' |
- | (5.1.4) Default Base URI (application-dependent) |
- `----------------------------------------------------------'
-
-5.1.1. Base URI Embedded in Content
-
- Within certain media types, a base URI for relative references can be
- embedded within the content itself so that it can be readily obtained
- by a parser. This can be useful for descriptive documents, such as
- tables of contents, which may be transmitted to others through
- protocols other than their usual retrieval context (e.g., email or
- USENET news).
-
- It is beyond the scope of this specification to specify how, for each
- media type, a base URI can be embedded. The appropriate syntax, when
- available, is described by the data format specification associated
- with each media type.
-
-5.1.2. Base URI from the Encapsulating Entity
-
- If no base URI is embedded, the base URI is defined by the
- representation's retrieval context. For a document that is enclosed
- within another entity, such as a message or archive, the retrieval
- context is that entity. Thus, the default base URI of a
- representation is the base URI of the entity in which the
- representation is encapsulated.
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 29]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- A mechanism for embedding a base URI within MIME container types
- (e.g., the message and multipart types) is defined by MHTML
- [RFC2557]. Protocols that do not use the MIME message header syntax,
- but that do allow some form of tagged metadata to be included within
- messages, may define their own syntax for defining a base URI as part
- of a message.
-
-5.1.3. Base URI from the Retrieval URI
-
- If no base URI is embedded and the representation is not encapsulated
- within some other entity, then, if a URI was used to retrieve the
- representation, that URI shall be considered the base URI. Note that
- if the retrieval was the result of a redirected request, the last URI
- used (i.e., the URI that resulted in the actual retrieval of the
- representation) is the base URI.
-
-5.1.4. Default Base URI
-
- If none of the conditions described above apply, then the base URI is
- defined by the context of the application. As this definition is
- necessarily application-dependent, failing to define a base URI by
- using one of the other methods may result in the same content being
- interpreted differently by different types of applications.
-
- A sender of a representation containing relative references is
- responsible for ensuring that a base URI for those references can be
- established. Aside from fragment-only references, relative
- references can only be used reliably in situations where the base URI
- is well defined.
-
-5.2. Relative Resolution
-
- This section describes an algorithm for converting a URI reference
- that might be relative to a given base URI into the parsed components
- of the reference's target. The components can then be recomposed, as
- described in Section 5.3, to form the target URI. This algorithm
- provides definitive results that can be used to test the output of
- other implementations. Applications may implement relative reference
- resolution by using some other algorithm, provided that the results
- match what would be given by this one.
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 30]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-5.2.1. Pre-parse the Base URI
-
- The base URI (Base) is established according to the procedure of
- Section 5.1 and parsed into the five main components described in
- Section 3. Note that only the scheme component is required to be
- present in a base URI; the other components may be empty or
- undefined. A component is undefined if its associated delimiter does
- not appear in the URI reference; the path component is never
- undefined, though it may be empty.
-
- Normalization of the base URI, as described in Sections 6.2.2 and
- 6.2.3, is optional. A URI reference must be transformed to its
- target URI before it can be normalized.
-
-5.2.2. Transform References
-
- For each URI reference (R), the following pseudocode describes an
- algorithm for transforming R into its target URI (T):
-
- -- The URI reference is parsed into the five URI components
- --
- (R.scheme, R.authority, R.path, R.query, R.fragment) = parse(R);
-
- -- A non-strict parser may ignore a scheme in the reference
- -- if it is identical to the base URI's scheme.
- --
- if ((not strict) and (R.scheme == Base.scheme)) then
- undefine(R.scheme);
- endif;
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 31]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- if defined(R.scheme) then
- T.scheme = R.scheme;
- T.authority = R.authority;
- T.path = remove_dot_segments(R.path);
- T.query = R.query;
- else
- if defined(R.authority) then
- T.authority = R.authority;
- T.path = remove_dot_segments(R.path);
- T.query = R.query;
- else
- if (R.path == "") then
- T.path = Base.path;
- if defined(R.query) then
- T.query = R.query;
- else
- T.query = Base.query;
- endif;
- else
- if (R.path starts-with "/") then
- T.path = remove_dot_segments(R.path);
- else
- T.path = merge(Base.path, R.path);
- T.path = remove_dot_segments(T.path);
- endif;
- T.query = R.query;
- endif;
- T.authority = Base.authority;
- endif;
- T.scheme = Base.scheme;
- endif;
-
- T.fragment = R.fragment;
-
-5.2.3. Merge Paths
-
- The pseudocode above refers to a "merge" routine for merging a
- relative-path reference with the path of the base URI. This is
- accomplished as follows:
-
- o If the base URI has a defined authority component and an empty
- path, then return a string consisting of "/" concatenated with the
- reference's path; otherwise,
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 32]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- o return a string consisting of the reference's path component
- appended to all but the last segment of the base URI's path (i.e.,
- excluding any characters after the right-most "/" in the base URI
- path, or excluding the entire base URI path if it does not contain
- any "/" characters).
-
-5.2.4. Remove Dot Segments
-
- The pseudocode also refers to a "remove_dot_segments" routine for
- interpreting and removing the special "." and ".." complete path
- segments from a referenced path. This is done after the path is
- extracted from a reference, whether or not the path was relative, in
- order to remove any invalid or extraneous dot-segments prior to
- forming the target URI. Although there are many ways to accomplish
- this removal process, we describe a simple method using two string
- buffers.
-
- 1. The input buffer is initialized with the now-appended path
- components and the output buffer is initialized to the empty
- string.
-
- 2. While the input buffer is not empty, loop as follows:
-
- A. If the input buffer begins with a prefix of "../" or "./",
- then remove that prefix from the input buffer; otherwise,
-
- B. if the input buffer begins with a prefix of "/./" or "/.",
- where "." is a complete path segment, then replace that
- prefix with "/" in the input buffer; otherwise,
-
- C. if the input buffer begins with a prefix of "/../" or "/..",
- where ".." is a complete path segment, then replace that
- prefix with "/" in the input buffer and remove the last
- segment and its preceding "/" (if any) from the output
- buffer; otherwise,
-
- D. if the input buffer consists only of "." or "..", then remove
- that from the input buffer; otherwise,
-
- E. move the first path segment in the input buffer to the end of
- the output buffer, including the initial "/" character (if
- any) and any subsequent characters up to, but not including,
- the next "/" character or the end of the input buffer.
-
- 3. Finally, the output buffer is returned as the result of
- remove_dot_segments.
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 33]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- Note that dot-segments are intended for use in URI references to
- express an identifier relative to the hierarchy of names in the base
- URI. The remove_dot_segments algorithm respects that hierarchy by
- removing extra dot-segments rather than treat them as an error or
- leaving them to be misinterpreted by dereference implementations.
-
- The following illustrates how the above steps are applied for two
- examples of merged paths, showing the state of the two buffers after
- each step.
-
- STEP OUTPUT BUFFER INPUT BUFFER
-
- 1 : /a/b/c/./../../g
- 2E: /a /b/c/./../../g
- 2E: /a/b /c/./../../g
- 2E: /a/b/c /./../../g
- 2B: /a/b/c /../../g
- 2C: /a/b /../g
- 2C: /a /g
- 2E: /a/g
-
- STEP OUTPUT BUFFER INPUT BUFFER
-
- 1 : mid/content=5/../6
- 2E: mid /content=5/../6
- 2E: mid/content=5 /../6
- 2C: mid /6
- 2E: mid/6
-
- Some applications may find it more efficient to implement the
- remove_dot_segments algorithm by using two segment stacks rather than
- strings.
-
- Note: Beware that some older, erroneous implementations will fail
- to separate a reference's query component from its path component
- prior to merging the base and reference paths, resulting in an
- interoperability failure if the query component contains the
- strings "/../" or "/./".
-
-
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 34]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-5.3. Component Recomposition
-
- Parsed URI components can be recomposed to obtain the corresponding
- URI reference string. Using pseudocode, this would be:
-
- result = ""
-
- if defined(scheme) then
- append scheme to result;
- append ":" to result;
- endif;
-
- if defined(authority) then
- append "//" to result;
- append authority to result;
- endif;
-
- append path to result;
-
- if defined(query) then
- append "?" to result;
- append query to result;
- endif;
-
- if defined(fragment) then
- append "#" to result;
- append fragment to result;
- endif;
-
- return result;
-
- Note that we are careful to preserve the distinction between a
- component that is undefined, meaning that its separator was not
- present in the reference, and a component that is empty, meaning that
- the separator was present and was immediately followed by the next
- component separator or the end of the reference.
-
-5.4. Reference Resolution Examples
-
- Within a representation with a well defined base URI of
-
- http://a/b/c/d;p?q
-
- a relative reference is transformed to its target URI as follows.
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 35]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-5.4.1. Normal Examples
-
- "g:h" = "g:h"
- "g" = "http://a/b/c/g"
- "./g" = "http://a/b/c/g"
- "g/" = "http://a/b/c/g/"
- "/g" = "http://a/g"
- "//g" = "http://g"
- "?y" = "http://a/b/c/d;p?y"
- "g?y" = "http://a/b/c/g?y"
- "#s" = "http://a/b/c/d;p?q#s"
- "g#s" = "http://a/b/c/g#s"
- "g?y#s" = "http://a/b/c/g?y#s"
- ";x" = "http://a/b/c/;x"
- "g;x" = "http://a/b/c/g;x"
- "g;x?y#s" = "http://a/b/c/g;x?y#s"
- "" = "http://a/b/c/d;p?q"
- "." = "http://a/b/c/"
- "./" = "http://a/b/c/"
- ".." = "http://a/b/"
- "../" = "http://a/b/"
- "../g" = "http://a/b/g"
- "../.." = "http://a/"
- "../../" = "http://a/"
- "../../g" = "http://a/g"
-
-5.4.2. Abnormal Examples
-
- Although the following abnormal examples are unlikely to occur in
- normal practice, all URI parsers should be capable of resolving them
- consistently. Each example uses the same base as that above.
-
- Parsers must be careful in handling cases where there are more ".."
- segments in a relative-path reference than there are hierarchical
- levels in the base URI's path. Note that the ".." syntax cannot be
- used to change the authority component of a URI.
-
- "../../../g" = "http://a/g"
- "../../../../g" = "http://a/g"
-
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 36]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- Similarly, parsers must remove the dot-segments "." and ".." when
- they are complete components of a path, but not when they are only
- part of a segment.
-
- "/./g" = "http://a/g"
- "/../g" = "http://a/g"
- "g." = "http://a/b/c/g."
- ".g" = "http://a/b/c/.g"
- "g.." = "http://a/b/c/g.."
- "..g" = "http://a/b/c/..g"
-
- Less likely are cases where the relative reference uses unnecessary
- or nonsensical forms of the "." and ".." complete path segments.
-
- "./../g" = "http://a/b/g"
- "./g/." = "http://a/b/c/g/"
- "g/./h" = "http://a/b/c/g/h"
- "g/../h" = "http://a/b/c/h"
- "g;x=1/./y" = "http://a/b/c/g;x=1/y"
- "g;x=1/../y" = "http://a/b/c/y"
-
- Some applications fail to separate the reference's query and/or
- fragment components from the path component before merging it with
- the base path and removing dot-segments. This error is rarely
- noticed, as typical usage of a fragment never includes the hierarchy
- ("/") character and the query component is not normally used within
- relative references.
-
- "g?y/./x" = "http://a/b/c/g?y/./x"
- "g?y/../x" = "http://a/b/c/g?y/../x"
- "g#s/./x" = "http://a/b/c/g#s/./x"
- "g#s/../x" = "http://a/b/c/g#s/../x"
-
- Some parsers allow the scheme name to be present in a relative
- reference if it is the same as the base URI scheme. This is
- considered to be a loophole in prior specifications of partial URI
- [RFC1630]. Its use should be avoided but is allowed for backward
- compatibility.
-
- "http:g" = "http:g" ; for strict parsers
- / "http://a/b/c/g" ; for backward compatibility
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 37]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-6. Normalization and Comparison
-
- One of the most common operations on URIs is simple comparison:
- determining whether two URIs are equivalent without using the URIs to
- access their respective resource(s). A comparison is performed every
- time a response cache is accessed, a browser checks its history to
- color a link, or an XML parser processes tags within a namespace.
- Extensive normalization prior to comparison of URIs is often used by
- spiders and indexing engines to prune a search space or to reduce
- duplication of request actions and response storage.
-
- URI comparison is performed for some particular purpose. Protocols
- or implementations that compare URIs for different purposes will
- often be subject to differing design trade-offs in regards to how
- much effort should be spent in reducing aliased identifiers. This
- section describes various methods that may be used to compare URIs,
- the trade-offs between them, and the types of applications that might
- use them.
-
-6.1. Equivalence
-
- Because URIs exist to identify resources, presumably they should be
- considered equivalent when they identify the same resource. However,
- this definition of equivalence is not of much practical use, as there
- is no way for an implementation to compare two resources unless it
- has full knowledge or control of them. For this reason,
- determination of equivalence or difference of URIs is based on string
- comparison, perhaps augmented by reference to additional rules
- provided by URI scheme definitions. We use the terms "different" and
- "equivalent" to describe the possible outcomes of such comparisons,
- but there are many application-dependent versions of equivalence.
-
- Even though it is possible to determine that two URIs are equivalent,
- URI comparison is not sufficient to determine whether two URIs
- identify different resources. For example, an owner of two different
- domain names could decide to serve the same resource from both,
- resulting in two different URIs. Therefore, comparison methods are
- designed to minimize false negatives while strictly avoiding false
- positives.
-
- In testing for equivalence, applications should not directly compare
- relative references; the references should be converted to their
- respective target URIs before comparison. When URIs are compared to
- select (or avoid) a network action, such as retrieval of a
- representation, fragment components (if any) should be excluded from
- the comparison.
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 38]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-6.2. Comparison Ladder
-
- A variety of methods are used in practice to test URI equivalence.
- These methods fall into a range, distinguished by the amount of
- processing required and the degree to which the probability of false
- negatives is reduced. As noted above, false negatives cannot be
- eliminated. In practice, their probability can be reduced, but this
- reduction requires more processing and is not cost-effective for all
- applications.
-
- If this range of comparison practices is considered as a ladder, the
- following discussion will climb the ladder, starting with practices
- that are cheap but have a relatively higher chance of producing false
- negatives, and proceeding to those that have higher computational
- cost and lower risk of false negatives.
-
-6.2.1. Simple String Comparison
-
- If two URIs, when considered as character strings, are identical,
- then it is safe to conclude that they are equivalent. This type of
- equivalence test has very low computational cost and is in wide use
- in a variety of applications, particularly in the domain of parsing.
-
- Testing strings for equivalence requires some basic precautions.
- This procedure is often referred to as "bit-for-bit" or
- "byte-for-byte" comparison, which is potentially misleading. Testing
- strings for equality is normally based on pair comparison of the
- characters that make up the strings, starting from the first and
- proceeding until both strings are exhausted and all characters are
- found to be equal, until a pair of characters compares unequal, or
- until one of the strings is exhausted before the other.
-
- This character comparison requires that each pair of characters be
- put in comparable form. For example, should one URI be stored in a
- byte array in EBCDIC encoding and the second in a Java String object
- (UTF-16), bit-for-bit comparisons applied naively will produce
- errors. It is better to speak of equality on a character-for-
- character basis rather than on a byte-for-byte or bit-for-bit basis.
- In practical terms, character-by-character comparisons should be done
- codepoint-by-codepoint after conversion to a common character
- encoding.
-
- False negatives are caused by the production and use of URI aliases.
- Unnecessary aliases can be reduced, regardless of the comparison
- method, by consistently providing URI references in an already-
- normalized form (i.e., a form identical to what would be produced
- after normalization is applied, as described below).
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 39]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- Protocols and data formats often limit some URI comparisons to simple
- string comparison, based on the theory that people and
- implementations will, in their own best interest, be consistent in
- providing URI references, or at least consistent enough to negate any
- efficiency that might be obtained from further normalization.
-
-6.2.2. Syntax-Based Normalization
-
- Implementations may use logic based on the definitions provided by
- this specification to reduce the probability of false negatives.
- This processing is moderately higher in cost than character-for-
- character string comparison. For example, an application using this
- approach could reasonably consider the following two URIs equivalent:
-
- example://a/b/c/%7Bfoo%7D
- eXAMPLE://a/./b/../b/%63/%7bfoo%7d
-
- Web user agents, such as browsers, typically apply this type of URI
- normalization when determining whether a cached response is
- available. Syntax-based normalization includes such techniques as
- case normalization, percent-encoding normalization, and removal of
- dot-segments.
-
-6.2.2.1. Case Normalization
-
- For all URIs, the hexadecimal digits within a percent-encoding
- triplet (e.g., "%3a" versus "%3A") are case-insensitive and therefore
- should be normalized to use uppercase letters for the digits A-F.
-
- When a URI uses components of the generic syntax, the component
- syntax equivalence rules always apply; namely, that the scheme and
- host are case-insensitive and therefore should be normalized to
- lowercase. For example, the URI <HTTP://www.EXAMPLE.com/> is
- equivalent to <http://www.example.com/>. The other generic syntax
- components are assumed to be case-sensitive unless specifically
- defined otherwise by the scheme (see Section 6.2.3).
-
-6.2.2.2. Percent-Encoding Normalization
-
- The percent-encoding mechanism (Section 2.1) is a frequent source of
- variance among otherwise identical URIs. In addition to the case
- normalization issue noted above, some URI producers percent-encode
- octets that do not require percent-encoding, resulting in URIs that
- are equivalent to their non-encoded counterparts. These URIs should
- be normalized by decoding any percent-encoded octet that corresponds
- to an unreserved character, as described in Section 2.3.
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 40]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-6.2.2.3. Path Segment Normalization
-
- The complete path segments "." and ".." are intended only for use
- within relative references (Section 4.1) and are removed as part of
- the reference resolution process (Section 5.2). However, some
- deployed implementations incorrectly assume that reference resolution
- is not necessary when the reference is already a URI and thus fail to
- remove dot-segments when they occur in non-relative paths. URI
- normalizers should remove dot-segments by applying the
- remove_dot_segments algorithm to the path, as described in
- Section 5.2.4.
-
-6.2.3. Scheme-Based Normalization
-
- The syntax and semantics of URIs vary from scheme to scheme, as
- described by the defining specification for each scheme.
- Implementations may use scheme-specific rules, at further processing
- cost, to reduce the probability of false negatives. For example,
- because the "http" scheme makes use of an authority component, has a
- default port of "80", and defines an empty path to be equivalent to
- "/", the following four URIs are equivalent:
-
- http://example.com
- http://example.com/
- http://example.com:/
- http://example.com:80/
-
- In general, a URI that uses the generic syntax for authority with an
- empty path should be normalized to a path of "/". Likewise, an
- explicit ":port", for which the port is empty or the default for the
- scheme, is equivalent to one where the port and its ":" delimiter are
- elided and thus should be removed by scheme-based normalization. For
- example, the second URI above is the normal form for the "http"
- scheme.
-
- Another case where normalization varies by scheme is in the handling
- of an empty authority component or empty host subcomponent. For many
- scheme specifications, an empty authority or host is considered an
- error; for others, it is considered equivalent to "localhost" or the
- end-user's host. When a scheme defines a default for authority and a
- URI reference to that default is desired, the reference should be
- normalized to an empty authority for the sake of uniformity, brevity,
- and internationalization. If, however, either the userinfo or port
- subcomponents are non-empty, then the host should be given explicitly
- even if it matches the default.
-
- Normalization should not remove delimiters when their associated
- component is empty unless licensed to do so by the scheme
-
-
-
-Berners-Lee, et al. Standards Track [Page 41]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- specification. For example, the URI "http://example.com/?" cannot be
- assumed to be equivalent to any of the examples above. Likewise, the
- presence or absence of delimiters within a userinfo subcomponent is
- usually significant to its interpretation. The fragment component is
- not subject to any scheme-based normalization; thus, two URIs that
- differ only by the suffix "#" are considered different regardless of
- the scheme.
-
- Some schemes define additional subcomponents that consist of case-
- insensitive data, giving an implicit license to normalizers to
- convert this data to a common case (e.g., all lowercase). For
- example, URI schemes that define a subcomponent of path to contain an
- Internet hostname, such as the "mailto" URI scheme, cause that
- subcomponent to be case-insensitive and thus subject to case
- normalization (e.g., "mailto:Joe@Example.COM" is equivalent to
- "mailto:Joe@example.com", even though the generic syntax considers
- the path component to be case-sensitive).
-
- Other scheme-specific normalizations are possible.
-
-6.2.4. Protocol-Based Normalization
-
- Substantial effort to reduce the incidence of false negatives is
- often cost-effective for web spiders. Therefore, they implement even
- more aggressive techniques in URI comparison. For example, if they
- observe that a URI such as
-
- http://example.com/data
-
- redirects to a URI differing only in the trailing slash
-
- http://example.com/data/
-
- they will likely regard the two as equivalent in the future. This
- kind of technique is only appropriate when equivalence is clearly
- indicated by both the result of accessing the resources and the
- common conventions of their scheme's dereference algorithm (in this
- case, use of redirection by HTTP origin servers to avoid problems
- with relative references).
-
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 42]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-7. Security Considerations
-
- A URI does not in itself pose a security threat. However, as URIs
- are often used to provide a compact set of instructions for access to
- network resources, care must be taken to properly interpret the data
- within a URI, to prevent that data from causing unintended access,
- and to avoid including data that should not be revealed in plain
- text.
-
-7.1. Reliability and Consistency
-
- There is no guarantee that once a URI has been used to retrieve
- information, the same information will be retrievable by that URI in
- the future. Nor is there any guarantee that the information
- retrievable via that URI in the future will be observably similar to
- that retrieved in the past. The URI syntax does not constrain how a
- given scheme or authority apportions its namespace or maintains it
- over time. Such guarantees can only be obtained from the person(s)
- controlling that namespace and the resource in question. A specific
- URI scheme may define additional semantics, such as name persistence,
- if those semantics are required of all naming authorities for that
- scheme.
-
-7.2. Malicious Construction
-
- It is sometimes possible to construct a URI so that an attempt to
- perform a seemingly harmless, idempotent operation, such as the
- retrieval of a representation, will in fact cause a possibly damaging
- remote operation. The unsafe URI is typically constructed by
- specifying a port number other than that reserved for the network
- protocol in question. The client unwittingly contacts a site running
- a different protocol service, and data within the URI contains
- instructions that, when interpreted according to this other protocol,
- cause an unexpected operation. A frequent example of such abuse has
- been the use of a protocol-based scheme with a port component of
- "25", thereby fooling user agent software into sending an unintended
- or impersonating message via an SMTP server.
-
- Applications should prevent dereference of a URI that specifies a TCP
- port number within the "well-known port" range (0 - 1023) unless the
- protocol being used to dereference that URI is compatible with the
- protocol expected on that well-known port. Although IANA maintains a
- registry of well-known ports, applications should make such
- restrictions user-configurable to avoid preventing the deployment of
- new services.
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 43]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- When a URI contains percent-encoded octets that match the delimiters
- for a given resolution or dereference protocol (for example, CR and
- LF characters for the TELNET protocol), these percent-encodings must
- not be decoded before transmission across that protocol. Transfer of
- the percent-encoding, which might violate the protocol, is less
- harmful than allowing decoded octets to be interpreted as additional
- operations or parameters, perhaps triggering an unexpected and
- possibly harmful remote operation.
-
-7.3. Back-End Transcoding
-
- When a URI is dereferenced, the data within it is often parsed by
- both the user agent and one or more servers. In HTTP, for example, a
- typical user agent will parse a URI into its five major components,
- access the authority's server, and send it the data within the
- authority, path, and query components. A typical server will take
- that information, parse the path into segments and the query into
- key/value pairs, and then invoke implementation-specific handlers to
- respond to the request. As a result, a common security concern for
- server implementations that handle a URI, either as a whole or split
- into separate components, is proper interpretation of the octet data
- represented by the characters and percent-encodings within that URI.
-
- Percent-encoded octets must be decoded at some point during the
- dereference process. Applications must split the URI into its
- components and subcomponents prior to decoding the octets, as
- otherwise the decoded octets might be mistaken for delimiters.
- Security checks of the data within a URI should be applied after
- decoding the octets. Note, however, that the "%00" percent-encoding
- (NUL) may require special handling and should be rejected if the
- application is not expecting to receive raw data within a component.
-
- Special care should be taken when the URI path interpretation process
- involves the use of a back-end file system or related system
- functions. File systems typically assign an operational meaning to
- special characters, such as the "/", "\", ":", "[", and "]"
- characters, and to special device names like ".", "..", "...", "aux",
- "lpt", etc. In some cases, merely testing for the existence of such
- a name will cause the operating system to pause or invoke unrelated
- system calls, leading to significant security concerns regarding
- denial of service and unintended data transfer. It would be
- impossible for this specification to list all such significant
- characters and device names. Implementers should research the
- reserved names and characters for the types of storage device that
- may be attached to their applications and restrict the use of data
- obtained from URI components accordingly.
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 44]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-7.4. Rare IP Address Formats
-
- Although the URI syntax for IPv4address only allows the common
- dotted-decimal form of IPv4 address literal, many implementations
- that process URIs make use of platform-dependent system routines,
- such as gethostbyname() and inet_aton(), to translate the string
- literal to an actual IP address. Unfortunately, such system routines
- often allow and process a much larger set of formats than those
- described in Section 3.2.2.
-
- For example, many implementations allow dotted forms of three
- numbers, wherein the last part is interpreted as a 16-bit quantity
- and placed in the right-most two bytes of the network address (e.g.,
- a Class B network). Likewise, a dotted form of two numbers means
- that the last part is interpreted as a 24-bit quantity and placed in
- the right-most three bytes of the network address (Class A), and a
- single number (without dots) is interpreted as a 32-bit quantity and
- stored directly in the network address. Adding further to the
- confusion, some implementations allow each dotted part to be
- interpreted as decimal, octal, or hexadecimal, as specified in the C
- language (i.e., a leading 0x or 0X implies hexadecimal; a leading 0
- implies octal; otherwise, the number is interpreted as decimal).
-
- These additional IP address formats are not allowed in the URI syntax
- due to differences between platform implementations. However, they
- can become a security concern if an application attempts to filter
- access to resources based on the IP address in string literal format.
- If this filtering is performed, literals should be converted to
- numeric form and filtered based on the numeric value, and not on a
- prefix or suffix of the string form.
-
-7.5. Sensitive Information
-
- URI producers should not provide a URI that contains a username or
- password that is intended to be secret. URIs are frequently
- displayed by browsers, stored in clear text bookmarks, and logged by
- user agent history and intermediary applications (proxies). A
- password appearing within the userinfo component is deprecated and
- should be considered an error (or simply ignored) except in those
- rare cases where the 'password' parameter is intended to be public.
-
-7.6. Semantic Attacks
-
- Because the userinfo subcomponent is rarely used and appears before
- the host in the authority component, it can be used to construct a
- URI intended to mislead a human user by appearing to identify one
- (trusted) naming authority while actually identifying a different
- authority hidden behind the noise. For example
-
-
-
-Berners-Lee, et al. Standards Track [Page 45]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- ftp://cnn.example.com&story=breaking_news@10.0.0.1/top_story.htm
-
- might lead a human user to assume that the host is 'cnn.example.com',
- whereas it is actually '10.0.0.1'. Note that a misleading userinfo
- subcomponent could be much longer than the example above.
-
- A misleading URI, such as that above, is an attack on the user's
- preconceived notions about the meaning of a URI rather than an attack
- on the software itself. User agents may be able to reduce the impact
- of such attacks by distinguishing the various components of the URI
- when they are rendered, such as by using a different color or tone to
- render userinfo if any is present, though there is no panacea. More
- information on URI-based semantic attacks can be found in [Siedzik].
-
-8. IANA Considerations
-
- URI scheme names, as defined by <scheme> in Section 3.1, form a
- registered namespace that is managed by IANA according to the
- procedures defined in [BCP35]. No IANA actions are required by this
- document.
-
-9. Acknowledgements
-
- This specification is derived from RFC 2396 [RFC2396], RFC 1808
- [RFC1808], and RFC 1738 [RFC1738]; the acknowledgements in those
- documents still apply. It also incorporates the update (with
- corrections) for IPv6 literals in the host syntax, as defined by
- Robert M. Hinden, Brian E. Carpenter, and Larry Masinter in
- [RFC2732]. In addition, contributions by Gisle Aas, Reese Anschultz,
- Daniel Barclay, Tim Bray, Mike Brown, Rob Cameron, Jeremy Carroll,
- Dan Connolly, Adam M. Costello, John Cowan, Jason Diamond, Martin
- Duerst, Stefan Eissing, Clive D.W. Feather, Al Gilman, Tony Hammond,
- Elliotte Harold, Pat Hayes, Henry Holtzman, Ian B. Jacobs, Michael
- Kay, John C. Klensin, Graham Klyne, Dan Kohn, Bruce Lilly, Andrew
- Main, Dave McAlpin, Ira McDonald, Michael Mealling, Ray Merkert,
- Stephen Pollei, Julian Reschke, Tomas Rokicki, Miles Sabin, Kai
- Schaetzl, Mark Thomson, Ronald Tschalaer, Norm Walsh, Marc Warne,
- Stuart Williams, and Henry Zongaro are gratefully acknowledged.
-
-10. References
-
-10.1. Normative References
-
- [ASCII] American National Standards Institute, "Coded Character
- Set -- 7-bit American Standard Code for Information
- Interchange", ANSI X3.4, 1986.
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 46]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", RFC 2234, November 1997.
-
- [STD63] Yergeau, F., "UTF-8, a transformation format of
- ISO 10646", STD 63, RFC 3629, November 2003.
-
- [UCS] International Organization for Standardization,
- "Information Technology - Universal Multiple-Octet Coded
- Character Set (UCS)", ISO/IEC 10646:2003, December 2003.
-
-10.2. Informative References
-
- [BCP19] Freed, N. and J. Postel, "IANA Charset Registration
- Procedures", BCP 19, RFC 2978, October 2000.
-
- [BCP35] Petke, R. and I. King, "Registration Procedures for URL
- Scheme Names", BCP 35, RFC 2717, November 1999.
-
- [RFC0952] Harrenstien, K., Stahl, M., and E. Feinler, "DoD Internet
- host table specification", RFC 952, October 1985.
-
- [RFC1034] Mockapetris, P., "Domain names - concepts and facilities",
- STD 13, RFC 1034, November 1987.
-
- [RFC1123] Braden, R., "Requirements for Internet Hosts - Application
- and Support", STD 3, RFC 1123, October 1989.
-
- [RFC1535] Gavron, E., "A Security Problem and Proposed Correction
- With Widely Deployed DNS Software", RFC 1535,
- October 1993.
-
- [RFC1630] Berners-Lee, T., "Universal Resource Identifiers in WWW: A
- Unifying Syntax for the Expression of Names and Addresses
- of Objects on the Network as used in the World-Wide Web",
- RFC 1630, June 1994.
-
- [RFC1736] Kunze, J., "Functional Recommendations for Internet
- Resource Locators", RFC 1736, February 1995.
-
- [RFC1737] Sollins, K. and L. Masinter, "Functional Requirements for
- Uniform Resource Names", RFC 1737, December 1994.
-
- [RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform
- Resource Locators (URL)", RFC 1738, December 1994.
-
- [RFC1808] Fielding, R., "Relative Uniform Resource Locators",
- RFC 1808, June 1995.
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 47]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part Two: Media Types", RFC 2046,
- November 1996.
-
- [RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997.
-
- [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
- Resource Identifiers (URI): Generic Syntax", RFC 2396,
- August 1998.
-
- [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D.
- Jensen, "HTTP Extensions for Distributed Authoring --
- WEBDAV", RFC 2518, February 1999.
-
- [RFC2557] Palme, J., Hopmann, A., and N. Shelness, "MIME
- Encapsulation of Aggregate Documents, such as HTML
- (MHTML)", RFC 2557, March 1999.
-
- [RFC2718] Masinter, L., Alvestrand, H., Zigmond, D., and R. Petke,
- "Guidelines for new URL Schemes", RFC 2718, November 1999.
-
- [RFC2732] Hinden, R., Carpenter, B., and L. Masinter, "Format for
- Literal IPv6 Addresses in URL's", RFC 2732, December 1999.
-
- [RFC3305] Mealling, M. and R. Denenberg, "Report from the Joint
- W3C/IETF URI Planning Interest Group: Uniform Resource
- Identifiers (URIs), URLs, and Uniform Resource Names
- (URNs): Clarifications and Recommendations", RFC 3305,
- August 2002.
-
- [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello,
- "Internationalizing Domain Names in Applications (IDNA)",
- RFC 3490, March 2003.
-
- [RFC3513] Hinden, R. and S. Deering, "Internet Protocol Version 6
- (IPv6) Addressing Architecture", RFC 3513, April 2003.
-
- [Siedzik] Siedzik, R., "Semantic Attacks: What's in a URL?",
- April 2001, <http://www.giac.org/practical/gsec/
- Richard_Siedzik_GSEC.pdf>.
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 48]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-Appendix A. Collected ABNF for URI
-
- URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
-
- hier-part = "//" authority path-abempty
- / path-absolute
- / path-rootless
- / path-empty
-
- URI-reference = URI / relative-ref
-
- absolute-URI = scheme ":" hier-part [ "?" query ]
-
- relative-ref = relative-part [ "?" query ] [ "#" fragment ]
-
- relative-part = "//" authority path-abempty
- / path-absolute
- / path-noscheme
- / path-empty
-
- scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
-
- authority = [ userinfo "@" ] host [ ":" port ]
- userinfo = *( unreserved / pct-encoded / sub-delims / ":" )
- host = IP-literal / IPv4address / reg-name
- port = *DIGIT
-
- IP-literal = "[" ( IPv6address / IPvFuture ) "]"
-
- IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )
-
- IPv6address = 6( h16 ":" ) ls32
- / "::" 5( h16 ":" ) ls32
- / [ h16 ] "::" 4( h16 ":" ) ls32
- / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
- / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
- / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32
- / [ *4( h16 ":" ) h16 ] "::" ls32
- / [ *5( h16 ":" ) h16 ] "::" h16
- / [ *6( h16 ":" ) h16 ] "::"
-
- h16 = 1*4HEXDIG
- ls32 = ( h16 ":" h16 ) / IPv4address
- IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 49]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- dec-octet = DIGIT ; 0-9
- / %x31-39 DIGIT ; 10-99
- / "1" 2DIGIT ; 100-199
- / "2" %x30-34 DIGIT ; 200-249
- / "25" %x30-35 ; 250-255
-
- reg-name = *( unreserved / pct-encoded / sub-delims )
-
- path = path-abempty ; begins with "/" or is empty
- / path-absolute ; begins with "/" but not "//"
- / path-noscheme ; begins with a non-colon segment
- / path-rootless ; begins with a segment
- / path-empty ; zero characters
-
- path-abempty = *( "/" segment )
- path-absolute = "/" [ segment-nz *( "/" segment ) ]
- path-noscheme = segment-nz-nc *( "/" segment )
- path-rootless = segment-nz *( "/" segment )
- path-empty = 0<pchar>
-
- segment = *pchar
- segment-nz = 1*pchar
- segment-nz-nc = 1*( unreserved / pct-encoded / sub-delims / "@" )
- ; non-zero-length segment without any colon ":"
-
- pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
-
- query = *( pchar / "/" / "?" )
-
- fragment = *( pchar / "/" / "?" )
-
- pct-encoded = "%" HEXDIG HEXDIG
-
- unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
- reserved = gen-delims / sub-delims
- gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@"
- sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
- / "*" / "+" / "," / ";" / "="
-
-Appendix B. Parsing a URI Reference with a Regular Expression
-
- As the "first-match-wins" algorithm is identical to the "greedy"
- disambiguation method used by POSIX regular expressions, it is
- natural and commonplace to use a regular expression for parsing the
- potential five components of a URI reference.
-
- The following line is the regular expression for breaking-down a
- well-formed URI reference into its components.
-
-
-
-Berners-Lee, et al. Standards Track [Page 50]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- ^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?
- 12 3 4 5 6 7 8 9
-
- The numbers in the second line above are only to assist readability;
- they indicate the reference points for each subexpression (i.e., each
- paired parenthesis). We refer to the value matched for subexpression
- <n> as $<n>. For example, matching the above expression to
-
- http://www.ics.uci.edu/pub/ietf/uri/#Related
-
- results in the following subexpression matches:
-
- $1 = http:
- $2 = http
- $3 = //www.ics.uci.edu
- $4 = www.ics.uci.edu
- $5 = /pub/ietf/uri/
- $6 = <undefined>
- $7 = <undefined>
- $8 = #Related
- $9 = Related
-
- where <undefined> indicates that the component is not present, as is
- the case for the query component in the above example. Therefore, we
- can determine the value of the five components as
-
- scheme = $2
- authority = $4
- path = $5
- query = $7
- fragment = $9
-
- Going in the opposite direction, we can recreate a URI reference from
- its components by using the algorithm of Section 5.3.
-
-Appendix C. Delimiting a URI in Context
-
- URIs are often transmitted through formats that do not provide a
- clear context for their interpretation. For example, there are many
- occasions when a URI is included in plain text; examples include text
- sent in email, USENET news, and on printed paper. In such cases, it
- is important to be able to delimit the URI from the rest of the text,
- and in particular from punctuation marks that might be mistaken for
- part of the URI.
-
- In practice, URIs are delimited in a variety of ways, but usually
- within double-quotes "http://example.com/", angle brackets
- <http://example.com/>, or just by using whitespace:
-
-
-
-Berners-Lee, et al. Standards Track [Page 51]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- http://example.com/
-
- These wrappers do not form part of the URI.
-
- In some cases, extra whitespace (spaces, line-breaks, tabs, etc.) may
- have to be added to break a long URI across lines. The whitespace
- should be ignored when the URI is extracted.
-
- No whitespace should be introduced after a hyphen ("-") character.
- Because some typesetters and printers may (erroneously) introduce a
- hyphen at the end of line when breaking it, the interpreter of a URI
- containing a line break immediately after a hyphen should ignore all
- whitespace around the line break and should be aware that the hyphen
- may or may not actually be part of the URI.
-
- Using <> angle brackets around each URI is especially recommended as
- a delimiting style for a reference that contains embedded whitespace.
-
- The prefix "URL:" (with or without a trailing space) was formerly
- recommended as a way to help distinguish a URI from other bracketed
- designators, though it is not commonly used in practice and is no
- longer recommended.
-
- For robustness, software that accepts user-typed URI should attempt
- to recognize and strip both delimiters and embedded whitespace.
-
- For example, the text
-
- Yes, Jim, I found it under "http://www.w3.org/Addressing/",
- but you can probably pick it up from <ftp://foo.example.
- com/rfc/>. Note the warning in <http://www.ics.uci.edu/pub/
- ietf/uri/historical.html#WARNING>.
-
- contains the URI references
-
- http://www.w3.org/Addressing/
- ftp://foo.example.com/rfc/
- http://www.ics.uci.edu/pub/ietf/uri/historical.html#WARNING
-
-
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 52]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-Appendix D. Changes from RFC 2396
-
-D.1. Additions
-
- An ABNF rule for URI has been introduced to correspond to one common
- usage of the term: an absolute URI with optional fragment.
-
- IPv6 (and later) literals have been added to the list of possible
- identifiers for the host portion of an authority component, as
- described by [RFC2732], with the addition of "[" and "]" to the
- reserved set and a version flag to anticipate future versions of IP
- literals. Square brackets are now specified as reserved within the
- authority component and are not allowed outside their use as
- delimiters for an IP literal within host. In order to make this
- change without changing the technical definition of the path, query,
- and fragment components, those rules were redefined to directly
- specify the characters allowed.
-
- As [RFC2732] defers to [RFC3513] for definition of an IPv6 literal
- address, which, unfortunately, lacks an ABNF description of
- IPv6address, we created a new ABNF rule for IPv6address that matches
- the text representations defined by Section 2.2 of [RFC3513].
- Likewise, the definition of IPv4address has been improved in order to
- limit each decimal octet to the range 0-255.
-
- Section 6, on URI normalization and comparison, has been completely
- rewritten and extended by using input from Tim Bray and discussion
- within the W3C Technical Architecture Group.
-
-D.2. Modifications
-
- The ad-hoc BNF syntax of RFC 2396 has been replaced with the ABNF of
- [RFC2234]. This change required all rule names that formerly
- included underscore characters to be renamed with a dash instead. In
- addition, a number of syntax rules have been eliminated or simplified
- to make the overall grammar more comprehensible. Specifications that
- refer to the obsolete grammar rules may be understood by replacing
- those rules according to the following table:
-
-
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 53]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- +----------------+--------------------------------------------------+
- | obsolete rule | translation |
- +----------------+--------------------------------------------------+
- | absoluteURI | absolute-URI |
- | relativeURI | relative-part [ "?" query ] |
- | hier_part | ( "//" authority path-abempty / |
- | | path-absolute ) [ "?" query ] |
- | | |
- | opaque_part | path-rootless [ "?" query ] |
- | net_path | "//" authority path-abempty |
- | abs_path | path-absolute |
- | rel_path | path-rootless |
- | rel_segment | segment-nz-nc |
- | reg_name | reg-name |
- | server | authority |
- | hostport | host [ ":" port ] |
- | hostname | reg-name |
- | path_segments | path-abempty |
- | param | *<pchar excluding ";"> |
- | | |
- | uric | unreserved / pct-encoded / ";" / "?" / ":" |
- | | / "@" / "&" / "=" / "+" / "$" / "," / "/" |
- | | |
- | uric_no_slash | unreserved / pct-encoded / ";" / "?" / ":" |
- | | / "@" / "&" / "=" / "+" / "$" / "," |
- | | |
- | mark | "-" / "_" / "." / "!" / "~" / "*" / "'" |
- | | / "(" / ")" |
- | | |
- | escaped | pct-encoded |
- | hex | HEXDIG |
- | alphanum | ALPHA / DIGIT |
- +----------------+--------------------------------------------------+
-
- Use of the above obsolete rules for the definition of scheme-specific
- syntax is deprecated.
-
- Section 2, on characters, has been rewritten to explain what
- characters are reserved, when they are reserved, and why they are
- reserved, even when they are not used as delimiters by the generic
- syntax. The mark characters that are typically unsafe to decode,
- including the exclamation mark ("!"), asterisk ("*"), single-quote
- ("'"), and open and close parentheses ("(" and ")"), have been moved
- to the reserved set in order to clarify the distinction between
- reserved and unreserved and, hopefully, to answer the most common
- question of scheme designers. Likewise, the section on
- percent-encoded characters has been rewritten, and URI normalizers
- are now given license to decode any percent-encoded octets
-
-
-
-Berners-Lee, et al. Standards Track [Page 54]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- corresponding to unreserved characters. In general, the terms
- "escaped" and "unescaped" have been replaced with "percent-encoded"
- and "decoded", respectively, to reduce confusion with other forms of
- escape mechanisms.
-
- The ABNF for URI and URI-reference has been redesigned to make them
- more friendly to LALR parsers and to reduce complexity. As a result,
- the layout form of syntax description has been removed, along with
- the uric, uric_no_slash, opaque_part, net_path, abs_path, rel_path,
- path_segments, rel_segment, and mark rules. All references to
- "opaque" URIs have been replaced with a better description of how the
- path component may be opaque to hierarchy. The relativeURI rule has
- been replaced with relative-ref to avoid unnecessary confusion over
- whether they are a subset of URI. The ambiguity regarding the
- parsing of URI-reference as a URI or a relative-ref with a colon in
- the first segment has been eliminated through the use of five
- separate path matching rules.
-
- The fragment identifier has been moved back into the section on
- generic syntax components and within the URI and relative-ref rules,
- though it remains excluded from absolute-URI. The number sign ("#")
- character has been moved back to the reserved set as a result of
- reintegrating the fragment syntax.
-
- The ABNF has been corrected to allow the path component to be empty.
- This also allows an absolute-URI to consist of nothing after the
- "scheme:", as is present in practice with the "dav:" namespace
- [RFC2518] and with the "about:" scheme used internally by many WWW
- browser implementations. The ambiguity regarding the boundary
- between authority and path has been eliminated through the use of
- five separate path matching rules.
-
- Registry-based naming authorities that use the generic syntax are now
- defined within the host rule. This change allows current
- implementations, where whatever name provided is simply fed to the
- local name resolution mechanism, to be consistent with the
- specification. It also removes the need to re-specify DNS name
- formats here. Furthermore, it allows the host component to contain
- percent-encoded octets, which is necessary to enable
- internationalized domain names to be provided in URIs, processed in
- their native character encodings at the application layers above URI
- processing, and passed to an IDNA library as a registered name in the
- UTF-8 character encoding. The server, hostport, hostname,
- domainlabel, toplabel, and alphanum rules have been removed.
-
- The resolving relative references algorithm of [RFC2396] has been
- rewritten with pseudocode for this revision to improve clarity and
- fix the following issues:
-
-
-
-Berners-Lee, et al. Standards Track [Page 55]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- o [RFC2396] section 5.2, step 6a, failed to account for a base URI
- with no path.
-
- o Restored the behavior of [RFC1808] where, if the reference
- contains an empty path and a defined query component, the target
- URI inherits the base URI's path component.
-
- o The determination of whether a URI reference is a same-document
- reference has been decoupled from the URI parser, simplifying the
- URI processing interface within applications in a way consistent
- with the internal architecture of deployed URI processing
- implementations. The determination is now based on comparison to
- the base URI after transforming a reference to absolute form,
- rather than on the format of the reference itself. This change
- may result in more references being considered "same-document"
- under this specification than there would be under the rules given
- in RFC 2396, especially when normalization is used to reduce
- aliases. However, it does not change the status of existing
- same-document references.
-
- o Separated the path merge routine into two routines: merge, for
- describing combination of the base URI path with a relative-path
- reference, and remove_dot_segments, for describing how to remove
- the special "." and ".." segments from a composed path. The
- remove_dot_segments algorithm is now applied to all URI reference
- paths in order to match common implementations and to improve the
- normalization of URIs in practice. This change only impacts the
- parsing of abnormal references and same-scheme references wherein
- the base URI has a non-hierarchical path.
-
-Index
-
- A
- ABNF 11
- absolute 27
- absolute-path 26
- absolute-URI 27
- access 9
- authority 17, 18
-
- B
- base URI 28
-
- C
- character encoding 4
- character 4
- characters 8, 11
- coded character set 4
-
-
-
-Berners-Lee, et al. Standards Track [Page 56]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- D
- dec-octet 20
- dereference 9
- dot-segments 23
-
- F
- fragment 16, 24
-
- G
- gen-delims 13
- generic syntax 6
-
- H
- h16 20
- hier-part 16
- hierarchical 10
- host 18
-
- I
- identifier 5
- IP-literal 19
- IPv4 20
- IPv4address 19, 20
- IPv6 19
- IPv6address 19, 20
- IPvFuture 19
-
- L
- locator 7
- ls32 20
-
- M
- merge 32
-
- N
- name 7
- network-path 26
-
- P
- path 16, 22, 26
- path-abempty 22
- path-absolute 22
- path-empty 22
- path-noscheme 22
- path-rootless 22
- path-abempty 16, 22, 26
- path-absolute 16, 22, 26
- path-empty 16, 22, 26
-
-
-
-Berners-Lee, et al. Standards Track [Page 57]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- path-rootless 16, 22
- pchar 23
- pct-encoded 12
- percent-encoding 12
- port 22
-
- Q
- query 16, 23
-
- R
- reg-name 21
- registered name 20
- relative 10, 28
- relative-path 26
- relative-ref 26
- remove_dot_segments 33
- representation 9
- reserved 12
- resolution 9, 28
- resource 5
- retrieval 9
-
- S
- same-document 27
- sameness 9
- scheme 16, 17
- segment 22, 23
- segment-nz 23
- segment-nz-nc 23
- sub-delims 13
- suffix 27
-
- T
- transcription 8
-
- U
- uniform 4
- unreserved 13
- URI grammar
- absolute-URI 27
- ALPHA 11
- authority 18
- CR 11
- dec-octet 20
- DIGIT 11
- DQUOTE 11
- fragment 24
- gen-delims 13
-
-
-
-Berners-Lee, et al. Standards Track [Page 58]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
- h16 20
- HEXDIG 11
- hier-part 16
- host 19
- IP-literal 19
- IPv4address 20
- IPv6address 20
- IPvFuture 19
- LF 11
- ls32 20
- OCTET 11
- path 22
- path-abempty 22
- path-absolute 22
- path-empty 22
- path-noscheme 22
- path-rootless 22
- pchar 23
- pct-encoded 12
- port 22
- query 24
- reg-name 21
- relative-ref 26
- reserved 13
- scheme 17
- segment 23
- segment-nz 23
- segment-nz-nc 23
- SP 11
- sub-delims 13
- unreserved 13
- URI 16
- URI-reference 25
- userinfo 18
- URI 16
- URI-reference 25
- URL 7
- URN 7
- userinfo 18
-
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 59]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-Authors' Addresses
-
- Tim Berners-Lee
- World Wide Web Consortium
- Massachusetts Institute of Technology
- 77 Massachusetts Avenue
- Cambridge, MA 02139
- USA
-
- Phone: +1-617-253-5702
- Fax: +1-617-258-5999
- EMail: timbl@w3.org
- URI: http://www.w3.org/People/Berners-Lee/
-
-
- Roy T. Fielding
- Day Software
- 5251 California Ave., Suite 110
- Irvine, CA 92617
- USA
-
- Phone: +1-949-679-2960
- Fax: +1-949-679-2972
- EMail: fielding@gbiv.com
- URI: http://roy.gbiv.com/
-
-
- Larry Masinter
- Adobe Systems Incorporated
- 345 Park Ave
- San Jose, CA 95110
- USA
-
- Phone: +1-408-536-3024
- EMail: LMM@acm.org
- URI: http://larry.masinter.net/
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 60]
-\f
-RFC 3986 URI Generic Syntax January 2005
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2005).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the IETF's procedures with respect to rights in IETF Documents can
- be found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at ietf-
- ipr@ietf.org.
-
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-Berners-Lee, et al. Standards Track [Page 61]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group R. Herriot
-Request for Comments: 3995 Global Workflow Solutions
-Category: Standards Track T. Hastings
-Updates: 2911, 2910 Xerox Corporation
- March 2005
-
-
- Internet Printing Protocol (IPP):
- Event Notifications and Subscriptions
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2005).
-
-Abstract
-
- This document describes an OPTIONAL extension to the Internet
- Printing Protocol/1.1: Model and Semantics (RFC 2911, RFC 2910).
- This extension allows a client to subscribe to printing related
- Events. Subscriptions are modeled as Subscription Objects. The
- Subscription Object specifies that when one of the specified Events
- occurs, the Printer delivers an asynchronous Event Notification to
- the specified Notification Recipient via the specified Push or Pull
- Delivery Method (i.e., protocol).
-
- A client associates Subscription Objects with a particular Job by
- performing the Create-Job-Subscriptions operation or by submitting a
- Job with subscription information. A client associates Subscription
- Objects with the Printer by performing a Create-Printer-Subscriptions
- operation. Four other operations are defined for Subscription
- Objects: Get-Subscriptions-Attributes, Get-Subscriptions, Renew-
- Subscription, and Cancel-Subscription.
-
-
-
-
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 1]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
- 1.1. Notification Overview. . . . . . . . . . . . . . . . . . 5
- 2. Models for Notification. . . . . . . . . . . . . . . . . . . . 8
- 2.1. Model for Simple Notification (Normative). . . . . . . . 8
- 2.2. Additional Models for Notification (Informative) . . . . 9
- 3. Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . 9
- 3.1. Conformance Terminology. . . . . . . . . . . . . . . . . 9
- 3.2. Other Terminology. . . . . . . . . . . . . . . . . . . . 10
- 4. Object Relationships . . . . . . . . . . . . . . . . . . . . . 12
- 4.1. Printer and Per-Printer Subscription Objects . . . . . . 13
- 4.2. Printer, Job and Per-Job Subscription Objects. . . . . . 13
- 5. Subscription Object. . . . . . . . . . . . . . . . . . . . . . 13
- 5.1. Rules for Support of Subscription Template Attributes. . 14
- 5.2. Rules for Processing Subscription Template Attributes. . 15
- 5.3. Subscription Template Attributes . . . . . . . . . . . . 18
- 5.3.1. notify-recipient-uri (uri) . . . . . . . . . . . 20
- 5.3.2. notify-pull-method (type2 keyword) . . . . . . . 21
- 5.3.3. notify-events (1setOf type2 keyword) . . . . . . 22
- 5.3.4. notify-attributes (1setOf type2 keyword) . . . . 29
- 5.3.5. notify-user-data (octetString(63)) . . . . . . . 30
- 5.3.6. notify-charset (charset) . . . . . . . . . . . . 31
- 5.3.7. notify-natural-language (naturalLanguage). . . . 31
- 5.3.8. notify-lease-duration (integer(0:67108863)). . . 32
- 5.3.9. notify-time-interval (integer(0:MAX)). . . . . . 33
- 5.4. Subscription Description Attributes. . . . . . . . . . . 34
- 5.4.1. notify-subscription-id (integer (1:MAX)). . . . 35
- 5.4.2. notify-sequence-number (integer (0:MAX)) . . . . 35
- 5.4.3. notify-lease-expiration-time (integer(0:MAX)). . 36
- 5.4.4. notify-printer-up-time (integer(1:MAX)). . . . . 37
- 5.4.5. notify-printer-uri (uri) . . . . . . . . . . . . 37
- 5.4.6. notify-job-id (integer(1:MAX)) . . . . . . . . . 37
- 5.4.7. notify-subscriber-user-name (name(MAX)). . . . . 38
- 6. Printer Description Attributes Related to Notification . . . . 38
- 6.1. printer-state-change-time (integer(1:MAX)) . . . . . . . 39
- 6.2. printer-state-change-date-time (dateTime). . . . . . . . 39
- 7. New Values for Existing Printer Description Attributes . . . . 39
- 7.1. operations-supported (1setOf type2 enum) . . . . . . . . 40
- 8. Attributes Only in Event Notifications . . . . . . . . . . . . 40
- 8.1. notify-subscribed-event (type2 keyword). . . . . . . . . 40
- 8.2. notify-text (text(MAX)). . . . . . . . . . . . . . . . . 41
- 9. Event Notification Content . . . . . . . . . . . . . . . . . . 41
- 9.1. Content of Machine Consumable Event Notifications. . . . 44
- 9.1.1. Event Notification Content Common to All Events. 44
- 9.1.2. Additional Event Notification Content for Job
- Events . . . . . . . . . . . . . . . . . . . . . 45
-
-
-
-
-Herriot & Hastings Standards Track [Page 2]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- 9.1.3. Additional Event Notification Content for
- Printer Events . . . . . . . . . . . . . . . . . 46
- 9.2. Content of Human Consumable Event Notification . . . . . 46
- 9.2.1. Event Notification Content Common to All Events. 47
- 9.2.2. Additional Event Notification Content for Job
- Events . . . . . . . . . . . . . . . . . . . . . 49
- 9.2.3. Additional Event Notification Content for
- Printer Events . . . . . . . . . . . . . . . . . 49
- 10. Delivery Methods . . . . . . . . . . . . . . . . . . . . . . . 50
- 11. Operations for Notification. . . . . . . . . . . . . . . . . . 52
- 11.1. Subscription Creation Operations . . . . . . . . . . . . 52
- 11.1.1. Create-Job-Subscriptions Operation . . . . . . . 52
- 11.1.2. Create-Printer-Subscriptions operation . . . . . 55
- 11.1.3. Job Creation Operations - Extensions for
- Notification . . . . . . . . . . . . . . . . . . 56
- 11.2 Other Operations. . . . . . . . . . . . . . . . . . . . . 58
- 11.2.1. Restart-Job Operation - Extensions for
- Notification . . . . . . . . . . . . . . . . . . 58
- 11.2.2. Validate-Job Operation - Extensions for
- Notification . . . . . . . . . . . . . . . . . . 59
- 11.2.3. Get-Printer-Attributes - Extensions for
- Notification . . . . . . . . . . . . . . . . . . 59
- 11.2.4. Get-Subscription-Attributes operation. . . . . . 60
- 11.2.5. Get-Subscriptions operation. . . . . . . . . . . 63
- 11.2.6. Renew-Subscription operation . . . . . . . . . . 66
- 11.2.7. Cancel-Subscription operation. . . . . . . . . . 68
- 12. Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . 70
- 12.1. successful-ok-ignored-subscriptions (0x0003) . . . . . . 70
- 12.2. client-error-ignored-all-subscriptions (0x0414). . . . . 71
- 13. Status Codes in Subscription Attributes Groups . . . . . . . . 71
- 13.1. client-error-uri-scheme-not-supported (0x040C) . . . . . 71
- 13.2. client-error-attributes-or-values-not-supported (0x040B) 71
- 13.3. client-error-too-many-subscriptions (0x0415) . . . . . . 72
- 13.4. successful-ok-too-many-events (0x0005) . . . . . . . . . 72
- 13.5. successful-ok-ignored-or-substituted-attributes (0x0001) 72
- 14. Encodings of Additional Attribute Tags . . . . . . . . . . . . 72
- 15. Conformance Requirements . . . . . . . . . . . . . . . . . . . 72
- 15.1. Conformance requirements for clients . . . . . . . . . . 73
- 15.2. Conformance requirements for Printers. . . . . . . . . . 73
- 16. Model for Notification with Cascading Printers (Informative) . 74
- 17. Distributed Model for Notification (Informative) . . . . . . . 75
- 18. Extended Notification Recipient (Informative). . . . . . . . . 76
- 19. Object Model for Notification (Normative). . . . . . . . . . . 77
- 19.1. Object relationships . . . . . . . . . . . . . . . . . . 78
- 19.2. Printer Object and Per-Printer Subscription Objects. . . 79
- 19.3. Job Object and Per-Job Subscription Objects. . . . . . . 79
- 20. Per-Job versus Per-Printer Subscription Objects (Normative). . 79
- 21. Normative References . . . . . . . . . . . . . . . . . . . . . 80
-
-
-
-Herriot & Hastings Standards Track [Page 3]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- 22. Informative References . . . . . . . . . . . . . . . . . . . . 80
- 23. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 81
- 23.1. Attribute Registrations. . . . . . . . . . . . . . . . . 82
- 23.2. Additional Enum Attribute Value Registrations within
- the IPP registry . . . . . . . . . . . . . . . . . . . . 83
- 23.3. Operation Registrations. . . . . . . . . . . . . . . . . 83
- 23.4. Status code Registrations. . . . . . . . . . . . . . . . 83
- 23.5. Attribute Group tag Registrations. . . . . . . . . . . . 84
- 23.6. Registration of Events . . . . . . . . . . . . . . . . . 84
- 23.7. Registration of Event Notification Delivery Methods. . . 85
- 23.7.1. Requirements for Registration of Event
- Notification Delivery Methods. . . . . . . . . . 85
- 23.7.2. Registration Procedure . . . . . . . . . . . . . 86
- 23.7.3. Delivery Method Document Registrations . . . . . 87
- 23.7.4. Registration Template. . . . . . . . . . . . . . 88
- 24. Internationalization Considerations. . . . . . . . . . . . . . 89
- 25. Security Considerations. . . . . . . . . . . . . . . . . . . . 89
- 25.1. Client access rights . . . . . . . . . . . . . . . . . . 89
- 25.2. Printer security threats . . . . . . . . . . . . . . . . 91
- 25.3. Notification Recipient security threats. . . . . . . . . 91
- 26. Description of the base IPP documents (Informative). . . . . . 92
- 27. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 93
- Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 94
- Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 95
-
-Tables
-
- Table 1 - Subscription Template Attributes. . . . . . . . . . . . 20
- Table 2 - Subscription Description Attributes . . . . . . . . . . 35
- Table 3 - Printer Description Attributes Associated with
- Notification. . . . . . . . . . . . . . . . . . . . . . 39
- Table 4 - Operation-id assignments. . . . . . . . . . . . . . . . 40
- Table 5 - Attributes in Event Notification Content. . . . . . . . 45
- Table 6 - Additional Event Notification Content for Job Events. . 46
- Table 7 - Combinations of Events and Subscribed Events for
- "job-impressions-completed" . . . . . . . . . . . . . . 46
- Table 8 - Additional Event Notification Content for Printer
- Events. . . . . . . . . . . . . . . . . . . . . . . . . 46
- Table 9 - Printer Name in Event Notification Content. . . . . . . 48
- Table 10 - Event Name in Event Notification Content. . . . . . . . 48
- Table 11 - Event Time in Event Notification Content. . . . . . . . 48
- Table 12 - Job Name in Event Notification Content. . . . . . . . . 49
- Table 13 - Job State in Event Notification Content . . . . . . . . 49
- Table 14 - Printer State in Event Notification Content . . . . . . 50
- Table 15 - Information about the Delivery Method . . . . . . . . . 51
- Table 16 - Printer Conformance Requirements for Operations . . . . 74
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 4]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-Figures
-
- Figure 1 - Model for Notification. . . . . . . . . . . . . . . . . 9
- Figure 2 - Model for Notification with Cascading Printers. . . . . 75
- Figure 3 - Opaque Use of a Notification Server Transparent to the
- Client. . . . . . . . . . . . . . . . . . . . . . . . . 76
- Figure 4 - Use of an Extended Notification Recipient transparent
- to the Printer. . . . . . . . . . . . . . . . . . . . . 77
- Figure 5 - Object Model for Notification . . . . . . . . . . . . . 78
-
-1. Introduction
-
- This IPP notification specification is an OPTIONAL extension to
- Internet Printing Protocol/1.1: Model and Semantics [RFC2911,
- RFC2910]. See Appendix 29 for a description of the base IPP
- documents. This document in combination with the following documents
- is intended to meet the most important notification requirements
- described in [RFC3997]:
-
- Internet Printing Protocol (IPP): "Job Progress Attributes"
- [RFC3381]
-
- Internet Printing Protocol (IPP): "The 'ippget' Delivery Method
- for Event Notifications" [RFC3996]
-
- This specification REQUIRES that clients and Printers support the
- 'ippget' Pull Delivery Method [RFC3996]. Conforming client and
- Printer implementations MAY support additional Push or Pull Delivery
- Methods as well. Note: this document does not define any Delivery
- Methods itself, but it does define the rules for conformance for
- Delivery Method Documents and their registration with IANA (see
- section 23.7.3).
-
- Refer to the Table of Contents for the layout of this document.
-
-1.1. Notification Overview
-
- This document defines operations that a client can perform in order
- to create Subscription Objects in a Printer and carry out other
- operations on them. A Subscription Object represents a Subscription
- abstraction. The Subscription Object specifies that when one of the
- specified Events occurs, the Printer delivers an asynchronous Event
- Notification to the specified Notification Recipient via the
- specified Delivery Method (i.e., protocol).
-
- When a client (called a Subscribing Client) performs an operation
- that creates a Subscription Object, the operation contains one or
- more Subscription Template Attributes Groups. Each such group holds
-
-
-
-Herriot & Hastings Standards Track [Page 5]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- information used by the Printer to initialize a newly created
- Subscription Object. The Printer creates one Subscription Object for
- each Subscription Template Attributes Group in the operation. This
- group is like the Job Template Attributes group defined in [RFC2911].
- The following is an example of the information included in a
- Subscription Template Attributes Group (see section 5 for details on
- the Subscription Object attributes):
-
- 1. The names of Subscribed Events that are of interest to the
- Notification Recipient.
-
- 2. The address (URL) of one Notification Recipient for a Push
- Delivery Method or the method for a Pull Delivery Method.
-
- 3. The Delivery Method (i.e., the protocol) which the Printer uses to
- deliver the Event Notification.
-
- 4. Some opaque data that the Printer delivers to the Notification
- Recipient in the Event Notification. For example, the
- Notification Recipient might use this opaque data as a forwarding
- address for the Event Notification.
-
- 5. The charset to use in text fields within an Event Notification
-
- 6. The natural language to use in the text fields of the Event
- Notification
-
- 7. The requested lease time in seconds for the Subscription Object
-
- An operation that creates a Subscription Object is called a
- Subscription Creation Operation. These operations include the
- following operations (see section 11.1 for further details):
-
- - Job Creation operation: When a client performs such an
- operation (Print-Job, Print-URI, and Create-Job), a client can
- include zero or more Subscription Template Attributes Groups in
- the request. The Printer creates one Subscription Object for
- each Subscription Template Attributes Group in the request, and
- the Printer associates each such Subscription Object with the
- newly created Job. This document extends these operations'
- definitions in [RFC2911] by adding Subscription Template
- Attributes Groups in the request and Subscription Attributes
- Groups in the response.
-
- - Create-Job-Subscriptions operation: A client can include one or
- more Subscription Template Attributes Groups in the request.
- The Printer creates one Subscription Object for each
-
-
-
-
-Herriot & Hastings Standards Track [Page 6]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Subscription Template Attributes Group and associates each with
- the job that is the target of this operation.
-
- - Create-Printer-Subscriptions operation: A client can include
- one or more Subscription Template Attributes Groups in the
- request. The Printer creates one Subscription Object for each
- Subscription Template Attributes Group and associates each with
- the Printer that is the target of this operation.
-
- For each of the above operations:
-
- - the Printer associates a Subscription Object with the Printer
- or a specific Job. When a Subscription Object is associated
- with a Job Object, it is called a Per-Job Subscription Object.
- When a Subscription Object is associated with a Printer Object,
- it is called a Per-Printer Subscription Object.
-
- - the response contains one Subscription Attributes Group for
- each Subscription Template Attributes Group in the request and
- in the same order. When the Printer successfully creates a
- Subscription Object, its corresponding Subscription Attributes
- Group contains the "notify-subscription-id" attribute. This
- attribute uniquely identifies the Subscription Object and is
- analogous to a "job-id" for a Job object. Some operations
- described below use the "notify-subscription-id" to identify
- the target Subscription Object.
-
- This document defines the following additional operations (see
- section 11.2 for further details):
-
- - Restart-Job operation: When a client performs the Restart-Job
- operation [RFC2911], the Printer re-uses the same Job and its
- Subscription Objects.
-
- - Validate-Job operation: When a client performs this operation, a
- client can include zero or more Subscription Template Attributes
- Groups in the request. The Printer determines if it could create
- one Subscription Object for each Subscription Template Attributes
- Group in the request. This document extends this operation's
- definition in [RFC2911] by adding Subscription Template Attributes
- Groups in the request and Subscription Attributes Groups in the
- response.
-
- - Get-Subscription-Attributes operation: This operation allows a
- client to obtain the specified attributes of a target Subscription
- Object.
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 7]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- - Get-Subscriptions operation: This operation allows a client to
- obtain the specified attributes of all Subscription Objects
- associated with the Printer or a specified Job.
-
- - Renew-Subscription operation: This operation renews the lease on
- the target Per-Printer Subscription Object before it expires. A
- newly created Per-Printer Subscription Object receives an initial
- lease. It is the duty of the client to use this operation
- frequently enough to preserve a Per-Printer Subscription Object.
- The Printer deletes a Per-Printer Subscription Object when its
- lease expires. A Per-Job Subscription Object last exactly as long
- as its associated Job Object and thus doesn't have a lease.
-
- - Cancel-Subscription operation: This operation (1) cancels the
- lease on the specified Per-Printer Subscription Object and thereby
- deletes the Per-Printer Subscription Object or (2) deletes the
- Per-Job Subscription Object.
-
- When an Event occurs, the Printer finds all Subscription Objects
- listening for the Event (see section 9 for details on finding such
- Subscription Objects). For each such Subscription Object, the
- Printer:
-
- a) generates an Event Notification with information specified in
- section 9, AND
-
- b) either:
-
- i) If the Delivery Method is a Push Delivery Method as indicated
- by the presence of the Subscription Object's "notify-
- recipient-uri" attribute, delivers the Event Notification
- using the Delivery Method and target address identified in the
- Subscription Object's "notify-recipient-uri" attribute, OR
-
- ii) If the Delivery Method is a Pull Delivery Method as indicated
- by the presence of the Subscription Object's "notify-pull-
- method" attribute, saves Event Notification for a time period
- called the Event Life defined by the Delivery Method, i.e.,
- the Notification Recipient is expected to fetch the Event
- Notifications.
-
-2. Models for Notification
-
-2.1. Model for Simple Notification (Normative)
-
- As part of a Subscription Creation Operation, an IPP Printer (i.e.,
- located in an output device or a server) creates one or more
- Subscription Objects. In a Subscription Creation Operation, the
-
-
-
-Herriot & Hastings Standards Track [Page 8]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- client specifies the Notification Recipient to which the Printer is
- to deliver Event Notifications. A Notification Recipient can be the
- Subscribing Client or a third party.
-
- Figure 1 shows the Notification model for a simple Client-Printer
- relationship.
-
- embedded printer:
-
- output device or server
- PDA, desktop, or server +---------------+
- +--------+ | ########### |
- | client |-----Subscription ---------># Printer # |
- +--------+ Creation Operation | # Object # |
- +------------+ | #####|##### |
- |Notification| +-------|-------+
- |Recipient |<----IPP Event Notifications----+
- +------------+ (Job and/or Printer Events)
-
- Figure 1 - Model for Notification
-
-2.2. Additional Models for Notification (Informative)
-
- Additional models have been proposed (see Appendices 16, 17, and 18).
-
-3. Terminology
-
- This section defines terminology used throughout this document.
- Other terminology is defined in [RFC2911].
-
-3.1. Conformance Terminology
-
- Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD
- NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to
- conformance as defined in RFC 2119 [RFC2119] and [RFC2911] section
- 12.1. If an implementation supports the extension defined in this
- document, then these terms apply; otherwise, they do not. These
- terms define conformance to this document only; they do not affect
- conformance to other documents, unless explicitly stated otherwise.
-
- Note: a feature that is OPTIONAL in this document becomes REQUIRED if
- the Printer implements a Delivery Method that REQUIRES the feature.
-
- READ-ONLY - an adjective used in an attribute definition to indicate
- that an IPP Printer MUST NOT allow the attribute's value to be
- modified.
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 9]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-3.2. Other Terminology
-
- This document uses the same terminology as [RFC2911], such as
- "client", "Printer", "attribute", "attribute value", "keyword",
- "operation", "request", "response", "administrator", "operator", and
- "support". In addition, the following terms are defined for use in
- this document and the Delivery Method Documents:
-
- Compound Event Notification - two or more Event Notifications that a
- Printer delivers together as a single request or response. The
- Delivery Method Document specifies whether the Delivery Method
- supports Compound Event Notifications.
-
- Delivery Method - the mechanism by which the Printer delivers an
- Event Notification.
-
- Delivery Method Document - a document, separate from this document,
- that defines a Delivery Method.
-
- Event - some occurrence (either expected or unexpected) within the
- printing system of a change of state, condition, or configuration of
- a Job or Printer object. An Event occurs only at one instant in time
- and does not span the time the physical Event takes place. For
- example, jam-occurred and jam-cleared are two distinct, instantaneous
- Events, even though the jam may last for a while.
-
- Event Life - For a Pull Delivery Method, the length of time in
- seconds after an Event occurs during which the Printer will retain
- that Event for delivery in an Event Notification. After the Event
- Life expires, the Printer will no longer deliver an Event
- Notification for that Event in such a response.
-
- Event Notification - the information about an Event that the Printer
- delivers when an Event occurs.
-
- Event Notification Attributes Group - The attributes group which is
- used to deliver an Event Notification in a request (Push Delivery
- Methods) or a response (Pull Delivery Methods).
-
- Human Consumable Event Notification - localized text for human
- consumption only. There is no standardized format and thus programs
- should not try to parse this text.
-
- Job Creation operation - One of the operations that creates a Job
- object: Print-Job, Print-URI and Create-Job. The Restart-Job
- operation [RFC2911] is not considered a Job Creation operation, since
- the Printer re-uses the existing Job object. The Validate-Job
- operation is not considered a Job Creation operation because no Job
-
-
-
-Herriot & Hastings Standards Track [Page 10]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- object is created. Therefore, when a statement also applies to
- either the Restart-Job and/or the Validate-Job operation, they are
- mentioned explicitly.
-
- Job Event - an Event caused by some change in a particular job on the
- Printer, e.g., 'job-completed'.
-
- Machine Consumable Event Notification - bytes for program
- consumption. The bytes are formatted according to the Delivery
- Method document.
-
- Notification - when not in the phrases 'Event Notification' and
- 'Notification Recipient' - the concepts of this specification, i.e.,
- Events, Subscription Objects, and Event Notifications.
-
- Notification Recipient - the entity to which the Printer delivers an
- Event Notification. For Push Delivery Methods, the IPP Printer sends
- the Notifications to a Notification Recipient. For Pull Delivery
- Methods, the Notification Recipient is acting in the role of an IPP
- client and requests Event Notifications and so the terms "client" and
-
- "Notification Recipient" are used interchangeably with such Delivery
- Methods. For example, see [RFC3996].
-
- Per-Job Subscription Object - A Subscription Object that is
- associated with a single Job. The Create-Job-Subscriptions operation
- and Job Creation operations create such an object.
-
- Per-Printer Subscription Object - A Subscription Object that is
- associated with the Printer as a whole. The Create-Printer-
- Subscriptions operation creates such an object.
-
- Printer Event - an Event caused by some change in the Printer that is
- not specific to a job, e.g., 'printer-state-changed'.
-
- Pull Delivery Method - The Printer saves Event Notifications for some
- event life time and expects the Notification Recipient to request
- Event Notifications. The Printer delivers the Event Notifications in
- a response to such a request.
-
- Push Delivery Method -The Printer delivers the Event Notification
- shortly after an Event occurs.
-
- Subscribed Event - an Event that the Subscribing Client expresses
- interest in by making it a value of the "notify-events" attribute on
- a Subscription Object.
-
- Subscribed Job Event - a Subscribed Event that is a Job Event.
-
-
-
-Herriot & Hastings Standards Track [Page 11]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Subscribed Printer Event - a Subscribed Event that is a Printer
- Event.
-
- Subscribing Client - The client that creates the Subscription Object.
-
- Subscription Attributes Group - The attributes group in a response
- that contains Subscription Object attributes.
-
- Subscription Creation Operation - An operation that creates a
- Subscription Object: Job Creation operations, Create-Job-
- Subscriptions operation, Create-Printer-Subscriptions operation. In
- the context of a Job Creation operation, a Subscription Creation
- Operation is the part of the Job Creation operation that creates one
- or more Subscription objects. The Restart-Job operation [RFC2911] is
- not considered a Subscription Creation Operation, since the Printer
- re-uses the Job's existing Subscription Objects, rather than creating
- any new Subscription Objects.
-
- Subscription Creation Request - The request portion of a Subscription
- Creation Operation.
-
- Subscription Description Attributes - Subscription Object attributes
- that a Printer supplies during a Subscription Creation Operation.
-
- Subscription Object - An object containing a set of attributes that
- indicate: the Notification Recipient (for Push Delivery Method
- only), the Delivery Method, the Subscribed Events that cause the
- Printer to deliver an Event Notification, and the information to
- include in an Event Notification.
-
- Subscription Template Attributes - Subscription Object attributes
- that a client can supply in a Subscription Creation Operation and
- associated Printer Object attributes that specify supported and
- default values for the Subscription Object attributes.
-
- Subscription Template Attributes Group - The attributes group in a
- request that contains Subscription Object attributes that are
- Subscription Template Attributes.
-
-4. Object Relationships
-
- This section defines the object relationships between the Printer,
- Job, and Subscription Objects. It does not define the
- implementation. For an illustration of these relationships, see
- Appendix 19.
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 12]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-4.1. Printer and Per-Printer Subscription Objects
-
- 1. A Printer object can be associated with zero or more Per-Printer
- Subscription Objects.
-
- 2. Each Per-Printer Subscription Object is associated with exactly
- one Printer object.
-
-4.2. Printer, Job and Per-Job Subscription Objects
-
- 1. A Printer object is associated with zero or more Job objects.
-
- 2. Each Job object is associated with exactly one Printer object.
-
- 3. A Job object is associated with zero or more Per-Job Subscription
- Objects.
-
- 4. Each Per-Job Subscription Object is associated with exactly one
- Job object.
-
-5. Subscription Object
-
- A Subscribing Client creates a Subscription Object with a
- Subscription Creation Operation in order to indicate its interest in
- certain Events. See section 11 for a description of these
- operations. When an Event occurs, the Subscription Object specifies
- to the Printer where to deliver Event Notifications for Push Delivery
- Methods only, how to deliver them, and what to include in them. See
- section 9 for details on the contents of an Event Notification.
-
- Using the IPP Job Template attributes as a model (see [RFC2911]
- section 4.2), the attributes of a Subscription Object are divided
- into two categories: Subscription Template Attributes and
- Subscription Description Attributes.
-
- Subscription Template attributes are, in turn, like the Job Template
- attributes, divided into
-
- 1. Subscription Object attributes that a client can supply in a
- Subscription Creation Request and
-
- 2. their associated Printer Object attributes that specify supported
- and default values for the Subscription Object attributes
-
- The remainder of this section specifies general rules for
- Subscription Template Attributes and describes each attribute in a
- Subscription Object.
-
-
-
-
-Herriot & Hastings Standards Track [Page 13]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-5.1. Rules for Support of Subscription Template Attributes
-
- Subscription Template Attributes are fundamental to the Notification
- model described in this specification. The client supplies these
- attributes in Subscription Creation Operations and the Printer uses
- these attributes to populate a newly created Subscription Object.
-
- Subscription Objects attributes that are Subscription Template
- Attributes conform to the following rules:
-
- 1. Each attribute's name starts with the prefix string "notify-" and
- this document calls such attributes "notify-xxx".
-
- 2. For each "notify-xxx" Subscription Object attribute defined in
- column 1 of Table 1 in section 5.3, Table 1 specifies
- corresponding Printer attributes: "notify-xxx-default", "notify-
- xxx-supported", "yyy-supported" and "notify-max-xxx-supported"
- defined in column 2 of Table 1. Note "xxx" stands for the same
- string in each case and "yyy" stands for some other string.
-
- 3. If a Printer supports "notify-xxx" in column 1 of Table 1, then
- the Printer MUST support all associated attributes specified in
- column 2 of Table 1. For example, Table 1 shows that if the
- Printer supports "notify-events", it MUST support "notify-events-
- default", "notify-events-supported" and "notify-max-events-
- supported".
-
- 4. If a Printer does not support "notify-xxx" in column 1 of Table 1,
- then the Printer MUST NOT support any associated "notify-yyy"
- attributes specified in column 2 of Table 1. For example, Table 1
- shows that if the Printer doesn't support "notify-events", it MUST
- NOT support "notify-events-default", "notify-events-supported" and
- "notify-max-events-supported". Note this rule does not apply to
- attributes whose names do not start with the string "notify-" and
- are thus defined in another object and used by other attributes.
-
- 5. Most "notify-xxx" attributes have a corresponding "yyy-supported"
- attribute that specifies the supported values for "notify-xxx".
- Column 2 of Table 1 specifies the name of each "yyy-supported"
- attribute. The naming rules of IPP/1.1 (see [RFC2911]) are used
- when "yyy-supported" is "notify-xxx-supported".
-
- 6. Some "notify-xxx" attributes have a corresponding "notify-xxx-
- default" attribute that specifies the value for "notify-xxx" if
- the client does not supply it. Column 2 of Table 1 specifies the
- name of each "notify-xxx-default" attribute. The naming rules of
- IPP/1.1 (see [RFC2911]) are used.
-
-
-
-
-Herriot & Hastings Standards Track [Page 14]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- If a client wishes to present an end user with a list of supported
- values from which to choose, the client SHOULD query the Printer for
- its supported value attributes. The client SHOULD also query the
- default value attributes. If the client then limits selectable
- values to only those values that are supported, the client can
- guarantee that the values supplied by the client in the create
- request all fall within the set of supported values at the Printer.
- When querying the Printer, the client MAY enumerate each attribute by
- name in the Get-Printer-Attributes Request, or the client MAY just
- supply the 'subscription-template' group name in order to get the
- complete set of supported attributes (both supported and default
- attributes - see section 11.2.3).
-
-5.2. Rules for Processing Subscription Template Attributes
-
- This section defines a detailed set of rules that a Printer follows
- when it processes Subscription Template Attributes in a Subscription
- Creation Request. These rules are similar to the rules for
- processing Operation attributes in [RFC2911]. That is, the Printer
- may or may not support an attribute and a client may or may not
- supply the attribute. Some combinations of these cases are OK.
- Others return warnings or errors, and perhaps a list of unsupported
- attributes.
-
- A Printer MUST implement the following behavior for processing
- Subscription Template Attributes in a Subscription Creation Request:
-
- 1. If a client supplies a "notify-xxx" attribute from column 1 of
- Table 1 and the Printer supports it and its value, the Printer
- MUST populate the attribute on the created Subscription Object.
-
- 2. If a client supplies a "notify-xxx" attribute from column 1 of
- Table 1 and the Printer doesn't support it or its value, the
- Printer MUST NOT populate the attribute on the created
- Subscription Object with it. The Printer MUST do one of the
- following:
-
- a) If the value of the "notify-xxx" attribute is unsupported, the
- Printer MUST return the attribute with its value in the
- Subscription Attributes Group of the response.
-
- b) If "notify-xxx" is an unsupported attribute, the Printer MUST
- return the attribute in the Subscription Attributes Group of
- the response with the 'unsupported' out-of-band value.
-
- Note: The rules of this step are the same as for Unsupported
- Attributes [RFC2911] section 3.1.7. except that the unsupported
- attributes are returned in the Subscription Attributes Group
-
-
-
-Herriot & Hastings Standards Track [Page 15]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- rather than the Unsupported Attributes Group because Subscription
- Creation Operations can create more than one Subscription Object).
-
- 3. If a client is REQUIRED to supply a "notify-xxx" attribute from
- column 1 of Table 1 and the Printer doesn't support the supplied
- value, the Printer MUST NOT create a Subscription Object. The
- rules for Unsupported Attributes in step #2 still apply.
-
- 4. If a client does not supply a "notify-xxx" attribute from column 1
- of Table 1 and the attribute is REQUIRED for the client to supply,
- the Printer MUST reject the Subscription Creation Operation
- (including Job Creation operations) without creating a
- Subscription Object, and MUST return in the response:
-
- a) the status code 'client-error-bad-request' AND
-
- b) no Subscription Attribute Groups.
-
- 5. If a client does not supply a "notify-xxx" attribute from column 1
- of Table 1 that is OPTIONAL for the client to supply, and column 2
- of Table 1 either:
-
- a) specifies a "notify-xxx-default" attribute, the Printer MUST
- behave as if the client had supplied the "notify-xxx-default"
- attribute (see step #1) and populate the Subscription object
- with the value of the "notify-xxx-default" attribute as part of
- the Subscription Creation operation (unlike Job Template
- attributes where the Printer does not populate the Job object
- with defaults - see [RFC2911]) OR
-
- b) does not specify a "notify-xxx-default" attribute, the Printer
- MUST populate the "notify-xxx" attribute on the Subscription
- Object according to the definition of the "notify-xxx"
- attribute in a section 5.3. For some attributes, the "notify-
- xxx" is populated with the value of some other attribute, and
- for others, the "notify-xxx" is NOT populated on the
- Subscription object at all.
-
- 6. A Printer MUST create a Subscription Object for each Subscription
- Template Attributes group in a request unless the Printer:
-
- a) encounters some attributes in a Subscription Template
- Attributes Group that require the Printer not to create the
- Subscription Object OR
-
- b) would create a Per-Job Subscription Object when it doesn't have
- space for another Per-Job Subscription Object OR
-
-
-
-
-Herriot & Hastings Standards Track [Page 16]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- c) would create a Per-Printer Subscription Object when it doesn't
- have space for another Per-Printer Subscription Object.
-
- 7. A response MUST contain one Subscription Attributes Group for each
- Subscription Template Attributes Group in the request (and in the
- same order) whether the Printer creates a Subscription Object from
- the Subscription Template Attributes Group or not. However, the
- attributes in each Subscription Attributes Group can be in any
- order.
-
- 8. The Printer MUST populate each Subscription Attributes Group of
- the response such that each contains:
-
- a) the "notify-subscription-id" attribute (see section 5.4.1), if
- and only if the Printer creates a Subscription Object.
-
- b) the "notify-lease-duration" attribute (see section 5.3.8), if
- and only if the Printer creates a Per-Printer Subscription
- Object. The value of this attribute is the value of the
- Subscription Object's "notify-lease-duration" attribute. This
- value MAY be different from the client-supplied value (see
- section 5.3.8). If a client supplies this attribute in the
- creation of a Per-Job Subscription Object, it MUST appear in
- this group with the out-of-band value 'unsupported' to indicate
- that the Printer doesn't support it in this context.
-
- c) all of the unsupported Subscription Template Attributes from
- step #2. Note, they are not returned in the Unsupported
- Attributes Group in order to separate the unsupported
- attributes for each Subscription Object.
-
- d) the "notify-status-code" attribute if the Printer does not
- create the Subscription Object or if there are unsupported
- attributes from step #2. The possible values of the "notify-
- status-code" attribute are shown below (see section 13 for more
- details). The Printer returns the first value in the list
- below that describes the status.
-
- 'client-error-uri-scheme-not-supported': the Subscription
- Object was not created because the scheme of the "notify-
- recipient-uri" attribute is not supported. See section 13.1
- for more details about this status code. See step #3 in
- this section for the case that causes this error, and the
- resulting step #6a) that causes the Printer not to create
- the Subscription Object.
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 17]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- 'client-error-attributes-or-values-not-supported': the
- Subscription Object was not created because the method of
- the "notify-pull-method" attribute is not supported. See
- section 13.1 for more details about this status code. See
- step #3 in this section for the case that causes this error,
- and the resulting step #6a) that causes the Printer not to
- create the Subscription Object.
-
- 'client-error-too-many-subscriptions': the Subscription
- Object was not created because the Printer has no space for
- additional Subscription Objects. The client MAY try again
- later. See section 13.3 for more details about this status
- code. See steps #6b) and #6c) in this section for the cases
- that causes this error.
-
- 'successful-ok-too-many-events': the Subscription Object was
- created without the "notify-events" values included in this
- Subscription Attributes Group because the "notify-events"
- attribute contains too many values. See section 13.4 for
- more details about this status code. See step #2 in this
- section and section 5.3.3 for the cases that cause this
- status code.
-
- 'successful-ok-ignored-or-substituted-attributes': the
- Subscription Object was created but some supplied
- Subscription Template Attributes are unsupported. These
- unsupported attributes are also in the Subscription
- Attributes Group. See section 13.5 for more details about
- this status code. See step #2 in this section for the cases
- that cause this status code.
-
- 9. The Printer MUST validate all Subscription Template Attributes and
- MUST return all unsupported attributes and values in the
- corresponding Subscription Attributes Group of the response (see
- step #2) unless it determines that it could not create additional
- Subscription Objects because of condition #6b) or condition #6c).
- Then, the Printer NEED NOT validate these additional Subscription
- Template Attributes and the client MUST NOT expect to find
- unsupported attributes from step #2 in such additional
- Subscription Attribute Groups.
-
-5.3. Subscription Template Attributes
-
- This section contains the Subscription Template Attributes defined
- for the Subscription and Printer objects.
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 18]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Table 1 below shows the Subscription Template Attributes and has two
- columns:
-
- - Attribute in Subscription Object: the name and attribute syntax of
- each Subscription Object Attribute that is a Subscription Template
- Attribute
-
- - Default and Supported Printer Attributes: the default attribute
- and supported Printer attributes that are associated with the
- attribute in column 1.
-
- The "notify-recipient-uri" attribute is for use with Push Delivery
- Methods. The "notify-pull-method" attribute is for use with Pull
- Delivery Methods.
-
- For Push Delivery Methods, a Printer MUST support all attributes in
- Table 1 below except for "notify-pull-method" and "notify-attributes"
- (and "notify-pull-method-supported" and "notify-attributes-
- supported"). For Pull Delivery Methods, a Printer MUST support all
- attributes in Table 1 below except for "notify-recipient-uri" and
- "notify-attributes" (and "notify-schemes-supported" and "notify-
- attributes-supported"). If a Printer supports both Push and Pull
- Delivery Methods, then it MUST support both "notify-recipient-uri"
- and "notify-pull-method" attributes.
-
- For Pull Delivery Methods, a client MUST supply "notify-recipient-
- uri" and MAY omit any of the rest of the attributes in column 1 of
- Table 1 in a Subscription Creation Request. For Push Delivery
- Methods, a client MUST supply "notify-pull-method" and MAY omit any
- of the rest of the attributes in column 1 of Table 1 in a
- Subscription Creation Request. A client MUST NOT supply both
- "notify-recipient-uri" and "notify-pull-method" attributes in the
- same Subscription Creation Request.
-
- Note: The Default and Supported Printer attributes listed in column
- 2 of Table 1 do not have separate sections in this specification
- defining their semantics. Instead, the section for the corresponding
- Subscription Object attribute (column 1 of Table 1) contains the
- semantics of these Printer attributes. This approach follows the
- precedence of the Job Template attributes in section 4.2 of [RFC2911]
- where the corresponding "xxx-default" and "xxx-supported" Printer
- attributes are defined in the same section as the "xxx" Job
- attribute.
-
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 19]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Table 1 - Subscription Template Attributes
-
- Attribute in Subscription Default and Supported Printer
- Object Attributes
-
- notify-recipient-uri (uri) * notify-schemes-supported (1setOf
- uriScheme)
- notify-pull-method (type2 notify-pull-method-supported (1setOf
- keyword) ** type2 keyword)
- notify-events (1setOf type2 notify-events-default (1setOf type2
- keyword) keyword)
- notify-events-supported (1setOf type2
- keyword)
- notify-max-events-supported
- (integer(2:MAX))
-
- notify-attributes (1setOf notify-attributes-supported (1setOf
- type2 keyword) type2 keyword)
- notify-user-data
- (octetString(63))
- notify-charset (charset) charset-supported (1setOf charset)
- notify-natural-language generated-natural-language-supported
- (naturalLanguage) (1setOf naturalLanguage)
- notify-lease-duration notify-lease-duration-default
- (integer(0:MAX)) (integer(0:67108863))
- notify-lease-duration-supported
- (1setOf (integer(0: 67108863) |
- rangeOfInteger(0:67108863)))
- notify-time-interval
- (integer(0:MAX))
-
- * "notify-recipient-uri" is for Push Delivery Methods only.
- ** "notify-pull-method" is for Pull Delivery Methods only.
-
-5.3.1. notify-recipient-uri (uri)
-
- This attribute's value is a URL, which is a special case of a URI.
- Its value consists of a scheme and an address. The address specifies
- the Notification Recipient and the scheme specifies the Push Delivery
- Method for each Event Notification associated with this Subscription
- Object.
-
- If a Printer supports any Push Delivery Methods, a Printer MUST
- support this attribute and return the value as supplied by the client
- (no case conversion or other canonicalization) in any operation
- response that includes this attribute.
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 20]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- For a Push Delivery Method, a client MUST supply this attribute in a
- Subscription Creation Operation. Thus there is no need for a default
- Printer attribute.
-
- The URI scheme of the value of this attribute on a Subscription
- object MUST be a value of the "notify-schemes-supported (1setOf
- uriScheme)" Printer attribute (see section 5.3.1.1). Note: According
- to [RFC2396] the ":" terminates the scheme and so is not part of the
- scheme. Therefore, values of the "notify-schemes-supported" Printer
- attribute do not include the ":" character.
-
- If the client supplies an unsupported scheme in the value of this
- attribute, then the Printer MUST NOT create the Subscription Object
- and MUST return the "notify-status-code" attribute with the 'client-
- error-uri-scheme-not-supported' value in the Subscription Attributes
- Group in the response.
-
-5.3.1.1. notify-schemes-supported (1setOf uriScheme)
-
- This attribute contains the URI schemes supported in the "notify-
- recipient-uri" Subscription Template attribute. See sections 5.1 and
- 5.2 for the behavior of "xxx-supported" Subscription Template Printer
- attributes.
-
-5.3.2. notify-pull-method (type2 keyword)
-
- This attribute's value is a type2 keyword indicating which Pull
- Delivery Method is to be used.
-
- Since a Printer MUST support the 'ippget' Pull Delivery Method
- [RFC3996] (see section 15), a Printer MUST support this attribute and
- return the value as supplied by the client in any operation response
- that includes this attribute.
-
- For a Pull Delivery Method, a client MUST supply this attribute in a
- Subscription Creation Operation. Thus there is no need for a default
- Printer attribute.
-
- The keyword value of this attribute on a Subscription object MUST be
- a value of the "notify-pull-method-supported (1setOf type2 keyword)"
- Printer attribute.
-
- If the client supplies an unsupported method in the value of this
- attribute, then the Printer MUST NOT create the Subscription Object
- and MUST return the "notify-status-code" attribute with the 'client-
- error-attributes-or-values-not-supported' value in the Subscription
- Attributes Group in the response.
-
-
-
-
-Herriot & Hastings Standards Track [Page 21]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-5.3.2.1. notify-pull-method-supported (1setOf type2 keyword)
-
- See sections 5.1 and 5.2 for the behavior of "xxx-supported"
- Subscription Template Printer attributes.
-
-5.3.3. notify-events (1setOf type2 keyword)
-
- This attribute contains a set of Subscribed Events. When an Event
- occurs and it "matches" a value of this attribute, the Printer
- delivers an Event Notification using information in the Subscription
- Object. The details of "matching" are described subsection 5.3.3.5.
-
- A Printer MUST support this attribute.
-
- A client MAY supply this attribute in a Subscription Creation
- Operation. If the client does not supply this attribute in
- Subscription Creation Operation, the Printer MUST populate this
- attribute on the Subscription Object with its "notify-events-default"
- attribute value.
-
- Each keyword value of this attribute on a Subscription Object MUST be
- a value of the "notify-events-supported (1setOf type2 keyword)"
- Printer attribute.
-
- The number of values of this attribute MUST NOT exceed the value of
- the "notify-max-events-supported" attribute. A Printer MUST support
- at least 2 values per Subscription Object. If the number of values
- supplied by a client in a Subscription Creation Operation exceeds the
- value of this attribute, the Printer MUST treat extra values as
- unsupported values and MUST use the value of 'successful-ok-too-
- many-events' for the "notify-status-code" attribute in the
- Subscription Attributes Group of the response.
-
-5.3.3.1. notify-events-default (1setOf type2 keyword)
-
- See sections 5.1 and 5.2 for the behavior of "xxx-default"
- Subscription Template Printer attributes.
-
-5.3.3.2. notify-events-supported (1setOf type2 keyword)
-
- See sections 5.1 and 5.2 for the behavior of "xxx-supported"
- Subscription Template Printer attributes.
-
-
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 22]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-5.3.3.3. notify-max-events-supported (integer(2:MAX))
-
- This attribute specified the maximum number of events that the
- Printer supports for the "notify-events" Subscription Template
- attribute. See sections 5.1 and 5.2 for the behavior of "xxx-
- supported" Subscription Template Printer attributes.
-
-5.3.3.4. Standard Values for Subscribed Events
-
- Each value of this attribute is a keyword and it specifies a
- Subscribed Event that represents certain changes. Some keywords
- represent a subset of changes of another keyword, e.g., 'job-
- completed' is an Event value which is a sub-value of 'job-state-
- change'. See section 5.3.3.5 for the case where this attribute
- contains both a value and a sub-value.
-
- The values in this section are divided into three categories: No
- Events, Job Events and Printer Events.
-
- A Printer MUST support the Events indicated as "REQUIRED" and MAY
- support the Events indicated as "OPTIONAL".
-
-5.3.3.4.1. No Events
-
- The standard and only keyword value for No Events is:
-
- 'none': REQUIRED - no Event Notifications for any Events. As the
- sole value of "notify-events-supported", this value means that the
- Printer does not support the delivery of Event Notifications. As
- the sole value of "notify-events-default", this value means that a
- client MUST specify the "notify-events" attribute in order for a
- Subscription Creation Operation to succeed. If the Printer
- receives this value as the sole value of a Subscription Creation
- Operation, it does not create a Subscription Object. If a Printer
- receives this value with other values of a Subscription Creation
- Operation, the Printer MUST treat this value as an unsupported
- value.
-
-5.3.3.4.2. Subscribed Printer Events
-
- The standard keyword values for Subscribed Printer Events are:
-
- 'printer-state-changed': REQUIRED - the Printer changed state from
- any state to any other state. Specifically, the value of the
- Printer's "printer-state", "printer-state-reasons" or "printer-
- is-accepting-jobs" attributes changed.
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 23]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- This Subscribed Event value has the following sub-values:
- 'printer-restarted' and 'printer-shutdown'. A client can listen
- for any of these sub-values if it doesn't want to listen to all
- printer-state changes:
-
- 'printer-restarted': OPTIONAL - when the printer is powered
- up.
-
- 'printer-shutdown': OPTIONAL - when the device is being
- powered down.
-
- 'printer-stopped: REQUIRED - when the printer stops printing,
- i.e., the value of the "printer-state" Printer attribute
- becomes 'stopped'.
-
- 'printer-config-changed': OPTIONAL - when the configuration of a
- Printer has changed, i.e., the value of the "printer-message-
- from-operator" or any "configuration" Printer attribute has
- changed. A "configuration" Printer attribute is an attribute
- which can change value because of some human interaction either
- direct or indirect, and which is not covered by one of the other
- Events in this section. Examples of "configuration" Printer
- attributes are any of the Job Template attributes, such as "xxx-
- supported", "xxx-ready" and "xxx-default". The client has to
- perform a Get-Printer-Attributes to find out the new values of
- these changed attributes. This Event is useful for GUI clients
- and drivers to update the available printer capabilities to the
- user.
-
- This Event value has the following sub-values: 'printer-media-
- changed' and 'printer-finishings-changed'. A client can listen
- for any of these sub-values if it doesn't want to listen to all
- printer-configuration changes:
-
- 'printer-media-changed': OPTIONAL - when the media loaded on
- a printer has been changed, i.e., the "media-ready"
- attribute has changed. This Event includes two cases: an
- input tray that goes empty and an input tray that receives
- additional media of the same type or of a different type.
- The client must check the "media-ready" Printer attribute
- (see [RFC2911] section 4.2.11) separately to find out what
- changed.
-
- 'printer-finishings-changed': OPTIONAL - when the finisher on
- a printer has been changed, i.e., the "finishings-ready"
- attribute has changed. This Event includes two cases: a
- finisher that goes empty and a finisher that is refilled
- (even if it is not full). The client must check the
-
-
-
-Herriot & Hastings Standards Track [Page 24]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- "finishings-ready" Printer attribute separately to find out
- what changed.
-
- 'printer-queue-order-changed': OPTIONAL - the order of jobs in the
- Printer's queue has changed, so that an application that is
- monitoring the queue can perform a Get-Jobs operation to determine
- the new order. This Event does not include when a job enters the
- queue (the 'job-created' Event covers that) and does not include
- when a job leaves the queue (the 'job-completed' Event covers
- that).
-
-5.3.3.4.3. Subscribed Job Events
-
- The standard keyword values for Subscribed Job Events are:
-
- 'job-state-changed': REQUIRED - the job has changed from any state
- to any other state. Specifically, the Printer delivers this Event
- whenever the value of the "job-state" attribute or "job-state-
- reasons" attribute changes. When a Job is removed from the Job
- Retention or Job History phases (see [RFC2911] section 4.3.7.1),
- no Event is generated.
-
- This Event value has the following sub-values: 'job-created',
- 'job-completed' and 'job-stopped'. A client can listen for any of
- these sub-values if it doesn't want to listen to all 'job-state
- changes'.
-
- 'job-created': REQUIRED - the Printer has accepted a Job
- Creation operation, a Restart-Job operation [RFC2911], or any
- job operation that creates a Job object from an existing Job
- object. The Printer populates the job's "time-at-creation"
- attribute value (see [RFC2911] section 4.3.14.1). The Printer
- puts the job in the 'pending', 'pending-held' or 'processing'
- states.
-
- 'job-completed': REQUIRED - the job has reached one of the
- completed states, i.e., the value of the job's "job-state"
- attribute has changed to: 'completed', 'aborted', or
- 'canceled'. The Job's "time-at-completed" and "date-time-at-
- completed" (if supported) attributes are set (see [RFC2911]
- section 4.3.14). When a Job completes, a Notification
- Recipient MAY query the Job using the Get-Job-Attributes
- operation. To allow such a query, the Printer retains the Job
- in the Job Retention and/or the Job History phases (see
- [RFC2911] section 4.3.7.1) for a suitable amount of time that
- depends on implementation and the Delivery Methods supported.
- The Printer also delivers this Event when a Job is removed with
- the Purge-Job operation (see [RFC2911] section 3.2.9). In this
-
-
-
-Herriot & Hastings Standards Track [Page 25]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- case, the Event Notification MUST report the 'job-state' as
- 'canceled' and the Job object is no longer present for query.
-
- 'job-stopped: OPTIONAL - when the job stops printing, i.e.,
- the value of the "job-state" Job attribute becomes
- 'processing-stopped'.
-
- 'job-config-changed': OPTIONAL - when the configuration of a job has
- changed, i.e., the value of the "job-message-from-operator" or any
- of the "configuration" Job attributes have changed. A
- "configuration" Job attribute is an attribute that can change
- value because of some human interaction either direct or indirect.
- Examples of "configuration" Job attributes are any of the job
- template attributes and the "job-name" attribute. The client
- performs a Get-Job-Attributes to find out the new values of the
- changed attributes. This Event is useful for GUI clients and
- drivers to update the job information to the user.
-
- 'job-progress': OPTIONAL - when the Printer has completed Printing a
- sheet. See the separate [RFC3381] specification for additional
- attributes that a Printer MAY deliver in an Event Notification
- caused by this Event. The "notify-time-interval" attribute
- affects this Event by causing the Printer NOT to deliver an Event
- Notification every time a 'job-progress' Events occurs. See
- section 5.3.9 for full details.
-
-5.3.3.5. Rules for Matching of Subscribed Events
-
- When an Event occurs, the Printer MUST find each Subscription object
- whose "notify-events" attribute "matches" the Event. The rules for
- "matching" of Subscribed Events are described separately for Printer
- Events and for Job Events. This section also describes some special
- cases.
-
-5.3.3.5.1. Rules for Matching of Printer Events
-
- Given that the Printer causes Printer Event E to occur, for each
- Per-Job or Per-Printer Subscription S in the Printer, if E equals a
- value of this attribute in S or E is a sub-value of a value of this
- attribute in S, the Printer MUST generate an Event Notification.
-
- Consider the example. There are three Subscription Objects each with
- the Subscribed Printer Event 'printer-state-changed'. Subscription
- Object A is a Per-Printer Subscription Object. Subscription Object B
- is a Per-Job Subscription Object for Job 1, and Subscription Object C
- is a Per-Job Subscription Object for Job 2. When the Printer enters
- the 'stopped' state, the Printer delivers an Event Notification to
- the Notification Recipients of Subscription Objects A, B, and C
-
-
-
-Herriot & Hastings Standards Track [Page 26]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- because this is a Printer Event. Note if Job 1 has already
- completed, the Printer would not deliver an Event Notification for
- its Subscription Object, even if Job 1 is retained in the Job
- Retention and/or the Job History phases (see [RFC2911] section
- 4.3.7.1).
-
-5.3.3.5.2. Rules for Matching of Job Events
-
- Given that Job J causes Job Event E to occur:
-
- 1. For each Per-Printer Subscription S in the Printer, if E equals a
- value of this attribute in S or E is a sub-value of a value of
- this attribute in S, the Printer MUST generate an Event
- Notification.
-
- 2. For each Per-Job Subscription S associated with Job J, if E equals
- a value of this attribute in S or E is a sub-value of a value of
- this attribute in S, the Printer MUST generate an Event
- Notification.
-
- 3. For each Per-Job Subscription S that is NOT associated Job J, if E
- equals a value of this attribute in S or E is a sub-value of a
- value of this attribute in, the Printer MUST NOT generate an Event
- Notification from S.
-
- Consider the example: There are three Subscription Objects listening
- for the Job Event 'job-completed'. Subscription Object A is a Per-
- Printer Subscription Object. Subscription Object B is a Per-Job
- Subscription Object for Job 1, and Subscription Object C is a Per-Job
- Subscription Object for Job 2. In addition, Per-Printer Subscription
- Object D is listening for the Job Event 'job-state-changed'. When
- Job 1 completes, the Printer delivers an Event Notification to the
- Notification Recipient of Subscription Object A (because it is Per-
- Printer) and Subscription Object B because it is a Per-Job
- Subscription Object associated with the Job generating the Event.
- The Printer also delivers an Event Notification to the Notification
- Recipient of Subscription Object D because 'job-completed' is a sub-
- value of 'job-state-changed' - the value that Subscription Object D
- is listening for. The Printer does not deliver an Event Notification
- to the Notification Recipients of Subscription Object C because it is
- a Per-Job Subscription Object associated with some Job other than the
- Job generating the Event.
-
-5.3.3.5.3. Special Cases for Matching Rules
-
- This section contains two rules for the special case where a single
- Event produces multiple Event Notifications destined for the same
- Notification Recipient. These two rules clarify whether a Printer
-
-
-
-Herriot & Hastings Standards Track [Page 27]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- should send multiple Event Notifications or consolidate them into a
- single Event Notification.
-
- If an Event matches Subscribed Events in two different Subscription
- Objects and the Printer would deliver two identical Event
- Notifications (except for the "notify-subscription-id" attribute) to
- the same Notification Recipient using the same Delivery Method, the
- Printer MUST deliver both Event Notifications. That is, the Printer
- MUST NOT try to consolidate seemingly identical Event Notifications
- that occur in separate Subscription objects. Incidentally, the
- Printer MUST NOT reject Subscription Creation Operations that would
- create this scenario.
-
- Consider the example: At the time a Job completes, there are two
- Per-Printer Subscription Objects A and B with the same Notification
- Recipient R. Subscription Object A has the Subscribed Job Event
- 'job-state-changed'. Subscription Object B has the Subscribed Job
- Event 'job-completed'. Both Subscription Objects match the Event
- 'job-completed'. The Printer delivers two Event Notifications to the
- Notification Recipient R. One with the value of 'job-state-changed'
- for the "notify-subscribed-event" attribute and the other with the
- value of 'job-completed' for the "notify-subscribed-event"
- attribute.
-
- If an Event matches two Subscribed Events in a single Subscription
- object (e.g., a value and its sub-value), a Printer MAY deliver one
- Event Notification for each matched value in the Subscription Object
- or it MAY deliver only a single Event Notification. The rules in
- sections 5.3.3.5.1 and 5.3.3.5.2 are purposefully flexible about the
- number of Event Notifications sent when Event E matches two or more
- values in a Subscription Object.
-
- Consider the example: At the time a Job completes, a Subscription
- Object A has two Subscribed Job Events 'job-state-changed' and 'job-
- completed'. Both Subscribed Job Events match the Event 'job-
- completed'. The Printer delivers either one or two Event
- Notifications to the Notification Recipient of Subscription Object A,
- depending on implementation. If it delivers two Event Notifications,
- one has the value of 'job-state-changed' for the "notify-
- subscribed-event" attribute, and the other has the value of 'job-
- completed' for the "notify-subscribed-event" attribute. If it
- delivers one Event Notification, it has the value of either 'job-
- state-changed' or 'job-completed' for the "notify-subscribed-event"
- attribute, depending on implementation. The algorithm for choosing
- such a value is implementation dependent.
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 28]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-5.3.4. notify-attributes (1setOf type2 keyword)
-
- This attribute contains a set of attribute names. When a Printer
- delivers a Machine Consumable Event Notification, it includes a fixed
- set of attributes (see section 9.1). If this attribute is present
- and the Event Notification is Machine Consumable, the Printer also
- includes the attributes specified by this attribute.
-
- A Printer MAY support this attribute.
-
- A client MAY supply this attribute in a Subscription Creation
- Operation. If the client does not supply this attribute in
- Subscription Creation Operation or the Printer does not support this
- attribute, the Subscription Object either (1) MAY contain the
- "notify-attributes" attribute with a 'none' value or (2) NEED NOT
- contain the attribute at all. There is no "notify-attributes-
- default" Printer attribute.
-
- Each keyword value of this attribute on a Subscription Object MUST be
- a value of the "notify-attributes-supported (1setOf type2 keyword)"
- Printer attribute (see section 5.3.4.1). The "notify-attributes-
- supported" MAY contain any Printer attribute, Job attribute or
- Subscription Object attribute that the Printer supports in an Event
- Notification. It MUST NOT contain any of the attributes in Section
- 9.1 that a Printer automatically puts in an Event Notification; it
- would be redundant. If a client supplies an attribute in Section
- 9.1, the Printer MUST treat it as an unsupported attribute value of
- the "notify-attributes" attribute.
-
- The following rules apply to each keyword value N of the "notify-
- attributes" attribute: If the value N names:
-
- a) a Subscription attribute, the Printer MUST use the attribute N in
- the Subscription Object that is being used to generate the Event
- Notification.
-
- b) a Job attribute and the Printer is generating an Event
- Notification from a Per-Job Subscription Object S, the Printer
- MUST use the attribute N in the Job object associated with S.
-
- c) a Job attribute and the Printer is generating an Event
- Notification from a Per-Printer Subscription Object and the Event
- is:
-
- - a Job Event, the Printer MUST use the attribute N in the Job
- object that caused the Event.
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 29]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- - a Printer Event, the Printer MUST use the attribute N in the
- active Job.
-
- If a Printer supports this attribute and a Subscription Object
- contains this attribute and the Delivery Method generates a Machine
- Consumable Event Notification, the Printer MUST include in each Event
- Notification:
-
- a) the attributes specified in section 9.1 and
-
- b) each attribute named by this attribute.
-
- The Printer MUST NOT use this attribute to generate a Human
- Consumable Event Notification.
-
-5.3.4.1. notify-attributes-supported (1setOf type2 keyword)
-
- See sections 5.1 and 5.2 for the behavior of "xxx-supported"
- Subscription Template Printer attributes.
-
-5.3.5. notify-user-data (octetString(63))
-
- This attribute contains opaque data that some Delivery Methods
- include in each Machine Consumable Event Notification. The opaque
- data might contain, for example:
-
- - the identity of the Subscriber
-
- - a path or index to some Subscriber information
-
- - a key that identifies to the Notification Recipient the ultimate
- recipient of the Event Notification
-
- - the id for a Notification Recipient that had previously registered
- with an Instant Messaging Service
-
- A Printer MUST support this attribute.
-
- A client MAY supply this attribute in a Subscription Creation
- Operation. If the client does not supply this attribute in the
- Subscription Creation Operation, the Subscription Object either (1)
- MAY contain the "notify-user-data" attribute with a zero length value
- or (2) NEED NOT contain the attribute at all. There is no "notify-
- user-data-default" Printer attribute.
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 30]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- There is no "notify-user-data-supported" Printer attribute. Rather,
- any octetString whose length does not exceed 63 octets is a supported
- value. If the length exceeds 63 octets, the Printer MUST treat it as
- an unsupported value.
-
-5.3.6. notify-charset (charset)
-
- This attribute specifies the charset to be used in the Event
- Notification content sent to the Notification Recipient, whether the
- Event Notification content is Machine Consumable or Human Consumable.
-
- A Printer MUST support this attribute.
-
- A client MAY supply this attribute in a Subscription Creation
- Operation. If the client does not supply this attribute in
- Subscription Creation Operation or supplies an unsupported value, the
- Printer MUST populate this attribute in the Subscription Object with
- the value of the "attributes-charset" operation attribute, which is a
- REQUIRED attribute in all IPP requests (see [RFC2911]). If the value
- of the "attributes-charset" attribute is unsupported, the Printer
- MUST populate this attribute in the Subscription Object with the
- value of the Printer's "charset-configured" attribute. There is no
- "notify-charset-default" Printer attribute.
-
- The value of this attribute on a Subscription Object MUST be a value
- of the "charset-supported (1setOf charset)" Printer attribute.
-
-5.3.7. notify-natural-language (naturalLanguage)
-
- This attribute specifies the natural language to be used in any human
- consumable text in the Event Notification content sent to the
- Notification Recipient, whether the Event Notification content is
- Machine Consumable or Human Consumable.
-
- A Printer MUST support this attribute.
-
- A client MAY supply this attribute in a Subscription Creation
- Operation. If the client does not supply this attribute in
- Subscription Creation Operation or supplies an unsupported value, the
- Printer MUST populate this attribute in the Subscription Object with
- the value of the "attributes-natural-language" operation attribute,
- which is a REQUIRED attribute in all IPP requests (see [RFC2911]
- section 3.1.4). If the value of the "attributes-natural-language"
- attribute is unsupported, the Printer MUST populate this attribute in
- the Subscription Object with the value of the Printer's "natural-
- language-configured" attribute (see [RFC2911] section 4.4.19). There
- is no "notify-natural-language-default" Printer attribute.
-
-
-
-
-Herriot & Hastings Standards Track [Page 31]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- The value of this attribute on a Subscription Object MUST be a value
- of the "generated-natural-language-supported (1setOf type2
- naturalLanguage)" Printer attribute (see [RFC2911] section 4.4.20).
-
-5.3.8. notify-lease-duration (integer(0:67108863))
-
- This attribute specifies the duration of the lease (in seconds)
- associated with the Per-Printer Subscription Object at the time the
- Subscription Object was created or the lease was renewed. The
- duration of the lease is infinite if the value is 0, i.e., the lease
- never expires. See section 5.4.3 on "notify-lease-expiration-time
- (integer(0:MAX))" for more details.
-
- This attribute is not present on a Per-Job Subscription Object
- because the Subscription Object lasts exactly as long as the
- associated Job object. See discussion of the 'job-completed' event
- in section 5.3.3.4.3 about retention of the Job object after
- completion.
-
- A Printer MUST support this attribute.
-
- For a Subscription Object Creation operation of a Per-Job
- Subscription Object, the client MUST NOT supply this attribute. If
- the client does supply this attribute, the Printer MUST treat it as
- an unsupported attribute.
-
- For a Subscription Creation Operation of a Per-Printer Subscription
- Object or a Renew-Subscription operation, a client MAY supply this
- attribute. If the client does not supply this attribute, the Printer
- MUST populate this attribute with its "notify-lease-duration-default"
- (0:67108863) attribute value. If the client supplies this attribute
- with an unsupported value, the Printer MUST populate this attribute
- with a supported value, and this value SHOULD be as close as possible
- to the value requested by the client. Note: this rule implies that a
- Printer doesn't assign the value of 0 (infinite) unless the client
- requests it.
-
- After the Printer has populated this attribute with a supported
- value, the value represents the "granted duration" of the lease in
- seconds and the Printer updates the value of the Subscription
- Object's "notify-lease-expiration-time" attribute as specified in
- section 5.4.3.
-
- The value of this attribute on a Subscription Object MUST be a value
- of the "notify-lease-duration-supported" (1setOf (integer(0:67108863)
- | rangeOfInteger(0:67108863))) Printer attribute.
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 32]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- A Printer MAY require authentication in order to return the value of
- 0 (the lease never expires) as one of the values of "notify-lease-
- duration-supported", and to allow 0 as a value of the "notify-lease-
- duration" attribute.
-
- Note: The maximum value 67,108,863 is 2 raised to the 26 power minus
- 1 and is about 2 years in seconds. The value is considerably less
- than MAX so that there is virtually no chance of an overflow when the
- Printer adds it to the Printer's "printer-up-time" attribute value
- (see [RFC2911] section 4.4.29) to produce the "notify-lease-
- expiration-time" Subscription Description attribute value (see
- section 5.4.3).
-
-5.3.8.1. notify-lease-duration-default (integer(0:67108863))
-
- See sections 5.1 and 5.2 for the behavior of "xxx-default"
- Subscription Template Printer attributes.
-
-5.3.8.2. notify-lease-duration-supported (1setOf (integer(0: 67108863) |
- rangeOfInteger(0:67108863)))
-
- See sections 5.1 and 5.2 for the behavior of "xxx-supported"
- Subscription Template Printer attributes.
-
-5.3.9. notify-time-interval (integer(0:MAX))
-
- The 'job-progress' Event occurs each time that a Printer completes a
- sheet. Some Notification Recipients do not want to receive an Event
- Notification every time this Event occurs. This attribute allows a
- Subscribing Client to request how often it wants to receive Event
- Notifications for 'job-progress' Events. The value of this attribute
- MAY be any nonnegative integer (0,MAX) indicating the minimum number
- of seconds between 'job-progress' Event Notifications.
-
- The Printer MUST support this attribute if and only if the Printer
- supports the 'job-progress' Event.
-
- A client MAY supply this attribute in a Subscription Creation
- Operation. If the client does not supply this attribute in the
- Subscription Creation Operation, the Subscription Object either (1)
- MAY contain the "notify-time-interval" attribute with a '0' value or
- (2) NEED NOT contain this attribute at all. There is no "notify-
- time-interval-default" Printer attribute.
-
- There is no "notify-time-interval-supported" Printer attribute.
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 33]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- If the 'job-progress' Event occurs and a Subscription Object contains
- the 'job-progress' Event as a value of the 'notify-events' attribute,
- there are two cases to consider:
-
- 1. This attribute is not present on the Subscription Object or has
- the value of 0. The Printer MUST generate and deliver an Event
- Notification (as is the case with other Events).
-
- 2. This attribute is present with a nonzero value of N:
-
- a) If the Printer has not sent an Event Notification for the
- 'job-progress' Event for the associated Subscription Object
- within the past N seconds, the Printer MUST deliver an Event
- Notification for the Event that just occurred. Note when the
- Printer completes the first page of a Job, this rule implies
- that the Printer delivers an Event Notification for a Per-Job
- Subscription Object.
-
- b) Otherwise, the Printer MUST NOT generate or deliver an Event
- Notification for the associated Subscription Object. The
- Printer MUST NOT increase the value of the "notify-sequence-
- number" Subscription Object attribute (i.e., the sequence of
- values of the "notify-sequence-number" attribute counts the
- Event Notifications that the Printer sent and not the Events
- that do not cause an Event Notification to be sent).
-
- It is RECOMMENDED that a Subscribing Client use this attribute when
- it subscribes to the 'job-progress' Event, and that the value be
- sufficiently large to limit the frequency with which the Printer
- delivers Event Notifications requests.
-
- This attribute MUST NOT effect any Events other than 'job-progress'.
-
-5.4. Subscription Description Attributes
-
- Subscription Description Attributes are those attributes that a
- Printer adds to a Subscription Object at the time of its creation.
-
- A Printer MUST support all attributes in this Table 2.
-
- A client MUST NOT supply the attributes in Table 2 in a Subscription
- Template Attributes Group of a Subscription Creation Operation.
- There are no corresponding default or supported attributes.
-
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 34]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Table 2 - Subscription Description Attributes
-
- Subscription Object attributes:
-
- notify-subscription-id (integer(1:MAX))
- notify-sequence-number (integer(0:MAX))
- notify-lease-expiration-time (integer(0:MAX))
- notify-printer-up-time (integer(1:MAX))
- notify-printer-uri (uri)
- notify-job-id (integer(1:MAX))
- notify-subscriber-user-name (name(MAX))
-
-5.4.1. notify-subscription-id (integer (1:MAX))
-
- This attribute identifies a Subscription Object instance with a
- number that is unique within the context of the Printer. The Printer
- generates this value at the time it creates the Subscription Object.
-
- A Printer MUST support this attribute.
-
- The Printer MAY assign the value of this attribute sequentially as it
- creates Subscription Objects. However, if there is no security on
- Subscription objects, sequential assignment exposes the system to a
- passive traffic monitoring threat.
-
- The Printer SHOULD avoid re-using recent values of this attribute
- during continuous operation of the Printer as well as across power
- cycles. Then a Subscribing Client is unlikely to find that a stale
- reference accesses a new Subscription Object.
-
- The 0 value is not permitted in order to allow for compatibility with
- "job-id" and with MIB table index values, which are recommended not
- to be 0.
-
-5.4.2. notify-sequence-number (integer (0:MAX))
-
- The value of this attribute indicates the number of times that the
- Printer has generated and attempted to deliver an Event Notification
- for this Subscription object. When an Event Notification contains
- this attribute, the Notification Recipient can determine whether it
- missed some Event Notifications (i.e., numbers skipped) or received
- duplicates (i.e., same number twice).
-
- A Printer MUST support this attribute.
-
- When the Printer creates a Subscription Object, it MUST populate this
- attribute with a value of 0. This value indicates that the Printer
- has not sent any Event Notifications for this Subscription Object.
-
-
-
-Herriot & Hastings Standards Track [Page 35]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Each time the Printer delivers a newly generated Event Notification,
- it MUST increase the value of this attribute by 1. For some Delivery
- Methods, the Printer MUST include this attribute in each Event
- Notification, and the value MUST be the value after it is increased
- by 1. That is, the value of this attribute in the first Event
- Notification after Subscription object creation MUST be 1, the second
- MUST be 2, etc. If a Delivery Method is defined such that the
- Notification Recipient returns a response, the Printer can re-try
- delivering an Event Notification a certain number of times with the
- same sequence number when the Notification Recipient fails to return
- a response.
-
- If a Subscription Object lasts long enough to reach the value of MAX,
- its next value MUST be 0, i.e., it wraps.
-
-5.4.3. notify-lease-expiration-time (integer(0:MAX))
-
- This attribute specifies the time in the future when the lease on the
- Per-Printer Subscription Object will expire, i.e., the "printer-up-
- time" value at which the lease will expire. If the value is 0, the
- lease never expires.
-
- A Printer MUST support this attribute.
-
- When the Printer creates a Per-Job Subscription Object, this
- attribute MUST NOT be present - the Subscription Object lasts exactly
- as long as the associated Job object. See also the discussion of the
- 'job-completed' event in section 5.3.3.4.3 about retention of the Job
- object after completion so that a Notification Recipient can query
- the Job object after receiving the 'job-completed' Event
- Notification.
-
- When the Printer creates a Per-Printer Subscription Object, it
- populates this attribute with a value that is the sum of the values
- of the Printer's "printer-up-time" attribute and the Subscription
- Object's "notify-lease-duration" attribute with the following
- exception. If the value of the Subscription Object's "notify-lease-
- duration" attribute is 0 (i.e., no expiration time), then the value
- of this attribute MUST be set to 0 (i.e., no expiration time).
-
- When the Printer powers up, it MUST populate this attribute in each
- persistent Subscription Object with a value using the algorithm in
- the previous paragraph.
-
- When the "printer-up-time" equals the value of this attribute, the
- Printer MUST delete the Subscription Object. A client can extend a
- lease of a Per-Printer Subscription Object with the Renew-
- Subscription operation (see section 11.2.6).
-
-
-
-Herriot & Hastings Standards Track [Page 36]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Note: In order to compute the number of seconds remaining in a lease
- for a Per-Printer Subscription Object, a client can subtract the
- Subscription's "notify-printer-up-time" attribute (see section 5.4.4)
- from the Subscription's "notify-lease-expiration-time" attribute.
-
-5.4.4. notify-printer-up-time (integer(1:MAX))
-
- This attribute is an alias for the Printer's "printer-up-time"
- attribute " (see [RFC2911] section 4.4.29). In other words, when
- this attribute is queried with the Get-Subscriptions or Get-
- Subscription-Attributes operations (see sections 11.2.4 and 11.2.5),
- the value returned is the current value of the Printer's "printer-
- up-time" attribute, rather than the time at which the Subscription
- Object was created.
-
- A Printer MUST support this attribute.
-
- When the Printer creates a Per-Job Subscription Object, this
- attribute MUST NOT be present. When the Printer creates a Per-
- Printer Subscription Object, this attribute MUST be present.
-
- Note: this attribute exists in a Per-Printer Subscription Object so
- that a client using the Get-Subscription-Attributes or Get-
- Subscription operations can convert the Per-Printer Subscription's
- "notify-lease-expiration-time" attribute to wall clock time with one
- request. If the value of the "notify-lease-expiration-time"
- attribute is not 0 (i.e., no expiration time), then the difference
- between the "notify-lease-expiration-time" attribute and the
- "notify-printer-up-time" is the remaining number of seconds on the
- lease from the current time.
-
-5.4.5. notify-printer-uri (uri)
-
- This attribute identifies the Printer object that created this
- Subscription Object.
-
- A Printer MUST support this attribute.
-
- During a Subscription Creation Operation, the Printer MUST populate
- this attribute with the value of the "printer-uri" operation
- attribute in the request. From the Printer URI, the client can, for
- example, determine what security scheme was used.
-
-5.4.6. notify-job-id (integer(1:MAX))
-
- This attribute specifies whether the containing Subscription Object
- is a Per-Job or Per-Printer Subscription Object, and for Per-Job
- Subscription Objects, it specifies the associated Job.
-
-
-
-Herriot & Hastings Standards Track [Page 37]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- A Printer MUST support this attribute.
-
- If this attribute is not present, the Subscription Object MUST be a
- Per-Printer Subscription. If this attribute is present, the
- Subscription Object MUST be a Per-Job Subscription Object and this
- attribute MUST identify the Job with which the Subscription Object is
- associated.
-
- Note: This attribute could be useful to a Notification Recipient that
- receives an Event Notification generated from a Per-Job Subscription
- Object and caused by a Printer Event. The Event Notification gives
- access to the Printer and the Subscription Object. The Event
- Notification gives access to the associated Job only via this
- attribute. See discussion of the 'job-completed' event in section
- 5.3.3.4.3 about retention of the Job object after completion so that
- a Notification Recipient can query the Job object after receiving the
- 'job-completed' Event Notification.
-
-5.4.7. notify-subscriber-user-name (name(MAX))
-
- This attribute contains the name of the user who performed the
- Subscription Creation Operation.
-
- A Printer MUST support this attribute.
-
- The Printer MUST populates this attribute with the most authenticated
- printable name that it can obtain from the authentication service
- over which the Subscription Creation Operation was received. The
- Printer uses the same mechanism for determining the value of this
- attribute as it does for a Job's "job-originating-user-name" (see
- [RFC2911] section 4.3.6).
-
- Note: To help with authentication, a Subscription Object may have
- additional private attributes about the user, e.g., a credential of a
- principal. Such private attributes are implementation-dependent and
- not defined in this document.
-
-6. Printer Description Attributes Related to Notification
-
- This section defines the Printer Description attributes that are
- related to Notification. Table 3 lists the Printer Description
- attributes, indicates the Printer support required for conformance,
- and whether or not the attribute is READ-ONLY (see section 3.1):
-
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 38]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Table 3 - Printer Description Attributes Associated with Notification
-
- Printer object attributes: REQUIRED READ-ONLY
-
- printer-state-change-time (integer(1:MAX)) No Yes
- printer-state-change-date-time (dateTime) No Yes
-
-6.1. printer-state-change-time (integer(1:MAX))
-
- This OPTIONAL attribute records the most recent time at which the
- 'printer-state-changed' Printer Event occurred whether or not any
- Subscription objects were listening for this event. This attribute
- helps a client or operator to determine how long the Printer has been
- in its current state.
-
- A Printer MAY support this attribute and if so, the attribute MUST be
- READ-ONLY.
-
- On power-up, the Printer MUST populate this attribute with the value
- of its "printer-up-time" attribute, so that it always has a value.
- Whenever the 'printer-state-changed' Printer Event occurs, the
- Printer MUST update this attribute with the value of the Printer's
- "printer-up-time" attribute.
-
-6.2. printer-state-change-date-time (dateTime)
-
- This OPTIONAL attribute records the most recent time at which the
- 'printer-state-changed' Printer Event occurred whether or not there
- were any Subscription Objects listening for this event. This
- attribute helps a client or operator to determine how long the
- Printer has been in its current state.
-
- A Printer MAY support this attribute and if so, the attribute MUST be
- READ-ONLY.
-
- On power-up, the Printer MUST populate this attribute with the value
- of its "printer-current-time" attribute, so that it always has a
- value (see [RFC2911] section 4.4.30 on "printer-current-time").
- Whenever the 'printer-state-changed' Printer Event occurs, the
- Printer MUST update this attribute with the value of the Printer's
- "printer-current-time" attribute.
-
-7. New Values for Existing Printer Description Attributes
-
- This section contains those attributes for which additional values
- are added.
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 39]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-7.1. operations-supported (1setOf type2 enum)
-
- The following "operation-id" values are added in order to support the
- new operations defined in this document:
-
- Table 4 - Operation-id assignments
-
- Value Operation Name
-
- 0x0016 Create-Printer-Subscriptions
- 0x0017 Create-Job-Subscriptions
- 0x0018 Get-Subscription-Attributes
- 0x0019 Get-Subscriptions
- 0x001A Renew-Subscription
- 0x001B Cancel-Subscription
-
-8. Attributes Only in Event Notifications
-
- This section contains those attributes that exist only in Event
- Notifications and do not exist in any objects.
-
-8.1. notify-subscribed-event (type2 keyword)
-
- This attribute indicates the Subscribed Event that caused the Printer
- to deliver this Event Notification. This attribute exists only in
- Event Notifications.
-
- This attribute MUST contain one of the values of the "notify-events"
- attribute in the Subscription Object, i.e., one of the Subscribed
- Event values. Its value is the Subscribed Event that "matches" the
- Event that caused the Printer to deliver this Event Notification.
- This Subscribed Event value may be identical to the Event or the
- Event may be a sub-value of the Subscribed Event. For example, the
- 'job-completed' Event (which is a sub-event of the 'job-state-
- changed' event) would cause the Printer to deliver an Event
- Notification for either the 'job-completed' or 'job-state-changed'
- Subscribed Events and to deliver the 'job-completed' or 'job-state-
- changed' value for this attribute, respectively. See section 5.3.3.5
- for the "matching" rules of Subscribed Events and for additional
- examples.
-
- The Delivery Method Document specifies whether the Printer includes
- the value of this attribute in an Event Notification.
-
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 40]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-8.2. notify-text (text(MAX))
-
- This attribute contains a Human Consumable text message (see section
- 9.2). This message describes the Event and is encoded as plain text,
- i.e., 'text/plain' with the charset specified by Subscription
- Object's "notify-charset" attribute.
-
- Note: this attribute contains a text message only and must not
- contain any encoding information, such as 'text/plain'. The
- 'text/plain' encoding is implicit and thus the charset must be
- specified by an alternate mechanism, namely the "notify-charset"
- attribute.
-
- The Delivery Method Document specifies whether the Printer includes
- this attribute in an Event Notification.
-
-9. Event Notification Content
-
- This section defines the Event Notification content that the Printer
- delivers when an Event occurs.
-
- When an Event occurs, the Printer MUST find each Subscription object
- whose "notify-events" attribute "matches" the Event. See section
- 5.3.3.5 for details on "matching". For each matched Subscription
- Object, the Printer MUST create an Event Notification with the
- content and format that the Delivery Method Document specifies. The
- content contains the value of attributes specified by the Delivery
- Method Document. The Printer obtains the values immediately after
- the Event occurs. For example, if the "printer-state" attribute
- changes from 'idle' to 'processing', the Event 'printer-state-
- changed' occurs and the Printer puts various attributes into the
- Event Notification, including "printer-up-time" and "printer-state"
- with the values that they have immediately after the Event occurs,
- i.e., the value of "printer-state" is 'processing'.
-
- Event Notification Ordering:
-
- When a Printer delivers Event Notifications, the Event Notifications
- from any given Subscription Object MUST be in time stamp order, i.e.,
- in order of increasing "printer-up-time" attribute value in the Event
- Notification (see Table 5). These Event Notifications MAY be
- interleaved with those from other Subscription Objects, as long as
- those others are also in time stamp order. The Printer MUST observe
- these ordering requirements whether delivering multiple pending
- Events as multiple separate Event Notifications or together in a
- single Compound Event Notification.
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 41]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- If a Subscribing Client wants the Printer to deliver certain Event
- Notifications in time stamp order, the Subscribing Client uses a
- single Subscription Object. Even so, depending on the underlying
- transport, the actual order that a Notification Recipient receives
- separate Event Notifications may differ from the order sent by the
- Printer (e.g., email).
-
- Example: Consider two Per-Printer Subscription Objects: SO1 and SO2.
- SO1 requests 'job-state-changed' events and SO2 requests 'printer-
- state-changed' events. The number in parens is the time stamp. The
- following Event Notification sequences are the only ones that conform
- to the ordering requirements for the Printer to deliver the Event
- Notifications:
-
- (a) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO1:
- 'job-completed' (1009), SO2: 'printer-stopped' (1005)
-
- (b) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO2:
- 'printer-stopped' (1005), SO1: 'job-completed' (1009)
-
- (c) SO1: 'job-created' (1000), SO2: 'printer-stopped' (1005), SO1:
- 'job-stopped' (1005), SO1: 'job-completed' (1009)
-
- (d) SO2: 'printer-stopped (1005), SO1: 'job-created' (1000), SO1:
- 'job-stopped' (1005), SO1: 'job-completed' (1009)
-
- Examples (b) and (c) are interleaved; examples (a) and (d) are not
- interleaved and are not appropriate for some Delivery Methods.
-
- If two different Events occur simultaneously, or nearly so (e.g.,
- "printer-up-time" has the same value for both), the Printer MUST
- create a separate Event Notification for each Event, even if the
- associated Subscription Object is the same for both Events. However,
- the Printer MAY combine these distinct Event Notifications into a
- single Compound Event Notification if the Delivery Method supports
- Compound Event Notifications. For example, suppose that two nearly-
- simultaneously Events represent two successive 'printer-state-
- changed' Events, one from 'idle' to 'processing' and another from
- 'processing' to 'stopped'. These two Events have the same name but
- are different instances of the Event. Then the Printer MUST create a
- separate Event Notification for each Event and SHOULD accurately
- report the "printer-state" of the first Event as 'processing' and the
- second Event as 'stopped'.
-
- If a Subscription Object contains more than one Subscribed Event, and
- several Events occur in quick succession each matching a different
- Subscribed Event in the Subscription Object, the Printer MUST NOT
- generate a single Event Notification from several of these Events,
-
-
-
-Herriot & Hastings Standards Track [Page 42]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- but MAY combine distinct Event Notifications into a single Compound
- Event Notification if the Delivery Method supports Compound Event
- Notifications.
-
- After the Printer has created the Event Notification, the Printer
- delivers it via either a:
-
- Push Delivery Method: The Printer delivers the Event Notification
- shortly after an Event occurs. For some Push Delivery Methods,
- the Notification Recipient MUST deliver a response; for others it
- MUST NOT deliver a response.
-
- Pull Delivery Method: The Printer saves Event Notifications for
- some Event Life and expects the Notification Recipient to request
- Event Notifications. The Printer returns the Event Notifications
- in a response to such a request.
-
- If an error that meets the following conditions occurs, the Printer
- MUST cancel the Subscription Object.
-
- a) the error occurs during the delivering of an Event Notification
- generated from Subscription Object S AND
-
- b) the error would continue to occur every time the Printer delivers
- an Event Notification generated from Subscription Object S in the
- future.
-
- For example, if the address of the "notify-recipient-uri" of
- Subscription Object A references a non-existent target and the
- Printer determines this fact, it MUST delete Subscription Object A.
-
- The next two sections describe the values that a Printer delivers in
- the content of Machine Consumable and Human Consumable Event
- Notifications, respectively.
-
- The tables in the sub-sections of this section contain the following
- columns:
-
- a) Source Value: the name of the attribute that supplies the value
- for the Event Notification. Asterisks in this field refer to a
- note below the table.
-
- b) Delivers: if the Printer supports the value (column 1) on the
- Source Object (column 3) the Delivery Method MUST specify:
-
- MUST: that the Printer MUST deliver the value.
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 43]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- SHOULD: either that the Printer MUST deliver the value or that
- the value is incompatible with the Delivery Method.
-
- MAY: that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT,
- or NEED NOT deliver the value. The Delivery Method specifies
- the level of conformance for the Printer.
-
- c) Source Object: the object from which the source value comes. If
- the object is "Event Notification", the Printer fabricates the
- value when it delivers the Event Notification. See section 8.
-
-9.1. Content of Machine Consumable Event Notifications
-
- This section defines the attributes that a Delivery Method MUST
- mention in a Delivery Method Document when specifying the Machine
- Consumable Event Notification's contents.
-
- This document does not define the order of attributes in Event
- Notifications. However, Delivery Method Documents MAY define the
- order of some or all of the attributes.
-
- A Delivery Method Document MUST specify additional attributes (if
- any) that a Printer implementation delivers in a Machine Consumable
- Event Notification.
-
- Notification Recipients MUST be able to accept Event Notifications
- containing attributes they do not recognize. What a Notification
- Recipient does with an unrecognized attribute is implementation-
- dependent. Notification Recipients MAY attempt to display
- unrecognized attributes anyway or MAY ignore them.
-
- The next three sections define the attributes in Event Notification
- Contents that are:
-
- 1. for all Events
-
- 2. for Job Events only
-
- 3. for Printer Events only
-
-9.1.1. Event Notification Content Common to All Events
-
- This section lists the attributes that a Delivery Method Document
- MUST specify for all Events.
-
- Table 5 lists potential values in each Event Notification.
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 44]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Table 5 - Attributes in Event Notification Content
-
- Source Value Delivers Source Object
-
- notify-subscription-id (integer(1:MAX)) MUST Subscription
- notify-printer-uri (uri) MUST Subscription
- notify-subscribed-event (type2 keyword) MUST Event
- Notification
- printer-up-time (integer(MIN:MAX)) MUST Printer
- printer-current-time (dateTime) * MUST Printer
- notify-sequence-number (integer (0:MAX)) SHOULD Subscription
- notify-charset (charset) SHOULD Subscription
- notify-natural-language (naturalLanguage) SHOULD Subscription
- notify-user-data (octetString(63)) ** SHOULD Subscription
- notify-text (text) SHOULD Event
- Notification
- attributes from the "notify-attributes" MAY Printer
- attribute ***
- attributes from the "notify-attributes" MAY Job
- attribute ***
- attributes from the "notify-attributes" MAY Subscription
- attribute ***
-
- *A Printer MUST deliver this value only if and only if it supports
- the Printer's "printer-current-time" attribute.
-
- ** If the Subscription Object does not contain a "notify-user-data"
- attribute and the Delivery Method Document REQUIRES the Printer to
- deliver the "notify-user-data" source value in the Event
- Notification, the Printer MUST deliver an octet-string of length 0.
-
- *** The last three rows represent additional attributes that a client
- MAY request via the "notify-attributes" attribute. A Printer MAY
- support the "notify-attributes" attribute. The Delivery Method MUST
- say that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, or NEED
- NOT support the "notify-attributes" attribute and specific values of
- this attribute. The Delivery Method MAY say that support for the
- "notify-attributes" is conditioned on support of the attribute by the
- Printer or it MAY say that Printer MUST support the "notify-
- attributes" attribute if the Printer supports the Delivery Method.
-
-9.1.2. Additional Event Notification Content for Job Events
-
- This section lists the additional attributes that a Delivery Method
- Document MUST specify for Job Events. See Table 6.
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 45]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Table 6 - Additional Event Notification Content for Job Events
-
- Source Value Delivers Source
- Object
-
- job-id (integer(1:MAX)) MUST Job
- job-state (type1 enum) MUST Job
- job-state-reasons (1setOf type2 keyword) MUST Job
- job-impressions-completed (integer(0:MAX)) * MUST Job
-
- * The Printer MUST deliver the "job-impressions-completed" attribute
- in an Event Notification only for the combinations of Events and
- Subscribed Events shown in Table 7.
-
- Table 7 - Combinations of Events and Subscribed Events for "job-
- impressions-completed"
-
- Job Event Subscribed Job Event
-
- 'job-progress' 'job-progress'
- 'job-completed' 'job-completed'
- 'job-completed' 'job-state-changed'
-
-9.1.3. Additional Event Notification Content for Printer Events
-
- This section lists the additional attributes that a Delivery Method
- Document MUST specify for Printer Events. See Table 8.
-
- Table 8 - Additional Event Notification Content for Printer Events
-
- Source Value Delivers Source Object
-
- printer-state (type1 enum) MUST Printer
- printer-state-reasons (1setOf type2 MUST Printer
- keyword)
- printer-is-accepting-jobs (boolean) MUST Printer
-
-9.2. Content of Human Consumable Event Notification
-
- This section defines the information that a Delivery Method MUST
- mention in a Delivery Method Document when specifying the Human
- Consumable Event Notifications contents or the value of the "notify-
- text" attribute.
-
- Such a Delivery Method MUST specify the following information and a
- Printer SHOULD deliver it:
-
- a) the Printer name (see Table 9)
-
-
-
-Herriot & Hastings Standards Track [Page 46]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- b) the time of the Event (see Table 11)
-
- c) for Printer Events only:
-
- i) the Event (see Table 10) and/or Printer state information (see
- Table 14)
-
- d) for Job Events only:
-
- i) the job identity (see Table 12)
-
- ii) the Event (see Table 10) and/or Job state information (see
- Table 13)
-
- The subsections of this section specify the attributes that a Printer
- MUST use to obtain this information.
-
- A Delivery Method Document MUST specify additional information (if
- any) that a Printer implementation delivers in a Human Consumable
- Event Notification or in the "notify-text" attribute.
-
- A client MUST NOT request additional attributes via the "notify-
- attributes" attribute because this attribute works only for Machine
- Consumable Event Notifications.
-
- Notification Recipients MUST NOT expect to be able to parse the Human
- Consumable Event Notification contents or the value of the "notify-
- text" attribute.
-
- The next three sections define the attributes in Event Notification
- Contents that are:
-
- a) for all Events
- b) for Job Events only
- c) for Printer Events only
-
-9.2.1. Event Notification Content Common to All Events
-
- This section lists the source of the information that a Delivery
- Method MUST specify for all Events.
-
- There is a separate table for each piece of information. Each row in
- the table represents a source value for the information and the
- values are listed in order of preference, with the first one being
- the preferred one. An implementation SHOULD use the source value
- from the earliest row in each table. It MAY use the source value
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 47]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- from another row instead, or it MAY combine the source values from
- several rows. An implementation is free to determine the best way to
- present this information.
-
- In all tables of this section, all rows contain a "MAY" in order to
- state that the Delivery Method specifies the conformance.
-
- Table 9 lists the source of the information for the Printer Name.
- The "printer-name" is more user-friendly unless the Notification
- Recipient is in a place where the Printer name is not meaningful.
- For example, an implementation could have the intelligence to deliver
- the value of the "printer-name" attribute to a Notification Recipient
- that can access the Printer via value of the "printer-name" attribute
- and otherwise deliver the value of the "notify-printer-uri"
- attribute.
-
- Table 9 - Printer Name in Event Notification Content
-
- Source Value Delivers Source Object
-
- printer-name (name(127)) MAY Printer
- notify-printer-uri (uri) MAY Subscription
-
-
- Table 10 lists the source of the information for the Event name. A
- Printer MAY combine this information with state information described
- for Jobs in Table 13 or for Printers in Table 14.
-
- Table 10 - Event Name in Event Notification Content
-
- Source Value Delivers Source Object
-
- notify-subscribed-event (type2 keyword) MAY Subscription
-
- Table 11 lists the source of the information for the time that the
- Event occurred. A Printer can deliver this value only if it supports
- the Printer's "printer-current-time" attribute. If a Printer does
- not support the "printer-current-time" attribute, it MUST NOT deliver
- the "printer-up-time" value instead, since it is not an allowed
- option for human consumable information.
-
- Table 11 - Event Time in Event Notification Content
-
- Source Value Delivers Source Object
-
- printer-current-time (dateTime) MAY Printer
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 48]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-9.2.2. Additional Event Notification Content for Job Events
-
- This section lists the source of the additional information that a
- Delivery Method MUST specify for Job Events.
-
- Table 12 lists the source of the information for the job name. The
- "job-name" is likely more meaningful to a user than "job-id".
-
- Table 12 - Job Name in Event Notification Content
-
- Source Value Delivers Source Object
-
- job-name (name(MAX)) MAY Job
- job-id (integer(1:MAX)) MAY Job
-
- Table 13 lists the source of the information for the job state. If a
- Printer supports the "job-state-message" and "job-detailed-state-
- message" attributes, it SHOULD use those attributes for the job state
- information, otherwise, it should fabricate such information from the
- "job-state" and "job-state-reasons". For some Events, a Printer MAY
- combine this information with Event information.
-
- Table 13 - Job State in Event Notification Content
-
- Source Value Delivers Source
- Object
-
- job-state-message (text(MAX)) MAY Job
- job-detailed-status-messages (1setOf text(MAX)) MAY Job
- job-state (type1 enum) MAY Job
- job-state-reasons (1setOf type2 keyword) MAY Job
-
-9.2.3. Additional Event Notification Content for Printer Events
-
- This section lists the source of the additional information that a
- Delivery Method MUST specify for Printer Events.
-
- Table 14 lists the source of the information for the printer state.
- If a Printer supports the "printer-state-message", it SHOULD use that
- attribute for the job state information, otherwise it SHOULD
- fabricate such information from the "printer-state" and "printer-
- state-reasons". For some Events, a Printer MAY combine this
- information with Event information.
-
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 49]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Table 14 - Printer State in Event Notification Content
-
- Source Value Delivers Source
- Object
-
- printer-state-message (text(MAX)) MAY Printer
- printer-state (type1 enum) MAY Printer
- printer-state-reasons (1setOf type2 keyword) MAY Printer
- printer-is-accepting-jobs (boolean) MAY Printer
-
-10. Delivery Methods
-
- A Delivery Method is the mechanism, i.e., protocol, by which the
- Printer delivers an Event Notification to a Notification Recipient.
- There are several potential Delivery Methods for Event Notifications,
- standardized, as well as proprietary. This specification REQUIRES
- that the 'ippget' Pull Delivery Method [RFC3996] be supported.
- Conforming implementations MAY support additional Push or Pull
- Delivery Methods as well. This document does not define any of these
- delivery mechanisms. Each Delivery Method MUST be defined in a
- Delivery Method Document that is separate from this document. New
- Delivery Methods will be created as needed using an extension to the
- registration procedures defined in [RFC2911]. Such documents are
- registered with IANA (see section 23.7.3).
-
- The following sorts of Delivery Methods are possible:
-
- - The Notification Recipient polls for Event Notifications at
- intervals directed by the Printer
-
- - The Printer delivers Event Notifications to the Notification
- Recipient using http as the transport.
-
- - The Printer delivers an email message.
-
- This section specifies how to define a Delivery Method Document and
- what to put in such a document.
-
- A Delivery Method Document MUST contain an exact copy of the
- following paragraph, caption and table. In addition, column 2 of the
- table in the Delivery Method Document MUST contain answers to
- questions in column 1 for the Delivery Method. Also, the Delivery
- Method document MUST contain a reference to this document and call
- that reference [RFC3995] because the table contains an [RFC3995]
- reference.
-
- If a Printer supports this Delivery Method, the following are its
- characteristics.
-
-
-
-Herriot & Hastings Standards Track [Page 50]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Table 15 - Information about the Delivery Method
-
- Document Method Conformance Requirement Delivery Method
- Realization
-
- 1. What is the URL scheme name for the Push Delivery Method or the
- keyword method name for the Pull Delivery Method?
-
- 2. Is the Delivery Method REQUIRED, RECOMMENDED, or OPTIONAL for an
- IPP Printer to support?
-
- 3. What transport and delivery protocols does the Printer use to
- deliver the Event Notification Content, i.e., what is the entire
- network stack?
-
- 4. Can several Event Notifications be combined into a Compound Event
- Notification?
-
- 5. Is the Delivery Method initiated by the Notification Recipient
- (pull), or by the Printer (push)?
-
- 6. Is the Event Notification content Machine Consumable or Human
- Consumable?
-
- 7. What section in this document answers the following question?
- For a Machine Consumable Event Notification, what is the
- representation and encoding of values defined in section 9.1 of
- [RFC3995] and the conformance requirements thereof? For a Human
- Consumable Event Notification, what is the representation and
- encoding of pieces of information defined in section 9.2 of
- [RFC3995] and the conformance requirements thereof?
-
- 8. What are the latency and reliability of the transport and
- delivery protocol?
-
- 9. What are the security aspects of the transport and delivery
- protocol, e.g., how it is handled in firewalls?
-
- 10. What are the content length restrictions?
-
- 11. What are the additional values or pieces of information that a
- Printer delivers in an Event Notification content and the
- conformance requirements thereof?
-
- 12. What are the additional Subscription Template and/or
- Subscription Description attributes and the conformance
- requirements thereof?
-
-
-
-
-Herriot & Hastings Standards Track [Page 51]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- 13. What are the additional Printer Description attributes and the
- conformance requirements thereof?
-
-11. Operations for Notification
-
- This section defines all of the operations for Notification. Section
- 7.1 assigns the "operation-id" for each operation. The following two
- sub-sections define Subscription Creation Operations, and other
- operations.
-
-11.1. Subscription Creation Operations
-
- This section defines the Subscription Creation Operations. The first
- section on Create-Job-Subscriptions gives most of the information.
- The other Subscription Creation Operations refer to the section on
- Create-Job-Subscriptions, even though the Create-Job-Subscriptions
- operation is the only OPTIONAL operation in this document (see
- section 12).
-
- A Printer MUST support Create-Printer-Subscriptions and the
- Subscription Template Attributes Group in Job Creation operations.
- It MAY support Create-Job-Subscriptions operations.
-
-11.1.1. Create-Job-Subscriptions Operation
-
- The operation creates one or more Per-Job Subscription Objects. The
- client supplies one or more Subscription Template Attributes Groups
- each containing one or more of Subscription Template Attributes
- (defined in section 5.3).
-
- Except for errors, the Printer MUST create exactly one Per-Job
- Subscription Object from each Subscription Template Attributes Group
- in the request, even if the newly created Subscription Object would
- have identical behavior to some existing Subscription Object. The
- Printer MUST associate each newly created Per-Job Subscription Object
- with the target Job, which is specified by the "notify-job-id"
- operation attribute.
-
- The Printer MUST accept the request in any of the target job's 'not-
- completed' states, i.e., 'pending', 'pending-held', 'processing', or
- 'processing-stopped'. The Printer MUST NOT change the job's "job-
- state" attribute because of this operation. If the target job is in
- any of the 'completed' states, i.e., 'completed', 'canceled', or
- 'aborted, then the Printer MUST reject the request and return the
- 'client-error-not-possible' status code; the response MUST NOT
- contain any Subscription Attribute Groups.
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 52]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Access Rights: To create Per-Job Subscription Objects, the
- authenticated user (see [RFC2911] section 8.3) performing this
- operation MUST (1) be the job owner, (2) have Operator or
- Administrator access rights for this Printer (see [RFC2911] sections
- 1 and 8.5), or (3) be otherwise authorized by the Printer's
- administrator-configured security policy to create Per-Job
- Subscription Objects for the target job. Otherwise the Printer MUST
- reject the operation and return: the 'client-error-forbidden',
- 'client-error-not-authenticated', or 'client-error-not-authorized'
- status code as appropriate.
-
-11.1.1.1. Create-Job-Subscriptions Request
-
- The following groups of attributes are part of the Create-Job-
- Subscriptions Request:
-
- Group 1: Operation Attributes
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in [RFC2911] section 3.1.4.1.
-
- Target:
- The "printer-uri" attribute which defines the target for this
- operation as described in [RFC2911] section 3.1.5.
-
- Requesting User Name:
- The "requesting-user-name" attribute SHOULD be supplied by the
- client as described in [RFC2911] section 8.3.
-
-11.1.1.1.1. notify-job-id (integer(1:MAX))
-
- The client MUST supply this attribute and it MUST specify the Job
- object to associate the Per-Job Subscription with. The value of
- "notify-job-id" MUST be the value of the "job-id" of the associated
- Job object. If the client does not supply this attribute, the
- Printer MUST reject this request with a 'client-error-bad-request'
- status code.
-
- Group 2-N: Subscription Template Attributes
-
- For each occurrence of this group:
-
- The client MUST supply one or more Subscription Template
- Attributes in any order. See section 5.3 for a description of
- each such attribute. See section 5.2 for details on processing
- these attributes.
-
-
-
-
-Herriot & Hastings Standards Track [Page 53]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-11.1.1.2. Create-Job-Subscriptions Response
-
- The Printer MUST return to the client the following sets of
- attributes as part of a Create-Job-Subscriptions response:
-
- Group 1: Operation Attributes
-
- Status Message:
- In addition to the REQUIRED status code returned in every
- response, the response OPTIONALLY includes a "status-message"
- (text(255)) and/or a "detailed-status-message" (text(MAX))
- operation attribute as described in [RFC2911] sections 13 and
- 3.1.6.
-
- In this group, the Printer can return any status codes defined in
- [RFC2911] and section 12. The following is a description of the
- important status codes:
-
- successful-ok: the Printer created all Subscription Objects
- requested (see [RFC2911]).
-
- successful-ok-ignored-subscriptions: the Printer created some
- Subscription Objects requested but some failed. The
- Subscription Attributes Groups with a "notify-status-code"
- attribute are the ones that failed (see section 12.1).
-
- client-error-ignored-all-subscriptions: the Printer created no
- Subscription Objects requested and all failed. The
- Subscription Attributes Groups with a "notify-status-code"
- attribute are the ones that failed (see section 12.2).
-
- client-error-not-possible: For this operation and other Per-Job
- Subscription operations, this error can occur because the
- specified Job has already completed (see [RFC2911], whether or
- not the Job is retained in the Job Retention and/or Job History
- phases (see [RFC2911] section 4.3.7.1).
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in [RFC2911] section 3.1.4.2.
-
- Group 2: Unsupported Attributes
-
- See [RFC2911] section 3.1.7 for details on returning Unsupported
- Attributes. This group does not contain any unsupported
- Subscription Template Attributes; they are returned in the
- Subscription Attributes Group (see below).
-
-
-
-
-Herriot & Hastings Standards Track [Page 54]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Group 3-N: Subscription Attributes
-
- These groups MUST be returned unless the Printer is unable to
- interpret the entire request, e.g., the "status-code" parameter
- returned in Group 1 has the value: 'client-error-bad-request'.
-
- "notify-status-code" (type2 enum):
- Indicates the status of this subscription (see section 13 for
- the status code definitions). Section 5.2 defines when this
- attribute MUST be present in this group.
-
- See section 5.2 for details on the contents of each occurrence of
- this group.
-
-11.1.2. Create-Printer-Subscriptions operation
-
- The operation is identical to Create-Job-Subscriptions with
- exceptions noted in this section.
-
- The operation creates Per-Printer Subscription Objects instead of
- Per-Job Subscription Objects, and associates each newly created Per-
- Printer Subscription Object with the Printer specified by the
- operation target rather than with a specific Job.
-
- The Printer MUST accept the request in any of its states, i.e.,
- 'idle', 'processing', or 'stopped'. The Printer MUST NOT change its
- "printer-state" attribute because of this operation.
-
- Access Rights: To create Per-Printer Subscription Objects, the
- authenticated user (see [RFC2911] section 8.3) performing this
- operation MUST have (1) Operator or Administrator access rights for
- this Printer (see [RFC2911] sections 1 and 8.5), or (2) be otherwise
- authorized by the Printer's administrator-configured security policy
- to create Per-Printer Subscription Objects for this Printer.
- Otherwise, the Printer MUST reject the operation and return: the
- 'client-error-forbidden', 'client-error-not-authenticated', or
- 'client-error-not-authorized' status code as appropriate.
-
-11.1.2.1. Create-Printer-Subscriptions Request
-
- The groups are identical to the Create-Job-Subscriptions (see section
- 11.1.1.1) except that the Operation Attributes group MUST NOT contain
- the "notify-job-id" attribute. If the client does supply the
- "notify-job-id" attribute, then the Printer MUST treat it as any
- other unsupported Operation attribute and MUST return it in the
- Unsupported Attributes group.
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 55]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-11.1.2.2. Create-Printer-Subscriptions Response
-
- The groups are identical to the Create-Job-Subscriptions (see section
- 11.1.1.2).
-
-11.1.3. Job Creation Operations - Extensions for Notification
-
- This document extends the Job Creation operations (see section 3.2)
- to create Subscription Objects as a part of the operation.
-
- The Job Creation operations are identical to Create-Job-Subscriptions
- operation with exceptions noted in this section.
-
- Unlike the Create-Job-Subscriptions operation, a Job Creation
- operation associates the newly created Subscription Objects with the
- Job object created by this operation. The operation succeeds if and
- only if the Job creation succeeds. If the Printer does not create
- some or all of the requested Subscription Objects, the Printer MUST
- return a 'successful-ok-ignored-subscriptions' status-code instead
- of a 'successful-ok' status-code, but the Printer MUST NOT reject the
- operation because of a failure to create Subscription Objects.
-
- If the Job Creation operation includes a Job Template group, the
- client MUST supply it after the Operation Attributes group and before
- the first Subscription Template Attributes Group.
-
- If a Printer does not support this Notification specification, then
- it MUST treat the Subscription Attributes Group like an unknown group
- and ignore it (see [RFC2911] section 5.2.2). Because the Printer
- ignores the Subscription Attributes Group, it doesn't return them in
- the response either, thus indicating to the client that the Printer
- doesn't support Notification.
-
- After completion of a successful Job Creation operation, the Printer
- generates a 'job-created' event (see section 5.3.3.4.3).
-
- Access Rights: To create Per-Job Subscription Objects, the
- authenticated user (see [RFC2911] section 8.3) performing this
- operation MUST either have permission to create Jobs on the Printer
- or have Operator or Administrator access rights for this Printer (see
- [RFC2911] sections 1 and 8.5). Otherwise the Printer MUST reject the
- operation and return: the 'client-error-forbidden', 'client-error-
- not-authenticated', or 'client-error-not-authorized' status code as
- appropriate.
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 56]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-11.1.3.1. Job Creation Request
-
- The groups for this operation are sufficiently different from the
- Create-Job-Subscriptions operation that they are all presented here.
- The following groups of attributes are supplied as part of a Job
- Creation Request:
-
- Group 1: Operation Attributes
-
- Same as defined in [RFC2911] for Print-Job, Print-URI, and
- Create-Job requests.
-
- Group 2: Job Template Attributes
-
- The client OPTIONALLY supplies a set of Job Template attributes as
- defined in [RFC2911] section 4.2.
-
- Group 3 to N: Subscription Template Attributes
-
- The same as Group 2-N in Create-Job-Subscriptions. See section
- 11.1.1.1.
-
- Group N+1: Document Content (Print-Job only)
-
- The client MUST supply the document data to be processed.
-
-11.1.3.2. Job Creation Response
-
- The Printer MUST return to the client the following sets of
- attributes as part of a Print-Job, Print-URI, and Create-Job
- Response:
-
- Group 1: Operation Attributes
-
- Status Message:
-
- As defined in [RFC2911] for Print-Job, Print-URI, and Create-
- Job requests.
-
- In this group, the Printer can return any status codes defined
- in [RFC2911] and section 12. The following is a description of
- the important status codes:
-
- successful-ok: the Printer created the Job and all
- Subscription Objects requested (see [RFC2911].
-
- successful-ok-ignored-subscriptions: the Printer created
- the Job and not all of the Subscription Objects requested
-
-
-
-Herriot & Hastings Standards Track [Page 57]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- (see section 12.1). This status-code hides 'successful-ok-
- xxx' status-codes that could reveal problems in Job
- creation. The Printer MUST NOT return the 'client-error-
- ignored-all-subscriptions' status code for Job Creation
- operations because the Printer returns an error status-code
- only when it fails to create a Job.
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in [RFC2911] section 3.1.4.2.
-
- Group 2: Unsupported Attributes
-
- See [RFC2911] section 3.1.7 for details on returning Unsupported
- Attributes. This group does not contain any unsupported
- Subscription Template Attributes; they are returned in the
- Subscription Attributes Group (see below).
-
- Group 3: Job Object Attributes
-
- The "job-id" of the Job Object just created, etc., as defined in
- [RFC2911] for Print-Job, Print-URI, and Create-Job requests.
-
- Group 4 to N: Subscription Attributes
-
- These groups MUST be returned if and only if the client supplied
- Subscription Template Attributes and the operation was accepted.
-
- See section 5.2 for details on the contents of each occurrence of
- this group.
-
-11.2. Other Operations
-
- This section defines other operations on Subscription objects.
-
-11.2.1. Restart-Job Operation - Extensions for Notification
-
- The Restart-Job operation [RFC2911] is neither a Job Creation
- operation nor a Subscription Creation operation (see section 3.2).
-
- For the Restart-Job operation, the client MUST NOT supply any Job
- Subscription Attributes Groups. The Printer MUST treat any supplied
- Job Subscription Attributes as unsupported attributes.
-
- For this operation, the Printer does not return a job-id or any
- Subscription Attributes groups because the Printer reuses the
- existing Job object with the same job-id and the existing Per-Job
- Subscription Objects with the same subscription-ids. However, after
-
-
-
-Herriot & Hastings Standards Track [Page 58]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- successful completion of this operation, the Printer generates a
- 'job-created' event (see section 5.3.3.4.3).
-
-11.2.2. Validate-Job Operation - Extensions for Notification
-
- A client can test whether one or more Subscription Objects could be
- created using the Validate-Job operation. The client supplies one or
- more Subscription Template Attributes Groups (defined in section
- 5.3), just as in a Job Creation request.
-
- A Printer MUST support this extension to this operation.
-
- The Printer MUST accept requests that are identical to the Job
- Creation request defined in section 11.1.3.1, except that the request
- MUST NOT contain document data.
-
- The Printer MUST return the same groups and attributes as the Print-
- Job operation (section 11.1.3.1) with the following exceptions. The
- Printer MUST NOT return a Job Object Attributes Group because no Job
- is created. The Printer MUST NOT return the "notify-subscription-id"
- attribute in any Subscription Attribute Group because no Subscription
- Object is created.
-
- If the Printer would succeed in creating a Subscription Object, the
- corresponding Subscription Attributes Group either has no 'status-
- code' attribute or a 'status-code' attribute with a value of
- 'successful-ok-too-many-events' or 'successful-ok-ignored-or-
- substituted-attributes' (see sections 5.2 and 13). The status-codes
- have the same meaning as in Job Creation except the results state
- what "would happen".
-
- The Printer MUST validate Subscription Template Attributes Groups in
- the same manner as the Job Creation operations.
-
-11.2.3. Get-Printer-Attributes - Extensions for Notification
-
- This operation is extended so that it returns Printer attributes
- defined in this document.
-
- A Printer MUST support this extension to this operation.
-
- In addition to the requirements of [RFC2911] section 3.2.5, a Printer
- MUST support the following additional values for the "requested-
- attributes" Operation attribute in this operation and return such
- attributes in the Printer Object Attributes group of its response.
-
- 1. Subscription Template Attributes: Each supported attribute in
- column 2 of Table 1.
-
-
-
-Herriot & Hastings Standards Track [Page 59]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- 2. New Printer Description Attributes: Each supported attribute in
- section 6.
-
- 3. New Group Name: The 'subscription-template' group name, which
- names all supported Subscription Template Attribute in column 2 of
- Table 1. This group name is also used in the Get-Subscription-
- Attributes and Get-Subscriptions operation with an analogous
- meaning.
-
- 4. Extended Group Name: The 'all' group name, which names all Printer
- attributes according to [RFC2911] section 3.2.5. In this
- extension 'all' names all attributes specified in [RFC2911] plus
- those named in items 1 and 2 of this list.
-
-11.2.4. Get-Subscription-Attributes operation
-
- This operation allows a client to request the values of the
- attributes of a Subscription Object.
-
- A Printer MUST support this operation.
-
- This operation is almost identical to the Get-Job-Attributes
- operation (see [RFC2911] section 3.3.4). The only differences are
- that the operation is directed at a Subscription Object rather than a
- Job object, and the returned attribute group contains Subscription
- Object attributes rather than Job object attributes.
-
- Access Rights: The authenticated user (see [RFC2911] section 8.3)
- performing this operation MUST (1) be the Subscription Object owner,
- (2) have Operator or Administrator access rights for this Printer
- (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by
- the Printer's administrator-configured security policy to query the
- Subscription Object for the target job. Otherwise the Printer MUST
- reject the operation and return: the 'client-error-forbidden',
- 'client-error-not-authenticated', or 'client-error-not-authorized'
- status code as appropriate. Furthermore, the Printer's security
- policy MAY limit which attributes are returned, in a manner similar
- to the Get-Job-Attributes operation (see [RFC2911] end of section
- 3.3.4.2).
-
-11.2.4.1. Get-Subscription-Attributes Request
-
- The following groups of attributes are part of the Get-Subscription-
- Attributes request:
-
- Group 1: Operation Attributes
-
- Natural Language and Character Set:
-
-
-
-Herriot & Hastings Standards Track [Page 60]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in section [RFC2911] 3.1.4.1.
-
- Target:
- The "printer-uri" attribute which defines the target for this
- operation as described in [RFC2911] section 3.1.5.
-
- Requesting User Name:
- The "requesting-user-name" attribute SHOULD be supplied by the
- client as described in [RFC2911] section 8.3.
-
-11.2.4.1.1. "notify-subscription-id" (integer (1:MAX))
-
- The client MUST supply this attribute. The Printer MUST support this
- attribute. This attribute specifies the Subscription Object from
- which the client is requesting attributes. If the client omits this
- attribute, the Printer MUST reject this request with the 'client-
- error-bad-request' status code.
-
-11.2.4.1.2. "requested-attributes" (1setOf keyword)
-
- The client OPTIONALLY supplies this attribute. The Printer MUST
- support this attribute. This attribute specifies the attributes of
- the specified Subscription Object that the Printer MUST return in the
- response. Each value of this attribute is either an attribute name
- (defined in sections 5.3 and 5.4) or an attribute group name. The
- attribute group names are:
-
- - 'subscription-template': all attributes that are both defined in
- section 5.3 and present on the specified Subscription Object
- (column 1 of Table 1).
-
- - 'subscription-description': all attributes that are both defined
- in section 5.4 and present on the specified Subscription Object
- (Table 2).
-
- - 'all': all attributes that are present on the specified
- Subscription Object.
-
- A Printer MUST support all these group names.
-
- If the client omits this attribute, the Printer MUST respond as if
- this attribute had been supplied with a value of 'all'.
-
-11.2.4.2. Get-Subscription-Attributes Response
-
- The Printer returns the following sets of attributes as part of the
- Get-Subscription-Attributes Response:
-
-
-
-Herriot & Hastings Standards Track [Page 61]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Group 1: Operation Attributes
-
- Status Message:
- Same as [RFC2911].
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in [RFC2911] section 3.1.4.2. The
- "attributes-natural-language" MAY be the natural language of the
- Subscription Object, rather than the one requested.
-
- Group 2: Unsupported Attributes
-
- See [RFC2911] section 3.1.7 and section 3.2.5.2 for details on
- returning Unsupported Attributes.
-
- The response NEED NOT contain the "requested-attributes" operation
- attribute with any supplied keyword values that were requested by
- the client but are not supported by the IPP object. If the
- Printer object does return unsupported attributes referenced in
- the "requested-attributes" operation attribute, the values of the
- "requested-attributes" attribute returned MUST include only the
- unsupported keywords that were requested by the client. If the
- client had requested a group name, such as 'all', the resulting
- unsupported attributes returned MUST NOT include attribute keyword
- names described in the standard but not supported by the
- implementation.
-
- Group 3: Subscription Attributes
-
- This group contains a set of attributes with their current values.
- Each attribute returned in this group:
-
- a) MUST be specified by the "requested-attributes" attribute in the
- request, AND
-
- b) MUST be present on the specified Subscription Object AND
-
- c) MUST NOT be restricted by the security policy in force. For
- example, a Printer MAY prohibit a client who is not the creator of
- a Subscription Object from seeing some or all of its attributes.
- See [RFC2911] end of section 3.3.4.2 and section 8.
-
- The Printer can return the attributes of the Subscription Object
- in any order. The client MUST accept the attributes in any order.
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 62]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-11.2.5. Get-Subscriptions operation
-
- This operation allows a client to retrieve the values of attributes
- of all Subscription Objects belonging to a Job or Printer.
-
- A Printer MUST supported this operation.
-
- This operation is similar to the Get-Subscription-Attributes
- operation, except that this Get-Subscriptions operation returns
- attributes from possibly more than one object.
-
- This operation is similar to the Get-Jobs operation (see [RFC2911]
- section 3.2.6), except that the operation returns Subscription
- Objects rather than Job objects.
-
- Access Rights: To query Per-Job Subscription Objects of the
- specified job (client supplied the "notify-job-id" operation
- attribute - see section 11.2.5.1.1), the authenticated user (see
- [RFC2911] section 8.3) performing this operation MUST (1) be the
- Subscription Object owner, (2) have Operator or Administrator access
- rights for this Printer (see [RFC2911] sections 1 and 8.5), or (3) be
- otherwise authorized by the Printer's administrator-configured
- security policy to query the Subscription Object for the target job.
- To query Per-Printer Subscription Objects of the Printer (client
- omits the "notify-job-id" operation attribute - see section
- 11.2.5.1.1), the authenticated user (see [RFC2911] section 8.3)
- performing this operation MUST (1) have Operator or Administrator
- access rights for this Printer (see [RFC2911] sections 1 and 8.5), or
- (2) be otherwise authorized by the Printer's administrator-configured
- security policy to query Per-Printer Subscription Objects for the
- target Printer. Otherwise the Printer MUST reject the operation and
- return: the 'client-error-forbidden', 'client-error-not-
- authenticated', or 'client-error-not-authorized' status code as
- appropriate. Furthermore, the Printer's security policy MAY limit
- which attributes are returned, in a manner similar to the Get-Jobs
- and Get-Printer-Attributes operations (see [RFC2911] end of sections
- 3.2.6.2 and 3.2.5.2).
-
-11.2.5.1. Get-Subscriptions Request
-
- The following groups of attributes are part of the Get-Subscriptions
- request:
-
- Group 1: Operation Attributes
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in [RFC2911] section 3.1.4.1.
-
-
-
-Herriot & Hastings Standards Track [Page 63]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Target:
- The "printer-uri" attribute which defines the target for this
- operation as described in [RFC2911] section 3.1.5.
-
- Requesting User Name:
- The "requesting-user-name" attribute SHOULD be supplied by the
- client as described in [RFC2911] section 8.3.
-
-11.2.5.1.1. "notify-job-id" (integer(1:MAX))
-
- If the client specifies this attribute, the Printer returns the
- specified attributes of all Per-Job Subscription Objects associated
- with the Job whose "job-id" attribute value equals the value of this
- attribute. If the client does not specify this attribute, the
- Printer returns the specified attributes of all Per-Printer
- Subscription Objects. Note: there is no way to get all Per-Job
-
- Subscriptions known to the Printer in a single operation. A Get-Jobs
- operation followed by a Get-Subscriptions operation for each Job will
- return all Per-Job Subscriptions.
-
-11.2.5.1.2. "limit" (integer(1:MAX))
-
- The client OPTIONALLY supplies this attribute. The Printer MUST
- support this attribute. It is an integer value that determines the
- maximum number of Subscription Objects that a client will receive
- from the Printer even if the "my-subscriptions" attribute constrains
- which Subscription Objects are returned. The limit is a "stateless
- limit" in that if the value supplied by the client is 'N', then only
- the first 'N' Subscription Objects are returned in the Get-
- Subscriptions Response. There is no mechanism to allow for the next
- 'M' Subscription Objects after the first 'N' Subscription Objects.
- If the client does not supply this attribute, the Printer responds
- with all applicable Subscription Objects.
-
-11.2.5.1.3. "requested-attributes" (1setOf type2 keyword)
-
- The client OPTIONALLY supplies this attribute. The Printer MUST
- support this attribute. This attribute specifies the attributes of
- the specified Subscription Objects that the Printer MUST return in
- the response. Each value of this attribute is either an attribute
- name (defined in sections 5.3 and 5.4) or an attribute group name
- (defined in section 11.2.4.1). If the client omits this attribute,
- the Printer MUST respond as if the client had supplied this attribute
- with the one value: 'notify-subscription-id'.
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 64]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-11.2.5.1.4. "my-subscriptions" (boolean)
-
- The client OPTIONALLY supplies this attribute. The Printer MUST
- support this attribute. If the value is 'false', the Printer MUST
- consider the Subscription Objects from all users as candidates. If
- the value is 'true', the Printer MUST return the Subscription Objects
- created by the requesting user of this request. If the client does
- not supply this attribute, the Printer MUST respond as if the client
- had supplied the attribute with a value of 'false'. The means for
- authenticating the requesting user and matching the Subscription
- Objects is similar to that for Jobs which is described in [RFC2911]
- section 8.
-
-11.2.5.2 Get-Subscriptions Response
-
- The Printer returns the following sets of attributes as part of the
- Get-Subscriptions Response:
-
- Group 1: Operation Attributes
-
- Status Message:
- Same as [RFC2911].
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in [RFC2911] section 3.1.4.2.
-
- Group 2: Unsupported Attributes
-
- Same as for Get-Subscription-Attributes.
-
- Groups 3 to N: Subscription Attributes
-
- The Printer responds with one Subscription Attributes Group for
- each requested Subscription Object (see the "notify-job-id"
- attribute in the Operation Attributes Group of this operation).
-
- The Printer returns Subscription Objects in any order.
-
- If the "limit" attribute is present in the Operation Attributes
- group of the request, the number of Subscription Attributes Groups
- in the response MUST NOT exceed the value of the "limit"
- attribute.
-
- It there are no Subscription Objects associated with the specified
- Job or Printer, the Printer MUST return zero Subscription
- Attributes Groups and it MUST NOT treat this case as an error,
-
-
-
-
-Herriot & Hastings Standards Track [Page 65]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- i.e., the status-code MUST be 'successful-ok' unless something
- else causes the status code to have some other value.
-
- See the Group 3 response (Subscription Attributes Group) of the
- Get-Subscription-Attributes operation (section 11.2.4.2) for the
- attributes that a Printer returns in this group.
-
-11.2.6. Renew-Subscription operation
-
- This operation allows a client to request the Printer to extend the
- lease on a Per-Printer Subscription Object.
-
- The Printer MUST support this operation.
-
- The Printer MUST accept this request for a Per-Printer Subscription
- Object in any of the target Printer's states, i.e., 'idle',
- 'processing', or 'stopped', but MUST NOT change the Printer's
- "printer-state" attribute.
-
- The Printer MUST reject this request for a Per-Job Subscription
- Object because it has no lease (see section 5.4.3). The status code
- returned MUST be 'client-error-not-possible'.
-
- Access Rights: The authenticated user (see [RFC2911] section 8.3)
- performing this operation MUST (1) be the owner of the Per-Printer
- Subscription Object, (2) have Operator or Administrator access rights
- for the Printer (see [RFC2911] sections 1 and 8.5), or (3) be
- otherwise authorized by the Printer's administrator-configured
- security policy to renew Per-Printer Subscription Objects for the
- target Printer. Otherwise, the Printer MUST reject the operation and
- return: the 'client-error-forbidden', 'client-error-not-
- authenticated', or 'client-error-not-authorized' status code as
- appropriate.
-
-11.2.6.1. Renew-Subscription Request
-
- The following groups of attributes are part of the Renew-Subscription
- Request:
-
- Group 1: Operation Attributes
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in [RFC2911] section 3.1.4.1.
-
- Target:
- The "printer-uri" attribute which defines the target for this
- operation as described in [RFC2911] section 3.1.5.
-
-
-
-Herriot & Hastings Standards Track [Page 66]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Requesting User Name:
- The "requesting-user-name" (name(MAX)) attribute SHOULD be
- supplied by the client as described in [RFC2911] section 8.3.
-
-11.2.6.1.1. "notify-subscription-id" (integer (1:MAX))
-
- The client MUST supply this attribute. The Printer MUST support this
- attribute. This attribute specifies the Per-Printer Subscription
- Object whose lease the Printer MUST renew. If the client omits this
- attribute, the Printer MUST reject this request with the 'client-
- error-bad-request' status code.
-
- Group 2: Subscription Template Attributes
-
-11.2.6.1.2. "notify-lease-duration" (integer(0:MAX))
-
- The client MAY supply this attribute. It indicates the number of
- seconds to renew the lease for the specified Subscription Object. A
- value of 0 requests an infinite lease (which MAY require Operator
- access rights). If the client omits this attribute, the Printer MUST
- use the value of the Printer's "notify-lease-duration-default"
- attribute. See section 5.3.8 for more details.
-
-11.2.6.2. Renew-Subscription Response
-
- The Printer returns the following sets of attributes as part of the
- Renew-Subscription Response:
-
- Group 1: Operation Attributes
-
- Status Message:
- Same as [RFC2911].
-
- The following are some of the status codes returned (see
- [RFC2911]:
-
- successful-ok: The operation successfully renewed the lease
- on the Subscription Object for the requested duration.
-
- successful-ok-ignored-or-substituted-attributes: The
- operation successfully renewed the lease on the Subscription
- Object for some duration other than the amount requested.
-
- client-error-not-possible: The operation failed because the
- "notify-subscription-id" Operation attribute identified a
- Per-Job Subscription Object.
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 67]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- client-error-not-found: The operation failed because the
- "notify-subscription-id" Operation attribute identified a
- non-existent Subscription Object.
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in [RFC2911] section 3.1.4.2. The
- "attributes-natural-language" MAY be the natural language of the
- Subscription Object, rather than the one requested.
-
- Group 2: Unsupported Attributes
-
- See [RFC2911] section 3.1.7 for details on returning Unsupported
- Attributes.
-
- Group 3: Subscription Attributes
-
- The Printer MUST return the following Subscription Attribute:
-
-11.2.6.2.1. "notify-lease-duration" (integer(0:MAX))
-
- The value of this attribute MUST be the number of seconds that the
- Printer has granted for the lease of the Subscription Object (see
- section 5.3.8 for details, such as the value of this attribute when
- the Printer doesn't support the requested value).
-
-11.2.7. Cancel-Subscription operation
-
- This operation allows a client to delete a Subscription Object and
- stop the Printer from delivering more Event Notifications. Once
- performed, there is no way to reference the Subscription Object.
-
- A Printer MUST supported this operation.
-
- The Printer MUST accept this request in any of the target Printer's
- states, i.e., 'idle', 'processing', or 'stopped', but MUST NOT change
- the Printer's "printer-state" attribute.
-
- If the specified Subscription Object is a Per-Job Subscription
- Object, the Printer MUST accept this request in any of the target
- Job's states, but MUST NOT change the Job's "job-state" attribute or
- affect the Job.
-
- Note: There is no way to change any attributes on a Subscription
- Object, except the "notify-lease-duration" attribute (using the
- Renew-Subscription operation). In order to change other attributes,
- a client performs a Subscription Creation Operation and Cancel-
- Subscription operation on the old Subscription Object. If the client
-
-
-
-Herriot & Hastings Standards Track [Page 68]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- wants to avoid missing Event Notifications, it performs the
- Subscription Creation Operation first. If this order would create
- too many Subscription Objects on the Printer, the client reverses the
- order.
-
- Access Rights: The authenticated user (see [RFC2911] section 8.3)
- performing this operation MUST (1) be the owner of the Subscription
- Object, (2) have Operator or Administrator access rights for the
- Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise
- authorized by the Printer's administrator-configured security policy
- to cancel the target Subscription Object. Otherwise, the Printer
- MUST reject the operation and return: the 'client-error-forbidden',
- 'client-error-not-authenticated', or 'client-error-not-authorized'
- status code as appropriate.
-
-11.2.7.1. Cancel-Subscription Request
-
- The following groups of attributes are part of the Cancel-
- Subscription Request:
-
- Group 1: Operation Attributes
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in [RFC2911] section 3.1.4.1.
-
- Target:
- The "printer-uri" attribute which defines the target for this
- operation as described in [RFC2911] section 3.1.5.
-
- Requesting User Name:
- The "requesting-user-name" attribute SHOULD be supplied by the
- client as described in [RFC2911] section 8.3.
-
-11.2.7.1.1. "notify-subscription-id" (integer (1:MAX))
-
- The client MUST supply this attribute. The Printer MUST support this
- attribute. This attribute specifies the Subscription Object that the
- Printer MUST cancel. If the client omits this attribute, the Printer
- MUST reject this request with the 'client-error-bad-request' status
- code.
-
-
-
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 69]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-11.2.7.2. Cancel-Subscription Response
-
- The Printer returns the following sets of attributes as part of the
- Cancel-Subscription Response:
-
- Group 1: Operation Attributes
-
- Status Message:
- Same as [RFC2911].
-
- The following are some of the status codes returned (see
- [RFC2911]:
-
- successful-ok: The operation successfully canceled
- (deleted) the Subscription Object.
-
- client-error-not-found: The operation failed because the
- "notify-subscription-id" Operation attribute identified a
- non-existent Subscription Object.
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes as described in [RFC2911] section 3.1.4.2. The
- "attributes-natural-language" MAY be the natural language of the
- Subscription Object, rather than the one requested.
-
- Group 2: Unsupported Attributes
-
- See [RFC2911] section 3.1.7 for details on returning Unsupported
- Attributes.
-
-12. Status Codes
-
- The following status codes are defined as extensions for Notification
- and are returned as the value of the "status-code" parameter in the
- Operation Attributes Group of a response (see [RFC2911] section
- 3.1.6.1). Operations in this document can also return the status
- codes defined in section 13 of [RFC2911]. The 'successful-ok' status
- code is an example of such a status code.
-
-12.1. successful-ok-ignored-subscriptions (0x0003)
-
- The Subscription Creation Operation was unable to create all
- requested Subscription Objects.
-
- For a Create-Job-Subscriptions or Create-Printer-Subscriptions
- operation, this status code means that the Printer created one or
-
-
-
-
-Herriot & Hastings Standards Track [Page 70]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- more Subscription Objects, but not all requested Subscription
- Objects.
-
- For a Job Creation operation, this status code means that the Printer
- created the Job along with zero or more Subscription Objects. The
- Printer returns this status code even if other job attributes are
- unsupported or in conflict. That is, if an IPP Printer finds a
- warning that would allow it to return 'successful-ok-ignored-
- subscriptions' and either 'successful-ok-ignored-or-substituted-
- attributes' and/or 'successful-ok-conflicting-attributes', it MUST
- return 'successful-ok-ignored-subscriptions'.
-
-12.2. client-error-ignored-all-subscriptions (0x0414)
-
- This status code is the same as 'successful-ok-ignored-subscriptions'
- except that only the Create-Job-Subscriptions and Create-Printer-
- Subscriptions operation return it. They return this status code only
- when the Printer creates zero Subscription Objects.
-
-13. Status Codes in Subscription Attributes Groups
-
- This section contains values of the "notify-status-code" (type2 enum)
- attribute that the Printer returns in a Subscription Attributes Group
- in a response when the corresponding Subscription Object:
-
- 1. is not created or
-
- 2. is created and some of the client-supplied attributes are not
- supported.
-
- The following sections are ordered in decreasing order of importance
- of the status-codes.
-
-13.1. client-error-uri-scheme-not-supported (0x040C)
-
- This status code is defined in [RFC2911]. This document extends its
- meaning and allows it to be in a Subscription Attributes Group of a
- response.
-
- The scheme of the client-supplied URI in a "notify-recipient-uri"
- Subscription Template Attribute in a Subscription Creation Operation
- is not supported. See section 5.3.1.
-
-13.2. client-error-attributes-or-values-not-supported (0x040B)
-
- This status code is defined in [RFC2911]. This document extends its
- meaning and allows it to be in a Subscription Attributes Group of a
- response.
-
-
-
-Herriot & Hastings Standards Track [Page 71]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- The method of the client-supplied keyword in a "notify-pull-method"
- Subscription Template Attribute in a Subscription Creation Operation
- is not supported. See section 5.3.2.
-
-13.3. client-error-too-many-subscriptions (0x0415)
-
- The number of Subscription Objects supported by the Printer would be
- exceeded if this Subscription Object were created (see section 5.2).
-
-13.4. successful-ok-too-many-events (0x0005)
-
- The client supplied more Events in the "notify-events" operation
- attribute of a Subscription Creation Operation than the Printer
- supports, as indicated in its "notify-max-events-supported" Printer
- attribute (see section 5.3.3).
-
-13.5. successful-ok-ignored-or-substituted-attributes (0x0001)
-
- This status code is defined in [RFC2911]. This document extends its
- meaning to include unsupported Subscription Template Attributes and
- it can appear in a Subscription Attributes Group.
-
-14. Encodings of Additional Attribute Tags
-
- This section assigns values to two attributes tags as extensions to
- the encoding defined in [RFC2910]).
-
- The "subscription-attributes-tag" delimits Subscription Template
- Attributes Groups in requests and Subscription Attributes Groups in
- responses.
-
- The "event-notification-attributes-tag" delimits Event Notifications
- in Delivery Methods that use an IPP-like encoding.
-
- The following table specifies the values for the delimiter tags:
-
- Tag Value (Hex) Meaning
-
- 0x06 "subscription-attributes-tag"
- 0x07 "event-notification-attributes-tag"
-
-15. Conformance Requirements
-
- It is OPTIONAL for IPP clients and Printers to implement this Event
- Notification specification.
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 72]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-15.1. Conformance requirements for clients
-
- If this Event Notification specification is implemented by a client,
- the client MUST support the 'ippget' Pull Delivery Method and meet
- the conformance requirements as defined in [RFC3996] for clients. A
- client MAY support additional Delivery Methods.
-
-15.2. Conformance requirements for Printers
-
- If this Event Notification specification is implemented by a Printer,
- the Printer MUST:
-
- - meet the Conformance Requirements detailed in section 5 of
- [RFC2911].
-
- - support the Subscription Template Attributes Group in requests and
- the Subscription Attributes Group in responses.
-
- - support all of the following attributes:
-
- a. REQUIRED Subscription Object attributes in section 5.
- b. REQUIRED Printer Description object attributes in section 6.
- c. REQUIRED attributes in Event Notification content in section 8.
-
- - support the 'ippget' Pull Delivery Method and meet the conformance
- requirements as defined in [RFC3996] for Printers. The Printer
- MAY support additional Push and Pull Delivery Methods.
-
- - deliver Event Notifications that conform to the requirements of
- section 9 and the requirements of the Delivery Method Document for
- each supported Delivery Method (the conformance requirements for
- Delivery Method Documents is specified in section 10).
-
- - for all of the Job Creation Operations that the Printer supports,
- MUST support the REQUIRED extensions for notification defined in
- section 11.1.3.
-
- - meet the conformance requirements for operations as described in
- Table 16 and meet the requirements for Printers as specified in
- the indicated sub-sections of section 11:
-
-
-
-
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 73]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Table 16 - Printer Conformance Requirements for Operations
-
- Operation Printer
- Conformance
- Requirements
-
- Create-Printer-Subscriptions (section 11.1.2) REQUIRED
- Create-Job-Subscriptions (section 11.1.1) OPTIONAL
- Get-Subscription-Attributes (section 11.2.3) REQUIRED
- Get-Subscriptions (section 11.2.5) REQUIRED
- Renew-Subscription (section 11.2.6) REQUIRED
- Cancel-Subscription (section 11.2.7) REQUIRED
-
-16. Model for Notification with Cascading Printers (Informative)
-
- With this model (see Figure 2 below), there is an intervening Print
- server between the human user and the output-device. So the system
- effectively has two Printer objects. There are two cases to
- consider.
-
- 1. When the Printer 1 (in the server) generates Events, the system
- behaves like the client and Printer in Figure 1. In this case,
- Printer 1 delivers Event Notifications that are shown as Event
- Notifications (A) of Figure 2.
-
- 2. When the Printer 2 (in the output-device) generates Events, there
- are two possible system configurations:
-
- a) Printer 1 forwards the client-supplied Subscription Creation
- Operations to the downstream Printer 2 and lets Printer 2
- deliver the Event Notifications directly to the Notification
- Recipients supplied by the Client (Event Notifications(C) in
- the diagram).
-
- b) Printer 1 performs the client-supplied Subscription Creation
- Operations and also forwards the Subscription Creation
- Operations to Printer 2 with the Notification Recipient changed
- to be the Printer 1. When an Event occurs in Printer 2,
- Printer 2 delivers the Event Notification (B) to Notification
- Recipient of Printer 1, which relays the received Event
- Notification (B) to the client-supplied Notification Recipient
- (as Event Notifications(A) in the diagram). Note, when a
- client performs a Subscription Creation Operation, Printer 1
- need not forward the Subscription Creation Operation to Printer
- 2 if it would create a duplicate Subscription Object on Printer
- 2.
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 74]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Note: when Printer 1 is forwarding Subscription Creation Operations
- to Printer 2, it may request Printer 2 to create additional
- Subscription Objects (called "piggy-backing"). Piggy-backing is
- useful when:
-
- - Device A is configured to accept (IPP or non-IPP) requests from
- other servers.
-
- - Server S wants to receive Job Events that the client didn't
- request and Server S wants these Events for jobs it submits and
- not for other jobs.
-
- server S device A
- +------------+ +------------+
- | | | |
- +--------+ Subscription | ###########| | ###########|
- | client |--Creation ----># Printer #| Subscription | # Printer #|
- +--------+ Operation | # Object 1#|---Creation------|># Object 2#|
- | ###|#######| Operation | ####|#|####|
- +----|---^---+ +-----|-|----+
- +--------+ Event | | | |
- |Notific-|<-Notifications(A)-+ +-- Event Notifications(B)--+ |
- |ation Re|<-------------Event Notifications(C)-----------------+
- |cipient |
- +--------+
-
- Figure 2 - Model for Notification with Cascading Printers
-
-17. Distributed Model for Notification (Informative)
-
- A Printer implementation could use some other remote notification
- server to provide some or most of the service. For example, the
- remote notification server could deliver Event Notifications using
- Delivery Methods that are not directly supported by the output device
- or Printer object. Or, the remote notification server could store
- Subscription Objects (passed to it from the output device in response
- to Subscription Creation requests), accept Events, format the Event
- Notification in the natural language of the Notification Recipient,
- and deliver the Event Notifications to the Notification Recipient(s).
-
- Figure 3 shows this partitioning. The interface between the output
- device (or Printer object) and the remote notification server is
- outside the scope of this document and is intended to be transparent
- to the client and this document.
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 75]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- ***********************
- *
- * Printer in combination
- * with the distributed
- * Notification Server)
- *
- * output device or server
- * +---------------+
- PDA, desktop, or server * + ########### +
- +--------+ * | # # |
- | client |---IPP Subscription--------># Printer # |
- +--------+ Creation operation * | # Object # |
- * | #####|##### |
- * +-------|-------+
- * | Subscriptions
- * | OR Event
- +------------+ * | Notifications
- |Notification| IPP-defined * +------v--------+
- |Recipient |<--Event Notifications---| Notification |
- +------------+ * | Server |
- * +---------------+
- *
- *************************
- *** = Implementation configuration opaque boundary
-
- Figure 3 - Opaque Use of a Notification Server Transparent to the
- Client
-
-18. Extended Notification Recipient (Informative)
-
- The model allows for an extended Notification Recipient that is
- itself a notification server that forwards each Event Notification to
- another recipient (called the Ultimate Notification Recipient in this
- section). The Delivery Method to the Ultimate Recipient is probably
- different from the Delivery Method used by the Printer to the
- extended Notification Recipient.
-
- This extended Notification Recipient is transparent to the Printer
- but not to the client.
-
- When a client performs a Subscription Creation Operation, it
- specifies the extended Notification Recipient as it would any
- Notification Recipient. In addition, the client specifies the
- Ultimate Notification Recipient in the Subscription Creation
- Operation in a manner specified by the extended Notification
- Recipient. Typically, it is either some bytes in the value of
- "notify-user-data" or some additional parameter in the value of
- "notify-recipient-uri". The client also subscribes directly with the
-
-
-
-Herriot & Hastings Standards Track [Page 76]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- extended Notification Recipient (by means outside this document),
- since it is a notification server in its own right.
-
- The IPP Printer treats the extended Notification Recipient like any
- other Notification Recipient and the IPP Printer is not aware of the
- forwarding. The Delivery Method that the extended Notification
- Recipient uses for delivering the Event Notification to the Ultimate
- Notification Recipient is beyond the scope of this document and is
- transparent to the IPP Printer.
-
- Examples of this extended Notification Recipient are paging,
- immediate messaging services, general notification services, and NOS
- vendors' infrastructure. Figure 4 shows this approach.
-
- PDA, desktop, or server server or output device
- +---------------+
- +--------+ | ########### |
- | client |---Subscription Creation -----------># Printer # |
- +--------+ Operation | # Object # |
- | #####|##### |
- +------------+ +------------+ IPP-defined +-------|-------+
- |Ultimate | any |Notification|<--Event Notifications----+
- |Notification|<----|Recipient |
- |Recipient | +------------+
- +------------+ (Notification Server)
-
- Figure 4 - Use of an Extended Notification Recipient transparent to
- the Printer
-
-19. Object Model for Notification (Normative)
-
- This section describes the Notification object model that adds a
- Subscription Object which together with the Job and Printer object
- provide the complete Notification semantics.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 77]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- The object relationships can be seen pictorially as:
-
- Subscription Objects (Per-Printer Subscriptions) Printer object
- +----+ +------------+
- | s1 |<--------------------------------------------->| |
- +----++ | |
- | s2 |<-------------------------------------------->| p1 |
- +----++ | |
- | s3 |<------------------------------------------->| |
- +----+ +------------+
- Job objects
- +---------+
- | |
- +----+ | j1 |
- | s4 |<------->| |
- +----+ | |
- | | s4 is a Per-Job Subscription Object
- ++--------++
- | |
- +----+ | j2 |
- | s5 |<------>| |
- +----++ | |
- | s6 |<----->| | s5 and s6 are Per-Job Subscription
- +----+ ++--------++ Objects
- | |
- | j3 |
- | |
- | | <----> indicates association
- +---------+
-
- Figure 5 - Object Model for Notification
-
- s1, s2, and s3 are Per-Printer Subscription Objects and can identify
- Printer and/or Job Events.
-
- s4, s5, and s6 are Per-Job Subscription Objects and can identify
- Printer and/or Job Events.
-
-19.1. Object relationships
-
- This sub-section defines the object relationships between the
- Printer, Job, and Subscription Objects by example. Whether Per-
- Printer Subscription Objects are actually contained in a Printer
- object or are just bi-directionally associated with them in some way
- is IMPLEMENTATION DEPENDENT and is transparent to the client.
- Similarly, whether Per-Job Subscription Objects are actually
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 78]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- contained in a Job object or are just bi-directionally associated
- with them in some way is IMPLEMENTATION DEPENDENT and is transparent
- to the client. The object relationships are defined as follows:
-
-19.2. Printer Object and Per-Printer Subscription Objects
-
- 1. The Printer object contains (is associated with) zero or more
- Per-Printer Subscription Objects (p1 contains s1-s3 Per-Printer
- Subscription Objects).
-
- 2. Each Per-Printer Subscription Object (s1, s2, and s3) is contained
- in (or is associated with) exactly one Printer object (p1).
-
-19.3. Job Object and Per-Job Subscription Objects
-
- 1. A Job object (j1, j2, j3) is associated with zero or more Per-Job
- Subscription Objects (s4-s6). Job j1 is associated with Per-Job
- Subscription Object s4, Job j2 is associated with Per-Job
- Subscription Objects s5 and s6, and Job j3 is not associated with
- any Per-Job Subscription Object.
-
- 2. Each Per-Job Subscription Object is associated with exactly one
- Job object.
-
-20. Per-Job versus Per-Printer Subscription Objects (Normative)
-
- Per-Job and Per-Printer Subscription Objects are quite similar.
- Either type of Subscription Object can subscribe to Job Events,
- Printer Events, or both. Both types of Subscription Objects can be
- queried using the Get-Subscriptions and Get-Subscription-Attributes
- operations and canceled using the Cancel-Subscription operation.
- Both types of Subscription Objects create Subscription Objects which
- have the same Subscription Object attributes defined. However, there
- are some semantic differences between Per-Job Subscription Objects
- and Per-Printer Subscription Objects. A Per-Job Subscription Object
- is established by the client when submitting a job and after creating
- the job using the Create-Job-Subscriptions operation by specifying
- the "job-id" of the Job with the "notify-job-id" attribute. A Per-
- Printer Subscription Object is established between a client and a
- Printer using the Create-Printer-Subscriptions operation. Some
- specific differences are:
-
- 1. A client usually creates one or more Per-Job Subscription Objects
- as part of the Job Creation operations (Create-Job, Print-Job, and
- Print-URI), rather than using the OPTIONAL Create-Job-
- Subscriptions operation, especially since Printer implementations
- NEED NOT support the Create-Job-Subscriptions operation, since it
- is OPTIONAL.
-
-
-
-Herriot & Hastings Standards Track [Page 79]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- 2. For Per-Job Subscription Objects, the Subscription Object is only
- valid while the job is "not-complete" (see sections 5.4.3) while
- for the Per-Printer Subscription Objects, the Subscription Object
- is valid until the time (in seconds) that the Printer returned in
- the "notify-lease-expiration-time" operation attribute.
-
- 3. Job Events in a Per-Job Subscription Object apply only to "one
- job" (the Job created by the Job Creation operation or references
- by the Create-Job-Subscriptions operation) while Job Events in a
- Per-Printer Subscription Object apply to ALL jobs contained in the
- IPP Printer.
-
-21. Normative References
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119 , March 1997.
-
- [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter,
- "Uniform Resource Identifiers (URI): Generic
- Syntax", RFC 2396, August 1998.
-
- [RFC2717] Petke, R. and I. King, "Registration Procedures for
- URL Scheme Names", RFC 2717, November 1999.
-
- [RFC2910] Herriot, R., Butler, S., Moore, P., and R. Turner,
- "Internet Printing Protocol/1.1: Encoding and
- Transport", RFC 2910, September 2000.
-
- [RFC2911] deBry, R., Hastings, T., Herriot, R., Isaacson, S.,
- and P. Powell, "Internet Printing Protocol/1.1:
- Model and Semantics", RFC 2911, September 2000.
-
- [RFC3381] Hastings, T., Lewis, H., and R. Bergman, "IPP: Job
- Progress Attributes", RFC 3381, September 2002.
-
- [RFC3996] Herriot, R., Hastings, T., and H. Lewis, "Internet
- Printing Protocol (IPP): The 'ippget' Delivery
- Method for Event Notifications", RFC 3996, March
- 2005.
-
-22. Informative References
-
- [IANA-CON] Narten, T. and H. Alvestrand, "Guidelines for
- Writing an IANA Considerations Section in RFCs",
- BCP 26, RFC 2434, October 1998.
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 80]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- [RFC2565] Herriot, R., Butler, S., Moore, P., and R. Turner,
- "Internet Printing Protocol/1.0: Encoding and
- Transport", RFC 2565, April 1999.
-
- [RFC2566] deBry, R., Hastings, T., Herriot, R., Isaacson, S.,
- and P. Powell, "Internet Printing Protocol/1.0:
- Model and Semantics", RFC 2566, April 1999.
-
- [RFC2567] Wright, D., "Design Goals for an Internet Printing
- Protocol", RFC 2567, April 1999.
-
- [RFC2568] Zilles, S., "Rationale for the Structure and Model
- and Protocol for the Internet Printing Protocol",
- RFC 2568, April 1999.
-
- [RFC2569] Herriot, R., Hastings, T., Jacobs, N., and J.
- Martin, "Mapping between LPD and IPP Protocols",
- RFC 2569, April 1999.
-
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
- Masinter, L., Leach, P., and T. Berners-Lee,
- "Hypertext Transfer Protocol - HTTP/1.1", RFC 2616,
- June 1999.
-
- [RFC3196] Hastings, T., Manros, C., Zehler, P., Kugler, C.,
- and H. Holst, "Internet Printing Protocol/1.1:
- Implementer's Guide", RFC 3196, November 2001.
-
- [RFC3997] Hastings, T., Editor, deBry, R., and H. Lewis,
- "Internet Printing Protocol (IPP): Requirements for
- IPP Notifications", RFC 3997, March 2005.
-
-23. IANA Considerations
-
- This section contains the registration information that IANA added to
- the IPP Registry according to the procedures defined in RFC 2911
- [RFC2911] section 6 to cover the definitions in this document. In
- addition, this section defines how Events and Delivery Methods will
- be registered when they are defined in other documents. The
- resulting registrations have been published in the
- http://www.iana.org/assignments/ipp-registrations registry.
-
-
-
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 81]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-23.1. Attribute Registrations
-
- The following table lists all the attributes defined in this
- document. These have been registered according to the procedures in
- RFC 2911 [RFC2911] section 6.2.
-
- Subscription Template attributes: Reference Section
- --------------------------------- --------- -------
- notify-attributes (1setOf type2 keyword) [RFC3995] 5.3.4
- notify-attributes-supported (1setOf type2 keyword)
- [RFC3995] 5.3.4.1
- notify-charset (charset) [RFC3995] 5.3.6
- notify-events (1setOf type2 keyword) [RFC3995] 5.3.3
- notify-events-default (1setOf type2 keyword) [RFC3995] 5.3.3.1
- notify-events-supported (1setOf type2 keyword) [RFC3995] 5.3.3.2
- notify-lease-duration (integer(0:67108863)) [RFC3995] 5.3.8
- notify-lease-duration-default (integer(0:67108863))
- [RFC3995] 5.3.8.1
- notify-lease-duration-supported (1setOf (integer(0: 67108863) |
- rangeOfInteger(0:67108863))) [RFC3995] 5.3.8.2
- notify-max-events-supported (integer(2:MAX)) [RFC3995] 5.3.3.3
- notify-natural-language (naturalLanguage) [RFC3995] 5.3.7
- notify-pull-method (type2 keyword) [RFC3995] 5.3.2
- notify-pull-method-supported (1setOf type2 keyword)
- [RFC3995] 5.3.2.1
- notify-recipient-uri (uri) [RFC3995] 5.3.1
- notify-schemes-supported (1setOf uriScheme) [RFC3995] 5.3.1.1
- notify-time-interval (integer(0:MAX)) [RFC3995] 5.3.9
- notify-user-data (octetString(63)) [RFC3995] 5.3.5
-
- Subscription Description Attributes:
- notify-job-id (integer(1:MAX)) [RFC3995] 5.4.6
- notify-lease-expiration-time (integer(0:MAX)) [RFC3995] 5.4.3
- notify-printer-up-time (integer(1:MAX)) [RFC3995] 5.4.4
- notify-printer-uri (uri) [RFC3995] 5.4.5
- notify-sequence-number (integer (0:MAX)) [RFC3995] 5.4.2
- notify-subscriber-user-name (name(MAX)) [RFC3995] 5.4.7
- notify-subscription-id (integer (1:MAX)) [RFC3995] 5.4.1
-
- Printer Description Attributes:
- printer-state-change-date-time (dateTime) [RFC3995] 6.2
- printer-state-change-time (integer(1:MAX)) [RFC3995] 6.1
-
- Attributes Only in Event Notifications
- notify-subscribed-event (type2 keyword) [RFC3995] 8.1
- notify-text (text(MAX)) [RFC3995] 8.2
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 82]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-23.2. Additional Enum Attribute Value Registrations within the IPP
- registry
-
- The following table lists all the new enum attribute values defined
- in this document. These have been registered within the IPP registry
- according to the procedures in RFC 2911 [RFC2911] section 6.1.
-
- Attribute
- Value Name Reference Section
- ------ ----------------------------- --------- -------
- operations-supported (1setOf type2 enum) [RFC2911] 4.4.15
- 0x0016 Create-Printer-Subscriptions [RFC3995] 7.1
- 0x0017 Create-Job-Subscriptions [RFC3995] 7.1
- 0x0018 Get-Subscription-Attributes [RFC3995] 7.1
- 0x0019 Get-Subscriptions [RFC3995] 7.1
- 0x001A Renew-Subscription [RFC3995] 7.1
- 0x001B Cancel-Subscription [RFC3995] 7.1
-
-23.3. Operation Registrations
-
- The following table lists all of the operations defined in this
- document. These have been registered according to the procedures in
- RFC 2911 [RFC2911] section 6.4.
-
- Operation Name Reference Section
- --------------------------------- --------- -------
- Cancel-Subscription [RFC3995] 11.2.7
- Create-Job - Extensions [RFC3995] 11.1.3
- Create-Job-Subscriptions [RFC3995] 11.1.1
- Create-Printer-Subscriptions [RFC3995] 11.1.2
- Get-Printer-Attributes - Extensions [RFC3995] 11.2.3
- Get-Subscription-Attributes [RFC3995] 11.2.4
- Get-Subscriptions [RFC3995] 11.2.5
- Print-Job - Extensions [RFC3995] 11.1.3
- Print-URI - Extensions [RFC3995] 11.1.3
- Renew-Subscription [RFC3995] 11.2.6
- Validate-Job Operation - Extensions [RFC3995] 11.2.2
-
-23.4. Status code Registrations
-
- The following table lists all the status codes defined in this
- document. These have been registered according to the procedures in
- RFC 2911 [RFC2911] section 6.6.
-
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 83]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Value Status Code Name Reference Section
- ----- ---------------------------- --------- -------
- 0x0000:0x00FF - Successful:
- 0x0003 successful-ok-ignored-subscriptions [RFC3995] 12.1
- 0x0005 successful-ok-too-many-events [RFC3995] 13.4
-
- 0x0400:0x04FF - Client Error:
- 0x0414 client-error-ignored-all-subscriptions [RFC3995] 12.2
- 0x0415 client-error-too-many-subscriptions [RFC3995] 13.3
-
-23.5. Attribute Group tag Registrations
-
- The following table lists all the attribute group tags defined in
- this document. These have been registered according to the
- procedures in RFC 2911 [RFC2911] section 6.5.
-
- Value Attribute Group Tag Name Reference Section
- ----- -------------------------------- -------- -------
- 0x06 subscription-attributes-tag [RFC3995] 14
- 0x07 event-notification-attributes-tag [RFC3995] 14
-
-23.6. Registration of Events
-
- The following table lists all the Events defined in this document as
- type2 keywords to be used with the "notify-events", "notify-events-
- default", and "notify-events-supported" Subscription Template
- attributes (see section 5.3.3)). Rather than creating a separate
- section in the IPP Registry for Events, these event keywords have
- been registered according to the procedures of [RFC2911] section 7.1
- as additional keyword attribute values for use with the "notify-
- events" Subscription Template attribute (see section 5.3.3), i.e.,
- registered as keyword values for the "notify-events", "notify-
- events-default", and "notify-events-supported" attributes:
-
- Attribute (attribute syntax)
- Value Reference Section
- --------------------- --------- -------
- notify-events (1setOf type2 keyword) [RFC3995] 5.3.3
- notify-events-default (1setOf type2 keyword) [RFC3995] 5.3.3.1
- notify-events-supported (1setOf type2 keyword) [RFC3995] 5.3.3.2
- notify-subscribed-event (type2 keyword) [RFC3995] 8.1
- No Events:
- none [RFC3995] 5.3.3.4.1
- Printer Events:
- printer-state-changed [RFC3995] 5.3.3.4.2
- printer-restarted [RFC3995] 5.3.3.4.2
- printer-shutdown [RFC3995] 5.3.3.4.2
- printer-stopped [RFC3995] 5.3.3.4.2
-
-
-
-Herriot & Hastings Standards Track [Page 84]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- printer-config-changed [RFC3995] 5.3.3.4.2
- printer-media-changed [RFC3995] 5.3.3.4.2
- printer-finishings-changed [RFC3995] 5.3.3.4.2
- printer-queue-order-changed [RFC3995] 5.3.3.4.2
- Job Events:
- job-state-changed [RFC3995] 5.3.3.4.3
- job-created [RFC3995] 5.3.3.4.3
- job-completed [RFC3995] 5.3.3.4.3
- job-stopped [RFC3995] 5.3.3.4.3
- job-config-changed [RFC3995] 5.3.3.4.3
- job-progress [RFC3995] 5.3.3.4.3
-
-23.7. Registration of Event Notification Delivery Methods
-
- This section describes the requirements and procedures for
- registration and publication of Event Notification Delivery Methods
- and for the submission of such proposals.
-
-23.7.1. Requirements for Registration of Event Notification Delivery
- Methods
-
- Registered IPP Event Notification Delivery Methods are expected to
- follow a number of requirements described below.
-
-23.7.1.1. Required Characteristics
-
- A Delivery Method Document MUST either (1) contain all of the
- semantics of the Delivery Method or (2) contain the IPP Delivery
- Method registration requirements and a profile of some other protocol
- that in combination is the Delivery Method (e.g., mailto). The
- Delivery Method Document (and any documents it requires) MUST define
- either (1) a URL for a Push Delivery Method that the meets the
- requirements of [RFC2717]. or (2) a keyword for a Pull Delivery
- method.
-
- IPP Event Notification Delivery Method Documents MUST meet the
- requirements of this document (see sections 9 and 10).
-
- In addition, a Delivery Method Document MUST contain the following
- information:
-
- Type of registration: IPP Event Notification Delivery Method
- Name of this delivery method:
- Proposed URL scheme name of this Push Delivery Method or the
- keyword name of this Pull Delivery Method:
- Name of proposer:
- Address of proposer:
-
-
-
-
-Herriot & Hastings Standards Track [Page 85]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Email address of proposer:
- Is this delivery method REQUIRED or OPTIONAL for conformance to
- the IPP Event Notification and Subscriptions document:
- Is this delivery method defining Machine Consumable and/or Human
- Consumable content:
-
-23.7.1.2. Naming Requirements
-
- Exactly one (URL scheme or keyword) name MUST be assigned to each
- Delivery Method.
-
- Each assigned name MUST uniquely identify a single Delivery Method.
- All Push Delivery Method names MUST conform to the rules for URL
- scheme names, according to [RFC2396] and [RFC2717] for schemes in the
- IETF tree. All Pull Delivery Method names MUST conform to the rules
- for keywords according to [RFC2911].
-
-23.7.1.3. Functionality Requirements
-
- Delivery Methods MUST function as a protocol that is capable of
- delivering (push or pull) IPP Event Notifications to Notification
- Recipients.
-
-23.7.1.4. Usage and Implementation Requirements
-
- Use of a large number of Delivery Methods may hamper
- interoperability. However, the use of a large number of undocumented
- and/or unlabeled Delivery Methods hampers interoperability even more.
-
- A Delivery Method should therefore be registered ONLY if it adds
- significant functionality that is valuable to a large community, OR
- if it documents existing practice in a large community. Note that
- Delivery Methods registered for the second reason should be
- explicitly marked as being of limited or specialized use and should
- only be used with prior bilateral agreement.
-
-23.7.1.5. Publication Requirements
-
- Delivery Method Documents MUST be published in a standards track,
- informational, or experimental RFCs.
-
-23.7.2. Registration Procedure
-
- The IPP WG is developing a small number of Delivery Methods which are
- intended to be published as standards track RFCs. However, some
- parties may wish to register additional Delivery Methods in the
- future. This section describes the procedures for these additional
- Delivery Methods.
-
-
-
-Herriot & Hastings Standards Track [Page 86]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-23.7.2.1. Present the proposal to the Community
-
- First the Delivery Method Document MUST be an Internet-Draft with a
- target category of standards track, informational, or experimental.
- The same MUST be true for any documents that it references.
-
- Deliver the proposed Delivery Method Document proposal to the
- "ipp@pwg.org" mailing list. This mailing list has been established
- by [RFC2911] for reviewing proposed registrations and discussing
- other IPP matters. Proposed Delivery Method Documents are not
- formally registered and MUST NOT be used until approved.
-
- The intent of the public posting is to solicit comments and feedback
- on the definition and suitability of the Delivery Method and the name
- chosen for it over a four week period.
-
-23.7.2.2. Delivery Method Reviewer
-
- The Delivery Method Reviewer is the same person who has been
- appointed by the IETF Application Area Director(s) as the IPP
- Designated Expert according to [RFC2911] and [IANA-CON]. When the
- four week period is over and the IPP Designated Expert is convinced
- that consensus has been achieved, the IPP Designated Expert either
- approves the request for registration or rejects it. Rejection may
- occur because of significant objections raised on the list or
- objections raised externally.
-
- Decisions made by the Reviewer must be posted to the ipp@pwg.org
- mailing list within 14 days. Decisions made by the Reviewer may be
- appealed to the IESG.
-
-23.7.2.3. IANA Registration
-
- Provided that the Delivery Method registration proposal has either
- passed review or has been successfully appealed to the IESG, the IANA
- will be notified by the delivery method reviewer and asked to
- register the Delivery Method and make it available to the community.
-
-23.7.3. Delivery Method Document Registrations
-
- Each Push Delivery Method Document defines a URI scheme. Such a URI
- scheme is used in a URI value of the "notification-recipient" (uri)
- Subscription Template attribute (see section 5.3.1) and the uriScheme
- value of the "notify-schemes-supported" (1setOf uriScheme 5.3.1.1)
- Printer attribute(see section ). Rather than creating a separate
- section in the IPP Registry for Delivery Methods, Push Delivery
- Methods will be registered as an additional value of the "notify-
- schemes-supported" Printer attribute. These uriScheme values will be
-
-
-
-Herriot & Hastings Standards Track [Page 87]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- registered according to the procedures of [RFC2911] section 7.1 for
- additional attribute values. Therefore, the IPP Registry entry for a
- Push Delivery Method will be of the form:
-
- Attribute
- Value Ref. Section
- --------------------- -------- -------
- notify-schemes-supported (1setOf uriScheme) [RFC3995] 5.3.1.1
- <scheme name> RFC xxxx m.n
-
- Each Pull Delivery Method Document defines a keyword method which is
- registered as an additional value of the "notify-pull-method" and
- "notify-pull-method-supported" Printer attributes. These keyword
- values will be registered according to the procedures of [RFC2911]
- section 7.1 for additional attribute values. Therefore, the IPP
- Registry entry for a Pull Delivery Method will be of the form:
-
- Attribute
- Value Ref. Section
- --------------------- -------- -------
- notify-pull-method (type2 keyword) [RFC3995] 5.3.2
- notify-pull-method-supported (1setOf type2 keyword)
- [RFC3995] 5.3.2.1
- <method keyword name> RFC xxxx m.n
-
-23.7.4. Registration Template
-
- To: ipp@pwg.org
- Subject: Registration of a new Delivery Method
-
- Delivery Method name:
-
- (All Push Delivery Method names must be suitable for use as the value
- of a URL scheme in the IETF tree and all Pull Delivery Method names
- must be suitable IPP keywords according to [RFC2911])
-
- Published specification(s):
-
- (A specification for the Delivery Method must be openly available
- that accurately describes what is being registered.)
-
- Person & email address to contact for further information:
-
-
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 88]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-24. Internationalization Considerations
-
- This IPP Notification specification continues support for the
- internationalization of [RFC2911] of attributes containing text
- strings and names. Allowing a Subscribing Client to specify a
- different natural language and charset for each Subscription Object
- increases the internationalization support.
-
- The Printer MUST be able to localize the content of Human Consumable
- Event Notifications and to localize the value of "notify-text"
- attribute in Machine Consumable Event Notifications that it delivers
- to Notification Recipients. For localization, the Printer MUST use
- the value of the "notify-charset" attribute and the "notify-natural-
- language" attribute in the Subscription Object supplied by the
- Subscribing Client.
-
-25. Security Considerations
-
- Clients submitting Notification requests to the IPP Printer have the
- same security issues as submitting an IPP/1.1 print job request (see
- [RFC2911] section 3.2.1 and section 8). The same mechanisms used by
- IPP/1.1 can therefore be used by the client Notification submission.
- Operations that require authentication can use the HTTP
- authentication. Operations that require privacy can use the HTTP/TLS
- privacy. As with IPP/1.1 Print Job Objects, if there is no security
- on Subscription Objects, sequential assignment of subscription-ids
- exposes the system to a passive traffic monitoring threat.
-
-25.1. Client access rights
-
- The Subscription Object access control model is the same as the
- access control model for Job objects. The client MUST have the
- following access rights for the indicated Subscription operations:
-
- 1. Create-Job-Subscriptions (see section 11.1.1): A Per-Job
- Subscription object is associated with a Job. To create Per-Job
- Subscription Objects, the authenticated user (see [RFC2911]
- section 8.3) performing this operation MUST (1) be the job owner,
- (2) have Operator or Administrator access rights for this Printer
- (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized
- by the Printer's administrator-configured security policy to
- create Per-Job Subscription Objects for the target job.
-
- 2. Create-Printer-Subscriptions (see section 11.1.2): A Per-Printer
- Subscription object is associated with the Printer. To create
- Per-Printer Subscription Objects, the authenticated user (see
- [RFC2911] section 8.3) performing this operation MUST (1) have
- Operator or Administrator access rights for this Printer (see
-
-
-
-Herriot & Hastings Standards Track [Page 89]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- [RFC2911] sections 1 and 8.5) or (2) be otherwise authorized by
- the Printer's administrator-configured security policy to create
- Per-Printer Subscription Objects for this Printer.
-
- 3. Get-Subscription-Attributes (see section 11.2.4): The access
- control model for this operation is the same as that of the Get-
- Job-Attributes operation (see [RFC2911] section 3.3.4). The
- primary difference is that a Get-Subscription-Attributes operation
- is directed at a Subscription Object rather than at a Job object,
- and a returned attribute group contains Subscription Object
- attributes rather than Job object attributes. To query the
- specified Subscription Object, the authenticated user (see
- [RFC2911] section 8.3) performing this operation MUST (1) be the
- Subscription Object owner, (2) have Operator or Administrator
- access rights for this Printer (see [RFC2911] sections 1 and 8.5),
- or (3) be otherwise authorized by the Printer's administrator-
- configured security policy to query the Subscription Object for
- the target job. Furthermore, the Printer's security policy MAY
- limit which attributes are returned, in a manner similar to the
- Get-Job-Attributes operation (see [RFC2911] end of section
- 3.3.4.2).
-
- 4. Get-Subscriptions (see section 11.2.5): The access control model
- for this operation is the same as that of the Get-Jobs operation
- (see [RFC2911] section 3.2.6). The primary difference is that the
- operation is directed at Subscription Objects rather than at Job
- objects, and the returned attribute groups contain Subscription
- Object attributes rather than Job object attributes. To query
- Per-Job Subscription Objects of the specified job (client supplied
- the "notify-job-id" operation attribute - see section 11.2.5.1.1),
- the authenticated user (see [RFC2911] section 8.3) performing this
- operation MUST (1) be the Subscription Object owner, (2) have
- Operator or Administrator access rights for this Printer (see
- [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by
- the Printer's administrator-configured security policy to query
- the Subscription Object for the target job. To query Per-Printer
- Subscription Objects of the Printer (client omits the "notify-
- job-id" operation attribute - see section 11.2.5.1.1), the
- authenticated user (see [RFC2911] section 8.3) performing this
- operation MUST (1) have Operator or Administrator access rights
- for this Printer (see [RFC2911] sections 1 and 8.5), or (2) be
- otherwise authorized by the Printer's administrator-configured
- security policy to query Per-Printer Subscription Objects for the
- target Printer. Furthermore, the Printer's security policy MAY
- limit which attributes are returned, in a manner similar to the
- Get-Job-Attributes operation (see [RFC2911] end of section
- 3.2.6.2).
-
-
-
-
-Herriot & Hastings Standards Track [Page 90]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- 5. Renew-Subscriptions (see section 11.2.6): The authenticated user
- (see [RFC2911] section 8.3) performing this operation MUST (1) be
- the owner of the Per-Printer Subscription Object, (2) have
- Operator or Administrator access rights for the Printer (see
- [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by
- the Printer's administrator-configured security policy to renew
- Per-Printer Subscription Objects for the target Printer
-
- 6. Cancel-Subscription (see section 11.2.7): The authenticated user
- (see [RFC2911] section 8.3) performing this operation MUST (1) be
- the owner of the Subscription Object, (2) have Operator or
- Administrator access rights for the Printer (see [RFC2911]
- sections 1 and 8.5), or (3) be otherwise authorized by the
- Printer's administrator-configured security policy to cancel the
- target Subscription Object.
-
- The standard security concerns (delivery to the right user, privacy
- of content, tamper proof content) apply to each Delivery Method.
- Some Delivery Methods are more secure than others. Each Delivery
- Method Document MUST discuss its Security Considerations.
-
-25.2. Printer security threats
-
- Notification trap door: If a Printer supports the OPTIONAL "notify-
- attributes" Subscription Template attribute (see section 5.3.4) where
- the client can request that the Printer return any specified Job,
- Printer, and Subscription object attributes, the Printer MUST apply
- the same security policy to these requested attributes in the Get-
- Notifications request as it does for the Get-Jobs, Get-Job-
- Attributes, Get-Printer-Attributes, and Get-Subscription-Attributes
- requests.
-
-25.3. Notification Recipient security threats
-
- Unwanted Events Notifications (spam): For any Push Delivery Method,
- by far the biggest security concern is the abuse of notification:
- delivering unwanted Event Notifications to third parties (i.e.,
- spam). The problem is made worse by notification addresses that may
- be redistributed to multiple parties. There exist scenarios where
- third party notification is used (see Scenario #2 and #3 in
- [RFC3997]). Any fully secure solution would require active agreement
- of all recipients before delivering anything.
-
-
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 91]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-26. Description of the base IPP documents (Informative)
-
- The base set of IPP documents includes:
-
- Design Goals for an Internet Printing Protocol [RFC2567]
- Rationale for the Structure and Model and Protocol for the Internet
- Printing Protocol [RFC2568]
- Internet Printing Protocol/1.1: Model and Semantics [RFC2911]
- Internet Printing Protocol/1.1: Encoding and Transport [RFC2910]
- Internet Printing Protocol/1.1: Implementer's Guide [RFC3196]
- Mapping between LPD and IPP Protocols [RFC2569]
-
- The "Design Goals for an Internet Printing Protocol" document takes a
- broad look at distributed printing functionality, and it enumerates
- real-life scenarios that help to clarify the features that need to be
- included in a printing protocol for the Internet. It identifies
- requirements for three types of users: end users, operators, and
- administrators. It calls out a subset of end user requirements that
- are satisfied in IPP/1.0 [RFC2566, RFC2565]. A few OPTIONAL operator
- operations have been added to IPP/1.1 [RFC2911, RFC2910].
-
- The "Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol" document describes IPP from a high level
- view, defines a roadmap for the various documents that form the suite
- of IPP specification documents, and gives background and rationale
- for the IETF IPP working group's major decisions.
-
- The "Internet Printing Protocol/1.1: Model and Semantics" document
- describes a simplified model with abstract objects, their attributes,
- and their operations. The model introduces a Printer and a Job. The
- Job supports multiple documents per Job. The model document also
- addresses how security, internationalization, and directory issues
- are addressed.
-
- The "Internet Printing Protocol/1.1: Encoding and Transport" document
- is a formal mapping of the abstract operations and attributes defined
- in the model document onto HTTP/1.1 [RFC2616]. It also defines the
- encoding rules for a new Internet MIME media type called
- "application/ipp". This document also defines the rules for
- transporting over HTTP a message body whose Content-Type is
- "application/ipp". This document defines the 'ipp' scheme for
- identifying IPP printers and jobs.
-
- The "Internet Printing Protocol/1.1: Implementer's Guide" document
- gives insight and advice to implementers of IPP clients and IPP
- objects. It is intended to help them understand IPP/1.1 and some of
- the considerations that may assist them in the design of their client
- and/or IPP object implementations. For example, a typical order of
-
-
-
-Herriot & Hastings Standards Track [Page 92]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- processing requests is given, including error checking. Motivation
- for some of the specification decisions is also included.
-
- The "Mapping between LPD and IPP Protocols" document gives some
- advice to implementers of gateways between IPP and LPD (Line Printer
- Daemon) implementations.
-
-27. Contributors
-
- The following people made significant contributions to the design and
- review of this specification:
-
- Scott A. Isaacson
- Novell, Inc.
- 122 E 1700 S
- Provo, UT 84606
-
- Phone: 801-861-7366
- Fax: 801-861-2517
- EMail: sisaacson@novell.com
-
-
- Roger deBry
- Utah Valley State College
- Orem, UT 84058
-
- Phone: 801-863-8848
- EMail: debryro@uvsc.edu
-
-
- Jay Martin
- Underscore Inc.
- 9 Jacqueline St.
- Hudson, NH 03051-5308
-
- Phone: 603-889-7000
- Fax: 775-414-0245
- EMail: jkm@underscore.com
-
-
- Michael Shepherd
- Xerox Corporation
- 800 Phillips Road MS 128-51E
- Webster, NY 14450
-
- Phone: 716-422-2338
- Fax: 716-265-8871
- EMail: mshepherd@usa.xerox.com
-
-
-
-Herriot & Hastings Standards Track [Page 93]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
- Ron Bergman
- Ricoh Printing Systems America
- 1757 Tapo Canyon Road
- Simi Valley, CA 93063-3394
-
- Phone: 805-578-4421
- Fax: 805-578-4001
- EMail: ron.bergman@rpsa.ricoh.com
-
-Authors' Addresses
-
- Robert Herriot
- Global Workflow Solutions
- 706 Colorado Ave.
- Palo Alto, CA 94303
-
- Phone: 650-324-4000
- EMail: bob@herriot.com
-
-
- Tom Hastings
- Xerox Corporation
- 701 S Aviation Blvd, ESAE 242
- El Segundo, CA 90245
-
- Phone: 310-333-6413
- Fax: 310-333-6342
- EMail: hastings@cp10.es.xerox.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 94]
-\f
-RFC 3995 IPP: Event Notifications and Subscriptions March 2005
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2005).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at ietf-
- ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-Herriot & Hastings Standards Track [Page 95]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group R. Herriot
-Request for Comments: 3996 Global Workflow Solutions
-Updates: 2911 T. Hastings
-Category: Standards Track Xerox Corp.
- H. Lewis
- IBM Corp.
- March 2005
-
-
- Internet Printing Protocol (IPP):
- The 'ippget' Delivery Method for Event Notifications
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2005).
-
-Abstract
-
- This document describes an extension to the Internet Printing
- Protocol1.1: Model and Semantics (RFC 2911, RFC 2910). This document
- specifies the 'ippget' Pull Delivery Method for use with the
- "Internet Printing Protocol (IPP): Event Notifications and
- Subscriptions" specification (RFC 3995). This IPPGET Delivery Method
- is REQUIRED for all clients and Printers that support RFC 3995. The
- Notification Recipient, acting as a client, fetches (pulls) Event
- Notifications by using the Get-Notifications operation defined in
- this document.
-
-Table of Contents
-
- 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . 3
- 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 2.1. Conformance Terminology . . . . . . . . . . . . . . . . 4
- 2.2. Other Terminology . . . . . . . . . . . . . . . . . . . 4
- 3. Model and Operation . . . . . . . . . . . . . . . . . . . . . 4
- 4. General Information . . . . . . . . . . . . . . . . . . . . . 5
- 5. Get-Notifications Operation . . . . . . . . . . . . . . . . . 7
- 5.1. Get-Notifications Request . . . . . . . . . . . . . . . 8
- 5.1.1. notify-subscription-ids (1setOf integer(1:MAX)) 8
- 5.1.2. notify-sequence-numbers (1setOf integer(1:MAX)) 9
-
-
-
-Herriot, et al. Standards Track [Page 1]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- 5.1.3. notify-wait (boolean) . . . . . . . . . . . . . 10
- 5.2. Get-Notifications Response. . . . . . . . . . . . . . . 10
- 5.2.1. notify-get-interval (integer(0:MAX)). . . . . . 13
- 5.2.2. printer-up-time (integer(1:MAX)). . . . . . . . 14
- 6. Additional Information about Subscription Template Attributes 17
- 6.1. notify-pull-method (type2 keyword). . . . . . . . . . . 17
- 7. Subscription Description Attributes . . . . . . . . . . . . . 18
- 8. Additional Printer Description Attributes . . . . . . . . . . 18
- 8.1. ippget-event-life (integer(15:MAX)) . . . . . . . . . . 18
- 9. New Values for Existing Printer Description Attributes. . . . 19
- 9.1. notify-pull-method-supported (1setOf type2 keyword) . . 19
- 9.2. operations-supported (1setOf type2 enum). . . . . . . . 19
- 10. New Status Codes. . . . . . . . . . . . . . . . . . . . . . . 19
- 10.1. successful-ok-events-complete (0x0007) . . . . . . . . 20
- 11. Encoding and Transport. . . . . . . . . . . . . . . . . . . . 20
- 12. Conformance Requirements. . . . . . . . . . . . . . . . . . . 21
- 12.1. Conformance for IPP Printers . . . . . . . . . . . . . 21
- 12.2. Conformance for IPP Clients. . . . . . . . . . . . . . 22
- 13. Normative References. . . . . . . . . . . . . . . . . . . . . 23
- 14. Informative References. . . . . . . . . . . . . . . . . . . . 23
- 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
- 15.1. Attribute Registrations. . . . . . . . . . . . . . . . 24
- 15.2. Delivery Method and Additional Keyword Attribute Value
- registrations for Existing Attributes. . . . . . . . . 24
- 15.3. Additional Enum Attribute Values . . . . . . . . . . . 25
- 15.4. Operation Registrations. . . . . . . . . . . . . . . . 25
- 15.5. Status Code Registrations. . . . . . . . . . . . . . . 25
- 16. Internationalization Considerations . . . . . . . . . . . . . 25
- 17. Security Considerations . . . . . . . . . . . . . . . . . . . 26
- 17.1. Notification Recipient Client Access Rights. . . . . . 26
- 17.2. Printer Security Threats . . . . . . . . . . . . . . . 27
- 17.3. Notification Recipient Security Threats. . . . . . . . 27
- 17.4. Security Requirements for Printers . . . . . . . . . . 27
- 17.5. Security Requirements for clients. . . . . . . . . . . 28
- 18. Description of Base IPP Documents (Informative) . . . . . . . 28
- 19. Contributors. . . . . . . . . . . . . . . . . . . . . . . . . 29
- Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30
- Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 31
-
-Table of Tables
-
- Table 1. Information about the Delivery Method. . . . . . . . . . 5
- Table 2. Combinations of "notify-wait", "status-code", and
- "notify-get-interval". . . . . . . . . . . . . . . . . . 13
- Table 3. Attributes in Event Notification Content . . . . . . . . 15
- Table 4. Additional Attributes in Event Notification Content for
- Job Events . . . . . . . . . . . . . . . . . . . . . . . 16
-
-
-
-
-Herriot, et al. Standards Track [Page 2]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- Table 5. Combinations of Events and Subscribed Events for "job-
- impressions-completed" . . . . . . . . . . . . . . . . . 17
- Table 6. Additional Attributes in Event Notification Content for
- Printer Events . . . . . . . . . . . . . . . . . . . . . 17
- Table 7. Operation-id Assignments . . . . . . . . . . . . . . . . 19
- Table 8. The "event-notification-attributes-tag" Value. . . . . . 21
-
-1. Introduction
-
- This document describes an extension to the Internet Printing
- Protocol/1.1: Model and Semantics [RFC 2911], [RFC 2910]. This
- document specifies the 'ippget' Pull Delivery Method for use with the
- "Internet Printing Protocol (IPP): Event Notifications and
- Subscriptions" specification [RFC3995]. This IPPGET Delivery Method
- is REQUIRED for all clients and Printers that support [RFC3995]. The
- Notification Recipient, acting as a client, fetches (pulls) Event
- Notifications by using the Get-Notifications operation defined in
- this document. For a description of the base IPP documents, see
- section 21 of this document. For a description of the IPP Event
- Notification Model, see [RFC3995].
-
- With this Pull Delivery Method, when an Event occurs, the Printer
- saves the Event Notification for a period of time called the Event
- Life. The Notification Recipient fetches (pulls) the Event
- Notifications by using the Get-Notifications operation. This
- operation causes the Printer to return all Event Notifications held
- for the specified Subscription object(s). If the Notification
- Recipient has selected the Event Wait Mode option to wait for
- additional Event Notifications, the Printer MAY continue to return
- Event Notifications to the Notification Recipient as asynchronous
- Get-Notification responses as Events occur using the transaction
- originated by the Notification Recipient.
-
- The Notification Recipient can terminate Event Wait Mode (without
- closing the connection) by supplying the "notify-wait" (boolean)
- attribute with a 'false' value in a subsequent Get-Notifications
- request. Similarly, the Printer can terminate Event Wait Mode
- (without closing the connection) by returning the "notify-get-
- interval" (integer) operation attribute in a Get-Notifications
- response that tells the Notification Recipient how long to wait
- before trying again.
-
-2. Terminology
-
- This section defines the following terms that are used throughout
- this document:
-
-
-
-
-
-Herriot, et al. Standards Track [Page 3]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
-2.1. Conformance Terminology
-
- Capitalized terms such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD
- NOT, MAY, NEED NOT, and OPTIONAL have special meaning relating to
- conformance as defined in [RFC2119] and [RFC2911], section 12.1. If
- an implementation supports the extension defined in this document,
- then these terms apply; otherwise, they do not. These terms define
- conformance to this document only; they do not affect conformance to
- other documents, unless it is explicitly stated otherwise.
-
-2.2. Other terminology
-
- This document uses the same terminology as [RFC2911], including
- "client", "Printer", "Job", "attribute", "attribute value",
- "keyword", "operation", "request", "response", and "support", with
- the same meanings. This document also uses terminology defined in
- [RFC3995], such as "Subscription (object)", "Notification Recipient",
- "Event", "Event Notification", "Compound Event Notification", "Event
- Life", and "Event Notification Attribute Group", with the same
- meanings. In addition, this document defines the following terms for
- use in this document:
-
- Event Wait Mode: The mode requested by a Notification Recipient
- client in its Get-Notifications Request and granted by a Printer
- to keep the connection open while the Printer sends subsequent
- Get-Notification operation responses to the Notification
- Recipient in the form of Event Notifications as they occur.
-
-3. Model and Operation
-
- In a Subscription Creation Operation, when the "notify-pull-method"
- attribute is present and has the "ippget" keyword value, the client
- is requesting that the Printer use the "ippget" Pull Delivery Method
- for the Event Notifications associated with the new Subscription
- Object.
-
- When an Event occurs, the Printer MUST generate an Event Notification
- and MUST assign it the Event Life. The Printer MUST hold an Event
- Notification for its assigned Event Life.
-
- When a Notification Recipient wants to receive Event Notifications
- for a Subscription object, it performs the Get-Notifications
- operation supplying the Subscription object's subscription-id, which
- causes the Printer to return all un-expired Event Notifications held
- for that Subscription object. If the Notification Recipient has
- selected the Event Wait Mode option to wait for additional Event
- Notifications, the response to the Get-Notifications request
- continues indefinitely as the Printer continues to send Event
-
-
-
-Herriot, et al. Standards Track [Page 4]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- Notifications in the response as Events occur for that Subscription
- object.
-
- When the Notification Recipient requests Event Notifications for
- Per-Job Subscription Objects, the Notification Recipient typically
- performs the Get-Notifications operation within a second of
- performing the Subscription Creation operation. Because the Printer
- MUST save Event Notifications for at least 15 seconds (see section
- 8.1), the Notification Recipient is unlikely to miss any Event
- Notifications that occur between the Subscription Creation and the
- Get-Notifications operation.
-
- The 'ippget' Delivery Method is designed primarily for (1) a client
- that wants to get Events (from the job's Per-Job Subscription object)
- for a job that it has submitted and (2) a privileged client that
- wants to get all job or printer Events from a Per-Printer
- Subscription object.
-
-4. General Information
-
- If a Printer supports this Delivery Method, the following are its
- characteristics.
-
- Table 1. Information about the Delivery Method
-
- Document Method Conformance Requirement Delivery Method
- Realization
-
- 1. What is the URL scheme name for the 'ippget' keyword method
- Push Delivery Method, or the keyword name
- method name for the Pull Delivery
- Method?
-
- 2. Is the Delivery Method REQUIRED, REQUIRED
- RECOMMENDED, or OPTIONAL for an IPP
- Printer to support?
-
- 3. What transport and delivery protocols IPP with one new
- does the Printer use to deliver the operation.
- Event Notification Content; i.e.,
- what is the entire network stack?
-
- 4. Can several Event Notifications be Yes.
- combined into a Compound Event
- Notification?
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 5]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- 5. Is the Delivery Method initiated by This Delivery Method is
- the Notification Recipient (pull), a pull method with
- or by the Printer (push)? aspects of a push
- method, though the
- Printer does not
- initiate the operation.
-
- 6. Is the Event Notification content Machine Consumable.
- Machine Consumable or Human
- Consumable?
-
- 7. What section in this document answers Section 5.
- the following questions? For a Machine
- Consumable Event Notification, what is
- the representation and encoding of
- values defined in section 9.1 of
- [RFC3995], and what are the
- conformance requirements thereof? For
- a Human Consumable Event Notification,
- what is the representation and
- encoding of pieces of information
- defined in section 9.2 of
- [RFC3995], and the conformance
- requirements thereof?
-
- 8. What are the latency and reliability Same as IPP and the
- of the transport and delivery underlying HTTP
- protocol? transport.
-
- 9. What are the security aspects of the Same as IPP and the
- transport and delivery protocol; underlying HTTP
- e.g., how it is handled in transport and in the
- firewalls? same direction, so no
- new firewall
- considerations.
-
- 10. What are the content length None.
- restrictions?
-
- 11. What are the additional values or None.
- pieces of information that a Printer
- sends in an Event Notification content
- and the conformance requirements
- thereof?
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 6]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- 12. What are the additional Subscription None.
- Template and/or Subscription
- Description attributes and the
- conformance requirements thereof?
-
- 13. What are the additional Printer "ipp-event-life"
- Description attributes and the (integer (15: MAX))
- conformance requirements thereof?
-
-5. Get-Notifications Operation
-
- This operation is issued by a client acting in the role of a
- Notification Recipient requesting the Printer to return all Event
- Notifications held for the identified Subscription object(s).
-
- A Printer MUST support this operation, MUST accept the request in any
- state (see [RFC2911] "printer-state" and "printer-state-reasons"
- attributes), and MUST remain in the same state with the same
- "printer-state-reasons" values.
-
- When a Printer performs this operation, it MUST return all and only
- those Event Notifications
-
- 1. whose associated Subscription Object's "notify-subscription-id"
- Subscription Description attribute equals one of the values of
- the "notify-subscription-ids" (1setOf integer(1:MAX)) operation
- attribute AND
-
- 2. whose associated Subscription Object contains the "notify-pull-
- method" attribute and it has the 'ippget' keyword value, AND
-
- 3. whose "notify-sequence-number" is equal to or greater than the
- corresponding value of the "notify-sequence-numbers" (1setOf
- integer(1:MAX)) operation attribute if supplied AND
-
- 4. whose Event Life has not yet expired AND
-
- 5. where the Notification Recipient client has read-access rights to
- the identified Subscription Object (see Access Rights paragraph
- below).
-
- The Notification Recipient client MUST either (a) request Event Wait
- Mode by supplying the "notify-wait" operation attribute with a 'true'
- value or (b) suppress Event Wait Mode by omitting the "notify-wait"
- operation attribute or by supplying it with a 'false' value. To
- terminate Event Wait Mode subsequently, the Notification Recipient
- client MUST close the connection. To terminate Event Wait Mode, the
- Printer MUST either (a) return the "notify-get-interval" operation
-
-
-
-Herriot, et al. Standards Track [Page 7]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- attribute in a Get-Notifications response (RECOMMENDED behavior) or
- (b) close the connection. The "notify-get-interval" operation
- attributes tell the Notification Recipient how long to wait before
- trying a subsequent Get-Notifications request.
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation MUST be (1) the owner of each Subscription
- Object identified by the "notify-subscription-ids" operation
- attribute (see section 5.1.1), (2) an operator or administrator of
- the Printer (see [RFC2911], sections 1 and 8.5), or (3) otherwise
- authorized by the Printer's administrator-configured security policy
- to request Event Notifications from the target Subscription
- Object(s). Otherwise, the IPP Printer MUST reject the operation and
- return: 'client-error-forbidden', 'client-error-not-authenticated',
- or 'client-error-not-authorized' status code, as appropriate.
- Furthermore, the Printer's security policy MAY limit the attributes
- returned by the Get-Notifications operation, in a manner similar to
- that of the Get-Job-Attributes operation (see [RFC2911], end of
- section 3.3.4.2).
-
-5.1. Get-Notifications Request
-
- The following groups of attributes are part of the Get-Notifications
- Request:
-
- Group 1: Operation Attributes
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes, as described in [RFC2911], section 3.1.4.1.
-
- Target:
- The "printer-uri" (uri) operation attribute that is the target
- for this operation as described in [RFC2911], section 3.1.5.
-
- Requesting User Name:
- The "requesting-user-name" (name(MAX)) attribute SHOULD be
- supplied by the client as described in [RFC2911], section 8.3.
-
-5.1.1. notify-subscription-ids (1setOf integer(1:MAX))
-
- This attribute identifies one or more Subscription objects for which
- Events are requested. The client MUST supply this attribute with at
- least one value. The Printer object MUST support this attribute with
- multiple values.
-
- If no Subscription Object exists with the supplied identifier, or if
- the identified Subscription Object does not contain the "notify-
-
-
-
-Herriot, et al. Standards Track [Page 8]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- pull-method" attribute with the 'ippget' keyword value, the Printer
- MUST return the 'client-error-not-found' status code.
-
- Note: The name of both the "notify-subscription-ids" and
- "notify-sequence-numbers" end in 's', as they are multi-valued.
- However, there are other occurrences of these attribute names
- without the 's' that are single valued.
-
-5.1.2. notify-sequence-numbers (1setOf integer(1:MAX))
-
- This attribute specifies one or more of the lowest Event Notification
- sequence number values for the Subscription objects identified by the
- corresponding values of the "notify-subscription-ids" operation
- attribute. The Notification Recipient SHOULD supply this attribute,
- and the number of values SHOULD be the same as that of the "notify-
- subscriptions-ids" attribute. The Printer MUST support this
- attribute with multiple values.
-
- The Printer MUST NOT return Notification Events with lower sequence
- numbers for the corresponding Subscription object. Therefore, by
- supplying the proper values for this attribute the Notification
- Recipient can prevent getting the same Event Notifications from a
- Subscription object that were returned on a previous Get-
- Notifications request. The Notification Recipient SHOULD remember
- the highest "notify-sequence-number" value returned for each
- Subscription object requested and SHOULD pass that value for each
- requested Subscription object on the next Get-Notifications request.
-
- If the Notification Recipient supplies fewer values for this
- attribute (including omitting this attribute) than it does for the
- "notify-subscription-ids" operation attribute, the Printer assumes a
- '1' value for each missing value. A value of '1' causes the Printer
- to return any un-expired Event Notification for that Subscription
- object, as '1' is the lowest possible sequence number. If the
- Notification Recipient supplies more values for this attribute than
- the number of values for the "notify-subscription-ids" operation
- attribute, the Printer ignores the extra values.
-
- Note: If a Notification Recipient performs two consecutive Get-
- Notifications operations with the same value for "notify-sequence-
- number" (or omits the attribute), the time stamp value of the first
- Event Notification in the second Get-Notifications Response may be
- less than that of the time stamp of the last Event Notification in
- the first Get-Notification Response. This happens because the
- Printer sends all unexpired Event Notifications with an equal or
- higher sequence number according to the ordering specified in
- [RFC3995], and some Event Notifications from the first Get-
-
-
-
-
-Herriot, et al. Standards Track [Page 9]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- Notifications operation may not have expired by the time the second
- Get-Notifications operation occurs.
-
-5.1.3. notify-wait (boolean)
-
- This value indicates whether the Notification Recipient wants Event
- Wait Mode. The client MAY supply this attribute. The Printer object
- MUST support both values of this attribute.
-
- If the client supplies the 'false' value or omits this attribute, the
- client is not requesting Event Wait Mode. If the value is 'true',
- the client is requesting Event Wait Mode. See the beginning of
- section 5.2 for the rules for Event Wait Mode.
-
-5.2. Get-Notifications Response
-
- The Printer has the following options for responding to a Get-
- Notifications Request:
-
- 1. The Printer can reject the request and return the 'server-error-
- busy' status code if the Printer is too busy to accept this
- operation at this time. In this case, the Printer MUST return
- the "get-notify-interval" operation attribute to indicate when
- the client SHOULD try again.
-
- 2. If the Notification Recipient did not request Event Wait Mode
- ("notify-wait-mode" = 'false' or omitted), the Printer MUST
- immediately return whatever Event Notifications it currently
- holds in the requested Subscription object(s) and MUST return the
- "notify-get-interval" operation attribute with the number of
- seconds from now, at which the Notification Recipient SHOULD
- repeat the Get-Notifications Request to get future Event
- Notifications.
-
- 3. If the Notification Recipient requested Event Wait Mode
- ("notify-wait-mode" = 'true'), the Printer MUST immediately
- return whatever Event Notifications it currently holds in the
- requested Subscription object(s) and MUST continue to return
- Event Notifications as they occur until all the requested
- Subscription Objects are canceled. A Subscription Object is
- canceled either via the Cancel-Subscription operation or by the
- Printer (e.g., the Subscription Object is canceled when the
- associated Job completes and is no longer in the Job Retention or
- Job History phase; see the "ippget-event-life (integer(15:MAX))"
- attribute discussion in section 8.1).
-
- However, the Printer MAY decide to terminate Event Wait Mode at
- any time, including in the first response. In this case, the
-
-
-
-Herriot, et al. Standards Track [Page 10]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- Printer MUST return the "notify-get-interval" operation
- attribute. This attribute indicates that the Printer wishes to
- leave Event Wait Mode and the number of seconds in the future
- that the Notification Recipient SHOULD try the Get-Notifications
- operation again. The Notification Recipient MUST accept this
- response and MUST disconnect. If the Notification Recipient does
- not disconnect, the Printer SHOULD do so.
-
- From the Notification Recipient's view, the response appears as an
- initial burst of data, which includes the Operation Attributes Group
- and one Event Notification Attributes Group per Event Notification
- that the Printer is holding. After the initial burst of data, if the
- Notification Recipient has selected the Event Wait Mode option to
- wait for additional Event Notifications, the Notification Recipient
- receives occasional Event Notification Attribute Groups. Proxy
- servers may delay some Event Notifications or cause time-outs to
- occur. The client MUST be prepared to perform the Get-Notifications
- operation again when time-outs occur.
-
- Each attribute is encoded by using the IPP rules for encoding
- attributes [RFC2910] and MAY be encoded in any order. Note: the
- Get-Jobs response in [RFC2911] acts as a model for encoding multiple
- groups of attributes. See section 11 for the encoding and transport
- rules.
-
- The following groups of attributes are part of the Get-Notifications
- Response:
-
- Group 1: Operation Attributes
-
- Status Message: In addition to the REQUIRED status code returned
- in every response, the response OPTIONALLY includes a "status-
- message" (text(255)) and/or a "detailed-status-message"
- (text(MAX)) operation attribute, as described in [RFC2911],
- sections 13 and 3.1.6.
-
- The Printer can return any status codes defined in [RFC2911].
- If the status code is not 'successful-xxx', the Printer MUST
- NOT return any Event Notification Attribute groups. The
- following are descriptions of the important status codes:
-
- successful-ok: The response contains all Event Notification
- associated with the specified subscription-ids that had
- been supplied in the "notify-subscription-ids" operation
- attribute in the request. If the requested Subscription
- Objects have no associated Event Notification, the
- response MUST contain zero Event Notifications.
-
-
-
-
-Herriot, et al. Standards Track [Page 11]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- successful-ok-events-complete: Indicates when this return
- is the last return for all Subscription objects that
- match the request, whether or not Event Notifications are
- returned. This condition occurs for Event Wait Mode with
- Notification Recipients waiting for responses when (1)
- the Subscription Object is canceled with a Cancel-
- Subscription operation, (2) the Subscription Object is
- deleted, when the Per-Printer Subscription lease time
- expires, or (3) the 'job-completed' event occurs for a
- Per-Job Subscription. This condition also occurs for a
- Get-Notifications request that a Notification Recipient
- makes after the job completes, but before the Event Life
- expires. See section 10.1.
- client-error-not-found: The Printer has no Subscription
- Objects whose "notify-subscription-id" attribute equals
- any of the values of the "notify-subscription-ids"
- operation attribute supplied, or the identified
- Subscription Object does not contain the "notify-pull-
- method" attribute with the 'ippget' keyword value.
- server-error-busy: The Printer is too busy to accept this
- operation. The Printer SHOULD return the "notify-get-
- interval" operation attribute in the Operation Attributes
- of the response; then the Notification Recipient SHOULD
- wait for the number of seconds specified by the "notify-
- get-interval" operation attribute before performing this
- operation again. If the "notify-get-interval" Operation
- Attribute is not present, the Notification Recipient
- SHOULD use the normal network back-off algorithms to
- determine when to perform this operation again.
-
- Natural Language and Character Set:
- The "attributes-charset" and "attributes-natural-language"
- attributes, as described in [RFC2911], section 3.1.4.2.
-
- The Printer MUST use the values of "notify-charset" and
- "notify-natural-language", respectively, from one Subscription
- Object associated with the Event Notifications in this
- response.
-
- Normally, there is only one matched Subscription Object, or the
- value of the "notify-charset" and "notify-natural-language"
- attributes is the same in all Subscription Objects. If not,
- the Printer MUST pick one Subscription Object from which to
- obtain the value of these attributes. The algorithm for
- picking the Subscription Object is implementation dependent.
- The choice of natural language is not critical, because 'text'
- and 'name' values can override the "attributes-natural-
- language" operation attribute. The Printer's choice of charset
-
-
-
-Herriot, et al. Standards Track [Page 12]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- is critical because a bad choice may leave it unable to send
- some 'text' and 'name' values accurately.
-
-5.2.1. notify-get-interval (integer(0:MAX))
-
- The value of this operation attribute is the number of seconds that
- the Notification Recipient SHOULD wait before trying the Get-
- Notifications operation again. The Printer MUST return this
- operation attribute if (1) it is too busy to return events, (2) the
- Notification Recipient client did not request Event Wait Mode, or (3)
- the Printer is terminating Event Wait Mode. The client MUST accept
- this attribute and SHOULD reissue the Get-Notifications operation
- (with or without "notify-wait" = 'true') at the indicated number of
- seconds in the future in order to get more Event Notifications This
- value is intended to help the client be a good network citizen.
-
- The value of this attribute MUST be at least as large as that of the
- Printer's "ippget-event-life" Printer Description attribute (see
- section 8.1). The Printer MAY return a value that is larger than
- that of the "ippget-event-life" Printer Description attribute
- provided that the Printer increases the Event Life for this
- Subscription object so that Notification Recipients taking account of
- the larger value and polling with a longer interval will not miss
- events. Note: Implementing such an algorithm requires some hidden
- attributes in the Subscription object that are IMPLEMENTATION
- DEPENDENT.
-
- If the Printer wants to remain in Event Wait Mode, then the Printer
- MUST NOT return this attribute in the response.
-
- Here is a complete table of combinations of "notify-wait", "status-
- code", "notify-get-interval", and Event Notification Attributes
- Groups for Get-Notification initial (Wait and No Wait) Responses and
- subsequent Event Wait Mode Responses (which may stay in Event Wait
- Mode or may request the Notification Recipient to leave Event Wait
- Mode):
-
- Table 2. Combinations of "notify-wait", "status-code", and
- "notify-get-interval"
-
- Client sends: Printer returns: Printer Event
- returns: Notification
- "notify-wait" "status-code" "notify-get- Attribute
- interval" Groups
-
- 1. 'false'* 'successful-ok' MUST return N maybe
- 2. 'false'* 'not-found' MUST NOT MUST NOT
- 3. 'false'* 'busy' MUST return N MUST NOT
-
-
-
-Herriot, et al. Standards Track [Page 13]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- 4. 'false'* 'events- MUST NOT 'job-
- complete' completed'
- 5. 'true' 'successful-ok' MUST NOT MUST
- 6. 'true' 'successful-ok' MUST return N maybe
- 7. 'true' 'not-found' MUST NOT MUST NOT
- 8. 'true' 'busy' MUST return N MUST NOT
- 9. 'true' 'events- MUST NOT 'job-
- complete' completed' or
- maybe other
- * 'false' or client omits the "notify-wait" attribute.
-
- Explanation:
-
- 1-4: Client does not request Event Wait Mode.
- 5-9: Client requests Event Wait Mode.
- 2,7: Subscription object not found, or was canceled earlier;
- client should NOT try again.
- 3,8: Server busy, tells client to try later; client should try
- again in N seconds.
- 4: Client polled after job completed, but before Event Life
- expired, and got the 'job-completed' event, so the client
- shouldn't bother trying again; client should NOT try
- again later.
- 5: Printer returns one or more Event Notifications and is OK
- to stay in Event Wait Mode; the client waits for more
- Event Notifications to be returned.
- 6: Printer wants to leave Event Wait mode. Can happen on
- the first response (with or without Event Notifications)
- or happen on a subsequent response with or without Event
- Notifications; the client SHOULD try again in N seconds.
- 9: Either (1) the printer returns 'job-completed' event, or
- (2) the Subscription Object was canceled by either a
- Cancel-Job or a Per-Printer Subscription expired without
- being renewed. For case (1), at least one Event
- Notification MUST be returned; for case (2), it is
- unlikely that any Event Notifications are returned, and
- the client should NOT try again.
-
-5.2.2. printer-up-time (integer(1:MAX))
-
- The value of this attribute is the Printer's "printer-up-time"
- attribute at the time when the Printer sends this response. The
- Printer MUST return this attribute. Because each Event Notification
- also contains the value of this attribute when the event occurred,
- the value of this attribute lets a Notification Recipient know when
- each Event Notification occurred relative to the time of this
- response.
-
-
-
-
-Herriot, et al. Standards Track [Page 14]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- Group 2: Unsupported Attributes
- See [RFC2911], section 3.1.7, for details on returning
- Unsupported Attributes.
-
- Group 3 through N: Event Notification Attributes
- The Printer responds with one Event Notification Attributes
- Group per matched Event Notification. The entire response is
- considered a single Compound Event Notification (see
- [RFC3995]). The matched Event Notifications are all un-expired
- Event Notifications associated with the matched Subscription
- Objects and MUST follow the "Event Notification Ordering"
- requirements for Event Notifications within a Compound Event
- Notification specified in [RFC3995] section 9. In other words,
- the Printer MUST order these Event Notification groups in
- ascending time stamp (and sequence number) order for a
- Subscription object. If Event Notifications for multiple
- Subscription objects are being returned, the Notification
- Events for the next Subscription object follow in ascending
- time stamp order, etc.
-
- Each Event Notification Group MUST contain all of attributes
- specified in section 9.1 ("Content of Machine Consumable Event
- Notifications") of [RFC3995], with exceptions denoted by
- asterisks in the tables below.
-
- The tables below are identical to those in section 9.1
- ("Content of Machine Consumable Event Notifications") of
- [RFC3995], except that each cell in the "Sends" column is a
- "MUST".
-
- If more than one Event Notification is being returned and the
- status of each is not the same, then the Printer MUST return a
- "notify-status-code" attribute in each Event Notification
- Attributes group to indicate the differing status values.
-
- For an Event Notification for all Events, the Printer includes
- the attributes shown in Table 3.
-
- Table 3. Attributes in Event Notification Content
-
- Source Value Sends Source Object
-
- notify-subscription-id (integer(1:MAX)) MUST Subscription
- notify-printer-uri (uri) MUST Subscription
- notify-subscribed-event (type2 keyword) MUST Event
- Notification
- printer-up-time (integer(1:MAX)) * MUST Printer
- printer-current-time (dateTime) MUST ** Printer
-
-
-
-Herriot, et al. Standards Track [Page 15]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- notify-sequence-number (integer (0:MAX)) MUST Subscription
- notify-charset (charset) MUST Subscription
- notify-natural-language (naturalLanguage) MUST Subscription
- notify-user-data (octetString(63)) MUST *** Subscription
- notify-text (text) MUST Event
- Notification
- attributes from the "notify-attributes" MUST **** Printer
- attribute
- attributes from the "notify-attributes" MUST **** Job
- attribute
- attributes from the "notify-attributes" MUST **** Subscription
- attribute
-
- * As specified in [RFC3995] section 9, the value of the
- "printer-up-time" attribute sent in each Event Notification
- MUST be the time at which the Event occurred, not the time at
- which the Event Notification was sent.
-
- ** The Printer MUST send the "printer-current-time" attribute
- if and only if it supports the "printer-current-time" attribute
- on the Printer object.
-
- *** If the associated Subscription Object does not contain a
- "notify-user-data" attribute, the Printer MUST send an
- octet-string of length 0.
-
- **** If the "notify-attributes" attribute is present on the
- Subscription Object, the Printer MUST send all attributes
- specified by the "notify-attributes" attribute. Note: If the
- Printer doesn't support the "notify-attributes" attribute, it
- is not present on the associated Subscription Object.
-
- For Event Notifications for Job Events, the Printer includes
- the additional attributes shown in Table 4.
-
- Table 4. Additional Attributes in Event Notification Content for
- Job Events
-
- Source Value Sends Source Object
-
- job-id (integer(1:MAX)) MUST Job
- job-state (type1 enum) MUST Job
- job-state-reasons (1setOf type2 keyword) MUST Job
- job-impressions-completed (integer(0:MAX)) MUST * Job
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 16]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- * The Printer MUST send the "job-impressions-completed" attribute
- in an Event Notification only for the combinations of Events and
- Subscribed Events shown in Table 5.
-
- Table 5. Combinations of Events and Subscribed Events for
- "job-impressions-completed"
-
- Job Event Subscribed Job Event
-
- 'job-progress' 'job-progress'
- 'job-completed' 'job-completed'
- 'job-completed' 'job-state-changed'
-
- For Event Notification for Printer Events, the Printer includes
- the additional attributes shown in Table 6.
-
- Table 6. Additional Attributes in Event Notification Content for
- Printer Events
-
- Source Value Sends Source
- Object
-
- printer-state (type1 enum) MUST Printer
- printer-state-reasons (1setOf type2 keyword) MUST Printer
- printer-is-accepting-jobs (boolean) MUST Printer
-
-6. Additional Information about Subscription Template Attributes
-
- The 'ippget' Delivery Method does not define any addition
- Subscription Template attributes and has the conformance requirements
- for Subscription Template attributes defined in [RFC3995]. This
- section defines additional information about Subscription Template
- attributes defined in [RFC3995].
-
-6.1. notify-pull-method (type2 keyword)
-
- This Subscription Template attribute identifies the Pull Delivery
- Method to be used for the Subscription Object (see [RFC3995]). To
- support the 'ippget' Pull Delivery Method defined in this document,
- the Printer MUST support this attribute with the following keyword
- value:
-
- 'ippget': Indicates that the 'ippget' Pull Delivery Method is to
- be used for this Subscription Object.
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 17]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
-7. Subscription Description Attributes
-
- The 'ippget' Delivery Method has the conformance requirements for
- Subscription Description attributes defined in [RFC3995]. The
- 'ippget' Delivery Method does not define any addition Subscription
- Description attributes.
-
-8. Additional Printer Description Attributes
-
- This section defines additional Printer Description attributes for
- use with the 'ippget' Delivery Method.
-
-8.1. ippget-event-life (integer(15:MAX))
-
- This Printer Description attribute specifies the Event Life value
- that the Printer assigns to each Event; i.e., the number of seconds
- after an Event occurs during which a Printer will return that Event
- in an Event Notification in a Get-Notifications response. After the
- Event Life expires for the Event, the Printer MAY no longer return an
- Event Notification for that Event in a Get-Notifications response.
-
- The Printer MUST support this attribute if it supports the 'ippget'
- Delivery Method. The value MUST be 15 or more (at least 15 seconds),
- and 60 (seconds) is the RECOMMENDED value to align with the PWG Job
- Monitoring MIB [RFC2707] jmGeneralJobPersistence and
- jmGeneralAttributePersistence objects.
-
- For example, assume the following:
-
- 1. A client performs a Job Creation operation that creates a
- Subscription Object associated with the 'ippget' Delivery Method;
-
- 2. An Event associated with the new Job occurs immediately after the
- Subscription Object is created;
-
- 3. the same client or some other client performs a Get-Notifications
- operation so that the client is connected N seconds after the Job
- Creation operation.
-
- Then, if N is less than the value of this attribute, the client(s)
- performing the Get-Notifications operations can expect not to miss
- any Event-Notifications, barring some unforeseen lack of memory space
- in the Printer. Note: The client MUST initiate the Get-
- Notifications at a time that is sufficiently less that N seconds to
- account for network latency so that it is connected to the Printer
- before N seconds elapses.
-
-
-
-
-
-Herriot, et al. Standards Track [Page 18]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- If a Printer supports the 'ippget' Delivery Method, it MUST keep
- 'completed', 'canceled', or 'aborted' Job objects in the Job
- Retention and/or Job History phases for at least as long as this
- attribute's value. The Printer MAY retain jobs longer that this
- value. See [RFC2911], section 4.3.7.1, and the discussion in
- [RFC3995] (regarding the 'job-completed' event). The latter explains
- that a Notification Recipient can query the Job after receiving a
- 'job-completed' Event Notification in order to find out other
- information about the job that is 'completed', 'aborted', or
- 'canceled'. However, this attribute has no effect on the Cancel-
- Subscription operation, which deletes the Subscription object
- immediately whether or not it contains the "notify-pull-method"
- attribute with the 'ippget' keyword value. Immediately thereafter,
- subsequent Get-Notifications Responses MUST NOT contain Event
- Notifications associated with the canceled Subscription object.
-
-9. New Values for Existing Printer Description Attributes
-
- This section defines additional values for existing Printer
- Description attributes as defined in [RFC3995].
-
-9.1. notify-pull-method-supported (1setOf type2 keyword)
-
- The following keyword value for the "notify-pull-method-supported"
- attribute is added in order to support the new Delivery Method
- defined in this document:
-
- 'ippget': The IPP Notification Pull Delivery Method defined in
- this document.
-
-9.2. operations-supported (1setOf type2 enum)
-
- Table 7 lists the "operation-id" value defined in order to support
- the new Get-Notifications operation defined in this document.
-
- Table 7. Operation-id Assignments
-
- Value Operation Name
-
- 0x001C Get-Notifications
-
-10. New Status Codes
-
- The following status code is defined as an extension for this
- Delivery Method and is returned as the status code of the Get-
- Notifications operation in Group 1 or Group 3 to N (see section 5.2).
-
-
-
-
-
-Herriot, et al. Standards Track [Page 19]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
-10.1. successful-ok-events-complete (0x0007)
-
- The Printer MUST return the 'successful-ok-events-complete' status
- code to indicate when this Get-Notifications response is the last
- response for a Subscription object, whether or not there are Event
- Notifications being returned. This condition occurs for Event Wait
- Mode with Notification Recipients waiting for responses when (1) the
- Subscription Object is canceled with a Cancel-Subscription operation,
- (2) the Subscription object is deleted, when the Per-Printer
- Subscription lease time expires, or (3) the 'job-completed' event
- occurs for a Per-Job Subscription. This condition also occurs for a
- Get-Notifications request that a Notification Recipient makes after
- the job completes, but before the Event Life expires.
-
-11. Encoding and Transport
-
- This section defines the encoding and transport considerations for
- this Delivery Method based on [RFC2910].
-
- The encoding of a Get-Notifications Response is modeled after the
- Get-Jobs Response (see [RFC2911]). In a Get-Notifications Response,
- each Event Notification Attributes Group MUST start with an 'event-
- notification-attributes-tag' (see the section "Encodings of
- Additional Attribute Tags" in [RFC3995]), and end with an 'end-of-
- attributes-tag'. In addition, for Event Wait Mode the multi-
- part/related is used to separate each multiple response (in time) to
- a single Get-Notifications Request.
-
- The Printer returns Get-Notification Response as follows:
-
- 1. If the Notification Recipient client did not request Event Wait
- Mode ("notify-wait" = 'false' or omitted), the Printer ends the
- response with an 'end-of-attributes-tag' (see [RFC2911], Get-Jobs
- encoding), as with any operation response.
-
- 2. If the Notification Recipient client requests Event Wait Mode
- ("notify-wait" = 'true') and the Printer wishes to honor the
- request, the Printer MUST return the response as an
- application/ipp part inside a multi-part/related MIME media type.
- When one or more additional Events occur, the Printer returns
- each as an additional Event Notification Group using a separate
- application/ipp part under the multi-part/related type.
-
- 3. If the client requested Event Wait Mode ("notify-wait" = 'true'),
- but the Printer does not wish to honor the request in the initial
- response and wants the client explicitly polled for Event
- Notifications, the Printer MUST return the "notify-get-interval"
- operation attribute (see section 5.2.1). The Printer returns the
-
-
-
-Herriot, et al. Standards Track [Page 20]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- response as an application/ipp part that MAY be inside an multi-
- part/related type. The client MUST accept this response and
- reissue the Get-Notifications request in the future indicated by
- the value of the "notify-get-interval" attribute value.
-
- 4. If the client requested Event Wait Mode ("notify-wait" = 'true'),
- and the Printer initially honored the request but later wishes to
- leave Event Wait Mode, the Printer MUST return the "notify-get-
- interval" operation attribute (see section 5.2.1). The Printer
- returns the response as an application/ipp part that MUST be
- inside an multi-part/related type.
-
- NOTE: If a Notification Recipient fails to receive a response, it
- can ask the Printer for the same Event Notifications again. The
- Notification Recipient will receive the same Event Notifications that
- it should have received the first time, except for those Event
- Notifications that have expired in the meantime.
-
- The Printer MAY chunk the responses, but this has no significance to
- the IPP semantics.
-
- This notification delivery method uses the IPP transport and encoding
- [RFC2910] for the Get-Notifications operation with the following
- extension, allocated in [RFC3995]:
-
- Table 8. The "event-notification-attributes-tag" Value
-
- Tag Value (Hex) Meaning
-
- 0x07 "event-notification-attributes-tag"
-
-12. Conformance Requirements
-
- This section lists the conformance requirements for clients and
- Printers.
-
-12.1. Conformance for IPP Printers
-
- It is OPTIONAL for a Printer to support IPP Notifications as defined
- in [RFC3995]. However, if a Printer supports IPP Notifications, the
- Printer MUST support the 'ippget' Delivery Method, as defined in this
- document, as one of its Delivery Methods. IPP Printers that conform
- to this specification
-
- 1. MUST meet the conformance requirements defined in [RFC3995] for a
- Pull Delivery Method;
-
-
-
-
-
-Herriot, et al. Standards Track [Page 21]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- 2. MUST support the Get-Notifications operation defined in section
- 5, including Event Wait Mode;
-
- 3. MUST support the Subscription Template object attributes, as
- defined in section 6;
-
- 4. MUST support the Subscription Description object attributes, as
- defined in section 7;
-
- 5. MUST support the "ippget-event-life" Printer Description
- attribute defined in section 8.1, including retaining jobs in the
- Job Retention and/or Job History phases for at least as long as
- the value specified by the Printer's "ippget-event-life";
-
- 6. MUST support the additional values for IPP/1.1 Printer
- Description attributes defined in section 9;
-
- 7. MUST support the 'successful-ok-events-complete' status code, as
- described in section 10.1;
-
- 8. MUST listen for the IPP Get-Notifications operation requests on
- IANA-assigned well-known port 631, unless explicitly configured
- by system administrators or site policies;
-
- 9. SHOULD NOT listen for IPP Get-Notifications operation requests on
- any other port, unless explicitly configured by system
- administrators or site policies; and
-
- 10. MUST meet the security conformance requirements stated in section
- 18.4.
-
-12.2. Conformance for IPP Clients
-
- It is OPTIONAL for an IPP Client to support IPP Notifications as
- defined in [RFC3995]. However, if a client supports IPP
- Notifications, the client MUST support the 'ippget' Delivery Method
- as defined in this document as one of its Delivery Methods. IPP
- Clients that conform to this specification:
-
- 1. MUST create Subscription Objects by sending Subscription Creation
- operation requests containing the "notify-pull-method" attribute
- (as opposed to the "notify-recipient-uri" attribute) using the
- 'ippget' keyword value (see sections 6.1 and 15.2);
-
- 2. MUST send IPP Get-Notifications operation requests (see section
- 5.1) via the port specified in the associated 'ipp' URL (if
- present) or otherwise via IANA-assigned well-known port 631;
-
-
-
-
-Herriot, et al. Standards Track [Page 22]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- 3. MUST convert the associated 'ipp' URLs for use in IPP Get-
- Notifications operation to their corresponding 'http' URL forms
- for use in the HTTP layer, according to the rules in section 5,
- "IPP URL Scheme", in [RFC2910]; and
-
- 4. MUST meet the security conformance requirements stated in section
- 18.5.
-
-13. Normative References
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2910] Herriot, R., Butler, S., Moore, P., Turner, R., and J.
- Wenn, "Internet Printing Protocol/1.1: Encoding and
- Transport", RFC 2910, September 2000.
-
- [RFC2911] Hastings, T., Herriot, R., deBry, R., Isaacson, S., and
- P. Powell, "Internet Printing Protocol/1.1: Model and
- Semantics", RFC 2911, September 2000.
-
- [RFC3995] Herriot, R. and T. Hastings, "Internet Printing Protocol
- (IPP): Event Notifications and Subscriptions", RFC 3995,
- March 2005.
-
-14. Informative References
-
- [RFC2565] Herriot, R., Butler, S., Moore, P., and R. Turner,
- "Internet Printing Protocol/1.0: Encoding and
- Transport", RFC 2565, April 1999.
-
- [RFC2566] deBry, R., Hastings, T., Herriot, R., Isaacson, S., and
- P. Powell, "Internet Printing Protocol/1.0: Model and
- Semantics", RFC 2566, April 1999.
-
- [RFC2567] Wright, F., "Design Goals for an Internet Printing
- Protocol", RFC 2567, April 1999.
-
- [RFC2568] Zilles, S., "Rationale for the Structure of the Model
- and Protocol for the Internet Printing Protocol", RFC
- 2568, April 1999.
-
- [RFC2569] Herriot, R., Hastings, T., Jacobs, N., and J. Martin,
- "Mapping between LPD and IPP Protocols", RFC 2569, April
- 1999.
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 23]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
- Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
- Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
-
- [RFC2707] Bergman, R., Hastings, T., Isaacson, S., and H. Lewis,
- "Job Monitoring MIB - V1.0", RFC 2707, November 1999.
-
- [RFC3196] Hastings, T., Manros, C., Zehler, P., Kugler, C., and H.
- Holst, "Internet Printing Protocol/1.1: Implementor's
- Guide", RFC 3196, November 2001.
-
- [RFC3997] Hastings, T., Ed., deBry, R., and H. Lewis, "Internet
- Printing Protocol (IPP): Requirements for IPP
- Notifications", RFC 3997, March 2005.
-
-15. IANA Considerations
-
- This section contains the exact information that the IANA has added
- to the IPP Registries according to the procedures defined in
- [RFC2911], section 6. These registrations have been published in the
- http://www.iana.org/assignments/ipp-registrations registry.
-
-15.1. Attribute Registrations
-
- The following table lists the attributes defined in this document.
- This has been registered according to the procedures in RFC 2911
- [RFC2911] section 6.2.
-
- Printer Description attributes: Reference Section
- ------------------------------- --------- -------
- ippget-event-life (integer(15:MAX)) [RFC3996] 8.1
-
-15.2. Delivery Method and Additional Keyword Attribute Value
- Registrations for Existing Attributes
-
- This section lists additional keyword attribute value registrations
- for use with existing attributes defined in other documents. These
- have been registered according to the procedures in [RFC2911],
- section 6.1. According to [RFC3995], section 24.7.3, Pull Delivery
- Method registrations are the keyword attribute value registrations
- for the "notify-pull-method" and "notify-pull-method-supported"
- attributes.
-
-
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 24]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- Attribute (attribute syntax)
- Values Reference Section
- ----------------------- --------- -------
- notify-pull-method (type2 keyword) [RFC3995] 5.3.2
- notify-pull-method-supported (1setOf type2 keyword)
- [RFC3995] 5.3.2.1
- ippget [RFC3996] 9.1
-
-15.3. Additional Enum Attribute Values
-
- The following table lists the enum attribute values defined in this
- document. These have been registered according to the procedures in
- [RFC2911], section 6.1.
-
- Attribute (attribute syntax)
- Value Name Reference Section
- ------ ----------------------------- --------- -------
- operations-supported (1setOf type2 enum) [RFC2911] 4.4.15
- 0x001C Get-Notifications [RFC3996] 9.2
-
-15.4. Operation Registrations
-
- The following table lists the operations defined in this document.
- This has been registered according to the procedures in RFC 2911
- [RFC2911] section 6.4.
-
- Operations: Reference Section
- ----------- --------- -------
- Get-Notifications [RFC3996] 5
-
-15.5. Status Code Registrations
-
- The following table lists the status codes defined in this document.
- This has been registered according to the procedures in [RFC2911],
- section 6.6.
-
- Status codes: Reference Section
- ------------- --------- -------
- successful-ok-events-complete (0x0007) [RFC3996] 10.1
-
-16. Internationalization Considerations
-
- The IPP Printer MUST localize the "notify-text" attribute as
- specified in section 14 of [RFC3995].
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 25]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- In addition, when the client receives the Get-Notifications response,
- it is expected to localize the attributes that have the 'keyword'
- attribute syntax according to the charset and natural language
- requested in the Get-Notifications request.
-
-17. Security Considerations
-
- The IPP Model and Semantics document [RFC2911, section 8] discusses
- high-level security requirements (Client Authentication, Server
- Authentication and Operation Privacy). The IPP Transport and
- Encoding document [RFC2910, section 8] discusses the security
- requirements for the IPP protocol. Client Authentication is the
- mechanism by which the client proves its identity to the server in a
- secure manner. Server Authentication is the mechanism by which the
- server proves its identity to the client in a secure manner.
- Operation Privacy is defined as a mechanism for protecting operations
- from eavesdropping.
-
- The 'ippget' Delivery Method with its Get-Notifications operations
- leverages the security mechanism that are used in IPP/1.1 [RFC2910
- and RFC2911] without adding any additional security mechanisms in
- order to maintain the same security support as IPP/1.1.
-
- The access control model for the Get-Notifications operation defined
- in this document is the same as the access control model for the
- Get-Job-Attributes operation (see [RFC2911], section 3.2.6). The
- primary difference is that a Get-Notifications operation is directed
- at Subscription Objects rather than at Job objects, and a returned
- attribute group contains Event Notification attributes rather than
- Job object attributes.
-
-17.1. Notification Recipient Client Access Rights
-
- The Notification Recipient client MUST have the following access
- rights to the Subscription object(s) targeted by the Get-
- Notifications operation request:
-
- The authenticated user (see [RFC2911], section 8.3) performing
- this operation MUST be (1) the owner of each Subscription Object
- identified by the "notify-subscription-ids" operation attribute
- (see section 5.1.1), (2) an operator or administrator of the
- Printer (see [RFC2911], sections 1 and 8.5), or (3) otherwise
- authorized by the Printer's administrator-configured security
- policy to request Event Notifications from the target Subscription
- Object(s). Furthermore, the Printer's security policy MAY limit
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 26]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- the attributes returned by the Get-Notifications operation, in a
- manner similar to that of the Get-Job-Attributes operation (see
- [RFC2911], end of section 3.3.4.2).
-
-17.2. Printer Security Threats
-
- Because the Get-Notifications operation is sent in the same direction
- as are Job Creation operations, usually by the same client, this
- Event Notification Delivery Method poses no additional
- authentication, authorization, privacy, firewall, or port assignment
- issues above those for the IPP Get-Job-Attributes and Get-Printer-
- Attributes operations (see [RFC2911], sections 3.2.6 and 3.2.5).
-
-17.3. Notification Recipient Security Threats
-
- Unwanted Events Notifications (spam): Unlike Push Event Notification
- Delivery Methods in which the IPP Printer initiates the Event
- Notification, with the Pull Delivery Method defined in this document,
- the Notification Recipient is the client that initiates the Get-
- Notifications operation (see section 5). Therefore, with this method
- there is no chance of "spam" notifications.
-
- Note: When a client stays connected to a Printer by using the Event
- Wait Mode (see section 5.1.3) in order to receive Event Notifications
- as they occur, it can close down the IPP connection at any time and
- so can avoid future unwanted Event Notifications at any time.
-
- It is true that the client has control over whether to ask for Event
- Notifications. However, if the client subscribes to an event and
- does a Get-Notifications request, it gets all events for the
- Subscription Object in the sequence number range (see section 5.1.2),
- not just those it wants. If a client subscribes to a Per-Printer
- Subscription job event, such as 'job-completed', and someone then
- starts and cancels thousands of jobs, the client would have to
- receive these events in addition to those it is interested in. A
- client can protect itself better by subscribing to its own jobs by
- using a Per-Job Subscription, rather than create a Per-Printer
- subscription whose Job events apply to all jobs.
-
-17.4. Security Requirements for Printers
-
- For the Get-Notifications operation defined in this document, the
- same Printer conformance requirements apply for supporting and using
- Client Authentication, Server Authentication and Operation Privacy as
- stated in [RFC2910] section 8 for all IPP operations.
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 27]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
-17.5. Security Requirements for Clients
-
- For the Get-Notifications operation defined in this document, the
- same client conformance requirements apply for supporting and using
- Client Authentication, Server Authentication, and Operation Privacy
- as stated in [RFC2910], section 8, for all IPP operations.
-
-18. Description of Base IPP Documents (Informative)
-
- The base set of IPP documents includes the following:
-
- Design Goals for an Internet Printing Protocol [RFC2567]
- Rationale for the Structure and Model and Protocol for the Internet
- Printing Protocol [RFC2568]
- Internet Printing Protocol/1.1: Model and Semantics [RFC2911]
- Internet Printing Protocol/1.1: Encoding and Transport [RFC2910]
- Internet Printing Protocol/1.1: Implementer's Guide [RFC3196]
- Mapping between LPD and IPP Protocols [RFC2569]
-
- "Design Goals for an Internet Printing Protocol" takes a broad look
- at distributed printing functionality, and it enumerates real-life
- scenarios that help clarify the features that need to be included in
- a printing protocol for the Internet. It identifies requirements for
- three types of users: end users, operators, and administrators. It
- calls out a subset of end user requirements that are satisfied in
- IPP/1.0 [RFC2566, RFC2565]. A few OPTIONAL operator operations have
- been added to IPP/1.1.
-
- "Rationale for the Structure and Model and Protocol for the Internet
- Printing Protocol" describes IPP from a high-level view, defines a
- roadmap for the various documents that form the suite of IPP
- specification documents, and gives background and rationale for the
- IETF working group's major decisions.
-
- "Internet Printing Protocol/1.1: Model and Semantics" describes a
- simplified model with abstract objects, their attributes, and their
- operations that are independent of encoding and transport. It
- introduces a Printer and a Job object. The Job object optionally
- supports multiple documents per Job. It also addresses security,
- internationalization, and directory issues.
-
- "Internet Printing Protocol/1.1: Encoding and Transport" is a formal
- mapping of the abstract operations and attributes defined in the
- model document onto HTTP/1.1 [RFC2616]. It defines the encoding
- rules for a new Internet MIME media type called "application/ipp".
- This document also defines the rules for transporting over HTTP a
- message body whose Content-Type is "application/ipp". This document
- defines the 'ipp' scheme for identifying IPP printers and jobs.
-
-
-
-Herriot, et al. Standards Track [Page 28]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
- "Internet Printing Protocol/1.1: Implementer's Guide" gives insight
- and advice to implementers of IPP clients and IPP objects. It is
- intended to help them understand IPP/1.1 and some of the
- considerations that may assist them in the design of their client
- and/or IPP object implementations. For example, a typical order of
- processing requests is given, including error checking. Motivation
- for some of the specification decisions is also included.
-
- "Mapping between LPD and IPP Protocols" gives some advice to
- implementers of gateways between IPP and LPD (Line Printer Daemon)
- implementations.
-
-19. Contributors
-
- Carl Kugler and Harry Lewis contributed the basic idea of in-band
- "smart polling" coupled with multiple responses for a single
- operation on the same connection, with one response for each event as
- it occurs. Without their continual persuasion, we would not have
- arrived at this Delivery Method specification and would not have been
- able to agree on a single REQUIRED Delivery Method for IPP.
-
- Carl Kugler
- IBM Corporation
- 6300 Diagonal Highway
- Boulder, CO 80301
-
- EMail: kugler@us.ibm.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 29]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
-Authors' Addresses
-
- Robert Herriot
- Global Workflow Solutions
- 706 Colorado Ave.
- Palo Alto, CA 94303
-
- Phone: 650-324-4000
- EMail: bob@herriot.com
-
-
- Thomas N. Hastings
- Xerox Corporation
- 710 S Aviation Blvd. ESAE 242
- El Segundo CA 90245
-
- Phone: 310-333-6413
- Fax: 310-333-6342
- EMail: hastings@cp10.es.xerox.com
-
-
- Harry Lewis
- IBM Corporation
- 6300 Diagonal Hwy
- Boulder, CO 80301
-
- Phone: (303) 924-5337
- EMail: harryl@us.ibm.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 30]
-\f
-RFC 3996 IPP: The 'ippget' Delivery Method March 2005
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2005).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at ietf-
- ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-Herriot, et al. Standards Track [Page 31]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group T. Hastings, Ed.
-Request for Comments: 3997 Xerox Corporation
-Category: Informational R. K. deBry
- Utah Valley State College
- H. Lewis
- IBM Corporation
- March 2005
-
-
- Internet Printing Protocol (IPP):
- Requirements for IPP Notifications
-
-Status of This Memo
-
- This memo provides information for the Internet community. It does
- not specify an Internet standard of any kind. Distribution of this
- memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2005).
-
-Abstract
-
- This document is one of a set of documents that together describe all
- aspects of the Internet Printing Protocol (IPP). IPP is an
- application-level protocol that can be used for distributed printing
- on the Internet. There are multiple parts to IPP, but the primary
- architectural components are the Model, the Protocol, and an
- interface to Directory Services. This document provides a statement
- of the requirements for notifications as an optional part of an IPP
- Service.
-
-Table of Contents
-
- 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . 2
- 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2
- 3. Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . 6
- 4. Requirements. . . . . . . . . . . . . . . . . . . . . . . . . 10
- 5. Security Considerations for IPP Notifications Requirements. . 12
- 6. Internationalization Considerations . . . . . . . . . . . . . 13
- 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
- 8. References. . . . . . . . . . . . . . . . . . . . . . . . . . 14
- 8.1. Normative References. . . . . . . . . . . . . . . . . . 14
- 8.2. Informative References. . . . . . . . . . . . . . . . . 14
- 9. Appendix A: Description of the Base IPP Documents . . . . . . 15
- Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 16
- Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 17
-
-
-
-Hastings, et al. Informational [Page 1]
-\f
-RFC 3997 IPP: Notification Requirements March 2005
-
-
-1. Introduction
-
- This document is one of a set of documents that together describe all
- aspects of the Internet Printing Protocol (IPP). IPP is an
- application level protocol that can be used for distributed printing
- on the Internet. There are multiple parts to IPP, but the primary
- architectural components are the Model, the Protocol, and an
- interface to Directory Services. This document provides a statement
- of the requirements for notifications as an optional part of an IPP
- Service. See section 10 for a description of the base IPP documents.
-
- The scope of this requirements document covers functionality used by
- the following kinds of IPP Users: End Users, Print Administrators,
- and Operators. See [RFC3995] for the extensions to the Internet
- Printing Protocol/1.0 (IPP) [RFC2565], [RFC2566], IPP/1.1 [RFC2911],
- [RFC2910], and future versions.
-
-2. Terminology
-
- It is necessary to define a set of terms to be able to clearly
- express the requirements for notification services in an IPP System.
-
-2.1. Job-Submitting End User
-
- A human end user who submits a print job to an IPP Printer. This
- person may or may not be within the same security domain as the
- Printer. This person may or may not be geographically near the
- printer.
-
-2.2. Administrator
-
- A human user who established policy for and configures the print
- system.
-
-2.3. Operator
-
- A human user who carries out the policy established by the
- Administrator and controls the day-to-day running of the print
- system.
-
-2.4. Job-Submitting Application
-
- An application (for example, a batch application), acting on behalf
- of a Job Submitting End User, that submits a print job to an IPP
- Printer. The application may or may not be within the same security
- domain as the Printer. This application may or may not be
- geographically near the printer.
-
-
-
-
-Hastings, et al. Informational [Page 2]
-\f
-RFC 3997 IPP: Notification Requirements March 2005
-
-
-2.5. Security Domain
-
- For the purposes of this discussion, the set of network components
- that can communicate without going through a proxy or firewall. A
- security domain may be geographically very large; for example,
- anywhere within example.com.
-
-2.6. IPP Client
-
- The software component that sends IPP requests to an IPP Printer
- object and accepts IPP responses from an IPP Printer.
-
-2.7. Job Recipient
-
- A human who is the ultimate consumer of the print job. In many cases
- this will be the same person as the Job-Submitting End User, but this
- need not always be the case. For example, if I use IPP to print a
- document on a printer in a business partner's office, I am the Job-
- Submitting End User, and the person whom I intend the document for in
- my business partner's office is the Job Recipient. Since one of the
- goals of IPP is to be able to print near the Job Recipient, we would
- normally expect that person to be in the same security domain as, and
- geographically near, the Printer. However, this may not always be
- the case. For example, I submit a print job across the Internet to a
- XYZ's print shop. I am both the Submitting End User and the Job
- Recipient, but I am neither near nor in the same security domain as
- the Printer.
-
-2.8. Job Recipient Proxy
-
- A person acting on behalf of the Job Recipient. The Job Recipient
- Proxy physically picks up the printed document from the Printer if
- the Job Recipient cannot do so. The Proxy is by definition
- geographically near and in the same security domain as the printer.
- For example, I submit a print job from home to be printed on a
- printer at work. I'd like my secretary to pick up the print job and
- put it on my desk. In this case, I am acting as both a Job-
- Submitting End User and a Job Recipient. My secretary is acting as a
- Job Recipient Proxy.
-
-2.9. Notification Subscriber
-
- A client that requests the IPP Printer to send Event Notifications to
- one or more Notification Recipients. A Notification Subscriber may
- be a Job-Submitting End User or an End User, an Operator, or an
- Administrator that is not submitting a job.
-
-
-
-
-
-Hastings, et al. Informational [Page 3]
-\f
-RFC 3997 IPP: Notification Requirements March 2005
-
-
-2.10. Notification Source
-
- The entity that sends Event Notifications.
-
-2.11. Notification Recipient
-
- The entity that receives IPP Notifications about Job and/or Printer
- events. A Notification Recipient may be a Job Submitting End User, a
- Job-Submitting Application, a Job Recipient, a Job Recipient Proxy,
- an Operator, an Administrator, etc., and his or her representative,
- log file, usage statistics-gathering application, or other active or
- passive entities.
-
-2.12. Notification Recipient Agent
-
- A program that receives Event Notifications on behalf of the
- Notification Recipient. The agent may take some action on behalf of
- the recipient, forward the notification to the recipient via some
- alternative means (for example, page the recipient), or queue the
- notification for later retrieval by the recipient.
-
-2.13. Event
-
- An Event is an occurrence (either expected or unexpected) within the
- printing system of a change of state, condition, or configuration of
- a Job or Printer object.
-
-2.14. Event Notification
-
- When an event occurs, an Event Notification is generated that fully
- describes the event (what the event was, where it occurred, when it
- occurred, etc.). Event Notifications are delivered to all the
- Notification Recipients that are subscribed to that Event, if any.
- The Event Notification is delivered to the address of the
- Notification Recipient by using the notification delivery method
- defined in the subscription. However, an Event Notification is sent
- ONLY if there is a corresponding subscription.
-
-2.15. Notification Subscription
-
- A Notification Subscription is a request by a Notification Subscriber
- to the IPP Printer to send Event Notifications to specified
- Notification Recipient(s) when an event occurs.
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 4]
-\f
-RFC 3997 IPP: Notification Requirements March 2005
-
-
-2.16. Notification Attributes
-
- IPP Objects (for example, a print job) from which notification are
- being sent may have associated attributes. A user may want to have
- one or more of these returned along with a particular notification.
- In general, these may include any attribute associated with the
- object emitting the notification. Examples include the following:
-
- number-of-intervening jobs
- job-k-octets
- job-k-octets processed
- job impressions
- job-impressions-interpreted
- job-impressions-completed
- impressionsCompletedCurrentCopy (job MIB)
- sheetCompletedCopyNumber (job MIB)
- sheetsCompletedDocumentNumber (job MIB)
- Copies-requested
- Copy-type
- Output-destination
- Job-state-reasons
- Job ID
- Printer URI
- Subscription ID (for job independent subscription)
-
-2.17. Notification Delivery Method (or Delivery Method for Short)
-
- Event Notifications are delivered by using a Delivery Method. An
- example of a Delivery Method is email.
-
-2.18. Immediate Notification
-
- Notifications sent to the Notification Recipient or the Notification
- Recipient's agent in such a way that the notification arrives
- immediately, within the limits of common addressing, routing, network
- congestion, and quality of service.
-
-2.19. Store-and-Forward Notification
-
- Notifications that are not necessarily delivered to Notification
- Recipients immediately but are queued for delivery by an intermediate
- network application, for later retrieval. Email is an example of a
- store-and-forward notification delivery method.
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 5]
-\f
-RFC 3997 IPP: Notification Requirements March 2005
-
-
-2.20. Reliable Delivery of Notifications
-
- Notifications that are delivered by a reliable delivery of packets or
- character stream, with acknowledgement and retry, so that delivery of
- the notification is guaranteed within determinate time limits. For
- example, if the Notification Recipient has logged off and gone home
- for the day, an immediate notification cannot be guaranteed, even
- when sent over a reliable transport, because there is nothing there
- to catch it. Guaranteed delivery requires both store-and-forward
- notification and a reliable transport.
-
-2.21. Notification over Unreliable Transport
-
- Notifications are delivered via the fundamental transport address and
- routing framework, but no acknowledgement or retry is required.
- Process-to-process communications, if involved, are unconstrained.
-
-2.22. Human-Consumable Notification
-
- Notifications intended to be consumed by human end users only. Email
- would be an example of a Human-Consumable Notification, though it
- could also contain Machine-Consumable Notification.
-
-2.23. Machine-Consumable Notification
-
- Notifications that are intended for consumption by a program only,
- such as an IPP Client. Machine-Consumable Notifications may not
- contain human-readable information. Do we need both human and
- machine? Machine readable is intended for application-to-application
- only. The Notification Recipient could process the machine-readable
- Event Notification into human-readable format.
-
-2.24. Mixed Notification
-
- A mixed notification contains both Human-Consumable and Machine-
- Consumable information.
-
-3. Scenarios
-
- 1. Sitting in my office, I submit a print job to the printer down
- the hall. I am in the same security domain as the printer and,
- of course, geographically near. I want to know immediately when
- my print job will be completed (or if there is a problem)
- because the document I am working on is urgent. I submit the
- print job with the following attributes:
-
-
-
-
-
-
-Hastings, et al. Informational [Page 6]
-\f
-RFC 3997 IPP: Notification Requirements March 2005
-
-
- - Notification Recipient: Me
- - Notification Events: All
- - Notification Attributes: Job-state-reason
- - Notification Type: Immediate
-
- 2. Working from home, I submit a print job to the same printer as
- in the previous example. However, I am not at work, I cannot
- physically get the print file or do anything with it. It can
- wait until I get to work this afternoon. However, I'd like my
- secretary to pick up the output and put it on my desk so that it
- doesn't get lost or misfiled. I'd also like a store-and-forward
- notification sent to my email so that when I get to work I can
- tell whether there was a problem with the print job. I submit a
- print job with the following attributes:
-
- - Notification Recipient: My secretary
- - Notification Events: Print complete
- - Notification Type: Immediate
-
- - Notification Recipient: Me
- - Notification Events: Print complete
- - Notification Attributes: Impressions completed
- - Notification Type: Store and forward
-
- 3. Sitting in my office, I submit a print job to a client at an
- engineering firm my company works with on a daily basis. The
- engineering firm is in Belgium. I would like my client to know
- when the print job is complete so that she can pick it up from
- the printer in her building. It is important that she review it
- right away and send her comments back to me. I submit the print
- job with the following attributes:
-
- - Notification Recipient: Client at engineering firm
- - Notification Events: Print complete
- - Notification Type: Immediate
- - Notification Language: French
-
- 4. From a hotel room, I send a print job to a Kinko's store in the
- town I am working in, in order to get a printed report for the
- meeting I am attending in the morning. As I'm going out to
- dinner after I get this job submitted, an immediate notification
- won't do me much good. However, I'd like to check in the
- morning before I drive to the Kinko's store to see whether the
- file has been printed. An email notification is sufficient for
- this purpose. I submit the print job with the following
- attributes:
-
-
-
-
-
-Hastings, et al. Informational [Page 7]
-\f
-RFC 3997 IPP: Notification Requirements March 2005
-
-
- - Notification Recipient: Me
- - Notification Events: Print complete
- - Notification Type: Store and forward
-
- 5. I am printing a large, complex print file. I want to have some
- immediate feedback on the progress of the print job as it
- prints. I submit the print job with the following attributes:
-
- - Notification Recipient: Me
- - Notification Type: Immediate
- - Notification Events: All state transitions
- - Notification Attributes: Impression completed
-
- 6. I am an operator and one of my duties is to keep the printer
- running. I subscribe independently from a job submission so
- that my subscription outlasts any particular job. I subscribe
- with the following attributes:
-
- - Notification Recipient: Me
- - Notification Type: Immediate
- - Notification Events: All Printer state transitions
- - Notification Attributes: Printer state, printer state
- reasons, device powering up, device powering down
-
- 7. I am a usage statistics gathering application. I subscribe
- independently from a job submission so that my subscription
- outlasts any particular job. My subscription may persist across
- power cycles. I subscribe with the following attributes:
-
- - Notification Recipient: Me
- - Notification Type: Immediate
- - Notification Events: Job completion
- - Notification Attributes: Impression completed, sheets
- completed, time submitted, time started, time completed, job
- owner, job size in octets, etc.
-
- 8. I am a client application program that displays a list of jobs
- currently queued for printing on a printer. I display the
- "job-name", "job-state", "job-state-reasons", "page-count", and
- "intervening-jobs", either for the user's jobs or for all jobs.
- The window displaying the job list remains open for an
- independent amount of time, and it is desired that it represent
- the current state of the queue. It is desired that the
- application only perform a slow poll in order to recover from
- any missed notifications. So the event delivery mechanism
- provides the means to update the screen on all needed changes,
- including querying for some attributes that may not be delivered
- in the Notification.
-
-
-
-Hastings, et al. Informational [Page 8]
-\f
-RFC 3997 IPP: Notification Requirements March 2005
-
-
- 9. I am a client application program that displays a list of
- printers. For each Printer, I display the current state and
- configuration. The window displaying the printer list remains
- open for an independent amount of time, and it is desired that
- it represent the current state of each printer. It is desired
- that the application only need to perform a slow poll in order
- to recover from any missed notifications. So the event delivery
- mechanism provides the means to update the screen on all needed
- changes, including querying for some attributes that may not be
- delivered in the Notification.
-
- 10. I am an IPP Server that controls one or more devices and that
- implements an IPP Printer object to represent each device. I
- want to support IPP Notification for each of the IPP Printer
- objects that I implement. Many of these devices do not support
- notification (or IPP). So I need to support the IPP
- Notification semantics specified for each IPP Printer object
- myself on behalf of each of the devices that each of the IPP
- Printer objects represents. When I accept an IPP job creation
- requests, I convert it to what the device will accept. In some
- cases, I must poll the devices in order to be informed of their
- job and device state and state changes to be able to send IPP
- Notifications to subscribed Notification Recipients.
-
- 11. I am an IPP Server that controls one or more devices and that
- implements an IPP Printer object to represent each device. I
- want to support IPP Notification for each of the IPP Printer
- objects that I implement. These devices all support IPP,
- including IPP Notification. I would like the design choice for
- supporting IPP Notification for these objects either (1) by
- forwarding the notification to the IPP Printers that I, alone,
- control and have them send the notifications to the intended
- Notification Recipients without my involvement, or (2) by
- replacing the notification submitted with the Job to indicate me
- as the Notification Recipient; in turn I will forward
- Notifications to the Notification Recipients requested by my
- clients. Most of the rest of the contents of the IPP Job I send
- to the IPP Printers I control will be the same as those that I
- receive from my IPP clients.
-
- 12. I am an IPP Server that controls one or more devices and that
- implements an IPP Printer object to represent each device. I
- want to support IPP Notification for each of the IPP Printer
- objects that I implement. These devices all support IPP,
- including IPP Notification. Because these IPP Printers MAY also
- be controlled by other servers (using IPP or other protocols), I
- only want job events for the jobs that I send, but I do want
- Printer events all the time, so that I can show proper Printer
-
-
-
-Hastings, et al. Informational [Page 9]
-\f
-RFC 3997 IPP: Notification Requirements March 2005
-
-
- state to my clients. So I subscribe to these IPP Printers for
- Printer events with a long-standing subscription, with myself as
- the Notification Recipient. When I get a Job Creation request,
- I decide to which IPP Printer to send the job. When I do so, I
- also add a job subscription for Job events, with me as the
- Notification Recipient to the job's job subscriptions supplied
- by my clients (this usage is called "piggybacking"). These IPP
- Printers automatically remove their job subscriptions when the
- job finishes, as for all job subscriptions, so that I no longer
- get Job events when my jobs are completed.
-
-4. Requirements
-
- The following requirements are intended to be met by the IPP
- Notification specification (not the implementation). The following
- are true for the resulting IPP Notification Specification document:
-
- 1. It must indicate which of these requirements are REQUIRED and
- which are OPTIONAL for a conforming implementation to support.
- See [RFC2911], section 12.1, for the definition of these
- important conformance terms.
-
- 2. It must be designed so that an IPP Printer can transparently
- support the IPP Notification semantics by using third-party
- notification services that exist today or that may be
- standardized in the future.
-
- 3. It must define a means for a Job-Submitting End User to specify
- zero or more Notification Recipients when submitting a print job.
- A Submitter will not be able to prevent out-of-band subscriptions
- from authorized persons, such as Operators.
-
- 4. It must define a means, when specifying a Notification Recipient,
- for a Notification Subscriber to specify one or more notification
- events for that Notification Recipient, subject to administrative
- and security policy restrictions. Any of the following
- constitute Job or Printer Events for which a Job Submitting End
- User can specify that notifications be sent:
-
- - Any standard Printer MIB alert
- - Job Received (transition from Unknown to Pending)
- - Job Started (transition from Pending to Processing)
- - Page Complete (page is stacked)
- - Collated Copy Complete (last sheet of collated copy is
- stacked)
-
-
-
-
-
-
-Hastings, et al. Informational [Page 10]
-\f
-RFC 3997 IPP: Notification Requirements March 2005
-
-
- - Job Complete (transition from Processing or Processing-stopped
- to Completed)
- - Job Aborted (transition from Pending, Pending-held,
- - Processing, or Processing-stopped to Aborted)
- - Job Canceled (transition from Pending, Pending-held,
- - Processing, or Processing-held to Canceled)
- - Other job state changes, such as paused, purged
- - Device problems for which the job is destined
- - Job (interpreter) issues
-
- 5. It must define how an End User or Operator subscribes for
-
- - any set of Job Events for a specific job, or
- - any set of Printer Events while a specific job is not
- complete.
-
- 6. It must define how an End User or Operator subscribes for the
- following without having to submit a Job:
-
- - Any set of Printer Events for a defined period.
- - Any set of Job Events for all jobs, with no control over
- which jobs.
-
- 7. It must define how the Notification Subscriber is able to
- specify either immediate or store-and-forward notification
- independently for each Notification Recipient. The means may be
- explicit, or implied by the method of delivery chosen by the Job
- Submitting End User.
-
- 8. It must define common delivery methods: e.g., email.
-
- 9. It must define how an IPP Printer validates its ability to
- deliver an Event by using the specified delivery scheme. If it
- does not support the specified scheme, or if the specified
- scheme is invalid for some reason, then the IPP Printer accepts
- and performs the request anyway and indicates the unsupported
- attribute values. There is no requirement for the IPP Printer
- receiving the print request to validate the identity of a
- Notification Recipient, or the ability of the system to deliver
- an event to that recipient as requested (for example, if the
- Notification Recipient is not at work today).
-
- 10. It must define a class of IPP event notification delivery
- methods that can flow through corporate firewalls. However, an
- IPP printer need not test to guarantee delivery of the
- notification through a firewall before accepting a print job.
-
-
-
-
-
-Hastings, et al. Informational [Page 11]
-\f
-RFC 3997 IPP: Notification Requirements March 2005
-
-
- 11. It may define a means to deliver a notification to the
- submitting client when the delivery of an event notification to
- a specified Notification Recipient fails. A fallback means of
- subscribers to determine whether notifications have failed
- (i.e., polling) may be provided.
-
- 12. It must define a mechanism for localizing Human-Consumable
- Notifications by the Notification Source.
-
- 13. It may define a way to specify whether event delivery requires
- acknowledgement back to the Notification Source.
-
- 14. There must be a mechanism defined so that job-independent
- subscriptions do not become stale and do not require human
- intervention to be removed. However, a subscription must not be
- deemed stale only if it is unable to deliver an Event
- Notification, as temporary Notification delivery problems must
- be tolerated.
-
- 15. A mechanism must be defined so that an Event Subscriber is able
- to add an Event Subscription to a Job after the Job has been
- submitted.
-
- 16. A mechanism must be defined so that a client is able to cancel
- an Event Subscription on a job or printer after the job has been
- submitted.
-
- 17. A mechanism must be defined so that a client can obtain the set
- of current Subscriptions.
-
-5. Security Considerations for IPP Notifications Requirements
-
- By far the biggest security concern is the abuse of notification:
- sending unwanted notifications sent to third parties (i.e., spam).
- The problem is made worse by notification addresses that may be
- redistributed to multiple parties (e.g., mailing lists). Scenarios
- exist in which third-party notification is required (see scenarios 2
- and 3). The fully secure solution would require active agreement of
- all recipients before anything is sent out. However, requirement 9
- ("There is no requirement for an IPP Printer receiving the print
- request to validate the identity of an event recipient") argues
- against this. Certain systems may decide to disallow third-party
- notifications (a traditional fax model).
-
- The same security issues are present when Clients submit notification
- requests to the IPP Printer as when they submit an IPP/1.1 print job
- request. The same mechanisms used by IPP/1.1 can therefore be used
-
-
-
-
-Hastings, et al. Informational [Page 12]
-\f
-RFC 3997 IPP: Notification Requirements March 2005
-
-
- by the client notification submission. Operations that require
- authentication can use the HTTP authentication. Operations that
- require privacy can use the HTTP/TLS privacy.
-
- The notification access control model should be similar to the IPP
- access control model. Creating a notification subscription is
- associated with a user. Only the creator or an operator can cancel
- the subscription. The system may limit the listing of items to items
- owned by the user. Some subscriptions (e.g., those that have a
- lifetime longer than a job) can be done only by privileged users
- (operators and/or administrators), if that is the authorization
- policy.
-
- The standard security concerns (delivery to the right user, privacy
- of content, tamper-proof content) apply to the notification delivery.
- IPP should use the security mechanism of the delivery method used.
- Some delivery mechanisms are more secure than others. Therefore,
- sensitive notifications should use the delivery method that has the
- strongest security.
-
-6. Internationalization Considerations
-
- The Human-Consumable Notification must be localized to the natural
- language and charset that Notification Subscriber specifies within
- the choice of natural languages and charsets that the IPP Printer
- supports.
-
- The Machine-Consumable Notification data uses the "application/ipp"
- MIME media type. It contains attributes whose text values are
- required to be in the natural language and charset that the
- Notification Subscriber specifies within the choice of natural
- languages and charsets that the IPP Printer supports. See [RFC2566].
-
-7. IANA Considerations
-
- Some notification delivery methods have been registered with IANA for
- use in URLs. These will be defined in other documents.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 13]
-\f
-RFC 3997 IPP: Notification Requirements March 2005
-
-
-8. References
-
-8.1. Normative References
-
- [RFC2910] Herriot, R., Butler, S., Moore, P., Turner, R., and J.
- Wenn, "Internet Printing Protocol/1.1: Encoding and
- Transport", RFC 2910, September 2000.
-
- [RFC2911] Hastings, T., Herriot, R., deBry, R., Isaacson, S., and
- P. Powell, "Internet Printing Protocol/1.1: Model and
- Semantics", RFC 2911, September 2000.
-
- [RFC3995] Herriot, R. and T. Hastings, "Internet Printing Protocol
- (IPP): Event Notifications and Subscriptions", RFC 3995,
- March 2005.
-
-8.2. Informative References
-
- [RFC2565] Herriot, R., Butler, S., Moore, P., and R. Turner,
- "Internet Printing Protocol/1.0: Encoding and Transport",
- RFC 2565, April 1999.
-
- [RFC2566] deBry, R., Hastings, T., Herriot, R., Isaacson, S., and
- P. Powell, "Internet Printing Protocol/1.0: Model and
- Semantics", RFC 2566, April 1999.
-
- [RFC2567] Wright, F., "Design Goals for an Internet Printing
- Protocol", RFC 2567, April 1999.
-
- [RFC2568] Zilles, S., "Rationale for the Structure of the Model and
- Protocol for the Internet Printing Protocol", RFC 2568,
- April 1999.
-
- [RFC2569] Herriot, R., Hastings, T., Jacobs, N., and J. Martin,
- "Mapping between LPD and IPP Protocols", RFC 2569, April
- 1999.
-
- [RFC2639] Hastings, T., Manros, C., Zehler, P., Kugler, C., and H.
- Holst, "Internet Printing Protocol/1.1: Implementor's
- Guide", RFC 3196, November 2001.
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 14]
-\f
-RFC 3997 IPP: Notification Requirements March 2005
-
-
-9. Appendix A: Description of the Base IPP Documents
-
- The base set of IPP documents includes the following:
-
- Design Goals for an Internet Printing Protocol [RFC2567]
- Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol [RFC2568]
- Internet Printing Protocol/1.1: Model and Semantics [RFC2911]
- Internet Printing Protocol/1.1: Encoding and Transport [RFC2910]
- Internet Printing Protocol/1.1: Implementer's Guide [RFC3196]
- Mapping between LPD and IPP Protocols [RFC2569]
-
- "Design Goals for an Internet Printing Protocol" takes a broad look
- at distributed printing functionality, and it enumerates real-life
- scenarios that help clarify the features that need to be included in
- a printing protocol for the Internet. It identifies requirements for
- three types of users: end users, operators, and administrators. It
- calls out a subset of end-user requirements that are satisfied in
- IPP/1.0 [RFC2566], [RFC2565]. A few OPTIONAL operator operations
- have been added to IPP/1.1 [RFC2911], [RFC2910].
-
- "Rationale for the Structure and Model and Protocol for the Internet
- Printing Protocol" describes IPP from a high-level view, defines a
- roadmap for the various documents that form the suite of IPP
- specification documents, and gives background and rationale for the
- IETF IPP working group's major decisions.
-
- "Internet Printing Protocol/1.1: Model and Semantics" describes a
- simplified model with abstract objects, their attributes, and their
- operations. The model introduces a Printer and a Job. The Job
- supports multiple documents per Job. The model document also
- addresses security, internationalization, and directory issues.
-
- "Internet Printing Protocol/1.1: Encoding and Transport" is a formal
- mapping of the abstract operations and attributes defined in the
- model document onto HTTP/1.1 [RFC2616]. It also defines the encoding
- rules for a new Internet MIME media type called "application/ipp".
- This document also defines the rules for transporting over HTTP a
- message body whose Content-Type is "application/ipp". This document
- defines the "ipp" scheme for identifying IPP printers and jobs.
-
- "Internet Printing Protocol/1.1: Implementer's Guide" gives insight
- and advice to implementers of IPP clients and IPP objects. It is
- intended to help them understand IPP/1.1 and some of the
- considerations that may assist them in the design of their client
- and/or IPP object implementations. For example, a typical order of
- processing requests is given, including error checking. Motivation
- for some of the specification decisions is also included.
-
-
-
-Hastings, et al. Informational [Page 15]
-\f
-RFC 3997 IPP: Notification Requirements March 2005
-
-
- "Mapping between LPD and IPP Protocols" gives some advice to
- implementers of gateways between IPP and LPD (Line Printer Daemon )
- implementations.
-
-Authors' Addresses
-
- Tom Hastings (editor)
- Xerox Corporation
- 701 S Aviation Blvd, ESAE 242
- El Segundo, CA 90245
-
- Phone: 310-333-6413
- Fax: 310-333-6342
- EMail: hastings@cp10.es.xerox.com
-
-
- Roger deBry
- Utah Valley State College
-
- Phone: (801) 863-8848
- EMail: debryro@uvsc.edu
-
-
- Harry Lewis
- IBM Corporation
- 6300 Diagonal Hwy
- Boulder, CO 80301
-
- Phone: (303) 924-5337
- EMail: harryl@us.ibm.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 16]
-\f
-RFC 3997 IPP: Notification Requirements March 2005
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2005).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at ietf-
- ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-Hastings, et al. Informational [Page 17]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group C. Kugler
-Request for Comments: 3998 H. Lewis
-Category: Standards Track IBM Corporation
- T. Hastings, Ed.
- Xerox Corporation
- March 2005
-
-
- Internet Printing Protocol (IPP):
- Job and Printer Administrative Operations
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2005).
-
-Abstract
-
- This document specifies the following 16 additional OPTIONAL system
- administration operations for use with the Internet Printing
- Protocol/1.1 (IPP), plus a few associated attributes, values, and
- status codes, and using the IPP Printer object to manage printer
- fan-out and fan-in.
-
- Printer operations: Job operations:
- Enable-Printer and Disable-Printer Reprocess-Job
- Pause-Printer-After-Current-Job Cancel-Current-Job
- Hold-New-Jobs and Release-Held-New-Jobs Suspend-Current-Job
- Deactivate-Printer and Activate-Printer Resume-Job
- Restart-Printer Promote-Job
- Shutdown-Printer and Startup-Printer Schedule-Job-After
-
-
-
-
-
-
-
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 1]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
-Table of Contents
-
- 1. Introduction.................................................. 4
- 2. Terminology................................................... 4
- 2.1. Conformance Terminology................................. 4
- 2.2. Other Terminology....................................... 5
- 3. Definition of the Printer Operations.......................... 6
- 3.1. The Disable and Enable Printer Operations............... 7
- 3.1.1. Disable-Printer Operation....................... 7
- 3.1.2. Enable-Printer Operation........................ 8
- 3.2. The Pause and Resume Printer Operations................. 8
- 3.2.1. Pause-Printer-After-Current-Job Operation....... 9
- 3.3. Hold and Release New Jobs Operations.................... 11
- 3.3.1. Hold-New-Jobs Operation......................... 11
- 3.3.2. Release-Held-New-Jobs Operation................. 12
- 3.4. Deactivate and Activate Printer Operations.............. 12
- 3.4.1. Deactivate-Printer Operation.................... 13
- 3.4.2. Activate-Printer Operation...................... 13
- 3.5. Restart-Printer, Shutdown-Printer,
- and Startup-Printer Operations.......................... 14
- 3.5.1. Restart-Printer Operation....................... 14
- 3.5.2. Shutdown-Printer Operation...................... 14
- 3.5.3. Startup-Printer Operation....................... 15
- 4. Definition of the Job Operations.............................. 16
- 4.1. Reprocess-Job Operation................................. 17
- 4.2. Cancel-Current-Job Operation............................ 17
- 4.3. Suspend and Resume Job Operations....................... 18
- 4.3.1. Suspend-Current-Job Operation................... 19
- 4.3.2. Resume-Job Operation............................ 20
- 4.4. Job Scheduling Operations............................... 20
- 4.4.1. Promote-Job Operation........................... 20
- 4.4.2. Schedule-Job-After Operation.................... 21
- 5. Additional Status Codes....................................... 23
- 5.1. 'server-error-printer-is-deactivated' (0x050A).......... 23
- 6. Use of Operation Attributes
- That Are Messages from the Operator........................... 23
- 7. New Printer Description Attributes............................ 26
- 7.1. subordinate-printers-supported (1setOf uri)............. 26
- 7.2. parent-printers-supported (1setOf uri).................. 26
- 8. Additional Values for
- the "printer-state-reasons" Printer Description Attribute..... 26
- 8.1. 'hold-new-jobs' Value................................... 27
- 8.2. 'deactivated' Value..................................... 27
- 9. Additional Values for
- the "job-state-reasons" Job Description attribute............. 27
- 9.1. 'job-suspended' Value................................... 27
- 10. Use of the Printer Object to Represent
- IPP Printer Fan-Out and IPP Printer Fan-In.................... 27
-
-
-
-Kugler, et al. Standards Track [Page 2]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- 10.1. IPP Printer Fan-Out..................................... 28
- 10.2. IPP Printer Fan-In...................................... 28
- 10.3. Printer Object Attributes Used
- to Represent Printer Fan-Out and Printer Fan-In......... 29
- 10.4. Subordinate Printer URI................................. 29
- 10.5. Printer Object Attributes Used
- to Represent Output Device Fan-Out...................... 30
- 10.6. Figures to Show All Possible Configurations............. 30
- 10.7. Forwarding Requests..................................... 33
- 10.7.1. Forwarding Requests
- that Affect Printer Objects..................... 33
- 10.7.2. Forwarding Requests that Affect Jobs............ 35
- 10.8. Additional Attributes to Help with Fan-Out.............. 37
- 10.8.1. output-device-assigned (name(127))
- Job Description Attribute - from [RFC2911]...... 37
- 10.8.2. original-requesting-user-name (name(MAX))
- Operation and Job Description Attribute......... 37
- 10.8.3. requesting-user-name (name(MAX))
- Operation Attribute - Additional Semantics...... 38
- 10.8.4. job-originating-user-name (name(MAX))
- Job Description Attribute -
- Additional Semantics............................ 38
- 11. Conformance Requirements...................................... 38
- 12. Normative References.......................................... 39
- 13. Informative References........................................ 40
- 14. IANA Considerations........................................... 40
- 14.1. Attribute Registrations................................. 41
- 14.2. Attribute Value Registrations........................... 41
- 14.3. Additional Enum Attribute Value Registrations........... 41
- 14.4. Operation Registrations................................. 42
- 14.5. Status Code Registrations............................... 43
- 15. Internationalization Considerations........................... 43
- 16. Security Considerations....................................... 43
- 17. Summary of Base IPP Documents................................. 44
- Authors' Addresses................................................ 45
- Full Copyright Statement.......................................... 46
-
-List of Tables
-
- Table 1. Printer Operation Operation-Id Assignments.............. 6
- Table 2. Pause and Resume Printer Operations..................... 9
- Table 3. State Transition Table for
- Pause-Printer-After-Current-Job Operation............... 10
- Table 4. Job Operation Operation-Id Assignments.................. 16
- Table 5. Operation Attribute Support for Printer Operations...... 24
- Table 6. Operation Attribute Support for Job Operations.......... 25
- Table 7. Forwarding Operations that Affect Printer Objects....... 34
- Table 8. Forwarding Operations that Affect Jobs Objects.......... 36
-
-
-
-Kugler, et al. Standards Track [Page 3]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- Table 9. Conformance Requirement Dependencies for Operations..... 38
- Table 10. Conformance Requirement Dependencies
- for "printer-state-reasons" Values...................... 39
- Table 11. Conformance Requirement Dependencies
- for "job-state-reasons" Values.......................... 39
-
-List of Figures
-
- Figure 1. Embedded Printer Object................................ 31
- Figure 2. Hosted Printer Object.................................. 31
- Figure 3. Output Device Fan-Out.................................. 31
- Figure 4. Chained IPP Printer Objects............................ 32
- Figure 5. IPP Printer Object Fan-Out............................. 32
- Figure 6. IPP Printer Object Fan-In.............................. 33
-
-1. Introduction
-
- The Internet Printing Protocol (IPP) is an application level protocol
- that can be used for distributed printing using Internet tools and
- technologies. IPP version 1.1 ([RFC2911, RFC2910]) focuses on end-
- user functionality, with a few administrative operations included.
- This document defines additional OPTIONAL end user, operator, and
- administrator operations used to control Jobs and Printers. In
- addition, this document extends the semantic model of the Printer
- object by allowing them to be configured into trees and/or inverted
- trees that represent Printer object Fan-Out and Printer object Fan-
- In, respectively. The special case of a tree with only a single
- Subordinate node represents Chained Printers. This document is a
- registration proposal for an extension to IPP/1.0 and IPP/1.1
- following the registration procedures in those documents.
-
- The requirements and use cases for this document are defined in
- [RFC3239].
-
-2. Terminology
-
- This section defines the terminology used throughout this document.
-
-2.1. Conformance Terminology
-
- Capitalized terms such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD
- NOT, MAY, NEED NOT, and OPTIONAL have special meaning relating to
- conformance as defined in RFC 2119 [RFC2119] and [RFC2911], section
- 12.1. If an implementation supports the extension defined in this
- document, then these terms apply; otherwise, they do not. These
- terms define conformance to this document only; they do not affect
- conformance to other documents, unless explicitly stated otherwise.
-
-
-
-
-Kugler, et al. Standards Track [Page 4]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
-2.2. Other Terminology
-
- This document uses terms such as "client", "Printer", "Job",
- "attributes", "keywords", "operation", and "support". These terms
- have special meaning and are defined in the model terminology
- ([RFC2911], section 12.2).
-
- In addition, the following capitalized terms are defined:
-
- IPP Printer object (or Printer for short) - A software abstraction
- defined by [RFC2911].
-
- Printer Operation - An operation whose target is an IPP Printer
- object and whose effect is on the Printer object.
-
- Output Device - The physical imaging mechanism that an IPP Printer
- controls. Note: although this term is capitalized in this
- specification (but not in [RFC2911]), there is no formal object
- called an Output Device defined in this document (or in [RFC2911]).
-
- Output Device Fan-Out - A configuration in which an IPP Printer
- controls more than one Output Device.
-
- Printer Fan-Out - A configuration in which an IPP Printer object
- controls more than one Subordinate IPP Printer object.
-
- Printer Fan-In - A configuration in which an IPP Printer object is
- controlled by more than one IPP Printer object.
-
- Subordinate Printer - An IPP Printer object that is controlled by
- another IPP Printer object. Such a Subordinate Printer MAY have zero
- or more Subordinate Printers.
-
- Leaf Printer - An IPP Printer object that has no Subordinate
- Printers.
-
- Non-Leaf Printer - An IPP Printer object that has one or more
- Subordinate Printers. A Non-Leaf Printer is also called a Parent
- Printer.
-
- Chained Printer - a Non-Leaf Printer that has exactly one Subordinate
- Printer.
-
- Job Creation operations - IPP operations that create a Job object:
- Print-Job, Print-URI, and Create-Job.
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 5]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
-3. Definition of the Printer Operations
-
- All Printer Operations are directed at Printer objects. A client
- MUST always supply the "printer-uri" operation attribute in order to
- identify the correct target of the operation. These descriptions
- assume all of the common semantics of the IPP/1.1 Model and Semantics
- document ([RFC2911], section 3.1).
-
- The Printer Operations defined in this document are summarized in
- Table 1.
-
- Table 1. Printer Operation Operation-Id Assignments
-
- Operation Name Operation-Id Brief Description
- --------------------------------------------------------------------
- Enable-Printer 0x22 Allows the target Printer to accept
- Job Creation operations.
-
- Disable-Printer 0x23 Prevents the target Printer from
- accepting Job Creation operations.
-
- Pause-Printer- 0x24 Pauses the Printer after the current
- After-Current- job has been sent to the Output
- Job Device.
-
- Hold-New-Jobs 0x25 Finishes processing all currently
- pending jobs. Any new jobs are
- placed in the 'pending-held' state.
-
- Release-Held- 0x26 Releases all jobs to the 'pending'
- New-Jobs state that had been held by the
- effect of a previous Hold-New-Jobs
- operation and condition the Printer
- so that it no longer holds new jobs.
-
- Deactivate- 0x27 Puts the Printer into a read-only
- Printer deactivated state.
-
- Activate- 0x28 Restores the Printer to normal
- Printer activity.
-
- Restart-Printer 0x29 Restarts the target Printer and re-
- initializes the software.
-
- Shutdown- 0x2A Shuts down the target Printer so that
- Printer it cannot be restarted or queried.
-
-
-
-
-
-Kugler, et al. Standards Track [Page 6]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- Startup-Printer 0x2B Starts up the instance of the Printer
- object.
-
- All of the operations in this document are OPTIONAL for an IPP object
- to support. Unless the specification of an OPTIONAL operation
- requires support of another OPTIONAL operation, conforming
- implementations may support any combination of these operations.
- Many of the operations come in pairs, so both are REQUIRED if either
- one is implemented.
-
-3.1. The Disable and Enable Printer Operations
-
- This section defines the OPTIONAL Disable-Printer and Enable-Printer
- operations that stop and start the IPP Printer object from accepting
- new IPP jobs. If either of these operations are supported, both MUST
- be supported.
-
- These operations allow the operator to control whether the Printer
- will accept new Job Creation (Print-Job, Print-URI, and Create-Job)
- operations. These operations have no other effect on the Printer, so
- the Printer continues to accept all other operations and continues to
- schedule and process jobs normally. In other words, these operations
- control the "input of new jobs" to the IPP Printer, and the Pause and
- Resume operations (see section 3.2) independently control the "output
- of new jobs" from the IPP Printer to the Output Device.
-
-3.1.1. Disable-Printer Operation
-
- This OPTIONAL operation allows a client to stop the Printer object
- from accepting new jobs; i.e., it causes the Printer to reject
- subsequent Job Creation operations and return the 'server-error-not-
- accepting-jobs' status code. The Printer still accepts all other
- operations, including Validate-Job, Send-Document, and Send-URI
- operations. Thus a Disable-Printer operation allows a client to
- continue submitting multiple documents of a multiple document job if
- the Create-Job operation had already been accepted. All previously
- created or submitted Jobs and all Jobs currently processing continue
- unaffected.
-
- The IPP Printer MUST accept the request in any state. The Printer
- sets the value of its "printer-is-accepting-jobs" READ-ONLY Printer
- Description attribute to 'false' (see [RFC2911], section 4.4.20), no
- matter what the previous value was. This operation has no immediate
- or direct effect on the Printer's "printer-state" and "printer-
- state-reasons" attributes.
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 7]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation must be an operator or administrator of the
- Printer object (see [RFC2911] sections 1 and 8.5).
-
- The Disable-Printer Request and Disable-Printer Response have the
- same attribute groups and attributes as do the Pause-Printer
- operation (see [RFC2911], sections 3.2.7.1 and 3.2.7.2), including
- the new "printer-message-from-operator" operation attribute (see
- section 6).
-
-3.1.2. Enable-Printer Operation
-
- This OPTIONAL operation allows a client to start the Printer object
- accepting jobs; i.e., it causes the Printer to accept subsequent Job
- Creation operations. The Printer still accepts all other operations.
- All previously submitted and currently processing Jobs continue
- unaffected.
-
- The IPP Printer MUST accept the request in any state. The Printer
- sets the value of its "printer-is-accepting-jobs" READ-ONLY Printer
- Description attribute to 'true' (see [RFC2911], section 4.4.20), no
- matter what the previous value was. This operation has no immediate
- or direct effect on the Printer's "printer-state" and "printer-
- state-reasons" attributes.
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation must be an operator or administrator of the
- Printer object (see [RFC2911] sections 1 and 8.5).
-
- The Enable-Printer Request and Enable-Printer Response have the same
- attribute groups and attributes as does the Pause-Printer operation
- (see [RFC2911], sections 3.2.8.1 and 3.2.8.2), including the new
- "printer-message-from-operator" operation attribute (see section 6).
-
-3.2. The Pause and Resume Printer Operations
-
- This section leaves the OPTIONAL IPP/1.1 Pause-Printer (see
- [RFC2911], sections 3.2.7) ambiguous as to whether it stops the
- Printer immediately or after the current job. It also defines the
- OPTIONAL Pause-Printer-After-Current-Job operation as following the
- current job. These operations affect the scheduling of IPP jobs. If
- either of these Pause Printer operations are supported, then the
- Resume-Printer operation MUST be supported.
-
- These operations allow the operator to control whether the Printer
- will send new IPP jobs to the associated Output Device(s) that the
- IPP Printer object represents. These operations have no other effect
- on the Printer, so the Printer continues to accept all operations.
-
-
-
-Kugler, et al. Standards Track [Page 8]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- In other words, these operations control the "output of new jobs" to
- the Output Device(s), and the Disable and Enable Printer Operations
- (see section 3.1) independently control the "input of new jobs" to
- the IPP Printer.
-
- Table 2. Pause and Resume Printer Operations
-
- Pause and Resume Printers Description
- --------------------------------------------------------------------
- IPP/1.1 Pause Printer Stops the IPP Printer from sending
- new IPP Jobs to the Output Device(s)
- either immediately or after the
- current job completes, depending on
- implementation, as defined in
- [RFC2911].
-
- Pause-Printer-After- Stops the IPP Printer from sending
- Current-Job new IPP Jobs to the Output Device(s)
- after the current jobs finish.
-
- Resume-Printer Starts the IPP Printer sending IPP
- Jobs to the Output Device again.
-
-3.2.1. Pause-Printer-After-Current-Job Operation
-
- This OPTIONAL operation allows a client to stop the Printer object
- from sending IPP jobs to any of its Output Devices or Subordinate
- Printers. If the IPP Printer is in the middle of sending an IPP job
- to an Output Device or Subordinate Printer, the IPP Printer MUST
- complete sending that Job. However, after receiving this operation,
- the IPP Printer MUST NOT send any additional IPP jobs to any of its
- Output Devices or Subordinate Printers. In addition, after having
- received this operation, the IPP Printer MUST NOT start processing
- any more jobs, so additional jobs MUST NOT enter the 'processing'
- state.
-
- If the IPP Printer is not sending an IPP Job to the Output Device or
- Subordinate Printer (whether or not the Output Device or Subordinate
- Printer is busy processing any jobs), the IPP Printer object
- transitions immediately to the 'stopped' state by setting its
- "printer-state" attribute to 'stopped', removing the 'moving-to-
- paused' value, if present, from its "printer-state-reasons"
- attribute, and adding the 'paused' value to its "printer-state-
- reasons" attribute.
-
- If the implementation will take appreciable time to complete sending
- an IPP job that it has started sending to an Output Device or
- Subordinate Printer, the IPP Printer adds the 'moving-to-paused'
-
-
-
-Kugler, et al. Standards Track [Page 9]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- value to the Printer object's "printer-state-reasons" attribute (see
- section [RFC2911], 4.4.12). When the IPP Printer has completed
- sending IPP jobs that it was in the process of sending, the Printer
- object transitions to the 'stopped' state by setting its "printer-
- state" attribute to 'stopped', removing the 'moving-to-paused' value,
- if present, from its "printer-state-reasons" attribute, and adding
- the 'paused' value to its "printer-state-reasons" attribute.
-
- This operation MUST NOT affect the acceptance of Job Creation
- requests (see Disable-Printer Operation, section 3.1.1).
-
- For any jobs that are 'pending' or 'pending-held', the 'printer-
- stopped' values of the jobs' "job-state-reasons" attribute also
- apply. However, the IPP Printer NEED NOT update those jobs' "job-
- state-reasons" attributes and only have to return the 'printer-
- stopped' value when those jobs are queried by using the Get-Job-
- Attributes or Get-Jobs operations (so-called "lazy evaluation").
-
- The IPP Printer MUST accept the request in any state and transition
- the Printer to the indicated new "printer-state", and it MUST add the
- indicated value to "printer-state-reasons" attribute before returning
- as follows:
-
- Table 3. State Transition Table for Pause-Printer-After-Current-Job
- Operation
-
- Current New "printer IPP Printer's response status
- "printer- "printer- -state- code and action (REQUIRED/
- state" state" reasons" OPTIONAL state transition for
- a Printer to support):
- --------------------------------------------------------------------
- 'idle' 'stopped' 'paused' REQUIRED: 'successful-ok'
-
- 'processing' 'processing' 'moving- OPTIONAL: 'successful-ok';
- to- Later, when the IPP Printer
- paused' has finished sending IPP jobs
- to an Output Device, the
- "printer-state" becomes
- 'stopped', and the 'paused'
- value replaces the 'moving-to-
- paused' value in the "printer-
- state-reasons" attribute
-
- 'processing' 'stopped' 'paused' REQUIRED: 'successful-ok';
- the IPP Printer wasn't in the
- middle of sending an IPP job
- to an Output Device
-
-
-
-
-Kugler, et al. Standards Track [Page 10]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- 'stopped' 'stopped' 'paused' REQUIRED: 'successful-ok'
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation must be an operator or administrator of the
- Printer object (see [RFC2911], sections 1 and 8.5).
-
- The Pause-Printer-After-Current-Job Request and Pause-Printer-After-
- Current-Job Response have the same attribute groups and attributes as
- does the Pause-Printer operation (see [RFC2911], sections 3.2.7.1 and
- 3.2.7.2), including the new "printer-message-from-operator" operation
- attribute (see section 6).
-
-3.3. Hold and Release New Jobs Operations
-
- This section defines operations to condition the Printer to hold any
- new jobs and to release them.
-
-3.3.1. Hold-New-Jobs Operation
-
- This OPTIONAL operation allows a client to condition the Printer to
- complete the current 'pending' and 'processing' IPP Jobs but not to
- start processing any subsequently created IPP Jobs. If the IPP
- Printer is in the middle of sending an IPP job to an Output Device or
- Subordinate Printer, the IPP Printer MUST complete sending that Job.
- Furthermore, the IPP Printer MUST send all of the current 'pending'
- IPP Jobs to the Output Device(s) or Subordinate IPP Printer
- object(s). Any subsequently received Job Creation operations will
- cause the IPP Printer to put the Job into the 'pending-held' state,
- with the 'job-held-on-create' value being added to the job's "job-
- state-reasons" attribute. Thus all newly accepted jobs will be
- automatically held by the Printer.
-
- When the Printer completes all the 'pending' and 'processing' jobs,
- it enters the 'idle' state as usual. An operator monitoring Printer
- state changes will know when the Printer has completed all current
- jobs because the Printer enters the 'idle' state.
-
- This operation MUST NOT affect the acceptance of Job Creation
- requests (see Disable-Printer Operation, section 3.1.1), except to
- put the Jobs into the 'pending-held' state, instead of the 'pending'
- or 'processing' state.
-
- The IPP Printer MUST accept the request in any state, MUST NOT
- transition the Printer to any other "printer-state", and MUST add the
- 'hold-new-jobs' value to the Printer's "printer-state-reasons"
- attribute (whether the value was present or not).
-
-
-
-
-
-Kugler, et al. Standards Track [Page 11]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation must be an operator or administrator of the
- Printer object (see [RFC2911], sections 1 and 8.5).
-
- The Hold-New-Jobs Request and Hold-New-Jobs Response have the same
- attribute groups and attributes as does the Pause-Printer operation
- (see [RFC2911], sections 3.2.7.1 and 3.2.7.2), including the new
- "printer-message-from-operator" operation attribute (see section 6).
-
-3.3.2. Release-Held-New-Jobs Operation
-
- This OPTIONAL operation allows a client to undo the effect of a
- previous Hold-New-Jobs operation. In particular, the Printer
- releases all the jobs that it held as a consequence of a Hold-New-
- Jobs operations; i.e., while the 'hold-new-jobs' value was present in
- the Printer's "printer-state-reasons" attribute. In addition, the
- Printer MUST accept this request in any state, MUST NOT transition
- the Printer to any other "printer-state", and MUST remove the 'hold-
- new-jobs' value from its "printer-state-reasons" attribute (whether
- the value was present or not) so that the Printer no longer holds
- newly created jobs.
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation must be an operator or administrator of the
- Printer object (see [RFC2911], sections 1 and 8.5).
-
- The Release-Held-New-Jobs Request and Release-Held-New-Jobs Response
- have the same attribute groups and attributes as the Pause-Printer
- operation (see [RFC2911], sections 3.2.7.1 and 3.2.7.2), including
- the new "printer-message-from-operator" operation attribute (see
- section 6).
-
-3.4. Deactivate and Activate Printer Operations
-
- This section defines the OPTIONAL Deactivate-Printer and Activate-
- Printer operations that stop and start the IPP Printer object from
- accepting all requests except queries and performing work. If either
- of these operations are supported, both MUST be supported.
-
- These operations allow the operator to put the Printer into a dormant
- read-only condition and to take it out of this condition.
-
-
-
-
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 12]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
-3.4.1. Deactivate-Printer Operation
-
- This OPTIONAL operation allows a client to stop the Printer object
- from sending IPP jobs to any of its Output Devices or Subordinate
- Printers (Pause-Printer-After-Current-Job) and to stop the Printer
- object from accepting any requests but query requests. The Printer
- performs a Disable-Printer and a Pause-Printer-After-Current-Job
- operation immediately. If these two operations cannot be completed
- immediately, it includes use of all of the "printer-state-reasons".
- In addition, the Printer MUST immediately reject all requests, except
- for Activate-Printer, queries (Get-Printer-Attributes, Get-Job-
- Attributes, Get-Jobs, etc.), Send-Document, and Send-URI (so that
- partial job submission can be completed, see section 3.1.1). The
- Printer MUST then return the 'server-error-service-unavailable'
- status code.
-
- The IPP Printer MUST accept the request in any state. Immediately,
- the Printer MUST set the 'deactivated' value in its "printer-state-
- reasons" attribute. Note: neither the Disable-Printer nor the
- Pause-Printer-After-Current-Job set the 'deactivated' value.
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation must be an operator or administrator of the
- Printer object (see [RFC2911], sections 1 and 8.5).
-
- The Deactivate-Printer Request and Deactivate-Printer Response have
- the same attribute groups and attributes as does the Pause-Printer
- operation (see [RFC2911], sections 3.2.7.1 and 3.2.7.2), including
- the new "printer-message-from-operator" operation attribute (see
- section 6).
-
-3.4.2. Activate-Printer Operation
-
- This OPTIONAL operation allows a client to undo the effects of the
- Deactivate-Printer; i.e., it allows the Printer object to start
- sending IPP jobs to any of its Output Devices or Subordinate Printers
- (Pause-Printer-After-Current-Job) and starts the Printer object from
- accepting any requests. The Printer performs an Enable-Printer and a
- Resume-Printer operation immediately. In addition, the Printer MUST
- immediately start accepting all requests.
-
- The IPP Printer MUST accept the request in any state. The Printer
- MUST immediately remove the 'deactivated' value from its "printer-
- state-reasons" attribute (whether it is present or not).
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation must be an operator or administrator of the
- Printer object (see [RFC2911], sections 1 and 8.5).
-
-
-
-Kugler, et al. Standards Track [Page 13]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- The Activate-Printer Request and Activate-Printer Response have the
- same attribute groups and attributes as the Pause-Printer operation
- (see [RFC2911], sections 3.2.7.1 and 3.2.7.2), including the new
- "printer-message-from-operator" operation attribute (see section 6).
-
-3.5. Restart-Printer, Shutdown-Printer, and Startup-Printer Operations
-
- This section defines the OPTIONAL Restart-Printer, Shutdown-Printer,
- and Startup-Printer operations that initialize, shutdown, and start
- up the Printer object, respectively. Each of these operations is
- OPTIONAL, and any combination MAY be supported.
-
-3.5.1. Restart-Printer Operation
-
- This OPTIONAL operation allows a client to restart a Printer object
- whose operation is in need of initialization because of incorrect or
- erratic behavior; i.e., perform the effect of a software re-boot.
- The implementation MUST attempt to save any information about Jobs
- and the Printer object before re-initializing. However, this
- operation MAY have drastic consequences on the running system, so the
- client SHOULD first try the Deactivate-Printer operation to minimize
- the effect on the current state of the system. The effects of
- previous Disable-Printer, Pause Printer, and Deactivate-Printer
- operations are lost.
-
- The IPP Printer MUST accept the request in any state. The Printer
- object MUST initialize its Printer's "printer-state" to 'idle',
- remove the state reasons from its "printer-state-reasons" attribute,
- and change its "printer-is-accepting-jobs" attribute to 'true'.
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation must be an operator or administrator of the
- Printer object (see [RFC2911], sections 1 and 8.5).
-
- The Restart-Printer Request and Restart-Printer Response have the
- same attribute groups and attributes as does the Pause-Printer
- operation (see [RFC2911], sections 3.2.8.1 and 3.2.8.2), including
- the new "printer-message-from-operator" operation attribute (see
- section 6).
-
-3.5.2. Shutdown-Printer Operation
-
- This OPTIONAL operation allows a client to shutdown a Printer; i.e.,
- to stop processing jobs without losing any jobs and to make the
- Printer object unavailable for any operations using the IPP protocol.
- There is no way to bring the instance of the Printer object back to
- being used, except for the Startup-Printer (see section 3.5.3), which
- starts up a new instance of the Printer object for hosted
-
-
-
-Kugler, et al. Standards Track [Page 14]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- implementations. The purpose of Shutdown-Printer is to shutdown the
- Printer for an extended period, not to reset the device(s) or modify
- a Printer attribute. See Restart-Printer (section 3.5.1) and
- Startup-Printer (section 3.5.3) for the way to initialize the
- software. See the Disable-Printer operation (section 3.1) for a way
- for the client to stop the Printer from accepting Job Creation
- requests without stopping processing or shutting down.
-
- The Printer MUST add the 'shutdown' value (see [RFC2911], section
- 4.4.11) immediately to its "printer-state-reasons" Printer
- Description attribute. It then performs a Deactivate-Printer
- operation (see section 3.4.1), which in turn performs Disable-Printer
- and Pause-Printer-After-Current-Job operations).
-
- Note: To shutdown the Printer after all the currently submitted jobs
- have completed, the operator issues a Disable-Printer operation (see
- section 3.1.1) and then waits until all the jobs have completed. The
- Printer goes into the 'idle' state before issuing the Shutdown-
- Printer operation.
-
- The Printer object MUST accept this operation in any state and
- transition the Printer object through the "printer-states" and
- "printer-state-reasons" defined for the Pause-Printer-After-Current-
- Job operation until the activity is completed and the Printer object
- disappears.
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation must be an operator or administrator of the
- Printer object (see [RFC2911], sections 1 and 8.5).
-
- The Shutdown-Printer Request and Shutdown-Printer Response have the
- same attribute groups and attributes as does the Pause-Printer
- operation (see [RFC2911], sections 3.2.7.1 and 3.2.7.2), including
- the new "printer-message-from-operator" operation attribute (see
- section 6).
-
-3.5.3. Startup-Printer operation
-
- This OPTIONAL operation allows a client to start up an instance of a
- Printer object, provided that there isn't one already initiated. The
- purpose of Startup-Printer is to allow a hosted implementation of the
- IPP Printer object (i.e., a Server that implements an IPP Printer on
- behalf of a networked or local Output Device) to be started after the
- host is available (by means outside this document). See section
- 3.5.1 for the way to initialize the software or reset the Output
- Device(s) when the IPP Printer object has already been initiated.
-
-
-
-
-
-Kugler, et al. Standards Track [Page 15]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- The host MUST accept this operation only when the Printer object has
- not been initiated. If the Printer object already exists, the host
- must return the 'client-error-not-possible' status code.
-
- The result of this operation MUST be with the Printer object's
- "printer-state" set to 'idle', the state reasons removed from its
- "printer-state-reasons" attribute, and its "printer-is-accepting-
- jobs" attribute set to 'false'. Then the operator can reconfigure
- the Printer before performing an Enable-Printer operation. However,
- when a Printer is first powered up, it is RECOMMENDED that its
- "printer-is-accepting-jobs" attribute be set to 'true' in order to
- achieve easy "out of the box" operation.
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation must be an operator or administrator of the
- Printer object (see [RFC2911], sections 1 and 8.5).
-
- The Shutdown-Printer Request and Shutdown-Printer Response have the
- same attribute groups and attributes as does the Pause-Printer
- operation (see [RFC2911] sections 3.2.7.1 and 3.2.7.2), including the
- new "printer-message-from-operator" operation attribute (see section
- 6).
-
-4. Definition of the Job Operations
-
- All Job operations are directed at Job objects. A client MUST always
- supply some means to identify the Job object in order to select the
- correct target of the operation. That job identification MAY either
- be a single Job URI or a combination of a Printer URI and a Job ID.
- The IPP object implementation MUST support both forms of
- identification for every job.
-
- The Job Operations defined in this document are summarized in Table
- 4.
-
- Table 4. Job Operation Operation-Id Assignments
-
- Operation Name Operation-Id Brief description
- --------------------------------------------------------------------
- Reprocess-Job 0x2C Creates a copy of a completed target
- job with a new Job ID and processes it.
-
- Cancel-Current- 0x2D Cancels the current job on the target
- Job Printer or the specified job if it is
- the current job.
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 16]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- Suspend- 0x2E Suspends the current processing job on
- Current-Job the target Printer or the specified
- job if it is the current job, allowing
- other jobs to be processed instead.
-
- Resume-Job 0x2F Resumes the suspended target job.
-
- Promote-Job 0x30 Promotes the pending target job to be
- next after the current job(s) complete.
-
- Schedule-Job- 0x31 Schedules the target job immediately
- After after the specified job, all other
- scheduling factors being equal.
-
-4.1. Reprocess-Job Operation
-
- This OPTIONAL operation is a create job operation that allows a
- client to re-process a copy of a job that had been retained in the
- queue after processing was completed, canceled, or aborted (see
- [RFC2911], section 4.3.7.2). This operation is the same as the
- Restart-Job operation (see [RFC2911], section 3.3.7), except that the
- Printer creates a new job that is a copy of the target job and the
- target job is unchanged. New values are assigned to the "job-uri"
- and "job-id" attributes. The new job's Job Description attributes
- that track job progress, such as "job-impressions-completed", "job-
- media-sheets-completed", and "job-k-octets-processed", are
- initialized to 0, as with any create job operation. The target job
- moves to the Job History after a suitable period, independent of
- whether one or more Reprocess-Job operations have been performed upon
- it.
-
- If the Set-Job-Attributes operation is supported, then the "job-
- hold-until" operation attribute MUST be supported with at least the
- 'indefinite' value, so that a client can modify the new job before it
- is scheduled for processing by using the Set-Job-Attributes
- operation. After modifying the job, the client can release the job
- for processing by using the Release-Job operation specifying the
- newly assigned "job-uri" or "job-id" for the new job.
-
-4.2. Cancel-Current-Job Operation
-
- This OPTIONAL operation allows a client to cancel the current job on
- the target Printer or the specified job if it is the current job on
- the Printer. See [RFC2911], section 3.3.3, for the semantics of
- canceling a job. Since a Job might already be marking by the time a
- Cancel-Current-Job is received, some media sheet pages might print
- before the job is actually terminated.
-
-
-
-
-Kugler, et al. Standards Track [Page 17]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- If the client does not supply a "job-id" operation attribute, the
- Printer MUST accept the request and cancel the current job if there
- is a current job in the 'processing' or 'processing-stopped' state;
- otherwise, it MUST reject the request and return the 'client-error-
- not-possible' status code. If more than one job is in the
- 'processing' or 'processing-stopped' state, the one that is marking
- is canceled, and the others are unaffected.
-
- Warning: On a shared printer, there is a race condition. Between
- the time when a user issues this operation and the time of its
- acceptance, the current job might change to a different job. If the
- user or operator is authenticated to cancel the new job, the wrong
- job is canceled. To prevent this race from canceling the wrong job,
- the client MAY supply the "job-id" operation attribute, which is
- checked against the current job's job-id. If the job identified by
- the "job-id" attribute is not the current job on the Printer (i.e.,
- is not in the 'processing' or 'processing-stopped' state), the
- Printer MUST reject this operation and return the 'client-error-not-
- possible' status code. Otherwise, the Printer cancels the specified
- job.
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation must either be the job owner (as determined
- in the Job Creation operation) or an operator or administrator of the
- Printer object (see [RFC2911], sections 1 and 8.5).
-
- The Cancel-Current-Job Request and Cancel-Current-Job Response have
- the same attribute groups and attributes as does the Resume-Printer
- operation (see [RFC2911], section 3.2.8), including the new "job-
- message-from-operator" operation attribute (see section 6), with the
- addition of the following Group 1 Operation attribute in the request:
-
- "job-id" (integer(1:MAX)):
- The client OPTIONALLY supplies this Operation attribute to verify
- that the identified job is still the current job on the target
- Printer object. The IPP object MUST support this operation
- attribute if it supports this operation.
-
-4.3. Suspend and Resume Job Operations
-
- This section defines the Suspend-Current-Job and Resume-Job
- operations. These operations allow an operator or user to suspend a
- job while it is processing, allowing other jobs to be processed, and
- to resume the suspended job at a later point without losing any of
- the output.
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 18]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- If either of these operations is supported, both MUST be supported.
-
- The Hold-Job and Release-Job operations ([RFC2911], section 3.3.5)
- are for holding and releasing held jobs, not suspending and resuming
- suspended jobs.
-
-4.3.1. Suspend-Current-Job Operation
-
- This OPTIONAL operation allows a client to stop the current job on
- the target Printer or the specified job if it is the current job on
- the Printer, to allow other jobs to be processed instead. The
- Printer moves the current job or the target job to the 'processing-
- stopped' state and sets the 'job-suspended' value (see section 9.1)
- in the job's "job-state-reasons" attribute and processes other jobs.
-
- If the client does not supply a "job-id" operation attribute, the
- Printer MUST accept the request and suspend the current job if there
- is a current job in the 'processing' or 'processing-stopped' state.
- Otherwise, it MUST reject the request and return the 'client-error-
- not-possible' status code. If more than one job is in the
- 'processing' or 'processing-stopped' state, all of them are
- suspended.
-
- Warning: On a shared printer, there is a race condition. Between
- the time when a user issues this operation and the time of its
- acceptance, the current job might change to a different job. If the
- user or operator is authenticated to suspend the new job, the wrong
- job is suspended. To prevent this race from pausing the wrong job,
- the client MAY supply the "job-id" operation attribute, which is
- checked against the current job's job-id. If the job identified by
- the "job-id" attribute is not the current job on the Printer (i.e.,
- is not in the 'processing' or 'processing-stopped' state), the
- Printer MUST reject this operation and return the 'client-error-not-
- possible' status code. Otherwise, the Printer suspends the specified
- job and processed other jobs.
-
- The Printer MUST reject a Suspend-Current-Job request (and return the
- 'client-error-not-possible') for a job that has been suspended, i.e.,
- for a job in the 'processing-stopped' state, with the 'job-suspended'
- value in its "job-state-reasons" attribute.
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation must be either the job owner (as determined
- in the Job Creation operation) or an operator or administrator of the
- Printer object (see [RFC2911], sections 1 and 8.5).
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 19]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- The Suspend-Current-Job Request and Suspend-Current-Job Response have
- the same attribute groups and attributes as does the Pause-Printer
- operation (see [RFC2911], section 3.2.8 ), including the new "job-
- message-from-operator" operation attribute (see section 6), with the
- addition of the following Group 1 Operation attribute in the request:
-
- "job-id" (integer(1:MAX)):
- The client OPTIONALLY supplies this Operation attribute to verify
- that the identified job is still the current job on the target
- Printer object. The IPP object MUST support this operation
- attribute if it supports this operation.
-
-4.3.2. Resume-Job Operation
-
- This OPTIONAL operation allows a client to resume the target job at
- the point where it was suspended. The Printer moves the target job
- to the 'pending' state and removes the 'job-suspended' value from the
- job's "job-state-reasons" attribute.
-
- If the target job is not in the 'processing-stopped' state, with the
- 'job-suspended' value in the job's "job-state-reasons" attribute, the
- Printer MUST reject the request and return the 'client-error-not-
- possible' status code, since the job was not suspended.
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation must be either the job owner (as determined
- in the Job Creation operation) or an operator or administrator of the
- Printer object (see [RFC2911], sections 1 and 8.5).
-
- The Resume-Job Request and Resume-Job Response have the same
- attribute groups and attributes as the Release-Job operation (see
- [RFC2911], section 3.3.6), including the new "job-message-from-
- operator" operation attribute (see section 6).
-
-4.4. Job Scheduling Operations
-
- This section defines jobs that allow an operator to control the
- scheduling of jobs.
-
-4.4.1. Promote-Job Operation
-
- This OPTIONAL operation allows a client to make the pending target
- job be processed next after the current job completes. This
- operation is especially useful in a production printing environment
- where the operator is involved in job scheduling.
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 20]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- If the target job is in the 'pending' state, this operation does not
- change the job's state but causes the job to be processed after the
- current job(s) complete. If the target job is not in the 'pending'
- state, the Printer MUST reject the request and return the 'client-
- error-not-possible' status code.
-
- If the Printer implements the "job-priority" Job Template attribute
- (see [RFC2911], section 4.2.1), the Printer sets the job's "job-
- priority" to the highest value supported (so that the job will print
- before any of the other pending jobs). The Printer returns the
- target job immediately after the current job(s) in a Get-Jobs
- response (see [RFC2911], section 3.2.6) for the 'not-completed' jobs.
-
- When the current job is completed, canceled, suspended (see section
- 4.3.1), or aborted, the target of this operation is processed next.
-
- If a client issues this request (again) before the target of the
- operation of the original request started processing, the target of
- this new request is processed first.
-
- IPP is specified not to require queues for job scheduling, as there
- are other implementation techniques for scheduling multiple jobs,
- such as re-evaluating a criteria function for each job on a
- scheduling cycle. However, if an implementation does implement
- queues for jobs, then the Promote-Job operation puts the specified
- job at the front of the queue. A subsequent Promote-Job operation
- prior to the processing of the first job puts that specified job at
- the front of the queue, so that it is "in front" of the previously
- promoted job.
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation must be an operator or administrator of the
- Printer object (see [RFC2911], sections 1 and 8.5).
-
- The Promote-Job Request and Promote-Job Response have the same
- attribute groups and attributes as does the Cancel-Job operation (see
- [RFC2911], section 3.3.3), including the new "job-message-from-
- operator" operation attribute (see section 6).
-
-4.4.2. Schedule-Job-After Operation
-
- This OPTIONAL operation allows a client to request that the Printer
- schedule the target job so that it will be processed immediately
- after the specified predecessor job, all other scheduling factors
- being equal. This operation is specially useful in a production
- printing environment where the operator is involved in job
- scheduling.
-
-
-
-
-Kugler, et al. Standards Track [Page 21]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- If the target job is in the 'pending' state, this operation does not
- change the job's state but causes the job to be processed after the
- preceding job completes. The preceding job can be in the target
- 'pending', 'processing', or 'processing-stopped' state. If the
- target job is not in the 'pending' state, or if the predecessor job
- is not in the 'pending', 'processing', or 'processing-stopped' state,
- the Printer MUST reject the request, and it returns the 'client-
- error-not-possible' status code, as the job cannot have its position
- changed.
-
- If the Printer implements the "job-priority" Job Template attribute
- (see [RFC2911], section 4.2.1), the Printer sets the job's "job-
- priority" to that of the predecessor job (so that the job will print
- after the predecessor job). The Printer returns the target job
- immediately after the predecessor in a Get-Jobs response (see
- [RFC2911], section 3.2.6) for the 'not-completed' jobs.
-
- When the predecessor job completes processing or is canceled or
- aborted while processing, the target of this operation is processed
- next.
-
- If the client does not supply a predecessor job, this operation has
- the same semantics as Promote-Job (see section 4.4).
-
- IPP is specified not to require queues for job scheduling, as there
- are other implementation techniques for scheduling multiple jobs,
- such as re-evaluating a criteria function for each job on a
- scheduling cycle. However, if an implementation does implement
- queues for jobs, then the Schedule-Job-After operation puts the
- specified job immediately after the specified job in the queue. A
- subsequent Schedule-Job-After operation specifying the same job will
- cause its target job to be placed after that job, even though it is
- between the first target job and the specified job. For example,
- suppose the job queue consisted of jobs A, B, C, D, and E, in that
- order. A Schedule-Job-After with job E as the target and B as the
- specified job would result in the following queue: A, B, E, C, D. A
- subsequent Schedule-Job-After with Job D as the target and B as the
- specified job would result in the following queue: A, B, D, E, C.
-
- In other words, the link between the two jobs in a Schedule-Job-After
- operation is not retained; i.e., there is no attribute on either job
- that points to the other job as a result of this operation.
-
- Access Rights: The authenticated user (see [RFC2911], section 8.3)
- performing this operation must be an operator or administrator of the
- Printer object (see [RFC2911], sections 1 and 8.5).
-
-
-
-
-
-Kugler, et al. Standards Track [Page 22]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- The Schedule-Job-After Request have the same attribute groups and
- attributes as does the Cancel-Job operation (see [RFC2911], section
- 3.3.3), plus the new "job-message-from-operator" operation attribute
- (see section 6). In addition, the following operation attribute is
- defined:
-
- "predecessor-job-id":
- The client OPTIONALLY supplies this attribute. The Printer MUST
- support it, if it supports this operation. This attribute
- specifies the job after which the target job is to be processed.
- If the client omits this attribute, the Printer MUST process the
- target job next, i.e., after the current job, if there is one.
-
- The Schedule-Job-After Response has the same attribute groups,
- attributes, and status codes as does the Cancel-Job operation (see
- [RFC2911], section 3.3.3). The following status codes have
- particular meaning for this operation:
-
- 'client-error-not-possible' - The target job was not in the 'pending'
- state, or the predecessor job was not in the 'pending', 'processing',
- or 'processing-stopped' state.
-
- 'client-error-not-found' - Either the target job or the predecessor
- job was not found.
-
-5. Additional Status Codes
-
- This section defines new status codes used by the operations defined
- in this document.
-
-5.1. 'server-error-printer-is-deactivated' (0x050A)
-
- The Printer has been deactivated by the Deactivate-Printer operation
- and is only accepting the Activate-Printer (see section 3.5.1), Get-
- Job-Attributes, Get-Jobs, Get-Printer-Attributes, and any other Get-
- Xxxx operations. An operator can perform the Activate-Printer
- operation to allow the Printer to accept other operations.
-
-6. Use of Operation Attributes That Are Messages from the Operator
-
- This section summarizes the usage of the "printer-message-from-
- operator" and "job-message-from-operator" operation attributes
- [RFC3380] that set the corresponding Printer and Job Description
- attributes (see [RFC2911] for the definition of these). These
- operation attributes are defined for most of the Printer and Job
- operations that operators are likely to perform, respectively, so
- that operators can indicate the reasons for their actions.
-
-
-
-
-Kugler, et al. Standards Track [Page 23]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- Table 5 shows the operation attributes defined for use with the
- Printer Operations.
-
- Table 5. Operation Attribute Support for Printer Operations
-
- Operation Attribute A B
- ---------------------------------------------
- attributes-charset REQ REQ
- attributes-natural-language REQ REQ
- printer-uri REQ REQ
- requesting-user-name REQ REQ
- printer-message-from-operator Note OPT
-
- Legend:
- A: Get-Printer-Attributes, Set-Printer-Attributes
- B: All other Printer administrative operations, including, but
- not limited to, Pause-Printer, Pause-Printer-After-Current-
- Job, Resume-Printer, Hold-New-Jobs, Release-Held-New-Jobs,
- Purge-Jobs, Enable-Print, Disable-Printer, Restart-
- Printer, Shutdown-Printer, and Startup-Printer.
- REQ: REQUIRED for a Printer to support.
- OPT: OPTIONAL for a Printer to support; the Printer ignores the
- attribute if it is not supported.
- Note: According to [RFC3380], the Client MUST NOT supply the
- "printer-message-from-operator" operation attribute in a
- Get-Printer-Attributes or Set-Printer-Attributes operation;
- the Printer MUST ignore this operation attribute in these
- two operations. Instead, when it is used by an
- operator, the client MUST supply the
- "printer-message-from-operator" as (one of the) explicit
- attributes being set on the Printer object with the
- Set-Printer-Attributes operation.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 24]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- Table 6 shows the operation attributes defined for use with the Job
- operations.
-
- Table 6. Operation Attribute Support for Job Operations
-
- Operation Attribute A B C F
- ---------------------------------------------------------
- attributes-charset REQ REQ REQ REQ
- attributes-natural-language REQ REQ REQ REQ
- printer-uri REQ REQ REQ REQ
- job-uri REQ REQ REQ
- job-id REQ REQ REQ REQ
- requesting-user-name REQ REQ REQ REQ
- job-message-from-operator OPT OPT OPT Note
- message** OPT OPT OPT n/a
- job-hold-until n/a n/a OPT* n/a
-
- Legend:
- A: Cancel-Job, Resume-Job, Restart-Job, Promote-Job, Schedule-Job-
- After
- B: Cancel-Current-Job, Suspend-Current-Job
- C: Hold-Job, Release-Job, Reprocess-Job
- F: Get-Job-Attributes, Set-Job-Attributes
-
- REQ; REQUIRED for a Printer to support.
- OPT: OPTIONAL for a Printer to support; the Printer ignores the
- attribute if it is supplied, but not supported.
- n/a: not applicable for use with the operation; the Printer ignores
- the attribute.
- Note: According to [RFC3380], the Client MUST NOT supply the "job-
- message-from-operator" operation attribute in a Get-Job-
- Attributes or Set-Job-Attributes operation; the Printer MUST
- ignore this operation attribute in these two operations.
- Instead, when used by an operator, the client MUST supply the
- "job-message-from-operator" as (one of the) explicit attributes
- being set on the Job object with the Set-Job-Attributes
- operation.
- *: The Printer MUST support the "job-hold-until" operation
- attribute if it supports the "job-hold-until" Job Template
- attribute. For the Reprocess-Job operation, the client can
- hold the job and then modify the job before releasing it to
- be processed.
- **: In [RFC2911], the "message" operation attribute is defined to
- contain a message to the operator, but [RFC2911] does not
- define a Job Description attribute to store the message.
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 25]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
-7. New Printer Description Attributes
-
- The following new Printer Description attributes are needed to
- support the new operations defined in this document and the concepts
- of Printer Fan-Out (see section 10).
-
-7.1. subordinate-printers-supported (1setOf uri)
-
- This Printer attribute is REQUIRED if an implementation supports
- Subordinate Printers (see section 10) and contains the URIs of the
- immediate Subordinate Printer object(s) associated with this Printer
- object. Each Non-Leaf Printer object MUST support this Printer
- Description attribute. A Leaf Printer object either does not support
- the "subordinate-printers-supported" attribute or does so with the
- 'no-value' out-of-band value (see [RFC2911], section 4.1), depending
- on the implementation.
-
- The precise format of the Subordinate Printer URIs is implementation
- dependent (see section 10.4).
-
- If the Printer object does not have an associated Output Device, the
- Printer MAY automatically copy the value of the Subordinate Printer
- object's "printer-name" attribute to the Job object's "output-
- device-assigned" attribute (see [RFC2911], section 4.3.13). The
- "output-device-assigned" Job attribute identifies the Output Device
- to which the Printer object has assigned a job; for example, when a
- single Printer object is supporting Device Fan-Out or Printer Fan-
- Out.
-
-7.2. parent-printers-supported (1setOf uri)
-
- This Printer attribute is REQUIRED if an implementation supports
- Subordinate Printers (see section 10) and contains the URI of the
- Non-Leaf printer object(s) for which this Printer object is the
- immediate Subordinate; i.e., this Printer's immediate "parent" or
- "parents". Each Subordinate Printer object MUST support this Printer
- Description attribute. A Printer that has no parents either does not
- support the "parent-printers-supported" attribute or does so with the
- 'no-value' out-of-band value (see [RFC2911], section 4.1), depending
- on the implementation.
-
-8. Additional Values for the "printer-state-reasons" Printer
- Description Attribute
-
- This section defines additional values for the "printer-state-
- reasons" Printer Description attribute.
-
-
-
-
-
-Kugler, et al. Standards Track [Page 26]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
-8.1. 'hold-new-jobs' Value
-
- 'hold-new-jobs': The operator has issued the Hold-New-Jobs operation
- (see section 3.3.1) or other means, but the output-device(s) are
- taking an appreciable time to stop. Later, when all output has
- stopped, the "printer-state" becomes 'stopped', and the 'paused'
- value replaces the 'moving-to-paused' value in the "printer-
- state-reasons" attribute. This value MUST be supported if the
- Hold-New-Jobs operation is supported and the implementation takes
- significant time to pause a device in certain circumstances.
-
-8.2. 'deactivated' Value
-
- 'deactivated': A client has issued a Deactivate-Printer operation
- for the Printer object (see section 3.4.1), and the Printer is in
- the process of becoming deactivated or has become deactivated.
- The Printer MUST reject all requests except for Activate-Printer,
- queries (Get-Printer-Attributes, Get-Job-Attributes, Get-Jobs,
- etc.), Send-Document, and Send-URI (so that partial job submission
- can be completed; see section 3.1.1), and then return the
- 'server-error-service-unavailable' status code.
-
-9. Additional Values for the "job-state-reasons" Job Description
- Attribute
-
- This section defines additional values for the "job-state-reasons"
- Job Description attribute.
-
-9.1. 'job-suspended' Value
-
- 'job-suspended': While job processing has been suspended by the
- Suspend-Current-Job operation, other jobs can be processed on the
- Printer. The Job can be resumed with the Resume-Job operation,
- which removes this value.
-
-10. Use of the Printer Object to Represent IPP Printer Fan-Out and IPP
- Printer Fan-In
-
- This section defines how the Printer object MAY be used to represent
- IPP Printer Fan-Out and IPP Printer Fan-In. In Fan-Out, an IPP
- Printer is used to represent other IPP Printer objects. In Fan-In,
- several IPP Printer objects are used to represent another IPP Printer
- object.
-
-
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 27]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
-10.1. IPP Printer Fan-Out
-
- The IPP/1.1 Model and Semantics introduces the semantic concept of an
- IPP Printer object that represents more than one Output Device (see
- [RFC2911], section 2.1). This concept is called "Output Device Fan-
- Out". However, with Fan-Out there was no way to represent the
- individual states of the Output Devices or to perform operations on a
- specific Output Device. This document generalizes the semantics of
- the Printer object to represent Subordinate Fan-Out Output Devices
- such as IPP Printer objects. This concept is called "Printer object
- Fan-Out". A Printer object that has a Subordinate Printer object is
- called a Non-Leaf Printer object. Thus, a Non-Leaf Printer object
- supports one or more Subordinate Printer objects in order to
- represent Printer object Fan-Out. A Printer object that does not
- have any Subordinate Printer objects is called a Leaf Printer object.
-
- Each Non-Leaf Printer object submits jobs to its immediate
- Subordinate Printers and otherwise controls the Subordinate Printers
- by using IPP or other protocols. Whether pending jobs are kept in
- the Non-Leaf Printer until a Subordinate Printer can accept them or
- are kept in the Subordinate Printers depends on implementation and/or
- configuration policy. Furthermore, a Subordinate Printer object MAY,
- in turn, have Subordinate Printer objects. Thus a Printer object can
- be both a Non-Leaf Printer and a Subordinate Printer.
-
- A Subordinate Printer object MUST be a conforming Printer object, so
- it MUST support all of the REQUIRED [RFC2911] operations and
- attributes. However, with access control, the Subordinate Printer
- MAY be configured so that end-user clients are not permitted to
- perform any operations (or just Get-Printer-Attributes) while one or
- more Non-Leaf Printer object(s) are permitted to perform any
- operation.
-
-10.2. IPP Printer Fan-In
-
- The IPP/1.1 Model and Semantics did not preclude the semantic concept
- of multiple IPP Printer objects that represent a single Output Device
- (see [RFC2911], section 2.1). However, there was no way for the
- client to determine whether there was a Fan-In configuration; nor was
- there a way to perform operations on the Subordinate device. This
- specification generalizes the semantics of the Printer object to
- allow several Non-Leaf IPP Printer objects to represent a single
- Subordinate Printer object. Thus a Non-Leaf Printer object MAY share
- a Subordinate Printer object with one or more other Non-Leaf Printer
- objects in order to represent IPP Printer Fan-In.
-
- As with Fan-Out (see section 10.1), when a Printer object is a Non-
- Leaf Printer, it MUST NOT have an associated Output Device. As with
-
-
-
-Kugler, et al. Standards Track [Page 28]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- Fan-Out, a Leaf Printer object has one or more associated Output
- Devices. As with Fan-Out, the Non-Leaf Printer objects submit jobs
- to their Subordinate Printer objects and otherwise control the
- Subordinate Printer. As with Fan-Out, whether pending jobs are kept
- in the Non-Leaf Printers until the Subordinate Printer can accept
- them or are kept in the Subordinate Printer depends on the
- implementation and/or configuration policy.
-
-10.3. Printer Object Attributes Used to Represent Printer Fan-Out and
- Printer Fan-In
-
- The following Printer Description attributes are defined to represent
- the relationship between Printer object(s) and their Subordinate
- Printer object(s):
-
- 1. "subordinate-printers-supported" (1setOf uri) - Contains the
- URI of the immediate Subordinate Printer object(s).
-
- 2. "parent-printers-supported (1setOf uri) - Contains the URI of
- the Non-Leaf printer object(s) for which this Printer object is
- the immediate Subordinate; i.e., this Printer's immediate
- "parent" or "parents".
-
-10.4. Subordinate Printer URI
-
- Each Subordinate Printer object has a URI used as the target of each
- operation on the Subordinate Printer. The means to configure URIs
- for Subordinate Printer objects is implementation-dependent, as are
- all URIs. However, there are two distinct approaches:
-
- a. When the implementation seeks to make sure that no operation on
- a Subordinate Printer object "sneaks by" the parent Printer
- object (or that no Subordinate Printer is fronting for a device
- that is not networked), the host part of the URI specifies the
- host of the parent Printer. Then the parent Printer object can
- easily reflect the state of the Subordinate Printer objects in
- the parent's Printer object state and state reasons as the
- operation passes "through" the parent Printer object.
-
- b. When the Subordinate Printer is networked and the
- implementation allows operations to go directly to the
- Subordinate Printer (with proper access control) without
- knowledge of the parent Printer object, the host part of the
- URI is different from the host part of the parent Printer
- object. In this a case, the parent Printer object MAY keep its
- "printer-state" and "printer-state-reasons" up to date, either
- by polling the Subordinate Printer object or by subscribing to
- events with the Subordinate Printer object (see [RFC3995] for
-
-
-
-Kugler, et al. Standards Track [Page 29]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- means to subscribe to event notification when the Subordinate
- Printer object supports IPP notification). Alternatively, the
- parent Printer MAY wait until its "printer-state" and
- "printer-state-reasons" attributes are queried and then query
- all its Subordinate Printers in order to return the correct
- values.
-
-10.5. Printer Object Attributes Used to Represent Output Device Fan-Out
-
- Only Leaf IPP Printer objects are allowed to have one or more
- associated Output Devices. Each Leaf Printer object MAY support the
- "output-devices-supported" (1setOf name(127)) to indicate the user-
- friendly name(s) of the Output Device(s) that the Leaf Printer object
- represents. It is RECOMMENDED that each Leaf Printer object have
- only one associated Output Device, so that the individual Output
- Devices can be represented completely and controlled completely by
- clients. In other words, the Leaf Printer's "output-devices-
- supported" attribute SHOULD have only one value.
-
- Non-Leaf Printer MUST NOT have associated Output Devices. However, a
- Non-Leaf Printer SHOULD support an "output-devices-supported" (1setOf
- name(127)) Printer Description attribute that contains all the values
- of its immediate Subordinate Printers. As these Subordinate Printers
- MAY be Leaf or Non-Leaf, the same rules apply to them. Thus any
- Non-Leaf Printer SHOULD have an "output-devices-supported" (1setOf
- name(127)) attribute that contains all the values of the Output
- Devices associated with Leaf Printers of its complete sub-tree.
-
- When a configuration of Printers and Output Devices is added, moved,
- or changed, there can be moments when the tree structure is not
- consistent; i.e., times when a Non-Leaf Printer's "subordinate-
- printers-supported" does not agree with the Subordinate Printer's
- "parent-printers-supported". Therefore, the operator SHOULD first
- Deactivate all Printers being configured in this way, update all
- pointer attributes, and then reactivate them. A useful client tool
- would validate a tree structure before Activating the Printers
- involved.
-
-10.6. Figures to Show All Possible Configurations
-
- Figures 1, 2, and 3 are taken from [RFC2911] to show the
- configurations possible with IPP/1.0 and IPP/1.1 where all Printer
- objects are Leaf Printer objects. The remaining figures show
- additional configurations using Non-Leaf and Leaf Printer objects.
-
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 30]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- Legend:
-
- ----> indicates a network protocol with the direction of its requests
-
- ##### indicates a Printer object that is either
- embedded in an Output Device, or
- hosted in a server.
- The Printer object might or might not be capable
- of queuing/spooling.
-
- any indicates any network protocol or direct
- connect, including IPP.
-
- Output Device
- +---------------+
- | ########### |
- O +--------+ | # (Leaf) # |
- /|\ | client |------------IPP-----------------># Printer # |
- / \ +--------+ | # Object # |
- | ########### |
- +---------------+
-
- Figure 1. Embedded Printer Object
-
-
- ########### Output Device
- O +--------+ # (Leaf) # +---------------+
- /|\ | client |---IPP----># Printer #---any->| |
- / \ +--------+ # object # | |
- ########### +---------------+
-
- Figure 2. Hosted Printer Object
-
-
- +---------------+
- | |
- +->| Output Device |
- ########### any/ | |
- O +--------+ # (Leaf) # / +---------------+
- /|\ | client |---IPP----># Printer #--*
- / \ +--------+ # Object # \ +---------------+
- ########### any\ | |
- +->| Output Device |
- | |
- +---------------+
-
- Figure 3. Output Device Fan-Out
-
-
-
-
-Kugler, et al. Standards Track [Page 31]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- ########### ###########
- O +--------+ # Non-Leaf# # subord. #
- /|\ | client |---IPP----># Printer #---IPP----># Printer #
- / \ +--------+ # object # # object #
- ########### ###########
-
- The Subordinate Printer can be a Non-Leaf Printer, as in Figures 4
- through 6, or can be a Leaf Printer, as in Figures 1 through 3.
-
- Figure 4. Chained IPP Printer Objects
-
-
- +------IPP--------------------->###########
- / +---># subord. #
- / / # Printer #
- / ########### IPP # object #
- O +--------+ # Non-Leaf# / ###########
- /|\ | client |---IPP----># Printer #--*
- / \ +--------+ # object # \
- \ ########### IPP ###########
- \ \ # subord. #
- \ +---># Printer #
- +------IPP---------------------># object #
- ###########
-
- The Subordinate Printer can be a Non-Leaf Printer, as in Figures 4
- through 6, or can be a Leaf Printer, as in Figures 1 through 3.
-
- Figure 5. IPP Printer Object Fan-Out
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 32]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- ###########
- # Non-Leaf#
- +---># Printer #-+
- / # object # \
- IPP ########### \ ###########
- O +--------+ / +-IPP-># subord. #
- /|\ | client |--+-----------IPP---------------># Printer #
- / \ +--------+ \ +-IPP-># object #
- IPP ########### / ###########
- \ # Non-Leaf# /
- +---># Printer #-+
- # object #
- ###########
-
- The Subordinate Printer can be a Non-Leaf Printer, as in Figures 4
- through 6, or can be a Leaf Printer, as in Figures 1 through 3.
-
- Figure 6. IPP Printer Object Fan-In
-
-10.7. Forwarding Requests
-
- This section describes the forwarding of Job and Printer requests to
- Subordinate Printer objects.
-
-10.7.1. Forwarding Requests that Affect Printer Objects
-
- In Printer Fan-Out, Printer Fan-In, and Chained Printers, the Non-
- Leaf IPP Printer object MUST NOT forward the operations that affect
- Printer objects to its Subordinate Printer objects. If a client
- seeks to explicitly target a Subordinate Printer, the client MUST
- specify the URI of the Subordinate Printer. The client can determine
- the URI of any Subordinate Printers by querying the Printer's
- "subordinate-printers-supported (1setOf uri) attribute (see section
- 7.1).
-
- Table 7 lists the operations that affect Printer objects and the
- forwarding behavior that a Non-Leaf Printer MUST exhibit to its
- immediate Subordinate Printers. Operations that affect jobs have a
- different forwarding rule (see section 10.7.2 and Table 8):
-
-
-
-
-
-
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 33]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- Table 7. Forwarding Operations that Affect Printer Objects
-
- Printer Operation Non-Leaf Printer Action
- ---------------------------------------------------------------
- Printer Operations:
-
- Enable-Printer MUST NOT forward to any of its Subordinate
- Printers
- Disable-Printer MUST NOT forward to any of its Subordinate
- Printers
- Hold-New-Jobs MUST NOT forward to any of its Subordinate
- Printers
- Release-Held-New- MUST NOT forward to any of its Subordinate
- Jobs Printers
- Deactivate-Printer MUST NOT forward to any of its Subordinate
- Printers
- Activate-Printer MUST NOT forward to any of its Subordinate
- Printers
- Restart-Printer MUST NOT forward to any of its Subordinate
- Printers
- Shutdown-Printer MUST NOT forward to any of its Subordinate
- Printers
- Startup-Printer MUST NOT forward to any of its Subordinate
- Printers
-
- IPP/1.1 Printer See [RFC2911]
- Operations:
-
- Get-Printer- MUST NOT forward to any of its Subordinate
- Attributes Printers
- Pause-Printer MUST NOT forward to any of its Subordinate
- Printers
- Resume-Printer MUST NOT forward to any of its Subordinate
- Printers
-
- Set Operations: See [RFC3380]
-
- Set-Printer- MUST NOT forward to any of its Subordinate
- Attributes Printers
-
-
-
-
-
-
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 34]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
-10.7.2. Forwarding Requests that Affect Jobs
-
- Unlike Printer Operations that only affect Printer objects (see
- section 10.7.1), a Non-Leaf Printer object MUST forward operations
- that directly affect jobs to the appropriate Job object(s) in one or
- more of its immediate Subordinate Printer objects. Forwarding is
- REQUIRED since the purpose of this Job operation is to affect the
- indicated job, which may have been forwarded itself. This forwarding
- MAY be immediate or queued, depending on the operation and the
- implementation. For example, a Non-Leaf Printer object MAY
- queue/spool jobs, feeding a job at a time to its Subordinate
- Printer(s), or MAY forward jobs immediately to one of its Subordinate
- Printers. In either case, the Non-Leaf Printer object forwards Job
- Creation operations to one of its Subordinate Printers. Only the
- time of forwarding of the Job Creation operations depends on whether
- the policy is to queue/spool jobs in the Non-Leaf Printer or the
- Subordinate Printer.
-
- When a Non-Leaf Printer object creates a Job object in its
- Subordinate Printer, whether that Non-Leaf Printer object keeps a
- fully formed Job object or just keeps a mapping from the "job-ids"
- that it assigned to those assigned by its Subordinate Printer object
- is IMPLEMENTATION-DEPENDENT. In either case, the Non-Leaf Printer
- MUST be able to accept and carry out future Job operations that
- specify the "job-id" that the Non-Leaf Printer assigned and returned
- to the job submitting client.
-
- Table 8 lists the operations that directly affect jobs and the
- forwarding behavior that a Non-Leaf Printer MUST exhibit to its
- Subordinate Printers.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 35]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- Table 8. Forwarding Operations that Affect Jobs Objects
-
- Operation Non-Leaf Printer action
- ---------------------------------------------------------------
- Job operations:
-
- Reprocess-Job MUST forward to the appropriate Job in one of
- its Subordinate Printers
- Cancel-Current- MUST NOT forward
- Job
- Resume-Job MUST forward to the appropriate Job in one of
- its Subordinate Printers
- Promote-Job MUST forward to the appropriate Job in one of
- its Subordinate Printers
-
- IPP/1.1 Printer
- operations:
-
- Print-Job MUST forward immediately or queue to the
- appropriate Subordinate Printer
- Print-URI MUST forward immediately or queue to the
- appropriate Subordinate Printer
- Validate-Job MUST forward to the appropriate Subordinate
- Printer
- Create-Job MUST forward immediately or queue to the
- appropriate Subordinate Printer
- Get-Jobs MUST forward to all its Subordinate Printers
- Purge-Jobs MUST forward to all its Subordinate Printers
-
- IPP/1.1 Job
- operations:
-
- Send-Document MUST forward immediately or queue to the
- appropriate Job in one of its Subordinate
- Printers
- Send-URI MUST forward immediately or queue to the
- appropriate Job in one of its Subordinate
- Printers
- Cancel-Job MUST forward to the appropriate Job in one of
- its Subordinate Printers
- Get-Job- MUST forward to the appropriate Job in one of
- Attributes its Subordinate Printers if the Non-Leaf
- Printer doesn't know the complete status of the
- Job object
- Hold-Job MUST forward to the appropriate Job in one of
- its Subordinate Printers
- Release-Job MUST forward to the appropriate Job in one of
- its Subordinate Printers
-
-
-
-Kugler, et al. Standards Track [Page 36]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- Restart-Job MUST forward to the appropriate Job in one of
- its Subordinate Printers
-
- IPP Set operations: See [RFC3380]
-
- Set-Job- MUST forward to the appropriate Job in one of
- Attributes its Subordinate Printers
-
- When a Printer receives a request that REQUIRES forwarding, it does
- so on a "best efforts basis" and returns a response to its client
- without waiting for responses from any of its Subordinate Printers.
- Such forwarded requests could fail.
-
-10.8. Additional Attributes to Help with Fan-Out
-
- The following operation and Job Description attributes are defined to
- help represent Job relationships for Fan-Out and forwarding of jobs.
-
-10.8.1. output-device-assigned (name(127)) Job Description Attribute -
- from [RFC2911]
-
- [RFC2911] defines "output-device-assigned" as follows: "This
- attribute identifies the Output Device to which the Printer object
- has assigned this job. If an Output Device implements an embedded
- Printer object, the Printer object NEED NOT set this attribute. If a
- print server implements a Printer object, the value MAY be empty
- (zero-length string) or not returned until the Printer object assigns
- an Output Device to the job. This attribute is particularly useful
- when a single Printer object supports multiple devices (so called
- "Device Fan-Out" see [RFC2911] section 2.1)." See also section 10.1
- in this specification.
-
-10.8.2. original-requesting-user-name (name(MAX)) Operation and Job
- Description Attribute
-
- The operation attribute containing the user name of the original
- user; i.e., corresponding to the "requesting-user-name" operation
- attribute (see [RFC2911], section 3.2.1.1) that the original client
- supplied to the first Printer object. The Printer copies the
- "original-requesting-user-name" operation attribute to the
- corresponding Job Description attribute.
-
-
-
-
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 37]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
-10.8.3. requesting-user-name (name(MAX)) Operation Attribute -
- Additional Semantics
-
- The IPP/1.1 "requesting-user-name" operation attribute (see [RFC2911]
- section 3.2.1.1) is updated by each client to be itself on each hop;
- i.e., the "requesting-user-name" represents the client forwarding the
- request, not the original client.
-
-10.8.4. job-originating-user-name (name(MAX)) Job Description Attribute
- - Additional Semantics
-
- The "job-originating-user-name" Job Description attribute (see
- [RFC2911], section 4.3.6) remains as the authenticated original user,
- not the parent Printer's authenticated host, and is forwarded by each
- client without changing the value.
-
-11. Conformance Requirements
-
- The Job and Printer Administrative operations defined in this
- document are OPTIONAL operations. However, some operations MUST be
- implemented if others are implemented, as shown in Table 9.
-
- Table 9. Conformance Requirement Dependencies for Operations
-
- Operations REQUIRED If any of these operations are
- supported:
- --------------------------------------------------------------------
- Enable-Printer Disable-Printer
- Disable-Printer Enable-Printer
- Pause-Printer Resume-Printer
- Resume-Printer Pause-Printer,
- Pause-Printer-After-Current-Job
- Hold-New-Jobs Release-Held-New-Jobs
- Release-Held-New-Jobs Hold-New-Jobs
- Activate-Printer, Deactivate-Printer
- Disable-Printer,
- Pause-Printer-After-Current-Job
- Deactivate-Printer, Activate-Printer
- Enable-Printer,
- Resume-Printer
- Restart-Printer none
- Shutdown-Printer none
- Startup-Printer none
- Reprocess-Job none
- Cancel-Current-Job none
- Resume-Job Suspend-Current-Job
- Suspend-Current-Job Resume-Job
-
-
-
-
-Kugler, et al. Standards Track [Page 38]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- Promote-Job none
- Schedule-Job-After Promote-Job
-
- Tables 10 and 11 list the "printer-state-reasons" and "job-state-
- reasons" values that are REQUIRED if the indicated operations are
- supported.
-
- Table 10. Conformance Requirement Dependencies for
- "printer-state-reasons" Values
-
- "printer-state- Conformance If any of the following Printer
- reasons" values: Requirement Operations are supported:
- --------------------------------------------------------------------
- 'paused' REQUIRED Pause-Printer,
- Pause-Printer-After-Current-Job,
- or Deactivate-Printer
- 'hold-new-jobs' REQUIRED Hold-New-Jobs
- 'moving-to-paused' OPTIONAL Pause-Printer,
- Pause-Printer-After-Current-Job,
- Deactivate-Printer
- 'deactivated' REQUIRED Deactivate-Printer
-
-
- Table 11. Conformance Requirement Dependencies for "job-state-
- reasons" Values
-
- "job-state-reasons" Conformance If any of the following Job
- values: Requirement operations are supported:
-
- 'job-suspended' REQUIRED Suspend-Current-Job
- 'printer-stopped' REQUIRED Always REQUIRED
-
-12. Normative References
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
- RFC 2246, January 1999.
-
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
- Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
- Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
-
- [RFC2910] Herriot, R., Butler, S., Moore, P., Turner, R., and J.
- Wenn, "Internet Printing Protocol/1.1: Encoding and
- Transport", RFC 2910, September 2000.
-
-
-
-
-Kugler, et al. Standards Track [Page 39]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- [RFC2911] Hastings, T., Herriot, R., deBry, R., Isaacson, S., and P.
- Powell, "Internet Printing Protocol/1.1: Model and
- Semantics", RFC 2911, September 2000.
-
- [RFC3380] Hastings, T., Herriot, R., Kugler, C., and H. Lewis,
- "Internet Printing Protocol (IPP): Job and Printer Set
- Operations", RFC 3380, September 2002.
-
-13. Informative References
-
- [RFC2567] Wright, F., "Design Goals for an Internet Printing
- Protocol", RFC 2567, April 1999.
-
- [RFC2568] Zilles, S., "Rationale for the Structure of the Model and
- Protocol for the Internet Printing Protocol", RFC 2568,
- April 1999.
-
- [RFC2569] Herriot, R., Hastings, T., Jacobs, N., and J. Martin,
- "Mapping between LPD and IPP Protocols", RFC 2569, April
- 1999.
-
- [RFC3196] Hastings, T., Manros, C., Zehler, P., Kugler, C., and H.
- Holst, "Internet Printing Protocol/1.1: Implementor's
- Guide", RFC 3196, November 2001.
-
- [RFC3239] Kugler, C., Lewis, H., and T. Hastings, "Internet Printing
- Protocol (IPP): Requirements for Job, Printer, and Device
- Administrative Operations", RFC 3239, February 2002.
-
- [RFC3995] Herriot, R. and T. Hastings, "Internet Printing Protocol
- (IPP): Event Notifications and Subscriptions", RFC 3995,
- February 2005.
-
-14. IANA Considerations
-
- This section contains the registration information that IANA added to
- the IPP Registry according to the procedures defined in [RFC2911],
- section 6, to cover the definitions in this document. The resulting
- registrations have been published as additions to the
- http://www.iana.org/assignments/ipp-registrations file.
-
-
-
-
-
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 40]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
-14.1. Attribute Registrations
-
- The following table lists all the attributes defined in this
- document. These have been registered according to the procedures in
- [RFC2911], section 6.2.
-
- Name Reference Section
- -------------------------------------- --------- -------
- Job Description attributes:
- original-requesting-user-name (name(MAX)) [RFC3998] 10.8.2
-
- Printer Description attributes:
- subordinate-printers-supported (1setOf uri) [RFC3998] 7.1
- parent-printers-supported (1setOf uri) [RFC3998] 7.2
-
- Operation attributes:
- original-requesting-user-name (name(MAX)) [RFC3998] 10.8.2
-
-14.2. Attribute Value Registrations
-
- This section lists the additional values defined in this document for
- existing attributes.
-
- Attribute
- Value Reference Section
- --------------------- --------- -------
- job-state-reasons (1setOf type2 keyword)
- job-suspended [RFC3998] 9.1
-
-
- printer-state-reasons (1setOf type2 keyword)
- hold-new-jobs [RFC3998] 8.1
- deactivated [RFC3998] 8.2
-
-14.3. Additional Enum Attribute Value Registrations
-
- The following table lists all the new enum attribute values defined
- in this document. These have been registered according to the
- procedures in [RFC2911], section 6.1.
-
-
-
-
-
-
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 41]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- Attribute (attribute syntax)
- Value Name Reference Section
- ------- -------------------- --------- -------
- operations-supported (1setOf type2 enum) [RFC2911] 4.4.1
- 0x0022 Enable-Printer [RFC3998] 3
- 0x0023 Disable-Printer [RFC3998] 3
- 0x0024 Pause-Printer-After-Current-Job [RFC3998] 3
- 0x0025 Hold-New-Jobs [RFC3998] 3
- 0x0026 Release-Held-New-Jobs [RFC3998] 3
- 0x0027 Deactivate-Printer [RFC3998] 3
- 0x0028 Activate-Printer [RFC3998] 3
- 0x0029 Restart-Printer [RFC3998] 3
- 0x002A Shutdown-Printer [RFC3998] 3
- 0x002B Startup-Printer [RFC3998] 3
- 0x002C Reprocess-Job [RFC3998] 4
- 0x002D Cancel-Current-Job [RFC3998] 4
- 0x002E Suspend-Current-Job [RFC3998] 4
- 0x002F Resume-Job [RFC3998] 4
- 0x0030 Promote-Job [RFC3998] 4
- 0x0031 Schedule-Job-After [RFC3998] 4
-
-14.4. Operation Registrations
-
- The following table lists all the operations defined in this
- document. These have been registered according to the procedures in
- [RFC2911], section 6.4.
-
- Name Reference Section
- ----------------------------- --------- -------
- Activate-Printer [RFC3998] 3.4.2
- Cancel-Current-Job [RFC3998] 4.2
- Deactivate-Printer [RFC3998] 3.4.1
- Disable-Printer [RFC3998] 3.1.1
- Enable-Printer [RFC3998] 3.1.2
- Hold-New-Jobs [RFC3998] 3.3.1
- Pause-Printer-After-Current-Job [RFC3998] 3.2.1
- Promote-Job [RFC3998] 4.4.1
- Release-Held-New-Jobs [RFC3998] 3.3.2
- Reprocess-Job [RFC3998] 4.1
- Restart-Printer [RFC3998] 3.5.1
- Resume-Job [RFC3998] 4.3.2
- Schedule-Job-After [RFC3998] 4.4.2
- Shutdown-Printer [RFC3998] 3.5.2
- Startup-Printer [RFC3998] 3.5.3
- Suspend-Current-Job [RFC3998] 4.3.1
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 42]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
-14.5. Status Code Registrations
-
- The following table lists the status code defined in this document.
- This has been registered according to the procedures in [RFC2911],
- section 6.6.
-
- Value Name Reference Section
- ------ ------------------------ --------- -------
- 0x0000:0x00FF - "successful"
- none at this time
-
- 0x0100:0x01FF - "informational"
- none at this time
-
- 0x0300:0x03FF - "redirection" See RFC 2911 Errata
- none at this time
-
- 0x0400:0x04FF - "client-error"
- none at this time
-
- 0x0500:0x05FF - "server-error"
- 0x050A server-error-printer-is-deactivated [RFC3998] 5.1
-
-15. Internationalization Considerations
-
- This document has the same localization considerations as [RFC2911].
-
-16. Security Considerations
-
- The IPP Model and Semantics document [RFC2911] discusses high level
- security requirements (Client Authentication, Server Authentication,
- and Operation Privacy). Client Authentication is the mechanism by
- which the client proves its identity to the server in a secure
- manner. Server Authentication is the mechanism by which the server
- proves its identity to the client in a secure manner. Operation
- Privacy is defined as a mechanism for protecting operations from
- eavesdropping.
-
- Printer operations defined in this specification (see section 3), as
- well as Pause-Printer, Resume-Printer, and Purge-Job (defined in
- [RFC2911]) are intended for use by an operator and/or administrator.
- Job operations defined in this specification (see section 4) and
- Cancel-Job, Hold-Job, and Release-Job (defined in [RFC2911]) are
- intended for use by the job owner, operator, or administrator of the
- Printer object. These operator and administrator operations affect
- service for all users.
-
-
-
-
-
-Kugler, et al. Standards Track [Page 43]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- Inappropriate use of an administrative operation by an
- unauthenticated end user can affect the quality of service for all
- users. Therefore, IPP Printer implementations MUST support both
- successful certificate-based TLS [RFC2246] client authentication and
- successful operator/administrator authorization (see [RFC2911],
- sections 5.2.7 and 8, and [RFC2910]) to perform the administrative
- operations defined in this document. [RFC2910] requires the IPP
- Printer to support the minimum cipher suite specified for TLS/1.0.
- The means for authorizing an operator or administrator of the Printer
- object are outside the scope of this specification, RFC 2910, and RFC
- 2911.
-
- The use of TLS and Client Authentication solves the Denial of
- Service, Man in the Middle, and Masquerading security threats.
-
-17. Summary of Base IPP Documents
-
- The base set of IPP documents includes the following:
-
- Design Goals for an Internet Printing Protocol [RFC2567]
- Rationale for the Structure and Model and Protocol for the
- Internet Printing Protocol [RFC2568]
- Internet Printing Protocol/1.1: Model and Semantics [RFC2911]
- Internet Printing Protocol/1.1: Encoding and Transport [RFC2910]
- Internet Printing Protocol/1.1: Implementer's Guide [RFC3196]
- Mapping between LPD and IPP Protocols [RFC2569]
-
- "Design Goals for an Internet Printing Protocol" takes a broad look
- at distributed printing functionality, and it enumerates real-life
- scenarios that help clarify the features that have to be included in
- a printing protocol for the Internet. It identifies requirements for
- three types of users: end users, operators, and administrators. It
- calls out a subset of end user requirements that are satisfied in
- IPP/1.0. A few OPTIONAL operator operations have been added to
- IPP/1.1.
-
- "Rationale for the Structure and Model and Protocol for the Internet
- Printing Protocol" describes IPP from a high level view, defines a
- roadmap for the various documents that form the suite of IPP
- specification documents, and gives background and rationale for the
- IETF working group's major decisions.
-
- "Internet Printing Protocol/1.1: Model and Semantics" describes a
- simplified model with abstract objects, their attributes, and their
- operations that are independent of encoding and transport. It
- introduces a Printer and a Job object. The Job object optionally
- supports multiple documents per Job. It also addresses security,
- internationalization, and directory issues.
-
-
-
-Kugler, et al. Standards Track [Page 44]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
- "Internet Printing Protocol/1.1: Encoding and Transport" is a formal
- mapping of the abstract operations and attributes defined in the
- model document onto HTTP/1.1 [RFC2616]. It defines the encoding
- rules for a new Internet MIME media type called "application/ipp".
- This document also defines the rules for transporting over HTTP a
- message body whose Content-Type is "application/ipp". This document
- defines the 'ippget' scheme for identifying IPP printers and jobs.
-
- "Internet Printing Protocol/1.1: Implementer's Guide" gives insight
- and advice to implementers of IPP clients and IPP objects. It is
- intended to help them understand IPP/1.1 and some of the
- considerations that may assist them in the design of their client
- and/or IPP object implementations. For example, a typical order of
- processing requests is given, including error checking. Motivation
- for some of the specification decisions is also included.
-
- "Mapping between LPD and IPP Protocols" gives some advice to
- implementers of gateways between IPP and LPD (Line Printer Daemon)
- implementations.
-
-Authors' Addresses
-
- Carl Kugler
- IBM Corporation, 003G
- 6300 Diagonal Hwy
- Boulder, CO 80301
-
- Phone: (303) 924-5060
- EMail: kugler@us.ibm.com
-
-
- Tom Hastings, editor
- Xerox Corporation
- 701 S Aviation Blvd. ESAE 242
- El Segundo, CA 90245
-
- Phone: 310-333-6413
- Fax: 310-333-6342
- EMail: hastings@cp10.es.xerox.com
-
-
- Harry Lewis
- IBM Corporation
- 6300 Diagonal Hwy
- Boulder, CO 80301
-
- Phone: (303) 924-5337
- EMail: harryl@us.ibm.com
-
-
-
-Kugler, et al. Standards Track [Page 45]
-\f
-RFC 3998 IPP: Job and Printer Operations March 2005
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2005).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at ietf-
- ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-Kugler, et al. Standards Track [Page 46]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group P. Leach
-Request for Comments: 4122 Microsoft
-Category: Standards Track M. Mealling
- Refactored Networks, LLC
- R. Salz
- DataPower Technology, Inc.
- July 2005
-
-
- A Universally Unique IDentifier (UUID) URN Namespace
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2005).
-
-Abstract
-
- This specification defines a Uniform Resource Name namespace for
- UUIDs (Universally Unique IDentifier), also known as GUIDs (Globally
- Unique IDentifier). A UUID is 128 bits long, and can guarantee
- uniqueness across space and time. UUIDs were originally used in the
- Apollo Network Computing System and later in the Open Software
- Foundation's (OSF) Distributed Computing Environment (DCE), and then
- in Microsoft Windows platforms.
-
- This specification is derived from the DCE specification with the
- kind permission of the OSF (now known as The Open Group).
- Information from earlier versions of the DCE specification have been
- incorporated into this document.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Leach, et al. Standards Track [Page 1]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
- 2. Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 3. Namespace Registration Template . . . . . . . . . . . . . . . 3
- 4. Specification . . . . . . . . . . . . . . . . . . . . . . . . 5
- 4.1. Format. . . . . . . . . . . . . . . . . . . . . . . . . . 5
- 4.1.1. Variant. . . . . . . . . . . . . . . . . . . . . . 6
- 4.1.2. Layout and Byte Order. . . . . . . . . . . . . . . 6
- 4.1.3. Version. . . . . . . . . . . . . . . . . . . . . . 7
- 4.1.4. Timestamp. . . . . . . . . . . . . . . . . . . . . 8
- 4.1.5. Clock Sequence . . . . . . . . . . . . . . . . . . 8
- 4.1.6. Node . . . . . . . . . . . . . . . . . . . . . . . 9
- 4.1.7. Nil UUID . . . . . . . . . . . . . . . . . . . . . 9
- 4.2. Algorithms for Creating a Time-Based UUID . . . . . . . . 9
- 4.2.1. Basic Algorithm. . . . . . . . . . . . . . . . . . 10
- 4.2.2. Generation Details . . . . . . . . . . . . . . . . 12
- 4.3. Algorithm for Creating a Name-Based UUID. . . . . . . . . 13
- 4.4. Algorithms for Creating a UUID from Truly Random or
- Pseudo-Random Numbers . . . . . . . . . . . . . . . . . . 14
- 4.5. Node IDs that Do Not Identify the Host. . . . . . . . . . 15
- 5. Community Considerations . . . . . . . . . . . . . . . . . . . 15
- 6. Security Considerations . . . . . . . . . . . . . . . . . . . 16
- 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16
- 8. Normative References . . . . . . . . . . . . . . . . . . . . . 16
- A. Appendix A - Sample Implementation . . . . . . . . . . . . . . 18
- B. Appendix B - Sample Output of utest . . . . . . . . . . . . . 29
- C. Appendix C - Some Name Space IDs . . . . . . . . . . . . . . . 30
-
-1. Introduction
-
- This specification defines a Uniform Resource Name namespace for
- UUIDs (Universally Unique IDentifier), also known as GUIDs (Globally
- Unique IDentifier). A UUID is 128 bits long, and requires no central
- registration process.
-
- The information here is meant to be a concise guide for those wishing
- to implement services using UUIDs as URNs. Nothing in this document
- should be construed to override the DCE standards that defined UUIDs.
-
- There is an ITU-T Recommendation and ISO/IEC Standard [3] that are
- derived from earlier versions of this document. Both sets of
- specifications have been aligned, and are fully technically
- compatible. In addition, a global registration function is being
- provided by the Telecommunications Standardisation Bureau of ITU-T;
- for details see <http://www.itu.int/ITU-T/asn1/uuid.html>.
-
-
-
-
-
-Leach, et al. Standards Track [Page 2]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
-2. Motivation
-
- One of the main reasons for using UUIDs is that no centralized
- authority is required to administer them (although one format uses
- IEEE 802 node identifiers, others do not). As a result, generation
- on demand can be completely automated, and used for a variety of
- purposes. The UUID generation algorithm described here supports very
- high allocation rates of up to 10 million per second per machine if
- necessary, so that they could even be used as transaction IDs.
-
- UUIDs are of a fixed size (128 bits) which is reasonably small
- compared to other alternatives. This lends itself well to sorting,
- ordering, and hashing of all sorts, storing in databases, simple
- allocation, and ease of programming in general.
-
- Since UUIDs are unique and persistent, they make excellent Uniform
- Resource Names. The unique ability to generate a new UUID without a
- registration process allows for UUIDs to be one of the URNs with the
- lowest minting cost.
-
-3. Namespace Registration Template
-
- Namespace ID: UUID
- Registration Information:
- Registration date: 2003-10-01
-
- Declared registrant of the namespace:
- JTC 1/SC6 (ASN.1 Rapporteur Group)
-
- Declaration of syntactic structure:
- A UUID is an identifier that is unique across both space and time,
- with respect to the space of all UUIDs. Since a UUID is a fixed
- size and contains a time field, it is possible for values to
- rollover (around A.D. 3400, depending on the specific algorithm
- used). A UUID can be used for multiple purposes, from tagging
- objects with an extremely short lifetime, to reliably identifying
- very persistent objects across a network.
-
- The internal representation of a UUID is a specific sequence of
- bits in memory, as described in Section 4. To accurately
- represent a UUID as a URN, it is necessary to convert the bit
- sequence to a string representation.
-
- Each field is treated as an integer and has its value printed as a
- zero-filled hexadecimal digit string with the most significant
- digit first. The hexadecimal values "a" through "f" are output as
- lower case characters and are case insensitive on input.
-
-
-
-
-Leach, et al. Standards Track [Page 3]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- The formal definition of the UUID string representation is
- provided by the following ABNF [7]:
-
- UUID = time-low "-" time-mid "-"
- time-high-and-version "-"
- clock-seq-and-reserved
- clock-seq-low "-" node
- time-low = 4hexOctet
- time-mid = 2hexOctet
- time-high-and-version = 2hexOctet
- clock-seq-and-reserved = hexOctet
- clock-seq-low = hexOctet
- node = 6hexOctet
- hexOctet = hexDigit hexDigit
- hexDigit =
- "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" /
- "a" / "b" / "c" / "d" / "e" / "f" /
- "A" / "B" / "C" / "D" / "E" / "F"
-
- The following is an example of the string representation of a UUID as
- a URN:
-
- urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
-
- Relevant ancillary documentation:
- [1][2]
- Identifier uniqueness considerations:
- This document specifies three algorithms to generate UUIDs: the
- first leverages the unique values of 802 MAC addresses to
- guarantee uniqueness, the second uses pseudo-random number
- generators, and the third uses cryptographic hashing and
- application-provided text strings. As a result, the UUIDs
- generated according to the mechanisms here will be unique from all
- other UUIDs that have been or will be assigned.
-
- Identifier persistence considerations:
- UUIDs are inherently very difficult to resolve in a global sense.
- This, coupled with the fact that UUIDs are temporally unique
- within their spatial context, ensures that UUIDs will remain as
- persistent as possible.
-
- Process of identifier assignment:
- Generating a UUID does not require that a registration authority
- be contacted. One algorithm requires a unique value over space
- for each generator. This value is typically an IEEE 802 MAC
- address, usually already available on network-connected hosts.
- The address can be assigned from an address block obtained from
- the IEEE registration authority. If no such address is available,
-
-
-
-Leach, et al. Standards Track [Page 4]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- or privacy concerns make its use undesirable, Section 4.5
- specifies two alternatives. Another approach is to use version 3
- or version 4 UUIDs as defined below.
-
- Process for identifier resolution:
- Since UUIDs are not globally resolvable, this is not applicable.
-
- Rules for Lexical Equivalence:
- Consider each field of the UUID to be an unsigned integer as shown
- in the table in section Section 4.1.2. Then, to compare a pair of
- UUIDs, arithmetically compare the corresponding fields from each
- UUID in order of significance and according to their data type.
- Two UUIDs are equal if and only if all the corresponding fields
- are equal.
-
- As an implementation note, equality comparison can be performed on
- many systems by doing the appropriate byte-order canonicalization,
- and then treating the two UUIDs as 128-bit unsigned integers.
-
- UUIDs, as defined in this document, can also be ordered
- lexicographically. For a pair of UUIDs, the first one follows the
- second if the most significant field in which the UUIDs differ is
- greater for the first UUID. The second precedes the first if the
- most significant field in which the UUIDs differ is greater for
- the second UUID.
-
- Conformance with URN Syntax:
- The string representation of a UUID is fully compatible with the
- URN syntax. When converting from a bit-oriented, in-memory
- representation of a UUID into a URN, care must be taken to
- strictly adhere to the byte order issues mentioned in the string
- representation section.
-
- Validation mechanism:
- Apart from determining whether the timestamp portion of the UUID
- is in the future and therefore not yet assignable, there is no
- mechanism for determining whether a UUID is 'valid'.
-
- Scope:
- UUIDs are global in scope.
-
-4. Specification
-
-4.1. Format
-
- The UUID format is 16 octets; some bits of the eight octet variant
- field specified below determine finer structure.
-
-
-
-
-Leach, et al. Standards Track [Page 5]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
-4.1.1. Variant
-
- The variant field determines the layout of the UUID. That is, the
- interpretation of all other bits in the UUID depends on the setting
- of the bits in the variant field. As such, it could more accurately
- be called a type field; we retain the original term for
- compatibility. The variant field consists of a variable number of
- the most significant bits of octet 8 of the UUID.
-
- The following table lists the contents of the variant field, where
- the letter "x" indicates a "don't-care" value.
-
- Msb0 Msb1 Msb2 Description
-
- 0 x x Reserved, NCS backward compatibility.
-
- 1 0 x The variant specified in this document.
-
- 1 1 0 Reserved, Microsoft Corporation backward
- compatibility
-
- 1 1 1 Reserved for future definition.
-
- Interoperability, in any form, with variants other than the one
- defined here is not guaranteed, and is not likely to be an issue in
- practice.
-
-4.1.2. Layout and Byte Order
-
- To minimize confusion about bit assignments within octets, the UUID
- record definition is defined only in terms of fields that are
- integral numbers of octets. The fields are presented with the most
- significant one first.
-
- Field Data Type Octet Note
- #
-
- time_low unsigned 32 0-3 The low field of the
- bit integer timestamp
-
- time_mid unsigned 16 4-5 The middle field of the
- bit integer timestamp
-
- time_hi_and_version unsigned 16 6-7 The high field of the
- bit integer timestamp multiplexed
- with the version number
-
-
-
-
-
-Leach, et al. Standards Track [Page 6]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- clock_seq_hi_and_rese unsigned 8 8 The high field of the
- rved bit integer clock sequence
- multiplexed with the
- variant
-
- clock_seq_low unsigned 8 9 The low field of the
- bit integer clock sequence
-
- node unsigned 48 10-15 The spatially unique
- bit integer node identifier
-
- In the absence of explicit application or presentation protocol
- specification to the contrary, a UUID is encoded as a 128-bit object,
- as follows:
-
- The fields are encoded as 16 octets, with the sizes and order of the
- fields defined above, and with each field encoded with the Most
- Significant Byte first (known as network byte order). Note that the
- field names, particularly for multiplexed fields, follow historical
- practice.
-
- 0 1 2 3
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | time_low |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | time_mid | time_hi_and_version |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- |clk_seq_hi_res | clk_seq_low | node (0-1) |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | node (2-5) |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
-4.1.3. Version
-
- The version number is in the most significant 4 bits of the time
- stamp (bits 4 through 7 of the time_hi_and_version field).
-
- The following table lists the currently-defined versions for this
- UUID variant.
-
- Msb0 Msb1 Msb2 Msb3 Version Description
-
- 0 0 0 1 1 The time-based version
- specified in this document.
-
- 0 0 1 0 2 DCE Security version, with
- embedded POSIX UIDs.
-
-
-
-Leach, et al. Standards Track [Page 7]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- 0 0 1 1 3 The name-based version
- specified in this document
- that uses MD5 hashing.
-
- 0 1 0 0 4 The randomly or pseudo-
- randomly generated version
- specified in this document.
-
- 0 1 0 1 5 The name-based version
- specified in this document
- that uses SHA-1 hashing.
-
- The version is more accurately a sub-type; again, we retain the term
- for compatibility.
-
-4.1.4. Timestamp
-
- The timestamp is a 60-bit value. For UUID version 1, this is
- represented by Coordinated Universal Time (UTC) as a count of 100-
- nanosecond intervals since 00:00:00.00, 15 October 1582 (the date of
- Gregorian reform to the Christian calendar).
-
- For systems that do not have UTC available, but do have the local
- time, they may use that instead of UTC, as long as they do so
- consistently throughout the system. However, this is not recommended
- since generating the UTC from local time only needs a time zone
- offset.
-
- For UUID version 3 or 5, the timestamp is a 60-bit value constructed
- from a name as described in Section 4.3.
-
- For UUID version 4, the timestamp is a randomly or pseudo-randomly
- generated 60-bit value, as described in Section 4.4.
-
-4.1.5. Clock Sequence
-
- For UUID version 1, the clock sequence is used to help avoid
- duplicates that could arise when the clock is set backwards in time
- or if the node ID changes.
-
- If the clock is set backwards, or might have been set backwards
- (e.g., while the system was powered off), and the UUID generator can
- not be sure that no UUIDs were generated with timestamps larger than
- the value to which the clock was set, then the clock sequence has to
- be changed. If the previous value of the clock sequence is known, it
- can just be incremented; otherwise it should be set to a random or
- high-quality pseudo-random value.
-
-
-
-
-Leach, et al. Standards Track [Page 8]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- Similarly, if the node ID changes (e.g., because a network card has
- been moved between machines), setting the clock sequence to a random
- number minimizes the probability of a duplicate due to slight
- differences in the clock settings of the machines. If the value of
- clock sequence associated with the changed node ID were known, then
- the clock sequence could just be incremented, but that is unlikely.
-
- The clock sequence MUST be originally (i.e., once in the lifetime of
- a system) initialized to a random number to minimize the correlation
- across systems. This provides maximum protection against node
- identifiers that may move or switch from system to system rapidly.
- The initial value MUST NOT be correlated to the node identifier.
-
- For UUID version 3 or 5, the clock sequence is a 14-bit value
- constructed from a name as described in Section 4.3.
-
- For UUID version 4, clock sequence is a randomly or pseudo-randomly
- generated 14-bit value as described in Section 4.4.
-
-4.1.6. Node
-
- For UUID version 1, the node field consists of an IEEE 802 MAC
- address, usually the host address. For systems with multiple IEEE
- 802 addresses, any available one can be used. The lowest addressed
- octet (octet number 10) contains the global/local bit and the
- unicast/multicast bit, and is the first octet of the address
- transmitted on an 802.3 LAN.
-
- For systems with no IEEE address, a randomly or pseudo-randomly
- generated value may be used; see Section 4.5. The multicast bit must
- be set in such addresses, in order that they will never conflict with
- addresses obtained from network cards.
-
- For UUID version 3 or 5, the node field is a 48-bit value constructed
- from a name as described in Section 4.3.
-
- For UUID version 4, the node field is a randomly or pseudo-randomly
- generated 48-bit value as described in Section 4.4.
-
-4.1.7. Nil UUID
-
- The nil UUID is special form of UUID that is specified to have all
- 128 bits set to zero.
-
-4.2. Algorithms for Creating a Time-Based UUID
-
- Various aspects of the algorithm for creating a version 1 UUID are
- discussed in the following sections.
-
-
-
-Leach, et al. Standards Track [Page 9]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
-4.2.1. Basic Algorithm
-
- The following algorithm is simple, correct, and inefficient:
-
- o Obtain a system-wide global lock
-
- o From a system-wide shared stable store (e.g., a file), read the
- UUID generator state: the values of the timestamp, clock sequence,
- and node ID used to generate the last UUID.
-
- o Get the current time as a 60-bit count of 100-nanosecond intervals
- since 00:00:00.00, 15 October 1582.
-
- o Get the current node ID.
-
- o If the state was unavailable (e.g., non-existent or corrupted), or
- the saved node ID is different than the current node ID, generate
- a random clock sequence value.
-
- o If the state was available, but the saved timestamp is later than
- the current timestamp, increment the clock sequence value.
-
- o Save the state (current timestamp, clock sequence, and node ID)
- back to the stable store.
-
- o Release the global lock.
-
- o Format a UUID from the current timestamp, clock sequence, and node
- ID values according to the steps in Section 4.2.2.
-
- If UUIDs do not need to be frequently generated, the above algorithm
- may be perfectly adequate. For higher performance requirements,
- however, issues with the basic algorithm include:
-
- o Reading the state from stable storage each time is inefficient.
-
- o The resolution of the system clock may not be 100-nanoseconds.
-
- o Writing the state to stable storage each time is inefficient.
-
- o Sharing the state across process boundaries may be inefficient.
-
- Each of these issues can be addressed in a modular fashion by local
- improvements in the functions that read and write the state and read
- the clock. We address each of them in turn in the following
- sections.
-
-
-
-
-
-Leach, et al. Standards Track [Page 10]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
-4.2.1.1. Reading Stable Storage
-
- The state only needs to be read from stable storage once at boot
- time, if it is read into a system-wide shared volatile store (and
- updated whenever the stable store is updated).
-
- If an implementation does not have any stable store available, then
- it can always say that the values were unavailable. This is the
- least desirable implementation because it will increase the frequency
- of creation of new clock sequence numbers, which increases the
- probability of duplicates.
-
- If the node ID can never change (e.g., the net card is inseparable
- from the system), or if any change also reinitializes the clock
- sequence to a random value, then instead of keeping it in stable
- store, the current node ID may be returned.
-
-4.2.1.2. System Clock Resolution
-
- The timestamp is generated from the system time, whose resolution may
- be less than the resolution of the UUID timestamp.
-
- If UUIDs do not need to be frequently generated, the timestamp can
- simply be the system time multiplied by the number of 100-nanosecond
- intervals per system time interval.
-
- If a system overruns the generator by requesting too many UUIDs
- within a single system time interval, the UUID service MUST either
- return an error, or stall the UUID generator until the system clock
- catches up.
-
- A high resolution timestamp can be simulated by keeping a count of
- the number of UUIDs that have been generated with the same value of
- the system time, and using it to construct the low order bits of the
- timestamp. The count will range between zero and the number of
- 100-nanosecond intervals per system time interval.
-
- Note: If the processors overrun the UUID generation frequently,
- additional node identifiers can be allocated to the system, which
- will permit higher speed allocation by making multiple UUIDs
- potentially available for each time stamp value.
-
-4.2.1.3. Writing Stable Storage
-
- The state does not always need to be written to stable store every
- time a UUID is generated. The timestamp in the stable store can be
- periodically set to a value larger than any yet used in a UUID. As
- long as the generated UUIDs have timestamps less than that value, and
-
-
-
-Leach, et al. Standards Track [Page 11]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- the clock sequence and node ID remain unchanged, only the shared
- volatile copy of the state needs to be updated. Furthermore, if the
- timestamp value in stable store is in the future by less than the
- typical time it takes the system to reboot, a crash will not cause a
- reinitialization of the clock sequence.
-
-4.2.1.4. Sharing State Across Processes
-
- If it is too expensive to access shared state each time a UUID is
- generated, then the system-wide generator can be implemented to
- allocate a block of time stamps each time it is called; a per-
- process generator can allocate from that block until it is exhausted.
-
-4.2.2. Generation Details
-
- Version 1 UUIDs are generated according to the following algorithm:
-
- o Determine the values for the UTC-based timestamp and clock
- sequence to be used in the UUID, as described in Section 4.2.1.
-
- o For the purposes of this algorithm, consider the timestamp to be a
- 60-bit unsigned integer and the clock sequence to be a 14-bit
- unsigned integer. Sequentially number the bits in a field,
- starting with zero for the least significant bit.
-
- o Set the time_low field equal to the least significant 32 bits
- (bits zero through 31) of the timestamp in the same order of
- significance.
-
- o Set the time_mid field equal to bits 32 through 47 from the
- timestamp in the same order of significance.
-
- o Set the 12 least significant bits (bits zero through 11) of the
- time_hi_and_version field equal to bits 48 through 59 from the
- timestamp in the same order of significance.
-
- o Set the four most significant bits (bits 12 through 15) of the
- time_hi_and_version field to the 4-bit version number
- corresponding to the UUID version being created, as shown in the
- table above.
-
- o Set the clock_seq_low field to the eight least significant bits
- (bits zero through 7) of the clock sequence in the same order of
- significance.
-
-
-
-
-
-
-
-Leach, et al. Standards Track [Page 12]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- o Set the 6 least significant bits (bits zero through 5) of the
- clock_seq_hi_and_reserved field to the 6 most significant bits
- (bits 8 through 13) of the clock sequence in the same order of
- significance.
-
- o Set the two most significant bits (bits 6 and 7) of the
- clock_seq_hi_and_reserved to zero and one, respectively.
-
- o Set the node field to the 48-bit IEEE address in the same order of
- significance as the address.
-
-4.3. Algorithm for Creating a Name-Based UUID
-
- The version 3 or 5 UUID is meant for generating UUIDs from "names"
- that are drawn from, and unique within, some "name space". The
- concept of name and name space should be broadly construed, and not
- limited to textual names. For example, some name spaces are the
- domain name system, URLs, ISO Object IDs (OIDs), X.500 Distinguished
- Names (DNs), and reserved words in a programming language. The
- mechanisms or conventions used for allocating names and ensuring
- their uniqueness within their name spaces are beyond the scope of
- this specification.
-
- The requirements for these types of UUIDs are as follows:
-
- o The UUIDs generated at different times from the same name in the
- same namespace MUST be equal.
-
- o The UUIDs generated from two different names in the same namespace
- should be different (with very high probability).
-
- o The UUIDs generated from the same name in two different namespaces
- should be different with (very high probability).
-
- o If two UUIDs that were generated from names are equal, then they
- were generated from the same name in the same namespace (with very
- high probability).
-
- The algorithm for generating a UUID from a name and a name space are
- as follows:
-
- o Allocate a UUID to use as a "name space ID" for all UUIDs
- generated from names in that name space; see Appendix C for some
- pre-defined values.
-
- o Choose either MD5 [4] or SHA-1 [8] as the hash algorithm; If
- backward compatibility is not an issue, SHA-1 is preferred.
-
-
-
-
-Leach, et al. Standards Track [Page 13]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- o Convert the name to a canonical sequence of octets (as defined by
- the standards or conventions of its name space); put the name
- space ID in network byte order.
-
- o Compute the hash of the name space ID concatenated with the name.
-
- o Set octets zero through 3 of the time_low field to octets zero
- through 3 of the hash.
-
- o Set octets zero and one of the time_mid field to octets 4 and 5 of
- the hash.
-
- o Set octets zero and one of the time_hi_and_version field to octets
- 6 and 7 of the hash.
-
- o Set the four most significant bits (bits 12 through 15) of the
- time_hi_and_version field to the appropriate 4-bit version number
- from Section 4.1.3.
-
- o Set the clock_seq_hi_and_reserved field to octet 8 of the hash.
-
- o Set the two most significant bits (bits 6 and 7) of the
- clock_seq_hi_and_reserved to zero and one, respectively.
-
- o Set the clock_seq_low field to octet 9 of the hash.
-
- o Set octets zero through five of the node field to octets 10
- through 15 of the hash.
-
- o Convert the resulting UUID to local byte order.
-
-4.4. Algorithms for Creating a UUID from Truly Random or
- Pseudo-Random Numbers
-
- The version 4 UUID is meant for generating UUIDs from truly-random or
- pseudo-random numbers.
-
- The algorithm is as follows:
-
- o Set the two most significant bits (bits 6 and 7) of the
- clock_seq_hi_and_reserved to zero and one, respectively.
-
- o Set the four most significant bits (bits 12 through 15) of the
- time_hi_and_version field to the 4-bit version number from
- Section 4.1.3.
-
- o Set all the other bits to randomly (or pseudo-randomly) chosen
- values.
-
-
-
-Leach, et al. Standards Track [Page 14]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- See Section 4.5 for a discussion on random numbers.
-
-4.5. Node IDs that Do Not Identify the Host
-
- This section describes how to generate a version 1 UUID if an IEEE
- 802 address is not available, or its use is not desired.
-
- One approach is to contact the IEEE and get a separate block of
- addresses. At the time of writing, the application could be found at
- <http://standards.ieee.org/regauth/oui/pilot-ind.html>, and the cost
- was US$550.
-
- A better solution is to obtain a 47-bit cryptographic quality random
- number and use it as the low 47 bits of the node ID, with the least
- significant bit of the first octet of the node ID set to one. This
- bit is the unicast/multicast bit, which will never be set in IEEE 802
- addresses obtained from network cards. Hence, there can never be a
- conflict between UUIDs generated by machines with and without network
- cards. (Recall that the IEEE 802 spec talks about transmission
- order, which is the opposite of the in-memory representation that is
- discussed in this document.)
-
- For compatibility with earlier specifications, note that this
- document uses the unicast/multicast bit, instead of the arguably more
- correct local/global bit.
-
- Advice on generating cryptographic-quality random numbers can be
- found in RFC1750 [5].
-
- In addition, items such as the computer's name and the name of the
- operating system, while not strictly speaking random, will help
- differentiate the results from those obtained by other systems.
-
- The exact algorithm to generate a node ID using these data is system
- specific, because both the data available and the functions to obtain
- them are often very system specific. A generic approach, however, is
- to accumulate as many sources as possible into a buffer, use a
- message digest such as MD5 [4] or SHA-1 [8], take an arbitrary 6
- bytes from the hash value, and set the multicast bit as described
- above.
-
-5. Community Considerations
-
- The use of UUIDs is extremely pervasive in computing. They comprise
- the core identifier infrastructure for many operating systems
- (Microsoft Windows) and applications (the Mozilla browser) and in
- many cases, become exposed to the Web in many non-standard ways.
-
-
-
-
-Leach, et al. Standards Track [Page 15]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- This specification attempts to standardize that practice as openly as
- possible and in a way that attempts to benefit the entire Internet.
-
-6. Security Considerations
-
- Do not assume that UUIDs are hard to guess; they should not be used
- as security capabilities (identifiers whose mere possession grants
- access), for example. A predictable random number source will
- exacerbate the situation.
-
- Do not assume that it is easy to determine if a UUID has been
- slightly transposed in order to redirect a reference to another
- object. Humans do not have the ability to easily check the integrity
- of a UUID by simply glancing at it.
-
- Distributed applications generating UUIDs at a variety of hosts must
- be willing to rely on the random number source at all hosts. If this
- is not feasible, the namespace variant should be used.
-
-7. Acknowledgments
-
- This document draws heavily on the OSF DCE specification for UUIDs.
- Ted Ts'o provided helpful comments, especially on the byte ordering
- section which we mostly plagiarized from a proposed wording he
- supplied (all errors in that section are our responsibility,
- however).
-
- We are also grateful to the careful reading and bit-twiddling of Ralf
- S. Engelschall, John Larmouth, and Paul Thorpe. Professor Larmouth
- was also invaluable in achieving coordination with ISO/IEC.
-
-8. Normative References
-
- [1] Zahn, L., Dineen, T., and P. Leach, "Network Computing
- Architecture", ISBN 0-13-611674-4, January 1990.
-
- [2] "DCE: Remote Procedure Call", Open Group CAE Specification C309,
- ISBN 1-85912-041-5, August 1994.
-
- [3] ISO/IEC 9834-8:2004 Information Technology, "Procedures for the
- operation of OSI Registration Authorities: Generation and
- registration of Universally Unique Identifiers (UUIDs) and their
- use as ASN.1 Object Identifier components" ITU-T Rec. X.667,
- 2004.
-
- [4] Rivest, R., "The MD5 Message-Digest Algorithm ", RFC 1321, April
- 1992.
-
-
-
-
-Leach, et al. Standards Track [Page 16]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- [5] Eastlake, D., 3rd, Schiller, J., and S. Crocker, "Randomness
- Requirements for Security", BCP 106, RFC 4086, June 2005.
-
- [6] Moats, R., "URN Syntax", RFC 2141, May 1997.
-
- [7] Crocker, D. and P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", RFC 2234, November 1997.
-
- [8] National Institute of Standards and Technology, "Secure Hash
- Standard", FIPS PUB 180-1, April 1995,
- <http://www.itl.nist.gov/fipspubs/fip180-1.htm>.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Leach, et al. Standards Track [Page 17]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
-Appendix A. Appendix A - Sample Implementation
-
- This implementation consists of 5 files: uuid.h, uuid.c, sysdep.h,
- sysdep.c and utest.c. The uuid.* files are the system independent
- implementation of the UUID generation algorithms described above,
- with all the optimizations described above except efficient state
- sharing across processes included. The code has been tested on Linux
- (Red Hat 4.0) with GCC (2.7.2), and Windows NT 4.0 with VC++ 5.0.
- The code assumes 64-bit integer support, which makes it much clearer.
-
- All the following source files should have the following copyright
- notice included:
-
-copyrt.h
-
-/*
-** Copyright (c) 1990- 1993, 1996 Open Software Foundation, Inc.
-** Copyright (c) 1989 by Hewlett-Packard Company, Palo Alto, Ca. &
-** Digital Equipment Corporation, Maynard, Mass.
-** Copyright (c) 1998 Microsoft.
-** To anyone who acknowledges that this file is provided "AS IS"
-** without any express or implied warranty: permission to use, copy,
-** modify, and distribute this file for any purpose is hereby
-** granted without fee, provided that the above copyright notices and
-** this notice appears in all source code copies, and that none of
-** the names of Open Software Foundation, Inc., Hewlett-Packard
-** Company, Microsoft, or Digital Equipment Corporation be used in
-** advertising or publicity pertaining to distribution of the software
-** without specific, written prior permission. Neither Open Software
-** Foundation, Inc., Hewlett-Packard Company, Microsoft, nor Digital
-** Equipment Corporation makes any representations about the
-** suitability of this software for any purpose.
-*/
-
-
-uuid.h
-
-#include "copyrt.h"
-#undef uuid_t
-typedef struct {
- unsigned32 time_low;
- unsigned16 time_mid;
- unsigned16 time_hi_and_version;
- unsigned8 clock_seq_hi_and_reserved;
- unsigned8 clock_seq_low;
- byte node[6];
-} uuid_t;
-
-
-
-
-Leach, et al. Standards Track [Page 18]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
-/* uuid_create -- generate a UUID */
-int uuid_create(uuid_t * uuid);
-
-/* uuid_create_md5_from_name -- create a version 3 (MD5) UUID using a
- "name" from a "name space" */
-void uuid_create_md5_from_name(
- uuid_t *uuid, /* resulting UUID */
- uuid_t nsid, /* UUID of the namespace */
- void *name, /* the name from which to generate a UUID */
- int namelen /* the length of the name */
-);
-
-/* uuid_create_sha1_from_name -- create a version 5 (SHA-1) UUID
- using a "name" from a "name space" */
-void uuid_create_sha1_from_name(
-
- uuid_t *uuid, /* resulting UUID */
- uuid_t nsid, /* UUID of the namespace */
- void *name, /* the name from which to generate a UUID */
- int namelen /* the length of the name */
-);
-
-/* uuid_compare -- Compare two UUID's "lexically" and return
- -1 u1 is lexically before u2
- 0 u1 is equal to u2
- 1 u1 is lexically after u2
- Note that lexical ordering is not temporal ordering!
-*/
-int uuid_compare(uuid_t *u1, uuid_t *u2);
-
-
-uuid.c
-
-#include "copyrt.h"
-#include <string.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include <time.h>
-#include "sysdep.h"
-#include "uuid.h"
-
-/* various forward declarations */
-static int read_state(unsigned16 *clockseq, uuid_time_t *timestamp,
- uuid_node_t *node);
-static void write_state(unsigned16 clockseq, uuid_time_t timestamp,
- uuid_node_t node);
-static void format_uuid_v1(uuid_t *uuid, unsigned16 clockseq,
- uuid_time_t timestamp, uuid_node_t node);
-
-
-
-Leach, et al. Standards Track [Page 19]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
-static void format_uuid_v3or5(uuid_t *uuid, unsigned char hash[16],
- int v);
-static void get_current_time(uuid_time_t *timestamp);
-static unsigned16 true_random(void);
-
-/* uuid_create -- generator a UUID */
-int uuid_create(uuid_t *uuid)
-{
- uuid_time_t timestamp, last_time;
- unsigned16 clockseq;
- uuid_node_t node;
- uuid_node_t last_node;
- int f;
-
- /* acquire system-wide lock so we're alone */
- LOCK;
- /* get time, node ID, saved state from non-volatile storage */
- get_current_time(×tamp);
- get_ieee_node_identifier(&node);
- f = read_state(&clockseq, &last_time, &last_node);
-
- /* if no NV state, or if clock went backwards, or node ID
- changed (e.g., new network card) change clockseq */
- if (!f || memcmp(&node, &last_node, sizeof node))
- clockseq = true_random();
- else if (timestamp < last_time)
- clockseq++;
-
- /* save the state for next time */
- write_state(clockseq, timestamp, node);
-
- UNLOCK;
-
- /* stuff fields into the UUID */
- format_uuid_v1(uuid, clockseq, timestamp, node);
- return 1;
-}
-
-/* format_uuid_v1 -- make a UUID from the timestamp, clockseq,
- and node ID */
-void format_uuid_v1(uuid_t* uuid, unsigned16 clock_seq,
- uuid_time_t timestamp, uuid_node_t node)
-{
- /* Construct a version 1 uuid with the information we've gathered
- plus a few constants. */
- uuid->time_low = (unsigned long)(timestamp & 0xFFFFFFFF);
- uuid->time_mid = (unsigned short)((timestamp >> 32) & 0xFFFF);
- uuid->time_hi_and_version =
-
-
-
-Leach, et al. Standards Track [Page 20]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- (unsigned short)((timestamp >> 48) & 0x0FFF);
- uuid->time_hi_and_version |= (1 << 12);
- uuid->clock_seq_low = clock_seq & 0xFF;
- uuid->clock_seq_hi_and_reserved = (clock_seq & 0x3F00) >> 8;
- uuid->clock_seq_hi_and_reserved |= 0x80;
- memcpy(&uuid->node, &node, sizeof uuid->node);
-}
-
-/* data type for UUID generator persistent state */
-typedef struct {
- uuid_time_t ts; /* saved timestamp */
- uuid_node_t node; /* saved node ID */
- unsigned16 cs; /* saved clock sequence */
-} uuid_state;
-
-static uuid_state st;
-
-/* read_state -- read UUID generator state from non-volatile store */
-int read_state(unsigned16 *clockseq, uuid_time_t *timestamp,
- uuid_node_t *node)
-{
- static int inited = 0;
- FILE *fp;
-
- /* only need to read state once per boot */
- if (!inited) {
- fp = fopen("state", "rb");
- if (fp == NULL)
- return 0;
- fread(&st, sizeof st, 1, fp);
- fclose(fp);
- inited = 1;
- }
- *clockseq = st.cs;
- *timestamp = st.ts;
- *node = st.node;
- return 1;
-}
-
-/* write_state -- save UUID generator state back to non-volatile
- storage */
-void write_state(unsigned16 clockseq, uuid_time_t timestamp,
- uuid_node_t node)
-{
- static int inited = 0;
- static uuid_time_t next_save;
- FILE* fp;
-
-
-
-
-Leach, et al. Standards Track [Page 21]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- if (!inited) {
- next_save = timestamp;
- inited = 1;
- }
-
- /* always save state to volatile shared state */
- st.cs = clockseq;
- st.ts = timestamp;
- st.node = node;
- if (timestamp >= next_save) {
- fp = fopen("state", "wb");
- fwrite(&st, sizeof st, 1, fp);
- fclose(fp);
- /* schedule next save for 10 seconds from now */
- next_save = timestamp + (10 * 10 * 1000 * 1000);
- }
-}
-
-/* get-current_time -- get time as 60-bit 100ns ticks since UUID epoch.
- Compensate for the fact that real clock resolution is
- less than 100ns. */
-void get_current_time(uuid_time_t *timestamp)
-{
- static int inited = 0;
- static uuid_time_t time_last;
- static unsigned16 uuids_this_tick;
- uuid_time_t time_now;
-
- if (!inited) {
- get_system_time(&time_now);
- uuids_this_tick = UUIDS_PER_TICK;
- inited = 1;
- }
-
- for ( ; ; ) {
- get_system_time(&time_now);
-
- /* if clock reading changed since last UUID generated, */
- if (time_last != time_now) {
- /* reset count of uuids gen'd with this clock reading */
- uuids_this_tick = 0;
- time_last = time_now;
- break;
- }
- if (uuids_this_tick < UUIDS_PER_TICK) {
- uuids_this_tick++;
- break;
- }
-
-
-
-Leach, et al. Standards Track [Page 22]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- /* going too fast for our clock; spin */
- }
- /* add the count of uuids to low order bits of the clock reading */
- *timestamp = time_now + uuids_this_tick;
-}
-
-/* true_random -- generate a crypto-quality random number.
- **This sample doesn't do that.** */
-static unsigned16 true_random(void)
-{
- static int inited = 0;
- uuid_time_t time_now;
-
- if (!inited) {
- get_system_time(&time_now);
- time_now = time_now / UUIDS_PER_TICK;
- srand((unsigned int)
- (((time_now >> 32) ^ time_now) & 0xffffffff));
- inited = 1;
- }
-
- return rand();
-}
-
-/* uuid_create_md5_from_name -- create a version 3 (MD5) UUID using a
- "name" from a "name space" */
-void uuid_create_md5_from_name(uuid_t *uuid, uuid_t nsid, void *name,
- int namelen)
-{
- MD5_CTX c;
- unsigned char hash[16];
- uuid_t net_nsid;
-
- /* put name space ID in network byte order so it hashes the same
- no matter what endian machine we're on */
- net_nsid = nsid;
- net_nsid.time_low = htonl(net_nsid.time_low);
- net_nsid.time_mid = htons(net_nsid.time_mid);
- net_nsid.time_hi_and_version = htons(net_nsid.time_hi_and_version);
-
- MD5Init(&c);
- MD5Update(&c, &net_nsid, sizeof net_nsid);
- MD5Update(&c, name, namelen);
- MD5Final(hash, &c);
-
- /* the hash is in network byte order at this point */
- format_uuid_v3or5(uuid, hash, 3);
-}
-
-
-
-Leach, et al. Standards Track [Page 23]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
-void uuid_create_sha1_from_name(uuid_t *uuid, uuid_t nsid, void *name,
- int namelen)
-{
- SHA_CTX c;
- unsigned char hash[20];
- uuid_t net_nsid;
-
- /* put name space ID in network byte order so it hashes the same
- no matter what endian machine we're on */
- net_nsid = nsid;
- net_nsid.time_low = htonl(net_nsid.time_low);
- net_nsid.time_mid = htons(net_nsid.time_mid);
- net_nsid.time_hi_and_version = htons(net_nsid.time_hi_and_version);
-
- SHA1_Init(&c);
- SHA1_Update(&c, &net_nsid, sizeof net_nsid);
- SHA1_Update(&c, name, namelen);
- SHA1_Final(hash, &c);
-
- /* the hash is in network byte order at this point */
- format_uuid_v3or5(uuid, hash, 5);
-}
-
-/* format_uuid_v3or5 -- make a UUID from a (pseudo)random 128-bit
- number */
-void format_uuid_v3or5(uuid_t *uuid, unsigned char hash[16], int v)
-{
- /* convert UUID to local byte order */
- memcpy(uuid, hash, sizeof *uuid);
- uuid->time_low = ntohl(uuid->time_low);
- uuid->time_mid = ntohs(uuid->time_mid);
- uuid->time_hi_and_version = ntohs(uuid->time_hi_and_version);
-
- /* put in the variant and version bits */
- uuid->time_hi_and_version &= 0x0FFF;
- uuid->time_hi_and_version |= (v << 12);
- uuid->clock_seq_hi_and_reserved &= 0x3F;
- uuid->clock_seq_hi_and_reserved |= 0x80;
-}
-
-/* uuid_compare -- Compare two UUID's "lexically" and return */
-#define CHECK(f1, f2) if (f1 != f2) return f1 < f2 ? -1 : 1;
-int uuid_compare(uuid_t *u1, uuid_t *u2)
-{
- int i;
-
- CHECK(u1->time_low, u2->time_low);
- CHECK(u1->time_mid, u2->time_mid);
-
-
-
-Leach, et al. Standards Track [Page 24]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- CHECK(u1->time_hi_and_version, u2->time_hi_and_version);
- CHECK(u1->clock_seq_hi_and_reserved, u2->clock_seq_hi_and_reserved);
- CHECK(u1->clock_seq_low, u2->clock_seq_low)
- for (i = 0; i < 6; i++) {
- if (u1->node[i] < u2->node[i])
- return -1;
- if (u1->node[i] > u2->node[i])
- return 1;
- }
- return 0;
-}
-#undef CHECK
-
-
-sysdep.h
-
-#include "copyrt.h"
-/* remove the following define if you aren't running WIN32 */
-#define WININC 0
-
-#ifdef WININC
-#include <windows.h>
-#else
-#include <sys/types.h>
-#include <sys/time.h>
-#include <sys/sysinfo.h>
-#endif
-
-#include "global.h"
-/* change to point to where MD5 .h's live; RFC 1321 has sample
- implementation */
-#include "md5.h"
-
-/* set the following to the number of 100ns ticks of the actual
- resolution of your system's clock */
-#define UUIDS_PER_TICK 1024
-
-/* Set the following to a calls to get and release a global lock */
-#define LOCK
-#define UNLOCK
-
-typedef unsigned long unsigned32;
-typedef unsigned short unsigned16;
-typedef unsigned char unsigned8;
-typedef unsigned char byte;
-
-/* Set this to what your compiler uses for 64-bit data type */
-#ifdef WININC
-
-
-
-Leach, et al. Standards Track [Page 25]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
-#define unsigned64_t unsigned __int64
-#define I64(C) C
-#else
-#define unsigned64_t unsigned long long
-#define I64(C) C##LL
-#endif
-
-typedef unsigned64_t uuid_time_t;
-typedef struct {
- char nodeID[6];
-} uuid_node_t;
-
-void get_ieee_node_identifier(uuid_node_t *node);
-void get_system_time(uuid_time_t *uuid_time);
-void get_random_info(char seed[16]);
-
-
-sysdep.c
-
-#include "copyrt.h"
-#include <stdio.h>
-#include "sysdep.h"
-
-/* system dependent call to get IEEE node ID.
- This sample implementation generates a random node ID. */
-void get_ieee_node_identifier(uuid_node_t *node)
-{
- static inited = 0;
- static uuid_node_t saved_node;
- char seed[16];
- FILE *fp;
-
- if (!inited) {
- fp = fopen("nodeid", "rb");
- if (fp) {
- fread(&saved_node, sizeof saved_node, 1, fp);
- fclose(fp);
- }
- else {
- get_random_info(seed);
- seed[0] |= 0x01;
- memcpy(&saved_node, seed, sizeof saved_node);
- fp = fopen("nodeid", "wb");
- if (fp) {
- fwrite(&saved_node, sizeof saved_node, 1, fp);
- fclose(fp);
- }
- }
-
-
-
-Leach, et al. Standards Track [Page 26]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- inited = 1;
- }
-
- *node = saved_node;
-}
-
-/* system dependent call to get the current system time. Returned as
- 100ns ticks since UUID epoch, but resolution may be less than
- 100ns. */
-#ifdef _WINDOWS_
-
-void get_system_time(uuid_time_t *uuid_time)
-{
- ULARGE_INTEGER time;
-
- /* NT keeps time in FILETIME format which is 100ns ticks since
- Jan 1, 1601. UUIDs use time in 100ns ticks since Oct 15, 1582.
- The difference is 17 Days in Oct + 30 (Nov) + 31 (Dec)
- + 18 years and 5 leap days. */
- GetSystemTimeAsFileTime((FILETIME *)&time);
- time.QuadPart +=
-
- (unsigned __int64) (1000*1000*10) // seconds
- * (unsigned __int64) (60 * 60 * 24) // days
- * (unsigned __int64) (17+30+31+365*18+5); // # of days
- *uuid_time = time.QuadPart;
-}
-
-/* Sample code, not for use in production; see RFC 1750 */
-void get_random_info(char seed[16])
-{
- MD5_CTX c;
- struct {
- MEMORYSTATUS m;
- SYSTEM_INFO s;
- FILETIME t;
- LARGE_INTEGER pc;
- DWORD tc;
- DWORD l;
- char hostname[MAX_COMPUTERNAME_LENGTH + 1];
- } r;
-
- MD5Init(&c);
- GlobalMemoryStatus(&r.m);
- GetSystemInfo(&r.s);
- GetSystemTimeAsFileTime(&r.t);
- QueryPerformanceCounter(&r.pc);
- r.tc = GetTickCount();
-
-
-
-Leach, et al. Standards Track [Page 27]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
- r.l = MAX_COMPUTERNAME_LENGTH + 1;
- GetComputerName(r.hostname, &r.l);
- MD5Update(&c, &r, sizeof r);
- MD5Final(seed, &c);
-}
-
-#else
-
-void get_system_time(uuid_time_t *uuid_time)
-{
- struct timeval tp;
-
- gettimeofday(&tp, (struct timezone *)0);
-
- /* Offset between UUID formatted times and Unix formatted times.
- UUID UTC base time is October 15, 1582.
- Unix base time is January 1, 1970.*/
- *uuid_time = ((unsigned64)tp.tv_sec * 10000000)
- + ((unsigned64)tp.tv_usec * 10)
- + I64(0x01B21DD213814000);
-}
-
-/* Sample code, not for use in production; see RFC 1750 */
-void get_random_info(char seed[16])
-{
- MD5_CTX c;
- struct {
- struct sysinfo s;
- struct timeval t;
- char hostname[257];
- } r;
-
- MD5Init(&c);
- sysinfo(&r.s);
- gettimeofday(&r.t, (struct timezone *)0);
- gethostname(r.hostname, 256);
- MD5Update(&c, &r, sizeof r);
- MD5Final(seed, &c);
-}
-
-#endif
-
-utest.c
-
-#include "copyrt.h"
-#include "sysdep.h"
-#include <stdio.h>
-#include "uuid.h"
-
-
-
-Leach, et al. Standards Track [Page 28]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
-uuid_t NameSpace_DNS = { /* 6ba7b810-9dad-11d1-80b4-00c04fd430c8 */
- 0x6ba7b810,
- 0x9dad,
- 0x11d1,
- 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8
-};
-
-/* puid -- print a UUID */
-void puid(uuid_t u)
-{
- int i;
-
- printf("%8.8x-%4.4x-%4.4x-%2.2x%2.2x-", u.time_low, u.time_mid,
- u.time_hi_and_version, u.clock_seq_hi_and_reserved,
- u.clock_seq_low);
- for (i = 0; i < 6; i++)
- printf("%2.2x", u.node[i]);
- printf("\n");
-}
-
-/* Simple driver for UUID generator */
-void main(int argc, char **argv)
-{
- uuid_t u;
- int f;
-
- uuid_create(&u);
- printf("uuid_create(): "); puid(u);
-
- f = uuid_compare(&u, &u);
- printf("uuid_compare(u,u): %d\n", f); /* should be 0 */
- f = uuid_compare(&u, &NameSpace_DNS);
- printf("uuid_compare(u, NameSpace_DNS): %d\n", f); /* s.b. 1 */
- f = uuid_compare(&NameSpace_DNS, &u);
- printf("uuid_compare(NameSpace_DNS, u): %d\n", f); /* s.b. -1 */
- uuid_create_md5_from_name(&u, NameSpace_DNS, "www.widgets.com", 15);
- printf("uuid_create_md5_from_name(): "); puid(u);
-}
-
-Appendix B. Appendix B - Sample Output of utest
-
- uuid_create(): 7d444840-9dc0-11d1-b245-5ffdce74fad2
- uuid_compare(u,u): 0
- uuid_compare(u, NameSpace_DNS): 1
- uuid_compare(NameSpace_DNS, u): -1
- uuid_create_md5_from_name(): e902893a-9d22-3c7e-a7b8-d6e313b71d9f
-
-
-
-
-
-Leach, et al. Standards Track [Page 29]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
-Appendix C. Appendix C - Some Name Space IDs
-
- This appendix lists the name space IDs for some potentially
- interesting name spaces, as initialized C structures and in the
- string representation defined above.
-
- /* Name string is a fully-qualified domain name */
- uuid_t NameSpace_DNS = { /* 6ba7b810-9dad-11d1-80b4-00c04fd430c8 */
- 0x6ba7b810,
- 0x9dad,
- 0x11d1,
- 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8
- };
-
- /* Name string is a URL */
- uuid_t NameSpace_URL = { /* 6ba7b811-9dad-11d1-80b4-00c04fd430c8 */
- 0x6ba7b811,
- 0x9dad,
- 0x11d1,
- 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8
- };
-
- /* Name string is an ISO OID */
- uuid_t NameSpace_OID = { /* 6ba7b812-9dad-11d1-80b4-00c04fd430c8 */
- 0x6ba7b812,
- 0x9dad,
- 0x11d1,
- 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8
- };
-
- /* Name string is an X.500 DN (in DER or a text output format) */
- uuid_t NameSpace_X500 = { /* 6ba7b814-9dad-11d1-80b4-00c04fd430c8 */
- 0x6ba7b814,
- 0x9dad,
- 0x11d1,
- 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8
- };
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Leach, et al. Standards Track [Page 30]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
-Authors' Addresses
-
- Paul J. Leach
- Microsoft
- 1 Microsoft Way
- Redmond, WA 98052
- US
-
- Phone: +1 425-882-8080
- EMail: paulle@microsoft.com
-
-
- Michael Mealling
- Refactored Networks, LLC
- 1635 Old Hwy 41
- Suite 112, Box 138
- Kennesaw, GA 30152
- US
-
- Phone: +1-678-581-9656
- EMail: michael@refactored-networks.com
- URI: http://www.refactored-networks.com
-
-
- Rich Salz
- DataPower Technology, Inc.
- 1 Alewife Center
- Cambridge, MA 02142
- US
-
- Phone: +1 617-864-0455
- EMail: rsalz@datapower.com
- URI: http://www.datapower.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Leach, et al. Standards Track [Page 31]
-\f
-RFC 4122 A UUID URN Namespace July 2005
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2005).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at ietf-
- ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-Leach, et al. Standards Track [Page 32]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group D. Crocker, Ed.
-Request for Comments: 4234 Brandenburg InternetWorking
-Obsoletes: 2234 P. Overell
-Category: Standards Track THUS plc.
- October 2005
-
-
- Augmented BNF for Syntax Specifications: ABNF
-
-Status of This Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2005).
-
-Abstract
-
- Internet technical specifications often need to define a formal
- syntax. Over the years, a modified version of Backus-Naur Form
- (BNF), called Augmented BNF (ABNF), has been popular among many
- Internet specifications. The current specification documents ABNF.
- It balances compactness and simplicity, with reasonable
- representational power. The differences between standard BNF and
- ABNF involve naming rules, repetition, alternatives, order-
- independence, and value ranges. This specification also supplies
- additional rule definitions and encoding for a core lexical analyzer
- of the type common to several Internet specifications.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Crocker & Overell Standards Track [Page 1]
-\f
-RFC 4234 ABNF October 2005
-
-
-Table of Contents
-
- 1. INTRODUCTION ....................................................2
- 2. RULE DEFINITION .................................................3
- 2.1. Rule Naming ................................................3
- 2.2. Rule Form ..................................................3
- 2.3. Terminal Values ............................................4
- 2.4. External Encodings .........................................5
- 3. OPERATORS .......................................................6
- 3.1. Concatenation: Rule1 Rule2 ................................6
- 3.2. Alternatives: Rule1 / Rule2 ...............................6
- 3.3. Incremental Alternatives: Rule1 =/ Rule2 ...................7
- 3.4. Value Range Alternatives: %c##-## .........................7
- 3.5. Sequence Group: (Rule1 Rule2) .............................8
- 3.6. Variable Repetition: *Rule ................................8
- 3.7. Specific Repetition: nRule ................................9
- 3.8. Optional Sequence: [RULE] .................................9
- 3.9. Comment: ; Comment ........................................9
- 3.10. Operator Precedence .......................................9
- 4. ABNF DEFINITION OF ABNF ........................................10
- 5. SECURITY CONSIDERATIONS ........................................11
- 6. References .....................................................11
- 6.1. Normative References ......................................11
- 6.2. Informative References ....................................11
- Appendix A. ACKNOWLEDGEMENTS .....................................13
- Appendix B. APPENDIX - CORE ABNF OF ABNF .........................13
- B.1. Core Rules ...............................................13
- B.2. Common Encoding ..........................................14
-
-1. INTRODUCTION
-
- Internet technical specifications often need to define a formal
- syntax and are free to employ whatever notation their authors deem
- useful. Over the years, a modified version of Backus-Naur Form
- (BNF), called Augmented BNF (ABNF), has been popular among many
- Internet specifications. It balances compactness and simplicity,
- with reasonable representational power. In the early days of the
- Arpanet, each specification contained its own definition of ABNF.
- This included the email specifications, [RFC733] and then [RFC822],
- which came to be the common citations for defining ABNF. The current
- document separates those definitions to permit selective reference.
- Predictably, it also provides some modifications and enhancements.
-
- The differences between standard BNF and ABNF involve naming rules,
- repetition, alternatives, order-independence, and value ranges.
- Appendix B supplies rule definitions and encoding for a core lexical
- analyzer of the type common to several Internet specifications. It
- is provided as a convenience and is otherwise separate from the meta
-
-
-
-Crocker & Overell Standards Track [Page 2]
-\f
-RFC 4234 ABNF October 2005
-
-
- language defined in the body of this document, and separate from its
- formal status.
-
- Changes since [RFC2234]:
-
- In Section 3.7, the phrase: "That is, exactly <N> occurrences of
- <element>." was corrected to: "That is, exactly <n> occurrences of
- <element>."
-
- Some continuation comment lines needed to be corrected to begin
- with comment character (";").
-
-2. RULE DEFINITION
-
-2.1. Rule Naming
-
- The name of a rule is simply the name itself; that is, a sequence of
- characters, beginning with an alphabetic character, and followed by a
- combination of alphabetics, digits, and hyphens (dashes).
-
- NOTE:
-
- Rule names are case-insensitive
-
- The names <rulename>, <Rulename>, <RULENAME>, and <rUlENamE> all
- refer to the same rule.
-
- Unlike original BNF, angle brackets ("<", ">") are not required.
- However, angle brackets may be used around a rule name whenever their
- presence facilitates in discerning the use of a rule name. This is
- typically restricted to rule name references in free-form prose, or
- to distinguish partial rules that combine into a string not separated
- by white space, such as shown in the discussion about repetition,
- below.
-
-2.2. Rule Form
-
- A rule is defined by the following sequence:
-
- name = elements crlf
-
- where <name> is the name of the rule, <elements> is one or more rule
- names or terminal specifications, and <crlf> is the end-of-line
- indicator (carriage return followed by line feed). The equal sign
- separates the name from the definition of the rule. The elements
- form a sequence of one or more rule names and/or value definitions,
- combined according to the various operators defined in this document,
- such as alternative and repetition.
-
-
-
-Crocker & Overell Standards Track [Page 3]
-\f
-RFC 4234 ABNF October 2005
-
-
- For visual ease, rule definitions are left aligned. When a rule
- requires multiple lines, the continuation lines are indented. The
- left alignment and indentation are relative to the first lines of the
- ABNF rules and need not match the left margin of the document.
-
-2.3. Terminal Values
-
- Rules resolve into a string of terminal values, sometimes called
- characters. In ABNF, a character is merely a non-negative integer.
- In certain contexts, a specific mapping (encoding) of values into a
- character set (such as ASCII) will be specified.
-
- Terminals are specified by one or more numeric characters, with the
- base interpretation of those characters indicated explicitly. The
- following bases are currently defined:
-
- b = binary
-
- d = decimal
-
- x = hexadecimal
-
- Hence:
-
- CR = %d13
-
- CR = %x0D
-
- respectively specify the decimal and hexadecimal representation of
- [US-ASCII] for carriage return.
-
- A concatenated string of such values is specified compactly, using a
- period (".") to indicate a separation of characters within that
- value. Hence:
-
- CRLF = %d13.10
-
- ABNF permits the specification of literal text strings directly,
- enclosed in quotation-marks. Hence:
-
- command = "command string"
-
- Literal text strings are interpreted as a concatenated set of
- printable characters.
-
-
-
-
-
-
-
-Crocker & Overell Standards Track [Page 4]
-\f
-RFC 4234 ABNF October 2005
-
-
- NOTE:
-
- ABNF strings are case-insensitive and the character set for these
- strings is us-ascii.
-
- Hence:
-
- rulename = "abc"
-
- and:
-
- rulename = "aBc"
-
- will match "abc", "Abc", "aBc", "abC", "ABc", "aBC", "AbC", and
- "ABC".
-
- To specify a rule that IS case SENSITIVE, specify the characters
- individually.
-
- For example:
-
- rulename = %d97 %d98 %d99
-
- or
-
- rulename = %d97.98.99
-
- will match only the string that comprises only the lowercased
- characters, abc.
-
-2.4. External Encodings
-
- External representations of terminal value characters will vary
- according to constraints in the storage or transmission environment.
- Hence, the same ABNF-based grammar may have multiple external
- encodings, such as one for a 7-bit US-ASCII environment, another for
- a binary octet environment, and still a different one when 16-bit
- Unicode is used. Encoding details are beyond the scope of ABNF,
- although Appendix A (Core) provides definitions for a 7-bit US-ASCII
- environment as has been common to much of the Internet.
-
- By separating external encoding from the syntax, it is intended that
- alternate encoding environments can be used for the same syntax.
-
-
-
-
-
-
-
-
-Crocker & Overell Standards Track [Page 5]
-\f
-RFC 4234 ABNF October 2005
-
-
-3. OPERATORS
-
-3.1. Concatenation: Rule1 Rule2
-
- A rule can define a simple, ordered string of values (i.e., a
- concatenation of contiguous characters) by listing a sequence of rule
- names. For example:
-
- foo = %x61 ; a
-
- bar = %x62 ; b
-
- mumble = foo bar foo
-
- So that the rule <mumble> matches the lowercase string "aba".
-
- LINEAR WHITE SPACE: Concatenation is at the core of the ABNF parsing
- model. A string of contiguous characters (values) is parsed
- according to the rules defined in ABNF. For Internet specifications,
- there is some history of permitting linear white space (space and
- horizontal tab) to be freely and implicitly interspersed around major
- constructs, such as delimiting special characters or atomic strings.
-
- NOTE:
-
- This specification for ABNF does not provide for implicit
- specification of linear white space.
-
- Any grammar that wishes to permit linear white space around
- delimiters or string segments must specify it explicitly. It is
- often useful to provide for such white space in "core" rules that are
- then used variously among higher-level rules. The "core" rules might
- be formed into a lexical analyzer or simply be part of the main
- ruleset.
-
-3.2. Alternatives: Rule1 / Rule2
-
- Elements separated by a forward slash ("/") are alternatives.
- Therefore,
-
- foo / bar
-
- will accept <foo> or <bar>.
-
-
-
-
-
-
-
-
-Crocker & Overell Standards Track [Page 6]
-\f
-RFC 4234 ABNF October 2005
-
-
- NOTE:
-
- A quoted string containing alphabetic characters is a special form
- for specifying alternative characters and is interpreted as a
- non-terminal representing the set of combinatorial strings with
- the contained characters, in the specified order but with any
- mixture of upper and lower case.
-
-3.3. Incremental Alternatives: Rule1 =/ Rule2
-
- It is sometimes convenient to specify a list of alternatives in
- fragments. That is, an initial rule may match one or more
- alternatives, with later rule definitions adding to the set of
- alternatives. This is particularly useful for otherwise, independent
- specifications that derive from the same parent rule set, such as
- often occurs with parameter lists. ABNF permits this incremental
- definition through the construct:
-
- oldrule =/ additional-alternatives
-
- So that the rule set
-
- ruleset = alt1 / alt2
-
- ruleset =/ alt3
-
- ruleset =/ alt4 / alt5
-
- is the same as specifying
-
- ruleset = alt1 / alt2 / alt3 / alt4 / alt5
-
-3.4. Value Range Alternatives: %c##-##
-
- A range of alternative numeric values can be specified compactly,
- using dash ("-") to indicate the range of alternative values. Hence:
-
- DIGIT = %x30-39
-
- is equivalent to:
-
- DIGIT = "0" / "1" / "2" / "3" / "4" / "5" / "6" /
-
- "7" / "8" / "9"
-
- Concatenated numeric values and numeric value ranges cannot be
- specified in the same string. A numeric value may use the dotted
- notation for concatenation or it may use the dash notation to specify
-
-
-
-Crocker & Overell Standards Track [Page 7]
-\f
-RFC 4234 ABNF October 2005
-
-
- one value range. Hence, to specify one printable character between
- end of line sequences, the specification could be:
-
- char-line = %x0D.0A %x20-7E %x0D.0A
-
-3.5. Sequence Group: (Rule1 Rule2)
-
- Elements enclosed in parentheses are treated as a single element,
- whose contents are STRICTLY ORDERED. Thus,
-
- elem (foo / bar) blat
-
- matches (elem foo blat) or (elem bar blat), and
-
- elem foo / bar blat
-
- matches (elem foo) or (bar blat).
-
- NOTE:
-
- It is strongly advised that grouping notation be used, rather than
- relying on the proper reading of "bare" alternations, when
- alternatives consist of multiple rule names or literals.
-
- Hence, it is recommended that the following form be used:
-
- (elem foo) / (bar blat)
-
- It will avoid misinterpretation by casual readers.
-
- The sequence group notation is also used within free text to set off
- an element sequence from the prose.
-
-3.6. Variable Repetition: *Rule
-
- The operator "*" preceding an element indicates repetition. The full
- form is:
-
- <a>*<b>element
-
- where <a> and <b> are optional decimal values, indicating at least
- <a> and at most <b> occurrences of the element.
-
- Default values are 0 and infinity so that *<element> allows any
- number, including zero; 1*<element> requires at least one;
- 3*3<element> allows exactly 3 and 1*2<element> allows one or two.
-
-
-
-
-
-Crocker & Overell Standards Track [Page 8]
-\f
-RFC 4234 ABNF October 2005
-
-
-3.7. Specific Repetition: nRule
-
- A rule of the form:
-
- <n>element
-
- is equivalent to
-
- <n>*<n>element
-
- That is, exactly <n> occurrences of <element>. Thus, 2DIGIT is a 2-
- digit number, and 3ALPHA is a string of three alphabetic characters.
-
-3.8. Optional Sequence: [RULE]
-
- Square brackets enclose an optional element sequence:
-
- [foo bar]
-
- is equivalent to
-
- *1(foo bar).
-
-3.9. Comment: ; Comment
-
- A semi-colon starts a comment that continues to the end of line.
- This is a simple way of including useful notes in parallel with the
- specifications.
-
-3.10. Operator Precedence
-
- The various mechanisms described above have the following precedence,
- from highest (binding tightest) at the top, to lowest (loosest) at
- the bottom:
-
- Strings, Names formation
-
- Comment
-
- Value range
-
- Repetition
-
- Grouping, Optional
-
- Concatenation
-
- Alternative
-
-
-
-Crocker & Overell Standards Track [Page 9]
-\f
-RFC 4234 ABNF October 2005
-
-
- Use of the alternative operator, freely mixed with concatenations,
- can be confusing.
-
- Again, it is recommended that the grouping operator be used to
- make explicit concatenation groups.
-
-4. ABNF DEFINITION OF ABNF
-
- NOTES:
-
- 1. This syntax requires a formatting of rules that is relatively
- strict. Hence, the version of a ruleset included in a
- specification might need preprocessing to ensure that it can be
- interpreted by an ABNF parser.
-
- 2. This syntax uses the rules provided in Appendix B (Core).
-
- rulelist = 1*( rule / (*c-wsp c-nl) )
-
- rule = rulename defined-as elements c-nl
- ; continues if next line starts
- ; with white space
-
- rulename = ALPHA *(ALPHA / DIGIT / "-")
-
- defined-as = *c-wsp ("=" / "=/") *c-wsp
- ; basic rules definition and
- ; incremental alternatives
-
- elements = alternation *c-wsp
-
- c-wsp = WSP / (c-nl WSP)
-
- c-nl = comment / CRLF
- ; comment or newline
-
- comment = ";" *(WSP / VCHAR) CRLF
-
- alternation = concatenation
- *(*c-wsp "/" *c-wsp concatenation)
-
- concatenation = repetition *(1*c-wsp repetition)
-
- repetition = [repeat] element
-
- repeat = 1*DIGIT / (*DIGIT "*" *DIGIT)
-
-
-
-
-
-Crocker & Overell Standards Track [Page 10]
-\f
-RFC 4234 ABNF October 2005
-
-
- element = rulename / group / option /
- char-val / num-val / prose-val
-
- group = "(" *c-wsp alternation *c-wsp ")"
-
- option = "[" *c-wsp alternation *c-wsp "]"
-
- char-val = DQUOTE *(%x20-21 / %x23-7E) DQUOTE
- ; quoted string of SP and VCHAR
- ; without DQUOTE
-
- num-val = "%" (bin-val / dec-val / hex-val)
-
- bin-val = "b" 1*BIT
- [ 1*("." 1*BIT) / ("-" 1*BIT) ]
- ; series of concatenated bit values
- ; or single ONEOF range
-
- dec-val = "d" 1*DIGIT
- [ 1*("." 1*DIGIT) / ("-" 1*DIGIT) ]
-
- hex-val = "x" 1*HEXDIG
- [ 1*("." 1*HEXDIG) / ("-" 1*HEXDIG) ]
-
- prose-val = "<" *(%x20-3D / %x3F-7E) ">"
- ; bracketed string of SP and VCHAR
- ; without angles
- ; prose description, to be used as
- ; last resort
-
-5. SECURITY CONSIDERATIONS
-
- Security is truly believed to be irrelevant to this document.
-
-6. References
-
-6.1. Normative References
-
- [US-ASCII] American National Standards Institute, "Coded Character
- Set -- 7-bit American Standard Code for Information
- Interchange", ANSI X3.4, 1986.
-
-6.2. Informative References
-
- [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", RFC 2234, November 1997.
-
-
-
-
-
-Crocker & Overell Standards Track [Page 11]
-\f
-RFC 4234 ABNF October 2005
-
-
- [RFC733] Crocker, D., Vittal, J., Pogran, K., and D. Henderson,
- "Standard for the format of ARPA network text messages",
- RFC 733, November 1977.
-
- [RFC822] Crocker, D., "Standard for the format of ARPA Internet
- text messages", STD 11, RFC 822, August 1982.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Crocker & Overell Standards Track [Page 12]
-\f
-RFC 4234 ABNF October 2005
-
-
-Appendix A. ACKNOWLEDGEMENTS
-
- The syntax for ABNF was originally specified in RFC 733. Ken L.
- Harrenstien, of SRI International, was responsible for re-coding the
- BNF into an augmented BNF that makes the representation smaller and
- easier to understand.
-
- This recent project began as a simple effort to cull out the portion
- of RFC 822 that has been repeatedly cited by non-email specification
- writers, namely the description of augmented BNF. Rather than simply
- and blindly converting the existing text into a separate document,
- the working group chose to give careful consideration to the
- deficiencies, as well as benefits, of the existing specification and
- related specifications made available over the last 15 years, and
- therefore to pursue enhancement. This turned the project into
- something rather more ambitious than was first intended.
- Interestingly, the result is not massively different from that
- original, although decisions, such as removing the list notation,
- came as a surprise.
-
- This "separated" version of the specification was part of the DRUMS
- working group, with significant contributions from Jerome Abela,
- Harald Alvestrand, Robert Elz, Roger Fajman, Aviva Garrett, Tom
- Harsch, Dan Kohn, Bill McQuillan, Keith Moore, Chris Newman, Pete
- Resnick, and Henning Schulzrinne.
-
- Julian Reschke warrants a special thanks for converting the Draft
- Standard version to XML source form.
-
-Appendix B. APPENDIX - CORE ABNF OF ABNF
-
- This Appendix is provided as a convenient core for specific grammars.
- The definitions may be used as a core set of rules.
-
-B.1. Core Rules
-
- Certain basic rules are in uppercase, such as SP, HTAB, CRLF, DIGIT,
- ALPHA, etc.
-
- ALPHA = %x41-5A / %x61-7A ; A-Z / a-z
-
- BIT = "0" / "1"
-
- CHAR = %x01-7F
- ; any 7-bit US-ASCII character,
- ; excluding NUL
-
-
-
-
-
-Crocker & Overell Standards Track [Page 13]
-\f
-RFC 4234 ABNF October 2005
-
-
- CR = %x0D
- ; carriage return
-
- CRLF = CR LF
- ; Internet standard newline
-
- CTL = %x00-1F / %x7F
- ; controls
-
- DIGIT = %x30-39
- ; 0-9
-
- DQUOTE = %x22
- ; " (Double Quote)
-
- HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
-
- HTAB = %x09
- ; horizontal tab
-
- LF = %x0A
- ; linefeed
-
- LWSP = *(WSP / CRLF WSP)
- ; linear white space (past newline)
-
- OCTET = %x00-FF
- ; 8 bits of data
-
- SP = %x20
-
- VCHAR = %x21-7E
- ; visible (printing) characters
-
- WSP = SP / HTAB
- ; white space
-
-B.2. Common Encoding
-
- Externally, data are represented as "network virtual ASCII" (namely,
- 7-bit US-ASCII in an 8-bit field), with the high (8th) bit set to
- zero. A string of values is in "network byte order", in which the
- higher-valued bytes are represented on the left-hand side and are
- sent over the network first.
-
-
-
-
-
-
-
-Crocker & Overell Standards Track [Page 14]
-\f
-RFC 4234 ABNF October 2005
-
-
-Authors' Addresses
-
- Dave Crocker (editor)
- Brandenburg InternetWorking
- 675 Spruce Dr.
- Sunnyvale, CA 94086
- US
-
- Phone: +1.408.246.8253
- EMail: dcrocker@bbiw.net
-
-
- Paul Overell
- THUS plc.
- 1/2 Berkeley Square
- 99 Berkeley Street
- Glasgow
- G3 7HR
- UK
-
- EMail: paul.overell@thus.net
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Crocker & Overell Standards Track [Page 15]
-\f
-RFC 4234 ABNF October 2005
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2005).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at ietf-
- ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-Crocker & Overell Standards Track [Page 16]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group A. Phillips, Ed.
-Request for Comments: 4646 Yahoo! Inc.
-BCP: 47 M. Davis, Ed.
-Obsoletes: 3066 Google
-Category: Best Current Practice September 2006
-
-
- Tags for Identifying Languages
-
-Status of This Memo
-
- This document specifies an Internet Best Current Practices for the
- Internet Community, and requests discussion and suggestions for
- improvements. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2005).
-
-Abstract
-
- This document describes the structure, content, construction, and
- semantics of language tags for use in cases where it is desirable to
- indicate the language used in an information object. It also
- describes how to register values for use in language tags and the
- creation of user-defined extensions for private interchange. This
- document, in combination with RFC 4647, replaces RFC 3066, which
- replaced RFC 1766.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 1]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
-Table of Contents
-
- 1. Introduction ....................................................3
- 2. The Language Tag ................................................4
- 2.1. Syntax .....................................................4
- 2.2. Language Subtag Sources and Interpretation .................7
- 2.2.1. Primary Language Subtag .............................8
- 2.2.2. Extended Language Subtags ..........................10
- 2.2.3. Script Subtag ......................................11
- 2.2.4. Region Subtag ......................................11
- 2.2.5. Variant Subtags ....................................13
- 2.2.6. Extension Subtags ..................................14
- 2.2.7. Private Use Subtags ................................16
- 2.2.8. Preexisting RFC 3066 Registrations .................16
- 2.2.9. Classes of Conformance .............................17
- 3. Registry Format and Maintenance ................................18
- 3.1. Format of the IANA Language Subtag Registry ...............18
- 3.2. Language Subtag Reviewer ..................................24
- 3.3. Maintenance of the Registry ...............................24
- 3.4. Stability of IANA Registry Entries ........................25
- 3.5. Registration Procedure for Subtags ........................29
- 3.6. Possibilities for Registration ............................32
- 3.7. Extensions and Extensions Registry ........................34
- 3.8. Initialization of the Registries ..........................37
- 4. Formation and Processing of Language Tags ......................38
- 4.1. Choice of Language Tag ....................................38
- 4.2. Meaning of the Language Tag ...............................40
- 4.3. Length Considerations .....................................41
- 4.3.1. Working with Limited Buffer Sizes ..................42
- 4.3.2. Truncation of Language Tags ........................43
- 4.4. Canonicalization of Language Tags .........................44
- 4.5. Considerations for Private Use Subtags ....................45
- 5. IANA Considerations ............................................46
- 5.1. Language Subtag Registry ..................................46
- 5.2. Extensions Registry .......................................47
- 6. Security Considerations ........................................48
- 7. Character Set Considerations ...................................48
- 8. Changes from RFC 3066 ..........................................49
- 9. References .....................................................52
- 9.1. Normative References ......................................52
- 9.2. Informative References ....................................53
- Appendix A. Acknowledgements ......................................55
- Appendix B. Examples of Language Tags (Informative) ...............56
-
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 2]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
-1. Introduction
-
- Human beings on our planet have, past and present, used a number of
- languages. There are many reasons why one would want to identify the
- language used when presenting or requesting information.
-
- A user's language preferences often need to be identified so that
- appropriate processing can be applied. For example, the user's
- language preferences in a Web browser can be used to select Web pages
- appropriately. Language preferences can also be used to select among
- tools (such as dictionaries) to assist in the processing or
- understanding of content in different languages.
-
- In addition, knowledge about the particular language used by some
- piece of information content might be useful or even required by some
- types of processing; for example, spell-checking, computer-
- synthesized speech, Braille transcription, or high-quality print
- renderings.
-
- One means of indicating the language used is by labeling the
- information content with an identifier or "tag". These tags can be
- used to specify user preferences when selecting information content,
- or for labeling additional attributes of content and associated
- resources.
-
- Tags can also be used to indicate additional language attributes of
- content. For example, indicating specific information about the
- dialect, writing system, or orthography used in a document or
- resource may enable the user to obtain information in a form that
- they can understand, or it can be important in processing or
- rendering the given content into an appropriate form or style.
-
- This document specifies a particular identifier mechanism (the
- language tag) and a registration function for values to be used to
- form tags. It also defines a mechanism for private use values and
- future extension.
-
- This document, in combination with [RFC4647], replaces [RFC3066],
- which replaced [RFC1766]. For a list of changes in this document,
- see Section 8.
-
- The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in [RFC2119].
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 3]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
-2. The Language Tag
-
- Language tags are used to help identify languages, whether spoken,
- written, signed, or otherwise signaled, for the purpose of
- communication. This includes constructed and artificial languages,
- but excludes languages not intended primarily for human
- communication, such as programming languages.
-
-2.1. Syntax
-
- The language tag is composed of one or more parts, known as
- "subtags". Each subtag consists of a sequence of alphanumeric
- characters. Subtags are distinguished and separated from one another
- by a hyphen ("-", ABNF [RFC4234] %x2D). A language tag consists of a
- "primary language" subtag and a (possibly empty) series of subsequent
- subtags, each of which refines or narrows the range of languages
- identified by the overall tag.
-
- Usually, each type of subtag is distinguished by length, position in
- the tag, and content: subtags can be recognized solely by these
- features. The only exception to this is a fixed list of
- grandfathered tags registered under RFC 3066 [RFC3066]. This makes
- it possible to construct a parser that can extract and assign some
- semantic information to the subtags, even if the specific subtag
- values are not recognized. Thus, a parser need not have an up-to-
- date copy (or any copy at all) of the subtag registry to perform most
- searching and matching operations.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 4]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- The syntax of the language tag in ABNF [RFC4234] is:
-
- Language-Tag = langtag
- / privateuse ; private use tag
- / grandfathered ; grandfathered registrations
-
- langtag = (language
- ["-" script]
- ["-" region]
- *("-" variant)
- *("-" extension)
- ["-" privateuse])
-
- language = (2*3ALPHA [ extlang ]) ; shortest ISO 639 code
- / 4ALPHA ; reserved for future use
- / 5*8ALPHA ; registered language subtag
-
- extlang = *3("-" 3ALPHA) ; reserved for future use
-
- script = 4ALPHA ; ISO 15924 code
-
- region = 2ALPHA ; ISO 3166 code
- / 3DIGIT ; UN M.49 code
-
- variant = 5*8alphanum ; registered variants
- / (DIGIT 3alphanum)
-
- extension = singleton 1*("-" (2*8alphanum))
-
- singleton = %x41-57 / %x59-5A / %x61-77 / %x79-7A / DIGIT
- ; "a"-"w" / "y"-"z" / "A"-"W" / "Y"-"Z" / "0"-"9"
- ; Single letters: x/X is reserved for private use
-
- privateuse = ("x"/"X") 1*("-" (1*8alphanum))
-
- grandfathered = 1*3ALPHA 1*2("-" (2*8alphanum))
- ; grandfathered registration
- ; Note: i is the only singleton
- ; that starts a grandfathered tag
-
- alphanum = (ALPHA / DIGIT) ; letters and numbers
-
- Figure 1: Language Tag ABNF
-
- Note: There is a subtlety in the ABNF for 'variant': variants
- starting with a digit MAY be four characters long, while those
- starting with a letter MUST be at least five characters long.
-
-
-
-
-Phillips & Davis Best Current Practice [Page 5]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- All subtags have a maximum length of eight characters and whitespace
- is not permitted in a language tag. For examples of language tags,
- see Appendix B.
-
- Note that although [RFC4234] refers to octets, the language tags
- described in this document are sequences of characters from the
- US-ASCII [ISO646] repertoire. Language tags MAY be used in documents
- and applications that use other encodings, so long as these encompass
- the US-ASCII repertoire. An example of this would be an XML document
- that uses the UTF-16LE [RFC2781] encoding of [Unicode].
-
- The tags and their subtags, including private use and extensions, are
- to be treated as case insensitive: there exist conventions for the
- capitalization of some of the subtags, but these MUST NOT be taken to
- carry meaning.
-
- For example:
-
- o [ISO639-1] recommends that language codes be written in lowercase
- ('mn' Mongolian).
-
- o [ISO3166-1] recommends that country codes be capitalized ('MN'
- Mongolia).
-
- o [ISO15924] recommends that script codes use lowercase with the
- initial letter capitalized ('Cyrl' Cyrillic).
-
- However, in the tags defined by this document, the uppercase US-ASCII
- letters in the range 'A' through 'Z' are considered equivalent and
- mapped directly to their US-ASCII lowercase equivalents in the range
- 'a' through 'z'. Thus, the tag "mn-Cyrl-MN" is not distinct from
- "MN-cYRL-mn" or "mN-cYrL-Mn" (or any other combination), and each of
- these variations conveys the same meaning: Mongolian written in the
- Cyrillic script as used in Mongolia.
-
- Although case distinctions do not carry meaning in language tags,
- consistent formatting and presentation of the tags will aid users.
- The format of the tags and subtags in the registry is RECOMMENDED.
- In this format, all non-initial two-letter subtags are uppercase, all
- non-initial four-letter subtags are titlecase, and all other subtags
- are lowercase.
-
-
-
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 6]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
-2.2. Language Subtag Sources and Interpretation
-
- The namespace of language tags and their subtags is administered by
- the Internet Assigned Numbers Authority (IANA) [RFC2860] according to
- the rules in Section 5 of this document. The Language Subtag
- Registry maintained by IANA is the source for valid subtags: other
- standards referenced in this section provide the source material for
- that registry.
-
- Terminology in this section:
-
- o Tag or tags refers to a complete language tag, such as
- "fr-Latn-CA". Examples of tags in this document are enclosed in
- double-quotes ("en-US").
-
- o Subtag refers to a specific section of a tag, delimited by hyphen,
- such as the subtag 'Latn' in "fr-Latn-CA". Examples of subtags in
- this document are enclosed in single quotes ('Latn').
-
- o Code or codes refers to values defined in external standards (and
- that are used as subtags in this document). For example, 'Latn'
- is an [ISO15924] script code that was used to define the 'Latn'
- script subtag for use in a language tag. Examples of codes in
- this document are enclosed in single quotes ('en', 'Latn').
-
- The definitions in this section apply to the various subtags within
- the language tags defined by this document, excepting those
- "grandfathered" tags defined in Section 2.2.8.
-
- Language tags are designed so that each subtag type has unique length
- and content restrictions. These make identification of the subtag's
- type possible, even if the content of the subtag itself is
- unrecognized. This allows tags to be parsed and processed without
- reference to the latest version of the underlying standards or the
- IANA registry and makes the associated exception handling when
- parsing tags simpler.
-
- Subtags in the IANA registry that do not come from an underlying
- standard can only appear in specific positions in a tag.
- Specifically, they can only occur as primary language subtags or as
- variant subtags.
-
- Note that sequences of private use and extension subtags MUST occur
- at the end of the sequence of subtags and MUST NOT be interspersed
- with subtags defined elsewhere in this document.
-
- Single-letter and single-digit subtags are reserved for current or
- future use. These include the following current uses:
-
-
-
-Phillips & Davis Best Current Practice [Page 7]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- o The single-letter subtag 'x' is reserved to introduce a sequence
- of private use subtags. The interpretation of any private use
- subtags is defined solely by private agreement and is not defined
- by the rules in this section or in any standard or registry
- defined in this document.
-
- o All other single-letter subtags are reserved to introduce
- standardized extension subtag sequences as described in
- Section 3.7.
-
- The single-letter subtag 'i' is used by some grandfathered tags, such
- as "i-enochian", where it always appears in the first position and
- cannot be confused with an extension.
-
-2.2.1. Primary Language Subtag
-
- The primary language subtag is the first subtag in a language tag
- (with the exception of private use and certain grandfathered tags)
- and cannot be omitted. The following rules apply to the primary
- language subtag:
-
- 1. All two-character language subtags were defined in the IANA
- registry according to the assignments found in the standard ISO
- 639 Part 1, "ISO 639-1:2002, Codes for the representation of
- names of languages -- Part 1: Alpha-2 code" [ISO639-1], or using
- assignments subsequently made by the ISO 639 Part 1 maintenance
- agency or governing standardization bodies.
-
- 2. All three-character language subtags were defined in the IANA
- registry according to the assignments found in ISO 639 Part 2,
- "ISO 639-2:1998 - Codes for the representation of names of
- languages -- Part 2: Alpha-3 code - edition 1" [ISO639-2], or
- assignments subsequently made by the ISO 639 Part 2 maintenance
- agency or governing standardization bodies.
-
- 3. The subtags in the range 'qaa' through 'qtz' are reserved for
- private use in language tags. These subtags correspond to codes
- reserved by ISO 639-2 for private use. These codes MAY be used
- for non-registered primary language subtags (instead of using
- private use subtags following 'x-'). Please refer to Section 4.5
- for more information on private use subtags.
-
- 4. All four-character language subtags are reserved for possible
- future standardization.
-
- 5. All language subtags of 5 to 8 characters in length in the IANA
- registry were defined via the registration process in Section 3.5
- and MAY be used to form the primary language subtag. At the time
-
-
-
-Phillips & Davis Best Current Practice [Page 8]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- this document was created, there were no examples of this kind of
- subtag and future registrations of this type will be discouraged:
- primary languages are strongly RECOMMENDED for registration with
- ISO 639, and proposals rejected by ISO 639/RA will be closely
- scrutinized before they are registered with IANA.
-
- 6. The single-character subtag 'x' as the primary subtag indicates
- that the language tag consists solely of subtags whose meaning is
- defined by private agreement. For example, in the tag "x-fr-CH",
- the subtags 'fr' and 'CH' SHOULD NOT be taken to represent the
- French language or the country of Switzerland (or any other value
- in the IANA registry) unless there is a private agreement in
- place to do so. See Section 4.5.
-
- 7. The single-character subtag 'i' is used by some grandfathered
- tags (see Section 2.2.8) such as "i-klingon" and "i-bnn". (Other
- grandfathered tags have a primary language subtag in their first
- position.)
-
- 8. Other values MUST NOT be assigned to the primary subtag except by
- revision or update of this document.
-
- Note: For languages that have both an ISO 639-1 two-character code
- and an ISO 639-2 three-character code, only the ISO 639-1 two-
- character code is defined in the IANA registry.
-
- Note: For languages that have no ISO 639-1 two-character code and for
- which the ISO 639-2/T (Terminology) code and the ISO 639-2/B
- (Bibliographic) codes differ, only the Terminology code is defined in
- the IANA registry. At the time this document was created, all
- languages that had both kinds of three-character code were also
- assigned a two-character code; it is not expected that future
- assignments of this nature will occur.
-
- Note: To avoid problems with versioning and subtag choice as
- experienced during the transition between RFC 1766 and RFC 3066, as
- well as the canonical nature of subtags defined by this document, the
- ISO 639 Registration Authority Joint Advisory Committee (ISO 639/
- RA-JAC) has included the following statement in [iso639.prin]:
-
- "A language code already in ISO 639-2 at the point of freezing ISO
- 639-1 shall not later be added to ISO 639-1. This is to ensure
- consistency in usage over time, since users are directed in Internet
- applications to employ the alpha-3 code when an alpha-2 code for that
- language is not available."
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 9]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- In order to avoid instability in the canonical form of tags, if a
- two-character code is added to ISO 639-1 for a language for which a
- three-character code was already included in ISO 639-2, the two-
- character code MUST NOT be registered. See Section 3.4.
-
- For example, if some content were tagged with 'haw' (Hawaiian), which
- currently has no two-character code, the tag would not be invalidated
- if ISO 639-1 were to assign a two-character code to the Hawaiian
- language at a later date.
-
- For example, one of the grandfathered IANA registrations is
- "i-enochian". The subtag 'enochian' could be registered in the IANA
- registry as a primary language subtag (assuming that ISO 639 does not
- register this language first), making tags such as "enochian-AQ" and
- "enochian-Latn" valid.
-
-2.2.2. Extended Language Subtags
-
- The following rules apply to the extended language subtags:
-
- 1. Three-letter subtags immediately following the primary subtag are
- reserved for future standardization, anticipating work that is
- currently under way on ISO 639.
-
- 2. Extended language subtags MUST follow the primary subtag and
- precede any other subtags.
-
- 3. There MAY be up to three extended language subtags.
-
- 4. Extended language subtags MUST NOT be registered or used to form
- language tags. Their syntax is described here so that
- implementations can be compatible with any future revision of
- this document that does provide for their registration.
-
- Extended language subtag records, once they appear in the registry,
- MUST include exactly one 'Prefix' field indicating an appropriate
- language subtag or sequence of subtags that MUST always appear as a
- prefix to the extended language subtag.
-
- Example: In a future revision or update of this document, the tag
- "zh-gan" (registered under RFC 3066) might become a valid non-
- grandfathered (that is, redundant) tag in which the subtag 'gan'
- might represent the Chinese dialect 'Gan'.
-
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 10]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
-2.2.3. Script Subtag
-
- Script subtags are used to indicate the script or writing system
- variations that distinguish the written forms of a language or its
- dialects. The following rules apply to the script subtags:
-
- 1. All four-character subtags were defined according to
- [ISO15924]--"Codes for the representation of names of scripts":
- alpha-4 script codes, or subsequently assigned by the ISO 15924
- maintenance agency or governing standardization bodies, denoting
- the script or writing system used in conjunction with this
- language.
-
- 2. Script subtags MUST immediately follow the primary language
- subtag and all extended language subtags and MUST occur before
- any other type of subtag described below.
-
- 3. The script subtags 'Qaaa' through 'Qabx' are reserved for private
- use in language tags. These subtags correspond to codes reserved
- by ISO 15924 for private use. These codes MAY be used for non-
- registered script values. Please refer to Section 4.5 for more
- information on private use subtags.
-
- 4. Script subtags MUST NOT be registered using the process in
- Section 3.5 of this document. Variant subtags MAY be considered
- for registration for that purpose.
-
- 5. There MUST be at most one script subtag in a language tag, and
- the script subtag SHOULD be omitted when it adds no
- distinguishing value to the tag or when the primary language
- subtag's record includes a Suppress-Script field listing the
- applicable script subtag.
-
- Example: "sr-Latn" represents Serbian written using the Latin script.
-
-2.2.4. Region Subtag
-
- Region subtags are used to indicate linguistic variations associated
- with or appropriate to a specific country, territory, or region.
- Typically, a region subtag is used to indicate regional dialects or
- usage, or region-specific spelling conventions. A region subtag can
- also be used to indicate that content is expressed in a way that is
- appropriate for use throughout a region, for instance, Spanish
- content tailored to be useful throughout Latin America.
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 11]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- The following rules apply to the region subtags:
-
- 1. Region subtags MUST follow any language, extended language, or
- script subtags and MUST precede all other subtags.
-
- 2. All two-character subtags following the primary subtag were
- defined in the IANA registry according to the assignments found
- in [ISO3166-1] ("Codes for the representation of names of
- countries and their subdivisions -- Part 1: Country codes") using
- the list of alpha-2 country codes, or using assignments
- subsequently made by the ISO 3166 maintenance agency or governing
- standardization bodies.
-
- 3. All three-character subtags consisting of digit (numeric)
- characters following the primary subtag were defined in the IANA
- registry according to the assignments found in UN Standard
- Country or Area Codes for Statistical Use [UN_M.49] or
- assignments subsequently made by the governing standards body.
- Note that not all of the UN M.49 codes are defined in the IANA
- registry. The following rules define which codes are entered
- into the registry as valid subtags:
-
- A. UN numeric codes assigned to 'macro-geographical
- (continental)' or sub-regions MUST be registered in the
- registry. These codes are not associated with an assigned
- ISO 3166 alpha-2 code and represent supra-national areas,
- usually covering more than one nation, state, province, or
- territory.
-
- B. UN numeric codes for 'economic groupings' or 'other
- groupings' MUST NOT be registered in the IANA registry and
- MUST NOT be used to form language tags.
-
- C. UN numeric codes for countries or areas with ambiguous ISO
- 3166 alpha-2 codes, when entered into the registry, MUST be
- defined according to the rules in Section 3.4 and MUST be
- used to form language tags that represent the country or
- region for which they are defined.
-
- D. UN numeric codes for countries or areas for which there is an
- associated ISO 3166 alpha-2 code in the registry MUST NOT be
- entered into the registry and MUST NOT be used to form
- language tags. Note that the ISO 3166-based subtag in the
- registry MUST actually be associated with the UN M.49 code in
- question.
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 12]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- E. UN numeric codes and ISO 3166 alpha-2 codes for countries or
- areas listed as eligible for registration in [RFC4645] but
- not presently registered MAY be entered into the IANA
- registry via the process described in Section 3.5. Once
- registered, these codes MAY be used to form language tags.
-
- F. All other UN numeric codes for countries or areas that do not
- have an associated ISO 3166 alpha-2 code MUST NOT be entered
- into the registry and MUST NOT be used to form language tags.
- For more information about these codes, see Section 3.4.
-
- 4. Note: The alphanumeric codes in Appendix X of the UN document
- MUST NOT be entered into the registry and MUST NOT be used to
- form language tags. (At the time this document was created,
- these values matched the ISO 3166 alpha-2 codes.)
-
- 5. There MUST be at most one region subtag in a language tag and the
- region subtag MAY be omitted, as when it adds no distinguishing
- value to the tag.
-
- 6. The region subtags 'AA', 'QM'-'QZ', 'XA'-'XZ', and 'ZZ' are
- reserved for private use in language tags. These subtags
- correspond to codes reserved by ISO 3166 for private use. These
- codes MAY be used for private use region subtags (instead of
- using a private use subtag sequence). Please refer to
- Section 4.5 for more information on private use subtags.
-
- "de-CH" represents German ('de') as used in Switzerland ('CH').
-
- "sr-Latn-CS" represents Serbian ('sr') written using Latin script
- ('Latn') as used in Serbia and Montenegro ('CS').
-
- "es-419" represents Spanish ('es') appropriate to the UN-defined
- Latin America and Caribbean region ('419').
-
-2.2.5. Variant Subtags
-
- Variant subtags are used to indicate additional, well-recognized
- variations that define a language or its dialects that are not
- covered by other available subtags. The following rules apply to the
- variant subtags:
-
- 1. Variant subtags are not associated with any external standard.
- Variant subtags and their meanings are defined by the
- registration process defined in Section 3.5.
-
- 2. Variant subtags MUST follow all of the other defined subtags, but
- precede any extension or private use subtag sequences.
-
-
-
-Phillips & Davis Best Current Practice [Page 13]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- 3. More than one variant MAY be used to form the language tag.
-
- 4. Variant subtags MUST be registered with IANA according to the
- rules in Section 3.5 of this document before being used to form
- language tags. In order to distinguish variants from other types
- of subtags, registrations MUST meet the following length and
- content restrictions:
-
- 1. Variant subtags that begin with a letter (a-z, A-Z) MUST be
- at least five characters long.
-
- 2. Variant subtags that begin with a digit (0-9) MUST be at
- least four characters long.
-
- Variant subtag records in the language subtag registry MAY include
- one or more 'Prefix' fields, which indicate the language tag or tags
- that would make a suitable prefix (with other subtags, as
- appropriate) in forming a language tag with the variant. For
- example, the subtag 'nedis' has a Prefix of "sl", making it suitable
- to form language tags such as "sl-nedis" and "sl-IT-nedis", but not
- suitable for use in a tag such as "zh-nedis" or "it-IT-nedis".
-
- "sl-nedis" represents the Natisone or Nadiza dialect of Slovenian.
-
- "de-CH-1996" represents German as used in Switzerland and as written
- using the spelling reform beginning in the year 1996 C.E.
-
- Most variants that share a prefix are mutually exclusive. For
- example, the German orthographic variations '1996' and '1901' SHOULD
- NOT be used in the same tag, as they represent the dates of different
- spelling reforms. A variant that can meaningfully be used in
- combination with another variant SHOULD include a 'Prefix' field in
- its registry record that lists that other variant. For example, if
- another German variant 'example' were created that made sense to use
- with '1996', then 'example' should include two Prefix fields: "de"
- and "de-1996".
-
-2.2.6. Extension Subtags
-
- Extensions provide a mechanism for extending language tags for use in
- various applications. See Section 3.7. The following rules apply to
- extensions:
-
- 1. Extension subtags are separated from the other subtags defined
- in this document by a single-character subtag ("singleton").
- The singleton MUST be one allocated to a registration authority
- via the mechanism described in Section 3.7 and MUST NOT be the
- letter 'x', which is reserved for private use subtag sequences.
-
-
-
-Phillips & Davis Best Current Practice [Page 14]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- 2. Note: Private use subtag sequences starting with the singleton
- subtag 'x' are described in Section 2.2.7 below.
-
- 3. An extension MUST follow at least a primary language subtag.
- That is, a language tag cannot begin with an extension.
- Extensions extend language tags, they do not override or replace
- them. For example, "a-value" is not a well-formed language tag,
- while "de-a-value" is.
-
- 4. Each singleton subtag MUST appear at most one time in each tag
- (other than as a private use subtag). That is, singleton
- subtags MUST NOT be repeated. For example, the tag
- "en-a-bbb-a-ccc" is invalid because the subtag 'a' appears
- twice. Note that the tag "en-a-bbb-x-a-ccc" is valid because
- the second appearance of the singleton 'a' is in a private use
- sequence.
-
- 5. Extension subtags MUST meet all of the requirements for the
- content and format of subtags defined in this document.
-
- 6. Extension subtags MUST meet whatever requirements are set by the
- document that defines their singleton prefix and whatever
- requirements are provided by the maintaining authority.
-
- 7. Each extension subtag MUST be from two to eight characters long
- and consist solely of letters or digits, with each subtag
- separated by a single '-'.
-
- 8. Each singleton MUST be followed by at least one extension
- subtag. For example, the tag "tlh-a-b-foo" is invalid because
- the first singleton 'a' is followed immediately by another
- singleton 'b'.
-
- 9. Extension subtags MUST follow all language, extended language,
- script, region, and variant subtags in a tag.
-
- 10. All subtags following the singleton and before another singleton
- are part of the extension. Example: In the tag "fr-a-Latn", the
- subtag 'Latn' does not represent the script subtag 'Latn'
- defined in the IANA Language Subtag Registry. Its meaning is
- defined by the extension 'a'.
-
- 11. In the event that more than one extension appears in a single
- tag, the tag SHOULD be canonicalized as described in
- Section 4.4.
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 15]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- For example, if the prefix singleton 'r' and the shown subtags were
- defined, then the following tag would be a valid example:
- "en-Latn-GB-boont-r-extended-sequence-x-private".
-
-2.2.7. Private Use Subtags
-
- Private use subtags are used to indicate distinctions in language
- important in a given context by private agreement. The following
- rules apply to private use subtags:
-
- 1. Private use subtags are separated from the other subtags defined
- in this document by the reserved single-character subtag 'x'.
-
- 2. Private use subtags MUST conform to the format and content
- constraints defined in the ABNF for all subtags.
-
- 3. Private use subtags MUST follow all language, extended language,
- script, region, variant, and extension subtags in the tag.
- Another way of saying this is that all subtags following the
- singleton 'x' MUST be considered private use. Example: The
- subtag 'US' in the tag "en-x-US" is a private use subtag.
-
- 4. A tag MAY consist entirely of private use subtags.
-
- 5. No source is defined for private use subtags. Use of private use
- subtags is by private agreement only.
-
- 6. Private use subtags are NOT RECOMMENDED where alternatives exist
- or for general interchange. See Section 4.5 for more information
- on private use subtag choice.
-
- For example: Users who wished to utilize codes from the Ethnologue
- publication of SIL International for language identification might
- agree to exchange tags such as "az-Arab-x-AZE-derbend". This example
- contains two private use subtags. The first is 'AZE' and the second
- is 'derbend'.
-
-2.2.8. Preexisting RFC 3066 Registrations
-
- Existing IANA-registered language tags from RFC 1766 and/or RFC 3066
- maintain their validity. These tags will be maintained in the
- registry in records of either the "grandfathered" or "redundant"
- type. Grandfathered tags contain one or more subtags that are not
- defined in the Language Subtag Registry (see Section 3). Redundant
- tags consist entirely of subtags defined above and whose independent
- registration is superseded by this document. For more information,
- see Section 3.8.
-
-
-
-
-Phillips & Davis Best Current Practice [Page 16]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- It is important to note that all language tags formed under the
- guidelines in this document were either legal, well-formed tags or
- could have been registered under RFC 3066.
-
-2.2.9. Classes of Conformance
-
- Implementations sometimes need to describe their capabilities with
- regard to the rules and practices described in this document. There
- are two classes of conforming implementations described by this
- document: "well-formed" processors and "validating" processors.
- Claims of conformance SHOULD explicitly reference one of these
- definitions.
-
- An implementation that claims to check for well-formed language tags
- MUST:
-
- o Check that the tag and all of its subtags, including extension and
- private use subtags, conform to the ABNF or that the tag is on the
- list of grandfathered tags.
-
- o Check that singleton subtags that identify extensions do not
- repeat. For example, the tag "en-a-xx-b-yy-a-zz" is not well-
- formed.
-
- Well-formed processors are strongly encouraged to implement the
- canonicalization rules contained in Section 4.4.
-
- An implementation that claims to be validating MUST:
-
- o Check that the tag is well-formed.
-
- o Specify the particular registry date for which the implementation
- performs validation of subtags.
-
- o Check that either the tag is a grandfathered tag, or that all
- language, script, region, and variant subtags consist of valid
- codes for use in language tags according to the IANA registry as
- of the particular date specified by the implementation.
-
- o Specify which, if any, extension RFCs as defined in Section 3.7
- are supported, including version, revision, and date.
-
- o For any such extensions supported, check that all subtags used in
- that extension are valid.
-
- o For variant and extended language subtags, if the registry
- contains one or more 'Prefix' fields for that subtag, check that
- the tag matches at least one prefix. The tag matches if all the
-
-
-
-Phillips & Davis Best Current Practice [Page 17]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- subtags in the 'Prefix' also appear in the tag. For example, the
- prefix "es-CO" matches the tag "es-Latn-CO-x-private" because both
- the 'es' language subtag and 'CO' region subtag appear in the tag.
-
-3. Registry Format and Maintenance
-
- This section defines the Language Subtag Registry and the maintenance
- and update procedures associated with it, as well as a registry for
- extensions to language tags (Section 3.7).
-
- The Language Subtag Registry contains a comprehensive list of all of
- the subtags valid in language tags. This allows implementers a
- straightforward and reliable way to validate language tags. The
- Language Subtag Registry will be maintained so that, except for
- extension subtags, it is possible to validate all of the subtags that
- appear in a language tag under the provisions of this document or its
- revisions or successors. In addition, the meaning of the various
- subtags will be unambiguous and stable over time. (The meaning of
- private use subtags, of course, is not defined by the IANA registry.)
-
-3.1. Format of the IANA Language Subtag Registry
-
- The IANA Language Subtag Registry ("the registry") consists of a text
- file that is machine readable in the format described in this
- section, plus copies of the registration forms approved in accordance
- with the process described in Section 3.5. The existing registration
- forms for grandfathered and redundant tags taken from RFC 3066 will
- be maintained as part of the obsolete RFC 3066 registry. The
- remaining set of initial subtags will not have registration forms
- created for them.
-
- The registry is in the text format described below. This format was
- based on the record-jar format described in [record-jar].
-
- Each line of text is limited to 72 characters, including all
- whitespace. Records are separated by lines containing only the
- sequence "%%" (%x25.25).
-
- Each field can be viewed as a single, logical line of ASCII
- characters, comprising a field-name and a field-body separated by a
- COLON character (%x3A). For convenience, the field-body portion of
- this conceptual entity can be split into a multiple-line
- representation; this is called "folding". The format of the registry
- is described by the following ABNF (per [RFC4234]):
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 18]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- registry = record *("%%" CRLF record)
- record = 1*( field-name *SP ":" *SP field-body CRLF )
- field-name = (ALPHA / DIGIT) [*(ALPHA / DIGIT / "-") (ALPHA / DIGIT)]
- field-body = *(ASCCHAR/LWSP)
- ASCCHAR = %x21-25 / %x27-7E / UNICHAR ; Note: AMPERSAND is %x26
- UNICHAR = "&#x" 2*6HEXDIG ";"
-
- Figure 2: Registry Format ABNF
-
- The sequence '..' (%x2E.2E) in a field-body denotes a range of
- values. Such a range represents all subtags of the same length that
- are in alphabetic or numeric order within that range, including the
- values explicitly mentioned. For example 'a..c' denotes the values
- 'a', 'b', and 'c' and '11..13' denotes the values '11', '12', and
- '13'.
-
- Characters from outside the US-ASCII [ISO646] repertoire, as well as
- the AMPERSAND character ("&", %x26) when it occurs in a field-body,
- are represented by a "Numeric Character Reference" using hexadecimal
- notation in the style used by [XML10] (see
- <http://www.w3.org/TR/REC-xml/#dt-charref>). This consists of the
- sequence "&#x" (%x26.23.78) followed by a hexadecimal representation
- of the character's code point in [ISO10646] followed by a closing
- semicolon (%x3B). For example, the EURO SIGN, U+20AC, would be
- represented by the sequence "€". Note that the hexadecimal
- notation MAY have between two and six digits.
-
- All fields whose field-body contains a date value use the "full-date"
- format specified in [RFC3339]. For example: "2004-06-28" represents
- June 28, 2004, in the Gregorian calendar.
-
- The first record in the file contains the single field whose field-
- name is "File-Date" (see Figure 3). The field-body of this record
- contains the last modification date of this copy of the registry,
- making it possible to compare different versions of the registry.
- The registry on the IANA website is the most current. Versions with
- an older date than that one are not up-to-date.
-
- File-Date: 2004-06-28
- %%
-
- Figure 3: Example of the File-Date Record
-
- Subsequent records represent subtags in the registry. Each of the
- fields in each record MUST occur no more than once, unless otherwise
- noted below. Each record MUST contain the following fields:
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 19]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- o 'Type'
-
- * Type's field-value MUST consist of one of the following
- strings: "language", "extlang", "script", "region", "variant",
- "grandfathered", and "redundant" and denotes the type of tag or
- subtag.
-
- o Either 'Subtag' or 'Tag'
-
- * Subtag's field-value contains the subtag being defined. This
- field MUST only appear in records of whose 'Type' has one of
- these values: "language", "extlang", "script", "region", or
- "variant".
-
- * Tag's field-value contains a complete language tag. This field
- MUST only appear in records whose 'Type' has one of these
- values: "grandfathered" or "redundant". Note that the field-
- value will always follow the 'grandfathered' production in the
- ABNF in Section 2.1
-
- o Description
-
- * Description's field-value contains a non-normative description
- of the subtag or tag.
-
- o Added
-
- * Added's field-value contains the date the record was added to
- the registry.
-
- The 'Subtag' or 'Tag' field MUST use lowercase letters to form the
- subtag or tag, with two exceptions. Subtags whose 'Type' field is
- 'script' (in other words, subtags defined by ISO 15924) MUST use
- titlecase. Subtags whose 'Type' field is 'region' (in other words,
- subtags defined by ISO 3166) MUST use uppercase. These exceptions
- mirror the use of case in the underlying standards.
-
- The field 'Description' MAY appear more than one time and contains a
- description of the tag or subtag in the record. At least one of the
- 'Description' fields MUST be written or transcribed into the Latin
- script; the same or additional fields MAY also include a description
- in a non-Latin script. The 'Description' field is used for
- identification purposes and SHOULD NOT be taken to represent the
- actual native name of the language or variation or to be in any
- particular language. Most descriptions are taken directly from
- source standards such as ISO 639 or ISO 3166.
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 20]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- Note: Descriptions in registry entries that correspond to ISO 639,
- ISO 15924, ISO 3166, or UN M.49 codes are intended only to indicate
- the meaning of that identifier as defined in the source standard at
- the time it was added to the registry. The description does not
- replace the content of the source standard itself. The descriptions
- are not intended to be the English localized names for the subtags.
- Localization or translation of language tag and subtag descriptions
- is out of scope of this document.
-
- Each record MAY also contain the following fields:
-
- o Preferred-Value
-
- * For fields of type 'language', 'extlang', 'script', 'region',
- and 'variant', 'Preferred-Value' contains the subtag of the
- same 'Type' that is preferred for forming the language tag.
-
- * For fields of type 'grandfathered' and 'redundant', a canonical
- mapping to a complete language tag.
-
- o Deprecated
-
- * Deprecated's field-value contains the date the record was
- deprecated.
-
- o Prefix
-
- * Prefix's field-value contains a language tag with which this
- subtag MAY be used to form a new language tag, perhaps with
- other subtags as well. This field MUST only appear in records
- whose 'Type' field-value is 'variant' or 'extlang'. For
- example, the 'Prefix' for the variant 'nedis' is 'sl', meaning
- that the tags "sl-nedis" and "sl-IT-nedis" might be appropriate
- while the tag "is-nedis" is not.
-
- o Comments
-
- * Comments contains additional information about the subtag, as
- deemed appropriate for understanding the registry and
- implementing language tags using the subtag or tag.
-
- o Suppress-Script
-
- * Suppress-Script contains a script subtag that SHOULD NOT be
- used to form language tags with the associated primary language
- subtag. This field MUST only appear in records whose 'Type'
- field-value is 'language'. See Section 4.1.
-
-
-
-
-Phillips & Davis Best Current Practice [Page 21]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- The field 'Deprecated' MAY be added to any record via the maintenance
- process described in Section 3.3 or via the registration process
- described in Section 3.5. Usually, the addition of a 'Deprecated'
- field is due to the action of one of the standards bodies, such as
- ISO 3166, withdrawing a code. In some historical cases, it might not
- have been possible to reconstruct the original deprecation date. For
- these cases, an approximate date appears in the registry. Although
- valid in language tags, subtags and tags with a 'Deprecated' field
- are deprecated and validating processors SHOULD NOT generate these
- subtags. Note that a record that contains a 'Deprecated' field and
- no corresponding 'Preferred-Value' field has no replacement mapping.
-
- The field 'Preferred-Value' contains a mapping between the record in
- which it appears and another tag or subtag. The value in this field
- is STRONGLY RECOMMENDED as the best choice to represent the value of
- this record when selecting a language tag. These values form three
- groups:
-
- 1. ISO 639 language codes that were later withdrawn in favor of
- other codes. These values are mostly a historical curiosity.
-
- 2. ISO 3166 region codes that have been withdrawn in favor of a new
- code. This sometimes happens when a country changes its name or
- administration in such a way that warrants a new region code.
-
- 3. Tags grandfathered from RFC 3066. In many cases, these tags have
- become obsolete because the values they represent were later
- encoded by ISO 639.
-
- Records that contain a 'Preferred-Value' field MUST also have a
- 'Deprecated' field. This field contains a date of deprecation.
- Thus, a language tag processor can use the registry to construct the
- valid, non-deprecated set of subtags for a given date. In addition,
- for any given tag, a processor can construct the set of valid
- language tags that correspond to that tag for all dates up to the
- date of the registry. The ability to do these mappings MAY be
- beneficial to applications that are matching, selecting, for
- filtering content based on its language tags.
-
- Note that 'Preferred-Value' mappings in records of type 'region'
- sometimes do not represent exactly the same meaning as the original
- value. There are many reasons for a country code to be changed, and
- the effect this has on the formation of language tags will depend on
- the nature of the change in question.
-
- In particular, the 'Preferred-Value' field does not imply retagging
- content that uses the affected subtag.
-
-
-
-
-Phillips & Davis Best Current Practice [Page 22]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- The field 'Preferred-Value' MUST NOT be modified once created in the
- registry. The field MAY be added to records of type "grandfathered"
- and "region" according to the rules in Section 3.3. Otherwise the
- field MUST NOT be added to any record already in the registry.
-
- The 'Preferred-Value' field in records of type "grandfathered" and
- "redundant" contains whole language tags that are strongly
- RECOMMENDED for use in place of the record's value. In many cases,
- the mappings were created by deprecation of the tags during the
- period before this document was adopted. For example, the tag
- "no-nyn" was deprecated in favor of the ISO 639-1-defined language
- code 'nn'.
-
- Records of type 'variant' MAY have more than one field of type
- 'Prefix'. Additional fields of this type MAY be added to a 'variant'
- record via the registration process.
-
- Records of type 'extlang' MUST have _exactly_ one 'Prefix' field.
-
- The field-value of the 'Prefix' field consists of a language tag
- whose subtags are appropriate to use with this subtag. For example,
- the variant subtag '1996' has a 'Prefix' field of "de". This means
- that tags starting with the sequence "de-" are appropriate with this
- subtag, so "de-Latg-1996" and "de-CH-1996" are both acceptable, while
- the tag "fr-1996" is an inappropriate choice.
-
- The field of type 'Prefix' MUST NOT be removed from any record. The
- field-value for this type of field MUST NOT be modified.
-
- The field 'Comments' MAY appear more than once per record. This
- field MAY be inserted or changed via the registration process and no
- guarantee of stability is provided. The content of this field is not
- restricted, except by the need to register the information, the
- suitability of the request, and by reasonable practical size
- limitations.
-
- The field 'Suppress-Script' MUST only appear in records whose 'Type'
- field-value is 'language'. This field MUST NOT appear more than one
- time in a record. This field indicates a script used to write the
- overwhelming majority of documents for the given language and that
- therefore adds no distinguishing information to a language tag. It
- helps ensure greater compatibility between the language tags
- generated according to the rules in this document and language tags
- and tag processors or consumers based on RFC 3066. For example,
- virtually all Icelandic documents are written in the Latin script,
- making the subtag 'Latn' redundant in the tag "is-Latn".
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 23]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
-3.2. Language Subtag Reviewer
-
- The Language Subtag Reviewer is appointed by the IESG for an
- indefinite term, subject to removal or replacement at the IESG's
- discretion. The Language Subtag Reviewer moderates the ietf-
- languages mailing list, responds to requests for registration, and
- performs the other registry maintenance duties described in
- Section 3.3. Only the Language Subtag Reviewer is permitted to
- request IANA to change, update, or add records to the Language Subtag
- Registry.
-
- The performance or decisions of the Language Subtag Reviewer MAY be
- appealed to the IESG under the same rules as other IETF decisions
- (see [RFC2026]). The IESG can reverse or overturn the decision of
- the Language Subtag Reviewer, provide guidance, or take other
- appropriate actions.
-
-3.3. Maintenance of the Registry
-
- Maintenance of the registry requires that as codes are assigned or
- withdrawn by ISO 639, ISO 15924, ISO 3166, and UN M.49, the Language
- Subtag Reviewer MUST evaluate each change, determine whether it
- conflicts with existing registry entries, and submit the information
- to IANA for inclusion in the registry. If a change takes place and
- the Language Subtag Reviewer does not do this in a timely manner,
- then any interested party MAY use the procedure in Section 3.5 to
- register the appropriate update.
-
- Note: The redundant and grandfathered entries together are the
- complete list of tags registered under [RFC3066]. The redundant tags
- are those that can now be formed using the subtags defined in the
- registry together with the rules of Section 2.2. The grandfathered
- entries include those that can never be legal under those same
- provisions.
-
- The set of redundant and grandfathered tags is permanent and stable:
- new entries in this section MUST NOT be added and existing entries
- MUST NOT be removed. Records of type 'grandfathered' MAY have their
- type converted to 'redundant'; see item 12 in Section 3.6 for more
- information. The decision-making process about which tags were
- initially grandfathered and which were made redundant is described in
- [RFC4645].
-
- RFC 3066 tags that were deprecated prior to the adoption of this
- document are part of the list of grandfathered tags, and their
- component subtags were not included as registered variants (although
- they remain eligible for registration). For example, the tag
- "art-lojban" was deprecated in favor of the language subtag 'jbo'.
-
-
-
-Phillips & Davis Best Current Practice [Page 24]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- The Language Subtag Reviewer MUST ensure that new subtags meet the
- requirements in Section 4.1 or submit an appropriate alternate subtag
- as described in that section. When either a change or addition to
- the registry is needed, the Language Subtag Reviewer MUST prepare the
- complete record, including all fields, and forward it to IANA for
- insertion into the registry. Each record being modified or inserted
- MUST be forwarded in a separate message.
-
- If a record represents a new subtag that does not currently exist in
- the registry, then the message's subject line MUST include the word
- "INSERT". If the record represents a change to an existing subtag,
- then the subject line of the message MUST include the word "MODIFY".
- The message MUST contain both the record for the subtag being
- inserted or modified and the new File-Date record. Here is an
- example of what the body of the message might contain:
-
- LANGUAGE SUBTAG MODIFICATION
- File-Date: 2005-01-02
- %%
- Type: variant
- Subtag: nedis
- Description: Natisone dialect
- Description: Nadiza dialect
- Added: 2003-10-09
- Prefix: sl
- Comments: This is a comment shown
- as an example.
- %%
-
- Figure 4: Example of a Language Subtag Modification Form
-
- Whenever an entry is created or modified in the registry, the
- 'File-Date' record at the start of the registry is updated to reflect
- the most recent modification date in the [RFC3339] "full-date"
- format.
-
- Before forwarding a new registration to IANA, the Language Subtag
- Reviewer MUST ensure that values in the 'Subtag' field match case
- according to the description in Section 3.1.
-
-3.4. Stability of IANA Registry Entries
-
- The stability of entries and their meaning in the registry is
- critical to the long-term stability of language tags. The rules in
- this section guarantee that a specific language tag's meaning is
- stable over time and will not change.
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 25]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- These rules specifically deal with how changes to codes (including
- withdrawal and deprecation of codes) maintained by ISO 639, ISO
- 15924, ISO 3166, and UN M.49 are reflected in the IANA Language
- Subtag Registry. Assignments to the IANA Language Subtag Registry
- MUST follow the following stability rules:
-
- 1. Values in the fields 'Type', 'Subtag', 'Tag', 'Added',
- 'Deprecated' and 'Preferred-Value' MUST NOT be changed and are
- guaranteed to be stable over time.
-
- 2. Values in the 'Description' field MUST NOT be changed in a way
- that would invalidate previously-existing tags. They MAY be
- broadened somewhat in scope, changed to add information, or
- adapted to the most common modern usage. For example, countries
- occasionally change their official names; a historical example
- of this would be "Upper Volta" changing to "Burkina Faso".
-
- 3. Values in the field 'Prefix' MAY be added to records of type
- 'variant' via the registration process.
-
- 4. Values in the field 'Prefix' MAY be modified, so long as the
- modifications broaden the set of prefixes. That is, a prefix
- MAY be replaced by one of its own prefixes. For example, the
- prefix "en-US" could be replaced by "en", but not by the
- prefixes "en-Latn", "fr", or "en-US-boont". If one of those
- prefixes were needed, a new Prefix SHOULD be registered.
-
- 5. Values in the field 'Prefix' MUST NOT be removed.
-
- 6. The field 'Comments' MAY be added, changed, modified, or removed
- via the registration process or any of the processes or
- considerations described in this section.
-
- 7. The field 'Suppress-Script' MAY be added or removed via the
- registration process.
-
- 8. Codes assigned by ISO 639, ISO 15924, and ISO 3166 that do not
- conflict with existing subtags of the associated type and whose
- meaning is not the same as an existing subtag of the same type
- are entered into the IANA registry as new records.
-
- 9. Codes assigned by ISO 639, ISO 15924, or ISO 3166 that are
- withdrawn by their respective maintenance or registration
- authority remain valid in language tags. A 'Deprecated' field
- containing the date of withdrawal is added to the record. If a
- new record of the same type is added that represents a
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 26]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- replacement value, then a 'Preferred-Value' field MAY also be
- added. The registration process MAY be used to add comments
- about the withdrawal of the code by the respective standard.
-
- Example
- The region code 'TL' was assigned to the country 'Timor-
- Leste', replacing the code 'TP' (which was assigned to 'East
- Timor' when it was under administration by Portugal). The
- subtag 'TP' remains valid in language tags, but its record
- contains the a 'Preferred-Value' of 'TL' and its field
- 'Deprecated' contains the date the new code was assigned
- ('2004-07-06').
-
- 10. Codes assigned by ISO 639, ISO 15924, or ISO 3166 that conflict
- with existing subtags of the associated type, including subtags
- that are deprecated, MUST NOT be entered into the registry. The
- following additional considerations apply to subtag values that
- are reassigned:
-
- A. For ISO 639 codes, if the newly assigned code's meaning is
- not represented by a subtag in the IANA registry, the
- Language Subtag Reviewer, as described in Section 3.5, SHALL
- prepare a proposal for entering in the IANA registry as soon
- as practical a registered language subtag as an alternate
- value for the new code. The form of the registered language
- subtag will be at the discretion of the Language Subtag
- Reviewer and MUST conform to other restrictions on language
- subtags in this document.
-
- B. For all subtags whose meaning is derived from an external
- standard (i.e., ISO 639, ISO 15924, ISO 3166, or UN M.49),
- if a new meaning is assigned to an existing code and the new
- meaning broadens the meaning of that code, then the meaning
- for the associated subtag MAY be changed to match. The
- meaning of a subtag MUST NOT be narrowed, however, as this
- can result in an unknown proportion of the existing uses of
- a subtag becoming invalid. Note: ISO 639 maintenance
- agency/registration authority (MA/RA) has adopted a similar
- stability policy.
-
- C. For ISO 15924 codes, if the newly assigned code's meaning is
- not represented by a subtag in the IANA registry, the
- Language Subtag Reviewer, as described in Section 3.5, SHALL
- prepare a proposal for entering in the IANA registry as soon
- as practical a registered variant subtag as an alternate
- value for the new code. The form of the registered variant
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 27]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- subtag will be at the discretion of the Language Subtag
- Reviewer and MUST conform to other restrictions on variant
- subtags in this document.
-
- D. For ISO 3166 codes, if the newly assigned code's meaning is
- associated with the same UN M.49 code as another 'region'
- subtag, then the existing region subtag remains as the
- preferred value for that region and no new entry is created.
- A comment MAY be added to the existing region subtag
- indicating the relationship to the new ISO 3166 code.
-
- E. For ISO 3166 codes, if the newly assigned code's meaning is
- associated with a UN M.49 code that is not represented by an
- existing region subtag, then the Language Subtag Reviewer,
- as described in Section 3.5, SHALL prepare a proposal for
- entering the appropriate UN M.49 country code as an entry in
- the IANA registry.
-
- F. For ISO 3166 codes, if there is no associated UN numeric
- code, then the Language Subtag Reviewer SHALL petition the
- UN to create one. If there is no response from the UN
- within ninety days of the request being sent, the Language
- Subtag Reviewer SHALL prepare a proposal for entering in the
- IANA registry as soon as practical a registered variant
- subtag as an alternate value for the new code. The form of
- the registered variant subtag will be at the discretion of
- the Language Subtag Reviewer and MUST conform to other
- restrictions on variant subtags in this document. This
- situation is very unlikely to ever occur.
-
- 11. UN M.49 has codes for both countries and areas (such as '276'
- for Germany) and geographical regions and sub-regions (such as
- '150' for Europe). UN M.49 country or area codes for which
- there is no corresponding ISO 3166 code SHOULD NOT be
- registered, except as a surrogate for an ISO 3166 code that is
- blocked from registration by an existing subtag. If such a code
- becomes necessary, then the registration authority for ISO 3166
- SHOULD first be petitioned to assign a code to the region. If
- the petition for a code assignment by ISO 3166 is refused or not
- acted on in a timely manner, the registration process described
- in Section 3.5 MAY then be used to register the corresponding UN
- M.49 code. At the time this document was written, there were
- only four such codes: 830 (Channel Islands), 831 (Guernsey), 832
- (Jersey), and 833 (Isle of Man). This way, UN M.49 codes remain
- available as the value of last resort in cases where ISO 3166
- reassigns a deprecated value in the registry.
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 28]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- 12. Stability provisions apply to grandfathered tags with this
- exception: should all of the subtags in a grandfathered tag
- become valid subtags in the IANA registry, then the field 'Type'
- in that record is changed from 'grandfathered' to 'redundant'.
- Note that this will not affect language tags that match the
- grandfathered tag, since these tags will now match valid
- generative subtag sequences. For example, if the subtag 'gan'
- in the language tag "zh-gan" were to be registered as an
- extended language subtag, then the grandfathered tag "zh-gan"
- would be deprecated (but existing content or implementations
- that use "zh-gan" would remain valid).
-
-3.5. Registration Procedure for Subtags
-
- The procedure given here MUST be used by anyone who wants to use a
- subtag not currently in the IANA Language Subtag Registry.
-
- Only subtags of type 'language' and 'variant' will be considered for
- independent registration of new subtags. Handling of subtags needed
- for stability and subtags necessary to keep the registry synchronized
- with ISO 639, ISO 15924, ISO 3166, and UN M.49 within the limits
- defined by this document are described in Section 3.3. Stability
- provisions are described in Section 3.4.
-
- This procedure MAY also be used to register or alter the information
- for the 'Description', 'Comments', 'Deprecated', or 'Prefix' fields
- in a subtag's record as described in Section 3.4. Changes to all
- other fields in the IANA registry are NOT permitted.
-
- Registering a new subtag or requesting modifications to an existing
- tag or subtag starts with the requester filling out the registration
- form reproduced below. Note that each response is not limited in
- size so that the request can adequately describe the registration.
- The fields in the "Record Requested" section SHOULD follow the
- requirements in Section 3.1.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 29]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- LANGUAGE SUBTAG REGISTRATION FORM
- 1. Name of requester:
- 2. E-mail address of requester:
- 3. Record Requested:
-
- Type:
- Subtag:
- Description:
- Prefix:
- Preferred-Value:
- Deprecated:
- Suppress-Script:
- Comments:
-
- 4. Intended meaning of the subtag:
- 5. Reference to published description
- of the language (book or article):
- 6. Any other relevant information:
-
- Figure 5: The Language Subtag Registration Form
-
- The subtag registration form MUST be sent to
- <ietf-languages@iana.org> for a two-week review period before it can
- be submitted to IANA. (This is an open list and can be joined by
- sending a request to <ietf-languages-request@iana.org>.)
-
- Variant subtags are usually registered for use with a particular
- range of language tags. For example, the subtag 'rozaj' is intended
- for use with language tags that start with the primary language
- subtag "sl", since Resian is a dialect of Slovenian. Thus, the
- subtag 'rozaj' would be appropriate in tags such as "sl-Latn-rozaj"
- or "sl-IT-rozaj". This information is stored in the 'Prefix' field
- in the registry. Variant registration requests SHOULD include at
- least one 'Prefix' field in the registration form.
-
- Extended language subtags are reserved for future standardization.
- These subtags will be REQUIRED to include exactly one 'Prefix' field
- once they are allowed for registration.
-
- The 'Prefix' field for a given registered subtag exists in the IANA
- registry as a guide to usage. Additional prefixes MAY be added by
- filing an additional registration form. In that form, the "Any other
- relevant information:" field MUST indicate that it is the addition of
- a prefix.
-
- Requests to add a prefix to a variant subtag that imply a different
- semantic meaning will probably be rejected. For example, a request
- to add the prefix "de" to the subtag 'nedis' so that the tag
-
-
-
-Phillips & Davis Best Current Practice [Page 30]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- "de-nedis" represented some German dialect would be rejected. The
- 'nedis' subtag represents a particular Slovenian dialect and the
- additional registration would change the semantic meaning assigned to
- the subtag. A separate subtag SHOULD be proposed instead.
-
- The 'Description' field MUST contain a description of the tag being
- registered written or transcribed into the Latin script; it MAY also
- include a description in a non-Latin script. Non-ASCII characters
- MUST be escaped using the syntax described in Section 3.1. The
- 'Description' field is used for identification purposes and doesn't
- necessarily represent the actual native name of the language or
- variation or to be in any particular language.
-
- While the 'Description' field itself is not guaranteed to be stable
- and errata corrections MAY be undertaken from time to time, attempts
- to provide translations or transcriptions of entries in the registry
- itself will probably be frowned upon by the community or rejected
- outright, as changes of this nature have an impact on the provisions
- in Section 3.4.
-
- When the two-week period has passed, the Language Subtag Reviewer
- either forwards the record to be inserted or modified to
- iana@iana.org according to the procedure described in Section 3.3, or
- rejects the request because of significant objections raised on the
- list or due to problems with constraints in this document (which MUST
- be explicitly cited). The Language Subtag Reviewer MAY also extend
- the review period in two-week increments to permit further
- discussion. The Language Subtag Reviewer MUST indicate on the list
- whether the registration has been accepted, rejected, or extended
- following each two-week period.
-
- Note that the Language Subtag Reviewer MAY raise objections on the
- list if he or she so desires. The important thing is that the
- objection MUST be made publicly.
-
- The applicant is free to modify a rejected application with
- additional information and submit it again; this restarts the two-
- week comment period.
-
- Decisions made by the Language Subtag Reviewer MAY be appealed to the
- IESG [RFC2028] under the same rules as other IETF decisions
- [RFC2026].
-
- All approved registration forms are available online in the directory
- http://www.iana.org/numbers.html under "languages".
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 31]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- Updates or changes to existing records follow the same procedure as
- new registrations. The Language Subtag Reviewer decides whether
- there is consensus to update the registration following the two-week
- review period; normally, objections by the original registrant will
- carry extra weight in forming such a consensus.
-
- Registrations are permanent and stable. Once registered, subtags
- will not be removed from the registry and will remain a valid way in
- which to specify a specific language or variant.
-
- Note: The purpose of the "Description" in the registration form is to
- aid people trying to verify whether a language is registered or what
- language or language variation a particular subtag refers to. In
- most cases, reference to an authoritative grammar or dictionary of
- that language will be useful; in cases where no such work exists,
- other well-known works describing that language or in that language
- MAY be appropriate. The Language Subtag Reviewer decides what
- constitutes "good enough" reference material. This requirement is
- not intended to exclude particular languages or dialects due to the
- size of the speaker population or lack of a standardized orthography.
- Minority languages will be considered equally on their own merits.
-
-3.6. Possibilities for Registration
-
- Possibilities for registration of subtags or information about
- subtags include:
-
- o Primary language subtags for languages not listed in ISO 639 that
- are not variants of any listed or registered language MAY be
- registered. At the time this document was created, there were no
- examples of this form of subtag. Before attempting to register a
- language subtag, there MUST be an attempt to register the language
- with ISO 639. Subtags MUST NOT be registered for codes that exist
- in ISO 639-1 or ISO 639-2, that are under consideration by the ISO
- 639 maintenance or registration authorities, or that have never
- been attempted for registration with those authorities. If ISO
- 639 has previously rejected a language for registration, it is
- reasonable to assume that there must be additional, very
- compelling evidence of need before it will be registered in the
- IANA registry (to the extent that it is very unlikely that any
- subtags will be registered of this type).
-
- o Dialect or other divisions or variations within a language, its
- orthography, writing system, regional or historical usage,
- transliteration or other transformation, or distinguishing
- variation MAY be registered as variant subtags. An example is the
- 'rozaj' subtag (the Resian dialect of Slovenian).
-
-
-
-
-Phillips & Davis Best Current Practice [Page 32]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- o The addition or maintenance of fields (generally of an
- informational nature) in Tag or Subtag records as described in
- Section 3.1 and subject to the stability provisions in
- Section 3.4. This includes descriptions, comments, deprecation
- and preferred values for obsolete or withdrawn codes, or the
- addition of script or extlang information to primary language
- subtags.
-
- o The addition of records and related field value changes necessary
- to reflect assignments made by ISO 639, ISO 15924, ISO 3166, and
- UN M.49 as described in Section 3.4.
-
- Subtags proposed for registration that would cause all or part of a
- grandfathered tag to become redundant but whose meaning conflicts
- with or alters the meaning of the grandfathered tag MUST be rejected.
-
- This document leaves the decision on what subtags or changes to
- subtags are appropriate (or not) to the registration process
- described in Section 3.5.
-
- Note: four-character primary language subtags are reserved to allow
- for the possibility of alpha4 codes in some future addition to the
- ISO 639 family of standards.
-
- ISO 639 defines a maintenance agency for additions to and changes in
- the list of languages in ISO 639. This agency is:
-
- International Information Centre for Terminology (Infoterm)
- Aichholzgasse 6/12, AT-1120
- Wien, Austria
- Phone: +43 1 26 75 35 Ext. 312 Fax: +43 1 216 32 72
-
- ISO 639-2 defines a maintenance agency for additions to and changes
- in the list of languages in ISO 639-2. This agency is:
-
- Library of Congress
- Network Development and MARC Standards Office
- Washington, D.C. 20540 USA
- Phone: +1 202 707 6237 Fax: +1 202 707 0115
- URL: http://www.loc.gov/standards/iso639-2
-
-
-
-
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 33]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- The maintenance agency for ISO 3166 (country codes) is:
-
- ISO 3166 Maintenance Agency
- c/o International Organization for Standardization
- Case postale 56
- CH-1211 Geneva 20 Switzerland
- Phone: +41 22 749 72 33 Fax: +41 22 749 73 49
- URL: http://www.iso.org/iso/en/prods-services/iso3166ma/index.html
-
- The registration authority for ISO 15924 (script codes) is:
-
- Unicode Consortium Box 391476
- Mountain View, CA 94039-1476, USA
- URL: http://www.unicode.org/iso15924
-
- The Statistics Division of the United Nations Secretariat maintains
- the Standard Country or Area Codes for Statistical Use and can be
- reached at:
-
- Statistical Services Branch
- Statistics Division
- United Nations, Room DC2-1620
- New York, NY 10017, USA
-
- Fax: +1-212-963-0623
- E-mail: statistics@un.org
- URL: http://unstats.un.org/unsd/methods/m49/m49alpha.htm
-
-3.7. Extensions and Extensions Registry
-
- Extension subtags are those introduced by single-character subtags
- ("singletons") other than 'x'. They are reserved for the generation
- of identifiers that contain a language component and are compatible
- with applications that understand language tags.
-
- The structure and form of extensions are defined by this document so
- that implementations can be created that are forward compatible with
- applications that might be created using singletons in the future.
- In addition, defining a mechanism for maintaining singletons will
- lend stability to this document by reducing the likely need for
- future revisions or updates.
-
- Single-character subtags are assigned by IANA using the "IETF
- Consensus" policy defined by [RFC2434]. This policy requires the
- development of an RFC, which SHALL define the name, purpose,
- processes, and procedures for maintaining the subtags. The
- maintaining or registering authority, including name, contact email,
-
-
-
-
-Phillips & Davis Best Current Practice [Page 34]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- discussion list email, and URL location of the registry, MUST be
- indicated clearly in the RFC. The RFC MUST specify or include each
- of the following:
-
- o The specification MUST reference the specific version or revision
- of this document that governs its creation and MUST reference this
- section of this document.
-
- o The specification and all subtags defined by the specification
- MUST follow the ABNF and other rules for the formation of tags and
- subtags as defined in this document. In particular, it MUST
- specify that case is not significant and that subtags MUST NOT
- exceed eight characters in length.
-
- o The specification MUST specify a canonical representation.
-
- o The specification of valid subtags MUST be available over the
- Internet and at no cost.
-
- o The specification MUST be in the public domain or available via a
- royalty-free license acceptable to the IETF and specified in the
- RFC.
-
- o The specification MUST be versioned, and each version of the
- specification MUST be numbered, dated, and stable.
-
- o The specification MUST be stable. That is, extension subtags,
- once defined by a specification, MUST NOT be retracted or change
- in meaning in any substantial way.
-
- o The specification MUST include in a separate section the
- registration form reproduced in this section (below) to be used in
- registering the extension upon publication as an RFC.
-
- o IANA MUST be informed of changes to the contact information and
- URL for the specification.
-
- IANA will maintain a registry of allocated single-character
- (singleton) subtags. This registry MUST use the record-jar format
- described by the ABNF in Section 3.1. Upon publication of an
- extension as an RFC, the maintaining authority defined in the RFC
- MUST forward this registration form to iesg@ietf.org, who MUST
- forward the request to iana@iana.org. The maintaining authority of
- the extension MUST maintain the accuracy of the record by sending an
- updated full copy of the record to iana@iana.org with the subject
- line "LANGUAGE TAG EXTENSION UPDATE" whenever content changes. Only
- the 'Comments', 'Contact_Email', 'Mailing_List', and 'URL' fields MAY
- be modified in these updates.
-
-
-
-Phillips & Davis Best Current Practice [Page 35]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- Failure to maintain this record, maintain the corresponding registry,
- or meet other conditions imposed by this section of this document MAY
- be appealed to the IESG [RFC2028] under the same rules as other IETF
- decisions (see [RFC2026]) and MAY result in the authority to maintain
- the extension being withdrawn or reassigned by the IESG.
-
- %%
- Identifier:
- Description:
- Comments:
- Added:
- RFC:
- Authority:
- Contact_Email:
- Mailing_List:
- URL:
- %%
-
- Figure 6: Format of Records in the Language Tag Extensions Registry
-
- 'Identifier' contains the single-character subtag (singleton)
- assigned to the extension. The Internet-Draft submitted to define
- the extension SHOULD specify which letter or digit to use, although
- the IESG MAY change the assignment when approving the RFC.
-
- 'Description' contains the name and description of the extension.
-
- 'Comments' is an OPTIONAL field and MAY contain a broader description
- of the extension.
-
- 'Added' contains the date the RFC was published in the "full-date"
- format specified in [RFC3339]. For example: 2004-06-28 represents
- June 28, 2004, in the Gregorian calendar.
-
- 'RFC' contains the RFC number assigned to the extension.
-
- 'Authority' contains the name of the maintaining authority for the
- extension.
-
- 'Contact_Email' contains the email address used to contact the
- maintaining authority.
-
- 'Mailing_List' contains the URL or subscription email address of the
- mailing list used by the maintaining authority.
-
- 'URL' contains the URL of the registry for this extension.
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 36]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- The determination of whether an Internet-Draft meets the above
- conditions and the decision to grant or withhold such authority rests
- solely with the IESG and is subject to the normal review and appeals
- process associated with the RFC process.
-
- Extension authors are strongly cautioned that many (including most
- well-formed) processors will be unaware of any special relationships
- or meaning inherent in the order of extension subtags. Extension
- authors SHOULD avoid subtag relationships or canonicalization
- mechanisms that interfere with matching or with length restrictions
- that sometimes exist in common protocols where the extension is used.
- In particular, applications MAY truncate the subtags in doing
- matching or in fitting into limited lengths, so it is RECOMMENDED
- that the most significant information be in the most significant
- (left-most) subtags and that the specification gracefully handle
- truncated subtags.
-
- When a language tag is to be used in a specific, known, protocol, it
- is RECOMMENDED that the language tag not contain extensions not
- supported by that protocol. In addition, note that some protocols
- MAY impose upper limits on the length of the strings used to store or
- transport the language tag.
-
-3.8. Initialization of the Registries
-
- Upon adoption of this document, an initial version of the Language
- Subtag Registry containing the various subtags initially valid in a
- language tag is necessary. This collection of subtags, along with a
- description of the process used to create it, is described by
- [RFC4645]. IANA SHALL publish the initial version of the registry
- described by this document from the content of [RFC4645]. Once
- published by IANA, the maintenance procedures, rules, and
- registration processes described in this document will be available
- for new registrations or updates.
-
- Registrations that are in process under the rules defined in
- [RFC3066] when this document is adopted MAY be completed under the
- former rules, at the discretion of the Language Tag Reviewer (as
- described in [RFC3066]). Until the IESG officially appoints a
- Language Subtag Reviewer, the existing Language Tag Reviewer SHALL
- serve as the Language Subtag Reviewer.
-
- Any new registrations submitted using the RFC 3066 forms or format
- after the adoption of this document and publication of the registry
- by IANA MUST be rejected.
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 37]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- An initial version of the Language Tag Extensions Registry described
- in Section 3.7 is also needed. The Language Tag Extensions Registry
- SHALL be initialized with a single record containing a single field
- of type "File-Date" as a placeholder for future assignments.
-
-4. Formation and Processing of Language Tags
-
- This section addresses how to use the information in the registry
- with the tag syntax to choose, form, and process language tags.
-
-4.1. Choice of Language Tag
-
- One is sometimes faced with the choice between several possible tags
- for the same body of text.
-
- Interoperability is best served when all users use the same language
- tag in order to represent the same language. If an application has
- requirements that make the rules here inapplicable, then that
- application risks damaging interoperability. It is strongly
- RECOMMENDED that users not define their own rules for language tag
- choice.
-
- Subtags SHOULD only be used where they add useful distinguishing
- information; extraneous subtags interfere with the meaning,
- understanding, and processing of language tags. In particular, users
- and implementations SHOULD follow the 'Prefix' and 'Suppress-Script'
- fields in the registry (defined in Section 3.1): these fields provide
- guidance on when specific additional subtags SHOULD (and SHOULD NOT)
- be used in a language tag.
-
- Of particular note, many applications can benefit from the use of
- script subtags in language tags, as long as the use is consistent for
- a given context. Script subtags were not formally defined in RFC
- 3066 and their use can affect matching and subtag identification by
- implementations of RFC 3066, as these subtags appear between the
- primary language and region subtags. For example, if a user requests
- content in an implementation of Section 2.5 of [RFC3066] using the
- language range "en-US", content labeled "en-Latn-US" will not match
- the request. Therefore, it is important to know when script subtags
- will customarily be used and when they ought not be used. In the
- registry, the Suppress-Script field helps ensure greater
- compatibility between the language tags generated according to the
- rules in this document and language tags and tag processors or
- consumers based on RFC 3066 by defining when users SHOULD NOT include
- a script subtag with a particular primary language subtag.
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 38]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- Extended language subtags (type 'extlang' in the registry; see
- Section 3.1) also appear between the primary language and region
- subtags and are reserved for future standardization. Applications
- might benefit from their judicious use in forming language tags in
- the future. Similar recommendations are expected to apply to their
- use as apply to script subtags.
-
- Standards, protocols, and applications that reference this document
- normatively but apply different rules to the ones given in this
- section MUST specify how the procedure varies from the one given
- here.
-
- The choice of subtags used to form a language tag SHOULD be guided by
- the following rules:
-
- 1. Use as precise a tag as possible, but no more specific than is
- justified. Avoid using subtags that are not important for
- distinguishing content in an application.
-
- * For example, 'de' might suffice for tagging an email written
- in German, while "de-CH-1996" is probably unnecessarily
- precise for such a task.
-
- 2. The script subtag SHOULD NOT be used to form language tags unless
- the script adds some distinguishing information to the tag. The
- field 'Suppress-Script' in the primary language record in the
- registry indicates which script subtags do not add distinguishing
- information for most applications.
-
- * For example, the subtag 'Latn' should not be used with the
- primary language 'en' because nearly all English documents are
- written in the Latin script and it adds no distinguishing
- information. However, if a document were written in English
- mixing Latin script with another script such as Braille
- ('Brai'), then it might be appropriate to choose to indicate
- both scripts to aid in content selection, such as the
- application of a style sheet.
-
- 3. If a tag or subtag has a 'Preferred-Value' field in its registry
- entry, then the value of that field SHOULD be used to form the
- language tag in preference to the tag or subtag in which the
- preferred value appears.
-
- * For example, use 'he' for Hebrew in preference to 'iw'.
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 39]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- 4. The 'und' (Undetermined) primary language subtag SHOULD NOT be
- used to label content, even if the language is unknown. Omitting
- the language tag altogether is preferred to using a tag with a
- primary language subtag of 'und'. The 'und' subtag MAY be useful
- for protocols that require a language tag to be provided. The
- 'und' subtag MAY also be useful when matching language tags in
- certain situations.
-
- 5. The 'mul' (Multiple) primary language subtag SHOULD NOT be used
- whenever the protocol allows the separate tags for multiple
- languages, as is the case for the Content-Language header in
- HTTP. The 'mul' subtag conveys little useful information:
- content in multiple languages SHOULD individually tag the
- languages where they appear or otherwise indicate the actual
- language in preference to the 'mul' subtag.
-
- 6. The same variant subtag SHOULD NOT be used more than once within
- a language tag.
-
- * For example, do not use "de-DE-1901-1901".
-
- To ensure consistent backward compatibility, this document contains
- several provisions to account for potential instability in the
- standards used to define the subtags that make up language tags.
- These provisions mean that no language tag created under the rules in
- this document will become obsolete.
-
-4.2. Meaning of the Language Tag
-
- The relationship between the tag and the information it relates to is
- defined by the context in which the tag appears. Accordingly, this
- section gives only possible examples of its usage.
-
- o For a single information object, the associated language tags
- might be interpreted as the set of languages that is necessary for
- a complete comprehension of the complete object. Example: Plain
- text documents.
-
- o For an aggregation of information objects, the associated language
- tags could be taken as the set of languages used inside components
- of that aggregation. Examples: Document stores and libraries.
-
- o For information objects whose purpose is to provide alternatives,
- the associated language tags could be regarded as a hint that the
- content is provided in several languages and that one has to
- inspect each of the alternatives in order to find its language or
- languages. In this case, the presence of multiple tags might not
- mean that one needs to be multi-lingual to get complete
-
-
-
-Phillips & Davis Best Current Practice [Page 40]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- understanding of the document. Example: MIME multipart/
- alternative.
-
- o In markup languages, such as HTML and XML, language information
- can be added to each part of the document identified by the markup
- structure (including the whole document itself). For example, one
- could write <span lang="fr">C'est la vie.</span> inside a
- Norwegian document; the Norwegian-speaking user could then access
- a French-Norwegian dictionary to find out what the marked section
- meant. If the user were listening to that document through a
- speech synthesis interface, this formation could be used to signal
- the synthesizer to appropriately apply French text-to-speech
- pronunciation rules to that span of text, instead of applying the
- inappropriate Norwegian rules.
-
- Language tags are related when they contain a similar sequence of
- subtags. For example, if a language tag B contains language tag A as
- a prefix, then B is typically "narrower" or "more specific" than A.
- Thus, "zh-Hant-TW" is more specific than "zh-Hant".
-
- This relationship is not guaranteed in all cases: specifically,
- languages that begin with the same sequence of subtags are NOT
- guaranteed to be mutually intelligible, although they might be. For
- example, the tag "az" shares a prefix with both "az-Latn"
- (Azerbaijani written using the Latin script) and "az-Cyrl"
- (Azerbaijani written using the Cyrillic script). A person fluent in
- one script might not be able to read the other, even though the text
- might be identical. Content tagged as "az" most probably is written
- in just one script and thus might not be intelligible to a reader
- familiar with the other script.
-
-4.3. Length Considerations
-
- [RFC3066] did not provide an upper limit on the size of language
- tags. While RFC 3066 did define the semantics of particular subtags
- in such a way that most language tags consisted of language and
- region subtags with a combined total length of up to six characters,
- larger registered tags were not only possible but were actually
- registered.
-
- Neither the language tag syntax nor other requirements in this
- document impose a fixed upper limit on the number of subtags in a
- language tag (and thus an upper bound on the size of a tag). The
- language tag syntax suggests that, depending on the specific
- language, more subtags (and thus a longer tag) are sometimes
- necessary to completely identify the language for certain
- applications; thus, it is possible to envision long or complex subtag
- sequences.
-
-
-
-Phillips & Davis Best Current Practice [Page 41]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
-4.3.1. Working with Limited Buffer Sizes
-
- Some applications and protocols are forced to allocate fixed buffer
- sizes or otherwise limit the length of a language tag. A conformant
- implementation or specification MAY refuse to support the storage of
- language tags that exceed a specified length. Any such limitation
- SHOULD be clearly documented, and such documentation SHOULD include
- what happens to longer tags (for example, whether an error value is
- generated or the language tag is truncated). A protocol that allows
- tags to be truncated at an arbitrary limit, without giving any
- indication of what that limit is, has the potential for causing harm
- by changing the meaning of tags in substantial ways.
-
- In practice, most language tags do not require more than a few
- subtags and will not approach reasonably sized buffer limitations;
- see Section 4.1.
-
- Some specifications or protocols have limits on tag length but do not
- have a fixed length limitation. For example, [RFC2231] has no
- explicit length limitation: the length available for the language tag
- is constrained by the length of other header components (such as the
- charset's name) coupled with the 76-character limit in [RFC2047].
- Thus, the "limit" might be 50 or more characters, but it could
- potentially be quite small.
-
- The considerations for assigning a buffer limit are:
-
- Implementations SHOULD NOT truncate language tags unless the
- meaning of the tag is purposefully being changed, or unless the
- tag does not fit into a limited buffer size specified by a
- protocol for storage or transmission.
-
- Implementations SHOULD warn the user when a tag is truncated since
- truncation changes the semantic meaning of the tag.
-
- Implementations of protocols or specifications that are space
- constrained but do not have a fixed limit SHOULD use the longest
- possible tag in preference to truncation.
-
- Protocols or specifications that specify limited buffer sizes for
- language tags MUST allow for language tags of up to 33 characters.
-
- Protocols or specifications that specify limited buffer sizes for
- language tags SHOULD allow for language tags of at least 42
- characters.
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 42]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- The following illustration shows how the 42-character recommendation
- was derived. The combination of language and extended language
- subtags was chosen for future compatibility. At up to 15 characters,
- this combination is longer than the longest possible primary language
- subtag (8 characters):
-
- language = 3 (ISO 639-2; ISO 639-1 requires 2)
- extlang1 = 4 (each subsequent subtag includes '-')
- extlang2 = 4 (unlikely: needs prefix="language-extlang1")
- extlang3 = 4 (extremely unlikely)
- script = 5 (if not suppressed: see Section 4.1)
- region = 4 (UN M.49; ISO 3166 requires 3)
- variant1 = 9 (MUST have language as a prefix)
- variant2 = 9 (MUST have language-variant1 as a prefix)
-
- total = 42 characters
-
- Figure 7: Derivation of the Limit on Tag Length
-
-4.3.2. Truncation of Language Tags
-
- Truncation of a language tag alters the meaning of the tag, and thus
- SHOULD be avoided. However, truncation of language tags is sometimes
- necessary due to limited buffer sizes. Such truncation MUST NOT
- permit a subtag to be chopped off in the middle or the formation of
- invalid tags (for example, one ending with the "-" character).
-
- This means that applications or protocols that truncate tags MUST do
- so by progressively removing subtags along with their preceding "-"
- from the right side of the language tag until the tag is short enough
- for the given buffer. If the resulting tag ends with a single-
- character subtag, that subtag and its preceding "-" MUST also be
- removed. For example:
-
- Tag to truncate: zh-Latn-CN-variant1-a-extend1-x-wadegile-private1
- 1. zh-Latn-CN-variant1-a-extend1-x-wadegile
- 2. zh-Latn-CN-variant1-a-extend1
- 3. zh-Latn-CN-variant1
- 4. zh-Latn-CN
- 5. zh-Latn
- 6. zh
-
- Figure 8: Example of Tag Truncation
-
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 43]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
-4.4. Canonicalization of Language Tags
-
- Since a particular language tag is sometimes used by many processes,
- language tags SHOULD always be created or generated in a canonical
- form.
-
- A language tag is in canonical form when:
-
- 1. The tag is well-formed according the rules in Section 2.1 and
- Section 2.2.
-
- 2. Subtags of type 'Region' that have a Preferred-Value mapping in
- the IANA registry (see Section 3.1) SHOULD be replaced with their
- mapped value. Note: In rare cases, the mapped value will also
- have a Preferred-Value.
-
- 3. Redundant or grandfathered tags that have a Preferred-Value
- mapping in the IANA registry (see Section 3.1) MUST be replaced
- with their mapped value. These items either are deprecated
- mappings created before the adoption of this document (such as
- the mapping of "no-nyn" to "nn" or "i-klingon" to "tlh") or are
- the result of later registrations or additions to this document
- (for example, "zh-guoyu" might be mapped to a language-extlang
- combination such as "zh-cmn" by some future update of this
- document).
-
- 4. Other subtags that have a Preferred-Value mapping in the IANA
- registry (see Section 3.1) MUST be replaced with their mapped
- value. These items consist entirely of clerical corrections to
- ISO 639-1 in which the deprecated subtags have been maintained
- for compatibility purposes.
-
- 5. If more than one extension subtag sequence exists, the extension
- sequences are ordered into case-insensitive ASCII order by
- singleton subtag.
-
- Example: The language tag "en-A-aaa-B-ccc-bbb-x-xyz" is in canonical
- form, while "en-B-ccc-bbb-A-aaa-X-xyz" is well-formed but not in
- canonical form.
-
- Example: The language tag "en-BU" (English as used in Burma) is not
- canonical because the 'BU' subtag has a canonical mapping to 'MM'
- (Myanmar), although the tag "en-BU" maintains its validity.
-
- Canonicalization of language tags does not imply anything about the
- use of upper or lowercase letters when processing or comparing
- subtags (and as described in Section 2.1). All comparisons MUST be
- performed in a case-insensitive manner.
-
-
-
-Phillips & Davis Best Current Practice [Page 44]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- When performing canonicalization of language tags, processors MAY
- regularize the case of the subtags (that is, this process is
- OPTIONAL), following the case used in the registry. Note that this
- corresponds to the following casing rules: uppercase all non-initial
- two-letter subtags; titlecase all non-initial four-letter subtags;
- lowercase everything else.
-
- Note: Case folding of ASCII letters in certain locales, unless
- carefully handled, sometimes produces non-ASCII character values.
- The Unicode Character Database file "SpecialCasing.txt" defines the
- specific cases that are known to cause problems with this. In
- particular, the letter 'i' (U+0069) in Turkish and Azerbaijani is
- uppercased to U+0130 (LATIN CAPITAL LETTER I WITH DOT ABOVE).
- Implementers SHOULD specify a locale-neutral casing operation to
- ensure that case folding of subtags does not produce this value,
- which is illegal in language tags. For example, if one were to
- uppercase the region subtag 'in' using Turkish locale rules, the
- sequence U+0130 U+004E would result instead of the expected 'IN'.
-
- Note: if the field 'Deprecated' appears in a registry record without
- an accompanying 'Preferred-Value' field, then that tag or subtag is
- deprecated without a replacement. Validating processors SHOULD NOT
- generate tags that include these values, although the values are
- canonical when they appear in a language tag.
-
- An extension MUST define any relationships that exist between the
- various subtags in the extension and thus MAY define an alternate
- canonicalization scheme for the extension's subtags. Extensions MAY
- define how the order of the extension's subtags are interpreted. For
- example, an extension could define that its subtags are in canonical
- order when the subtags are placed into ASCII order: that is,
- "en-a-aaa-bbb-ccc" instead of "en-a-ccc-bbb-aaa". Another extension
- might define that the order of the subtags influences their semantic
- meaning (so that "en-b-ccc-bbb-aaa" has a different value from
- "en-b-aaa-bbb-ccc"). However, extension specifications SHOULD be
- designed so that they are tolerant of the typical processes described
- in Section 3.7.
-
-4.5. Considerations for Private Use Subtags
-
- Private use subtags, like all other subtags, MUST conform to the
- format and content constraints in the ABNF. Private use subtags have
- no meaning outside the private agreement between the parties that
- intend to use or exchange language tags that employ them. The same
- subtags MAY be used with a different meaning under a separate private
- agreement. They SHOULD NOT be used where alternatives exist and
- SHOULD NOT be used in content or protocols intended for general use.
-
-
-
-
-Phillips & Davis Best Current Practice [Page 45]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- Private use subtags are simply useless for information exchange
- without prior arrangement. The value and semantic meaning of private
- use tags and of the subtags used within such a language tag are not
- defined by this document.
-
- Subtags defined in the IANA registry as having a specific private use
- meaning convey more information that a purely private use tag
- prefixed by the singleton subtag 'x'. For applications, this
- additional information MAY be useful.
-
- For example, the region subtags 'AA', 'ZZ', and in the ranges
- 'QM'-'QZ' and 'XA'-'XZ' (derived from ISO 3166 private use codes) MAY
- be used to form a language tag. A tag such as "zh-Hans-XQ" conveys a
- great deal of public, interchangeable information about the language
- material (that it is Chinese in the simplified Chinese script and is
- suitable for some geographic region 'XQ'). While the precise
- geographic region is not known outside of private agreement, the tag
- conveys far more information than an opaque tag such as "x-someLang",
- which contains no information about the language subtag or script
- subtag outside of the private agreement.
-
- However, in some cases content tagged with private use subtags MAY
- interact with other systems in a different and possibly unsuitable
- manner compared to tags that use opaque, privately defined subtags,
- so the choice of the best approach sometimes depends on the
- particular domain in question.
-
-5. IANA Considerations
-
- This section deals with the processes and requirements necessary for
- IANA to undertake to maintain the subtag and extension registries as
- defined by this document and in accordance with the requirements of
- [RFC2434].
-
- The impact on the IANA maintainers of the two registries defined by
- this document will be a small increase in the frequency of new
- entries or updates.
-
-5.1. Language Subtag Registry
-
- Upon adoption of this document, the registry will be initialized by a
- companion document: [RFC4645]. The criteria and process for
- selecting the initial set of records are described in that document.
- The initial set of records represents no impact on IANA, since the
- work to create it will be performed externally.
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 46]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- The new registry MUST be listed under "Language Tags" at
- <http://www.iana.org/numbers.html>, replacing the existing
- registrations defined by [RFC3066]. The existing set of registration
- forms and RFC 3066 registrations MUST be relabeled as "Language Tags
- (Obsolete)" and maintained (but not added to or modified).
-
- Future work on the Language Subtag Registry SHALL be limited to
- inserting or replacing whole records preformatted for IANA by the
- Language Subtag Reviewer as described in Section 3.3 of this document
- and archiving the forwarded registration form.
-
- Each record MUST be sent to iana@iana.org with a subject line
- indicating whether the enclosed record is an insertion of a new
- record (indicated by the word "INSERT" in the subject line) or a
- replacement of an existing record (indicated by the word "MODIFY" in
- the subject line). Records MUST NOT be deleted from the registry.
- IANA MUST place any inserted or modified records into the appropriate
- section of the language subtag registry, grouping the records by
- their 'Type' field. Inserted records MAY be placed anywhere in the
- appropriate section; there is no guarantee of the order of the
- records beyond grouping them together by 'Type'. Modified records
- MUST overwrite the record they replace.
-
- Included in any request to insert or modify records MUST be a new
- File-Date record. This record MUST be placed first in the registry.
- In the event that the File-Date record present in the registry has a
- later date than the record being inserted or modified, the existing
- record MUST be preserved.
-
-5.2. Extensions Registry
-
- The Language Tag Extensions Registry will also be generated and sent
- to IANA as described in Section 3.7. This registry can contain at
- most 35 records, and thus changes to this registry are expected to be
- very infrequent.
-
- Future work by IANA on the Language Tag Extensions Registry is
- limited to two cases. First, the IESG MAY request that new records
- be inserted into this registry from time to time. These requests
- MUST include the record to insert in the exact format described in
- Section 3.7. In addition, there MAY be occasional requests from the
- maintaining authority for a specific extension to update the contact
- information or URLs in the record. These requests MUST include the
- complete, updated record. IANA is not responsible for validating the
- information provided, only that it is properly formatted. It should
- reasonably be seen to come from the maintaining authority named in
- the record present in the registry.
-
-
-
-
-Phillips & Davis Best Current Practice [Page 47]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
-6. Security Considerations
-
- Language tags used in content negotiation, like any other information
- exchanged on the Internet, might be a source of concern because they
- might be used to infer the nationality of the sender, and thus
- identify potential targets for surveillance.
-
- This is a special case of the general problem that anything sent is
- visible to the receiving party and possibly to third parties as well.
- It is useful to be aware that such concerns can exist in some cases.
-
- The evaluation of the exact magnitude of the threat, and any possible
- countermeasures, is left to each application protocol (see BCP 72
- [RFC3552] for best current practice guidance on security threats and
- defenses).
-
- The language tag associated with a particular information item is of
- no consequence whatsoever in determining whether that content might
- contain possible homographs. The fact that a text is tagged as being
- in one language or using a particular script subtag provides no
- assurance whatsoever that it does not contain characters from scripts
- other than the one(s) associated with or specified by that language
- tag.
-
- Since there is no limit to the number of variant, private use, and
- extension subtags, and consequently no limit on the possible length
- of a tag, implementations need to guard against buffer overflow
- attacks. See Section 4.3 for details on language tag truncation,
- which can occur as a consequence of defenses against buffer overflow.
-
- Although the specification of valid subtags for an extension (see
- Section 3.7) MUST be available over the Internet, implementations
- SHOULD NOT mechanically depend on it being always accessible, to
- prevent denial-of-service attacks.
-
-7. Character Set Considerations
-
- The syntax in this document requires that language tags use only the
- characters A-Z, a-z, 0-9, and HYPHEN-MINUS, which are present in most
- character sets, so the composition of language tags should not have
- any character set issues.
-
- Rendering of characters based on the content of a language tag is not
- addressed in this memo. Historically, some languages have relied on
- the use of specific character sets or other information in order to
- infer how a specific character should be rendered (notably this
- applies to language- and culture-specific variations of Han
- ideographs as used in Japanese, Chinese, and Korean). When language
-
-
-
-Phillips & Davis Best Current Practice [Page 48]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- tags are applied to spans of text, rendering engines sometimes use
- that information in deciding which font to use in the absence of
- other information, particularly where languages with distinct writing
- traditions use the same characters.
-
-8. Changes from RFC 3066
-
- The main goals for this revision of language tags were the following:
-
- *Compatibility.* All RFC 3066 language tags (including those in the
- IANA registry) remain valid in this specification. The changes in
- this document represent additional constraints on language tags.
- That is, in no case is the syntax more permissive and processors
- based on the ABNF and other provisions of RFC 3066 (such as those
- described in [XMLSchema]) will be able to process the tags described
- by this document. In addition, this document defines language tags
- in such as way as to ensure future compatibility.
-
- *Stability.* Because of changes in the past in the underlying ISO
- standards, a valid RFC 3066 language tag could become invalid or have
- its meaning change. This has the potential of invalidating content
- that may have an extensive shelf-life. In this specification, once a
- language tag is valid, it remains valid forever.
-
- *Validity.* The structure of language tags defined by this document
- makes it possible to determine if a particular tag is well-formed
- without regard for the actual content or "meaning" of the tag as a
- whole. This is important because the registry grows and underlying
- standards change over time. In addition, it must be possible to
- determine if a tag is valid (or not) for a given point in time in
- order to provide reproducible, testable results. This process must
- not be error-prone; otherwise implementations might give different
- results. By having an authoritative registry with specific
- versioning information, the validity of language tags at any point in
- time can be precisely determined (instead of interpolating values
- from many separate sources).
-
- *Utility.* It is sometimes important to be able to differentiate
- between written forms of a language -- for many implementations this
- is more important than distinguishing between the spoken variants of
- a language. Languages are written in a wide variety of different
- scripts, so this document provides for the generative use of ISO
- 15924 script codes. Like the generative use of ISO language and
- country codes in RFC 3066, this allows combinations to be produced
- without resorting to the registration process. The addition of UN
- M.49 codes provides for the generation of language tags with regional
- scope, which is also required by some applications.
-
-
-
-
-Phillips & Davis Best Current Practice [Page 49]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- The recast of the registry from containing whole language tags to
- subtags is a key part of this. An important feature of RFC 3066 was
- that it allowed generative use of subtags. This allows people to
- meaningfully use generated tags, without the delays in registering
- whole tags or the need to register all of the combinations that might
- be useful.
-
- The choice of placing the extended language and script subtags
- between the primary language and region subtags was widely debated.
- This design was chosen because the prevalent matching and content
- negotiation schemes rely on the subtags being arranged in order of
- increasing specificity. That is, the subtags that mark a greater
- barrier to mutual intelligibility appear left-most in a tag. For
- example, when selecting content written in Azerbaijani, the script
- (Arabic, Cyrillic, or Latin) represents a greater barrier to
- understanding than any regional variations (those associated with
- Azerbaijan or Iran, for example). Individuals who prefer documents
- in a particular script, but can deal with the minor regional
- differences, can therefore select appropriate content. Applications
- that do not deal with written content will continue to omit these
- subtags.
-
- *Extensibility.* Because of the widespread use of language tags, it
- is disruptive to have periodic revisions of the core specification,
- even in the face of demonstrated need. The extension mechanism
- provides for a way for independent RFCs to define extensions to
- language tags. These extensions have a very constrained, well-
- defined structure that prevents extensions from interfering with
- implementations of language tags defined in this document.
-
- The document also anticipates features of ISO 639-3 with the addition
- of the extended language subtags, as well as the possibility of other
- ISO 639 parts becoming useful for the formation of language tags in
- the future.
-
- The use and definition of private use tags have also been modified,
- to allow people to use private use subtags to extend or modify
- defined tags and to move as much information as possible out of
- private use and into the regular structure.
-
- The goal for each of these modifications is to reduce or eliminate
- the need for future revisions of this document.
-
-
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 50]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- The specific changes in this document to meet these goals are:
-
- o Defines the ABNF and rules for subtags so that the category of all
- subtags can be determined without reference to the registry.
-
- o Adds the concept of well-formed vs. validating processors,
- defining the rules by which an implementation can claim to be one
- or the other.
-
- o Replaces the IANA language tag registry with a language subtag
- registry that provides a complete list of valid subtags in the
- IANA registry. This allows for robust implementation and ease of
- maintenance. The language subtag registry becomes the canonical
- source for forming language tags.
-
- o Provides a process that guarantees stability of language tags, by
- handling reuse of values by ISO 639, ISO 15924, and ISO 3166 in
- the event that they register a previously used value for a new
- purpose.
-
- o Allows ISO 15924 script code subtags and allows them to be used
- generatively. Defines a method for indicating in the registry
- when script subtags are necessary for a given language tag.
-
- o Adds the concept of a variant subtag and allows variants to be
- used generatively.
-
- o Adds the ability to use a class of UN M.49 tags for supra-national
- regions and to resolve conflicts in the assignment of ISO 3166
- codes.
-
- o Defines the private use tags in ISO 639, ISO 15924, and ISO 3166
- as the mechanism for creating private use language, script, and
- region subtags, respectively.
-
- o Adds a well-defined extension mechanism.
-
- o Defines an extended language subtag, possibly for use with certain
- anticipated features of ISO 639-3.
-
-
-
-
-
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 51]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
-9. References
-
-9.1. Normative References
-
- [ISO10646] International Organization for Standardization,
- "ISO/IEC 10646:2003. Information technology --
- Universal Multiple-Octet Coded Character Set (UCS)",
- 2003.
-
- [ISO15924] International Organization for Standardization, "ISO
- 15924:2004. Information and documentation -- Codes for
- the representation of names of scripts", January 2004.
-
- [ISO3166-1] International Organization for Standardization, "ISO
- 3166-1:1997. Codes for the representation of names of
- countries and their subdivisions -- Part 1: Country
- codes", 1997.
-
- [ISO639-1] International Organization for Standardization, "ISO
- 639-1:2002. Codes for the representation of names of
- languages -- Part 1: Alpha-2 code", 2002.
-
- [ISO639-2] International Organization for Standardization, "ISO
- 639-2:1998. Codes for the representation of names of
- languages -- Part 2: Alpha-3 code, first edition",
- 1998.
-
- [ISO646] International Organization for Standardization,
- "ISO/IEC 646:1991, Information technology -- ISO 7-bit
- coded character set for information interchange.",
- 1991.
-
- [RFC2026] Bradner, S., "The Internet Standards Process --
- Revision 3", BCP 9, RFC 2026, October 1996.
-
- [RFC2028] Hovey, R. and S. Bradner, "The Organizations Involved
- in the IETF Standards Process", BCP 11, RFC 2028,
- October 1996.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing
- an IANA Considerations Section in RFCs", BCP 26,
- RFC 2434, October 1998.
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 52]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- [RFC2860] Carpenter, B., Baker, F., and M. Roberts, "Memorandum
- of Understanding Concerning the Technical Work of the
- Internet Assigned Numbers Authority", RFC 2860,
- June 2000.
-
- [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
- Internet: Timestamps", RFC 3339, July 2002.
-
- [RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for
- Syntax Specifications: ABNF", RFC 4234, October 2005.
-
- [UN_M.49] Statistics Division, United Nations, "Standard Country
- or Area Codes for Statistical Use", UN Standard
- Country or Area Codes for Statistical Use, Revision 4
- (United Nations publication, Sales No. 98.XVII.9,
- June 1999.
-
-9.2. Informative References
-
- [RFC1766] Alvestrand, H., "Tags for the Identification of
- Languages", RFC 1766, March 1995.
-
- [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail
- Extensions) Part Three: Message Header Extensions for
- Non-ASCII Text", RFC 2047, November 1996.
-
- [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and
- Encoded Word Extensions: Character Sets, Languages,
- and Continuations", RFC 2231, November 1997.
-
- [RFC2781] Hoffman, P. and F. Yergeau, "UTF-16, an encoding of
- ISO 10646", RFC 2781, February 2000.
-
- [RFC3066] Alvestrand, H., "Tags for the Identification of
- Languages", BCP 47, RFC 3066, January 2001.
-
- [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing
- RFC Text on Security Considerations", BCP 72,
- RFC 3552, July 2003.
-
- [RFC4645] Ewell, D., Ed., "Initial Language Subtag Registry",
- RFC 4645, September 2006.
-
- [RFC4647] Phillips, A., Ed. and M. Davis, Ed., "Matching of
- Language Tags", BCP 47, RFC 4647, September 2006.
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 53]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- [Unicode] Unicode Consortium, "The Unicode Standard, Version
- 5.0", Boston, MA, Addison-Wesley, 2007. ISBN 0-321-
- 48091-0.
-
- [XML10] Bray (et al), T., "Extensible Markup Language (XML)
- 1.0", 02 2004.
-
- [XMLSchema] Biron, P., Ed. and A. Malhotra, Ed., "XML Schema Part
- 2: Datatypes Second Edition", 10 2004, <
- http://www.w3.org/TR/xmlschema-2/>.
-
- [iso639.prin] ISO 639 Joint Advisory Committee, "ISO 639 Joint
- Advisory Committee: Working principles for ISO 639
- maintenance", March 2000, <http://www.loc.gov/
- standards/iso639-2/iso639jac_n3r.html>.
-
- [record-jar] Raymond, E., "The Art of Unix Programming", 2003,
- <urn:isbn:0-13-142901-9>.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 54]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
-Appendix A. Acknowledgements
-
- Any list of contributors is bound to be incomplete; please regard the
- following as only a selection from the group of people who have
- contributed to make this document what it is today.
-
- The contributors to RFC 3066 and RFC 1766, the precursors of this
- document, made enormous contributions directly or indirectly to this
- document and are generally responsible for the success of language
- tags.
-
- The following people (in alphabetical order) contributed to this
- document or to RFCs 1766 and 3066:
-
- Glenn Adams, Harald Tveit Alvestrand, Tim Berners-Lee, Marc Blanchet,
- Nathaniel Borenstein, Karen Broome, Eric Brunner, Sean M. Burke, M.T.
- Carrasco Benitez, Jeremy Carroll, John Clews, Jim Conklin, Peter
- Constable, John Cowan, Mark Crispin, Dave Crocker, Elwyn Davies,
- Martin Duerst, Frank Ellerman, Michael Everson, Doug Ewell, Ned
- Freed, Tim Goodwin, Dirk-Willem van Gulik, Marion Gunn, Joel Halpren,
- Elliotte Rusty Harold, Paul Hoffman, Scott Hollenbeck, Richard
- Ishida, Olle Jarnefors, Kent Karlsson, John Klensin, Erkki
- Kolehmainen, Alain LaBonte, Eric Mader, Ira McDonald, Keith Moore,
- Chris Newman, Masataka Ohta, Dylan Pierce, Randy Presuhn, George
- Rhoten, Felix Sasaki, Markus Scherer, Keld Jorn Simonsen, Thierry
- Sourbier, Otto Stolz, Tex Texin, Andrea Vine, Rhys Weatherley, Misha
- Wolf, Francois Yergeau and many, many others.
-
- Very special thanks must go to Harald Tveit Alvestrand, who
- originated RFCs 1766 and 3066, and without whom this document would
- not have been possible. Special thanks must go to Michael Everson,
- who has served as Language Tag Reviewer for almost the complete
- period since the publication of RFC 1766. Special thanks to Doug
- Ewell, for his production of the first complete subtag registry, and
- his work in producing a test parser for verifying language tags.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 55]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
-Appendix B. Examples of Language Tags (Informative)
-
- Simple language subtag:
-
- de (German)
-
- fr (French)
-
- ja (Japanese)
-
- i-enochian (example of a grandfathered tag)
-
- Language subtag plus Script subtag:
-
- zh-Hant (Chinese written using the Traditional Chinese script)
-
- zh-Hans (Chinese written using the Simplified Chinese script)
-
- sr-Cyrl (Serbian written using the Cyrillic script)
-
- sr-Latn (Serbian written using the Latin script)
-
- Language-Script-Region:
-
- zh-Hans-CN (Chinese written using the Simplified script as used in
- mainland China)
-
- sr-Latn-CS (Serbian written using the Latin script as used in
- Serbia and Montenegro)
-
- Language-Variant:
-
- sl-rozaj (Resian dialect of Slovenian
-
- sl-nedis (Nadiza dialect of Slovenian)
-
- Language-Region-Variant:
-
- de-CH-1901 (German as used in Switzerland using the 1901 variant
- [orthography])
-
- sl-IT-nedis (Slovenian as used in Italy, Nadiza dialect)
-
-
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 56]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- Language-Script-Region-Variant:
-
- sl-Latn-IT-nedis (Nadiza dialect of Slovenian written using the
- Latin script as used in Italy. Note that this tag is NOT
- RECOMMENDED because subtag 'sl' has a Suppress-Script value of
- 'Latn')
-
- Language-Region:
-
- de-DE (German for Germany)
-
- en-US (English as used in the United States)
-
- es-419 (Spanish appropriate for the Latin America and Caribbean
- region using the UN region code)
-
- Private use subtags:
-
- de-CH-x-phonebk
-
- az-Arab-x-AZE-derbend
-
- Extended language subtags (examples ONLY: extended languages MUST be
- defined by revision or update to this document):
-
- zh-min
-
- zh-min-nan-Hant-CN
-
- Private use registry values:
-
- x-whatever (private use using the singleton 'x')
-
- qaa-Qaaa-QM-x-southern (all private tags)
-
- de-Qaaa (German, with a private script)
-
- sr-Latn-QM (Serbian, Latin-script, private region)
-
- sr-Qaaa-CS (Serbian, private script, for Serbia and Montenegro)
-
- Tags that use extensions (examples ONLY: extensions MUST be defined
- by revision or update to this document or by RFC):
-
- en-US-u-islamCal
-
- zh-CN-a-myExt-x-private
-
-
-
-
-Phillips & Davis Best Current Practice [Page 57]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
- en-a-myExt-b-another
-
- Some Invalid Tags:
-
- de-419-DE (two region tags)
-
- a-DE (use of a single-character subtag in primary position; note
- that there are a few grandfathered tags that start with "i-" that
- are valid)
-
- ar-a-aaa-b-bbb-a-ccc (two extensions with same single-letter
- prefix)
-
-Authors' Addresses
-
- Addison Phillips (Editor)
- Yahoo! Inc.
-
- EMail: addison@inter-locale.com
-
-
- Mark Davis (Editor)
- Google
-
- EMail: mark.davis@macchiato.com or mark.davis@google.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 58]
-\f
-RFC 4646 Tags for Identifying Languages September 2006
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2006).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78, and except as set forth therein, the authors
- retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at
- ietf-ipr@ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is provided by the IETF
- Administrative Support Activity (IASA).
-
-
-
-
-
-
-
-Phillips & Davis Best Current Practice [Page 59]
-\f
+++ /dev/null
-/*
- * "$Id: rfctohtml.c 6649 2007-07-11 21:46:42Z mike $"
- *
- * RFC file to HTML conversion program.
- *
- * Copyright 2007-2011 by Apple Inc.
- * Copyright 2006 by Easy Software Products.
- *
- * These coded instructions, statements, and computer programs are the
- * property of Apple Inc. and are protected by Federal copyright
- * law. Distribution and use rights are outlined in the file "LICENSE.txt"
- * which should have been included with this file. If this file is
- * file is missing or damaged, see the license at "http://www.cups.org/".
- *
- * Contents:
- *
- * main() - Convert a man page to HTML.
- * put_entity() - Put a single character, using entities as needed.
- * put_line() - Put a whole string for a line.
- */
-
-/*
- * Include necessary headers.
- */
-
-#include <cups/string-private.h>
-#include <stdlib.h>
-#include <cups/file.h>
-
-
-/*
- * Local functions...
- */
-
-void put_entity(cups_file_t *fp, int ch);
-void put_line(cups_file_t *fp, const char *line);
-
-
-/*
- * 'main()' - Convert a man page to HTML.
- */
-
-int /* O - Exit status */
-main(int argc, /* I - Number of command-line args */
- char *argv[]) /* I - Command-line arguments */
-{
- cups_file_t *infile, /* Input file */
- *outfile; /* Output file */
- char line[1024], /* Line from file */
- *lineptr, /* Pointer into line */
- title[2048], /* Title string */
- *titleptr, /* Pointer into title */
- name[1024], /* Heading anchor name */
- *nameptr; /* Pointer into anchor name */
- int rfc, /* RFC # */
- inheading, /* Inside a heading? */
- inpre, /* Inside preformatted text? */
- intoc, /* Inside table-of-contents? */
- toclevel, /* Current table-of-contents level */
- linenum; /* Current line on page */
-
-
- /*
- * Check arguments...
- */
-
- if (argc > 3)
- {
- fputs("Usage: rfctohtml [rfcNNNN.txt [rfcNNNN.html]]\n", stderr);
- return (1);
- }
-
- /*
- * Open files as needed...
- */
-
- if (argc > 1)
- {
- if ((infile = cupsFileOpen(argv[1], "r")) == NULL)
- {
- perror(argv[1]);
- return (1);
- }
- }
- else
- infile = cupsFileOpenFd(0, "r");
-
- if (argc > 2)
- {
- if ((outfile = cupsFileOpen(argv[2], "w")) == NULL)
- {
- perror(argv[2]);
- cupsFileClose(infile);
- return (1);
- }
- }
- else
- outfile = cupsFileOpenFd(1, "w");
-
- /*
- * Read from input and write the output...
- */
-
- cupsFilePuts(outfile,
- "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01 Transitional//EN\" "
- "\"http://www.w3.org/TR/html4/loose.dtd\">\n"
- "<html>\n"
- "<!-- SECTION: Specifications -->\n"
- "<head>\n"
- "\t<link rel=\"stylesheet\" type=\"text/css\" "
- "href=\"../cups-printable.css\">\n");
-
- /*
- * Skip the initial header stuff (working group ID, RFC #, authors, and
- * copyright...
- */
-
- linenum = 0;
- rfc = 0;
-
- while (cupsFileGets(infile, line, sizeof(line)))
- {
- linenum ++;
-
- if (line[0])
- break;
- }
-
- while (cupsFileGets(infile, line, sizeof(line)))
- {
- linenum ++;
-
- if (!line[0])
- break;
- else if (!_cups_strncasecmp(line, "Request for Comments:", 21))
- rfc = atoi(line + 21);
- }
-
- /*
- * Read the document title...
- */
-
- while (cupsFileGets(infile, line, sizeof(line)))
- {
- linenum ++;
-
- if (line[0])
- break;
- }
-
- for (lineptr = line; isspace(*lineptr & 255); lineptr ++);
-
- snprintf(title, sizeof(title), "RFC %d: %s", rfc, lineptr);
- titleptr = title + strlen(title);
-
- while (cupsFileGets(infile, line, sizeof(line)))
- {
- linenum ++;
-
- if (!line[0])
- break;
- else
- {
- for (lineptr = line; isspace(*lineptr & 255); lineptr ++);
-
- snprintf(titleptr, sizeof(title) - (titleptr - title), " %s", lineptr);
- titleptr += strlen(titleptr);
- }
- }
-
- cupsFilePrintf(outfile, "\t<title>%s</title>\n"
- "</head>\n"
- "<body>\n"
- "<h1 class='title'>%s</h1>\n", title, title);
-
- /*
- * Read the rest of the file...
- */
-
- inheading = 0;
- inpre = 0;
- intoc = 0;
- toclevel = 0;
-
- while (cupsFileGets(infile, line, sizeof(line)))
- {
- linenum ++;
-
- if (!line[0])
- {
- if (linenum > 50)
- continue;
-
- if (inpre)
- {
- cupsFilePuts(outfile, "</pre>\n");
- inpre = 0;
- }
-
- if (inheading)
- {
- if (inheading < 0)
- cupsFilePuts(outfile, "</h2>\n");
- else
- cupsFilePrintf(outfile, "</a></h%d>\n", inheading);
-
- inheading = 0;
- }
- }
- else if ((line[0] == ' ' ||
- (!isupper(line[0] & 255) && !isdigit(line[0] & 255) &&
- !strstr(line, "[Page "))) && !inheading)
- {
- if (inheading)
- {
- if (inheading < 0)
- cupsFilePuts(outfile, "</h2>\n");
- else
- cupsFilePrintf(outfile, "</a></h%d>\n", inheading);
-
- inheading = 0;
- }
-
- for (lineptr = line; *lineptr == ' '; lineptr ++);
-
- if (intoc)
- {
- char *temp; /* Temporary pointer into line */
- int level; /* Heading level */
-
-
- if (isdigit(*lineptr & 255))
- {
- strlcpy(name, lineptr, sizeof(name));
-
- for (nameptr = name, level = -1; *nameptr;)
- if (isdigit(*nameptr & 255))
- {
- while (isdigit(*nameptr & 255))
- nameptr ++;
-
- level ++;
- }
- else if (*nameptr == ' ')
- {
- *nameptr = '\0';
- break;
- }
- else
- nameptr ++;
-
- while (toclevel > level)
- {
- cupsFilePuts(outfile, "\n</ul>");
- toclevel --;
- }
-
- while (toclevel < level)
- {
- cupsFilePuts(outfile, "\n<ul style=\"list-style-type: none;\">\n");
- toclevel ++;
- }
-
- cupsFilePrintf(outfile, "\n<%s><a href=\"#s%s\">", toclevel ? "li" : "p",
- name);
- }
-
- temp = lineptr + strlen(lineptr) - 1;
-
- while (temp > lineptr)
- if (*temp == ' ' || !isdigit(*temp & 255))
- break;
- else
- temp --;
-
- if (*temp == ' ')
- {
- while (temp > lineptr)
- if (*temp != ' ' && *temp != '.')
- break;
- else
- *temp-- = '\0';
- }
- else
- temp = NULL;
-
- if (isdigit(*lineptr & 255))
- put_line(outfile, lineptr);
- else
- put_line(outfile, lineptr - 1);
-
- if (temp)
- cupsFilePuts(outfile, "</a>");
- }
- else if (!inpre)
- {
- cupsFilePuts(outfile, "\n<pre>");
- put_line(outfile, line);
- inpre = 1;
- }
- else
- {
- cupsFilePutChar(outfile, '\n');
- put_line(outfile, line);
- }
- }
- else if (strstr(line, "[Page "))
- {
- /*
- * Skip page footer and header...
- */
-
- cupsFileGets(infile, line, sizeof(line));
- cupsFileGets(infile, line, sizeof(line));
- cupsFileGets(infile, line, sizeof(line));
- cupsFileGets(infile, line, sizeof(line));
- linenum = 3;
- }
- else if (isdigit(line[0] & 255) && !inheading)
- {
- int level; /* Heading level */
-
-
- if (intoc)
- {
- while (toclevel > 0)
- {
- cupsFilePuts(outfile, "\n</ul>");
- toclevel --;
- }
-
- cupsFilePutChar(outfile, '\n');
- intoc = 0;
- }
-
- if (inpre)
- {
- cupsFilePuts(outfile, "</pre>\n");
- inpre = 0;
- }
-
- strlcpy(name, line, sizeof(name));
- for (nameptr = name, level = 1; *nameptr;)
- if (isdigit(*nameptr & 255))
- {
- while (isdigit(*nameptr & 255))
- nameptr ++;
-
- level ++;
- }
- else if (*nameptr == ' ')
- {
- *nameptr = '\0';
- break;
- }
- else
- nameptr ++;
-
- cupsFilePrintf(outfile, "\n<h%d class='title'><a name='s%s'>", level,
- name);
- put_line(outfile, line);
-
- intoc = 0;
- inheading = level;
- }
- else
- {
- if (intoc)
- {
- while (toclevel > 0)
- {
- cupsFilePuts(outfile, "\n</ul>");
- toclevel --;
- }
-
- cupsFilePutChar(outfile, '\n');
- intoc = 0;
- }
-
- if (!inheading)
- {
- cupsFilePuts(outfile, "\n<h2 class='title'>");
- inheading = -1;
- }
-
- put_line(outfile, line);
-
- intoc = !_cups_strcasecmp(line, "Table of Contents");
- toclevel = 0;
- }
- }
-
- if (inpre)
- cupsFilePuts(outfile, "</pre>\n");
-
- if (inheading)
- {
- if (inheading < 0)
- cupsFilePuts(outfile, "</h2>\n");
- else
- cupsFilePrintf(outfile, "</a></h%d>\n", inheading);
- }
-
- cupsFilePuts(outfile, "</body>\n"
- "</html>\n");
-
- /*
- * Close files...
- */
-
- cupsFileClose(infile);
- cupsFileClose(outfile);
-
- /*
- * Return with no errors...
- */
-
- return (0);
-}
-
-
-/*
- * 'put_entity()' - Put a single character, using entities as needed.
- */
-
-void
-put_entity(cups_file_t *fp, /* I - File */
- int ch) /* I - Character */
-{
- if (ch == '&')
- cupsFilePuts(fp, "&");
- else if (ch == '<')
- cupsFilePuts(fp, "<");
- else
- cupsFilePutChar(fp, ch);
-}
-
-
-/*
- * 'put_line()' - Put a whole string for a line.
- */
-
-void
-put_line(cups_file_t *fp, /* I - File */
- const char *s) /* I - String */
-{
- int whitespace, /* Saw whitespace */
- i, /* Looping var */
- len; /* Length of keyword */
- static const char * const keywords[] =/* Special keywords to boldface */
- {
- "MAY",
- "MUST",
- "NEED",
- "NOT",
- "OPTIONAL",
- "OPTIONALLY",
- "RECOMMENDED",
- "REQUIRED",
- "SHALL",
- "SHOULD"
- };
-
-
- whitespace = 1;
-
- while (*s)
- {
- if (*s == ' ')
- whitespace = 1;
-
- if (whitespace && isupper(*s & 255))
- {
- whitespace = 0;
-
- for (i = 0; i < (int)(sizeof(keywords) / sizeof(sizeof(keywords[0]))); i ++)
- {
- len = strlen(keywords[i]);
- if (!strncmp(s, keywords[i], len) &&
- (isspace(s[len] & 255) || ispunct(s[len] & 255) || !*s))
- {
- cupsFilePrintf(fp, "<b>%s</b>", keywords[i]);
- s += len;
- break;
- }
- }
-
- if (i >= (int)(sizeof(keywords) / sizeof(sizeof(keywords[0]))))
- put_entity(fp, *s++);
- }
- else
- {
- if (*s != ' ')
- whitespace = 0;
-
- put_entity(fp, *s++);
- }
- }
-}
-
-
-/*
- * End of "$Id: rfctohtml.c 6649 2007-07-11 21:46:42Z mike $".
- */
echo Configuring...
autoconf -f
rm -rf autom4te*.cache
-rm -rf standards
rm -rf tools
cd ..