Internet Engineering Task Force (IETF) M. Sweet Request for Comments: 8010 Apple Inc. Obsoletes: 2910, 3382 I. McDonald Category: Standards Track High North, Inc. ISSN: 2070-1721 January 2017 Internet Printing Protocol/1.1: Encoding and TransportAbstract
The Internet Printing Protocol (IPP) is an application-level protocol for distributed printing using Internet tools and technologies. This document defines the rules for encoding IPP operations, attributes, and values into the Internet MIME media type called "application/ipp". It also defines the rules for transporting a message body whose Content-Type is "application/ipp" over HTTP and/or HTTPS. The IPP data model and operation semantics are described in "Internet Printing Protocol/1.1: Model and Semantics" (RFC 8011). This document obsoletes RFCs 2910 and 3382. Status of This Memo This is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc8010.
Copyright Notice Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Conventions Used in This Document . . . . . . . . . . . . . . 5 2.1. Requirements Language . . . . . . . . . . . . . . . . . . 5 2.2. Printing Terminology . . . . . . . . . . . . . . . . . . 5 2.3. Abbreviations . . . . . . . . . . . . . . . . . . . . . . 6 3. Encoding of the Operation Layer . . . . . . . . . . . . . . . 6 3.1. Picture of the Encoding . . . . . . . . . . . . . . . . . 8 3.1.1. Request and Response . . . . . . . . . . . . . . . . 8 3.1.2. Attribute Group . . . . . . . . . . . . . . . . . . . 9 3.1.3. Attribute . . . . . . . . . . . . . . . . . . . . . . 9 3.1.4. Attribute-with-one-value . . . . . . . . . . . . . . 10 3.1.5. Additional-value . . . . . . . . . . . . . . . . . . 11 3.1.6. Collection Attribute . . . . . . . . . . . . . . . . 12 3.1.7. Member Attributes . . . . . . . . . . . . . . . . . . 13 3.1.8. Alternative Picture of the Encoding of a Request or a Response . . . . . . . . . . . . . . . . . . . . . . 14 3.2. Syntax of Encoding . . . . . . . . . . . . . . . . . . . 15 3.3. Attribute-group . . . . . . . . . . . . . . . . . . . . . 16 3.4. Required Parameters . . . . . . . . . . . . . . . . . . . 18 3.4.1. "version-number" . . . . . . . . . . . . . . . . . . 18 3.4.2. "operation-id" . . . . . . . . . . . . . . . . . . . 18 3.4.3. "status-code" . . . . . . . . . . . . . . . . . . . . 19 3.4.4. "request-id" . . . . . . . . . . . . . . . . . . . . 19 3.5. Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 19 3.5.1. "delimiter-tag" Values . . . . . . . . . . . . . . . 19 3.5.2. "value-tag" Values . . . . . . . . . . . . . . . . . 20 3.6. "name-length" . . . . . . . . . . . . . . . . . . . . . . 23 3.7. (Attribute) "name" . . . . . . . . . . . . . . . . . . . 23 3.8. "value-length" . . . . . . . . . . . . . . . . . . . . . 23 3.9. (Attribute) "value" . . . . . . . . . . . . . . . . . . . 24 3.10. Data . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4. Encoding of Transport Layer . . . . . . . . . . . . . . . . . 26 4.1. Printer URI, Job URI, and Job ID . . . . . . . . . . . . 26 5. IPP URI Schemes . . . . . . . . . . . . . . . . . . . . . . . 28 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 7. Internationalization Considerations . . . . . . . . . . . . . 31 8. Security Considerations . . . . . . . . . . . . . . . . . . . 31 8.1. Security Conformance Requirements . . . . . . . . . . . . 31 8.1.1. Digest Authentication . . . . . . . . . . . . . . . . 32 8.1.2. Transport Layer Security (TLS) . . . . . . . . . . . 32 8.2. Using IPP with TLS . . . . . . . . . . . . . . . . . . . 33 9. Interoperability with Other IPP Versions . . . . . . . . . . 33 9.1. The "version-number" Parameter . . . . . . . . . . . . . 34 9.2. Security and URI Schemes . . . . . . . . . . . . . . . . 34 10. Changes since RFC 2910 . . . . . . . . . . . . . . . . . . . 35 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 11.1. Normative References . . . . . . . . . . . . . . . . . . 36 11.2. Informative References . . . . . . . . . . . . . . . . . 38 Appendix A. Protocol Examples . . . . . . . . . . . . . . . . . 40 A.1. Print-Job Request . . . . . . . . . . . . . . . . . . . . 40 A.2. Print-Job Response (Successful) . . . . . . . . . . . . . 41 A.3. Print-Job Response (Failure) . . . . . . . . . . . . . . 42 A.4. Print-Job Response (Success with Attributes Ignored) . . 43 A.5. Print-URI Request . . . . . . . . . . . . . . . . . . . . 45 A.6. Create-Job Request . . . . . . . . . . . . . . . . . . . 46 A.7. Create-Job Request with Collection Attributes . . . . . . 46 A.8. Get-Jobs Request . . . . . . . . . . . . . . . . . . . . 48 A.9. Get-Jobs Response . . . . . . . . . . . . . . . . . . . . 49 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 51 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51
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 request and response. All IPP implementations support HTTP/1.1, the relevant parts of which are described in the following RFCs: o Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing [RFC7230] o Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content [RFC7231] o Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests [RFC7232] o Hypertext Transfer Protocol (HTTP/1.1): Caching [RFC7234] o Hypertext Transfer Protocol (HTTP/1.1): Authentication [RFC7235] o The 'Basic' HTTP Authentication Scheme [RFC7617] o HTTP Digest Access Authentication [RFC7616] IPP implementations can support HTTP/2, which is described in the following RFCs: o Hypertext Transfer Protocol Version 2 (HTTP/2) [RFC7540] o HPACK - Header Compression for HTTP/2 [RFC7541] 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 "Internet Printing Protocol/1.1: Model and Semantics" document [RFC8011] and subsequent extensions (collectively known as the IPP Model) define the semantics of such a message body and the supported values. This document specifies the encoding of an IPP request and response message.
2. Conventions Used in This Document
2.1. Requirements Language
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].2.2. Printing Terminology
Client: Initiator of outgoing IPP session requests and sender of outgoing IPP operation requests (Hypertext Transfer Protocol -- HTTP/1.1 [RFC7230] User Agent). Document: An object created and managed by a Printer that contains description, processing, and status information. A Document object may have attached data and is bound to a single Job. 'ipp' URI: An IPP URI as defined in [RFC3510]. 'ipps' URI: An IPPS URI as defined in [RFC7472]. Job: An object created and managed by a Printer that contains description, processing, and status information. The Job also contains zero or more Document objects. Logical Device: A print server, software service, or gateway that processes Jobs and either forwards or stores the processed Job or uses one or more Physical Devices to render output. Model: The semantics of operations, attributes, values, and status- codes used in the Internet Printing Protocol as defined in the Internet Printing Protocol/1.1: Model and Semantics document [RFC8011] and subsequent extensions. Output Device: A single Logical or Physical Device. Physical Device: A hardware implementation of an endpoint device, e.g., a marking engine, a fax modem, etc. Printer: Listener for incoming IPP session requests and receiver of incoming IPP operation requests (Hypertext Transfer Protocol -- HTTP/1.1 [RFC7230] Server) that represents one or more Physical Devices or a Logical Device.
2.3. Abbreviations
ABNF: Augmented Backus-Naur Form [RFC5234] ASCII: American Standard Code for Information Interchange [RFC20] HTTP: Hypertext Transfer Protocol [RFC7230] HTTPS: HTTP over TLS [RFC2818] IANA: Internet Assigned Numbers Authority IEEE: Institute of Electrical and Electronics Engineers IESG: Internet Engineering Steering Group IPP: Internet Printing Protocol (this document and [PWG5100.12]) ISTO: IEEE Industry Standards and Technology Organization LPD: Line Printer Daemon Protocol [RFC1179] PWG: IEEE-ISTO Printer Working Group RFC: Request for Comments TCP: Transmission Control Protocol [RFC793] TLS: Transport Layer Security [RFC5246] URI: Uniform Resource Identifier [RFC3986] URL: Uniform Resource Locator [RFC3986] UTF-8: Unicode Transformation Format - 8-bit [RFC3629]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 a sequence of characters where the characters are associated with some charset [RFC2978] 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 and 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 is henceforth called a LOCALIZED-STRING. An octet string MUST be in "Model order" with the first octet in the value (according to the Model 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. A one-octet integer, henceforth called a SIGNED-BYTE, is used for the version-number and tag fields. A two- byte integer, henceforth called a SIGNED-SHORT, is used for the operation-id, status-code, and length fields. A four-byte integer, henceforth called a SIGNED-INTEGER, is used for value fields and the request-id. The following two sections present the encoding of the operation layer in two ways: o informally through pictures and description o formally through Augmented Backus-Naur Form (ABNF), as specified by RFC 5234 [RFC5234] An operation request or response MUST use the encoding described in these two sections.
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 ----------------------------------------------- Figure 1: IPP Message Format The first three fields in the above diagram contain the value of attributes described in Section 4.1.1 of the Model and Semantics document [RFC8011]. 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). The Model 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 specifies whether the "data" field is present for each operation request and response.
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 ---------------------------------------------------------- Figure 2: Attribute Group Encoding An "attribute-group" field contains zero or more "attribute" fields. Note that 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 ---------------------------------------------------------- Figure 3: Attribute Encoding When an attribute is single valued (e.g., "copies" with a 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. 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 ----------------------------------------------- Figure 4: Single Value Attribute Encoding An "attribute-with-one-value" field is encoded with five subfields: o The "value-tag" field specifies the attribute syntax, e.g., 0x44 for the attribute syntax 'keyword'. o 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". o The "name" field contains the textual name of the attribute, e.g., "sides-supported". o 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'. o 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 ----------------------------------------------- Figure 5: Additional Attribute Value Encoding An "additional-value" is encoded with four subfields: o The "value-tag" field specifies the attribute syntax, e.g., 0x44 for the attribute syntax 'keyword'. o 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). o 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'. o The "value" field contains the value of the attribute, e.g., the textual value 'two-sided-long-edge'.
3.1.6. Collection Attribute
Collection attributes create a named group containing related "member" attributes. The "attribute-with-one-value" field for a collection attribute is encoded as follows: ----------------------------------------------- | value-tag (value is 0x34) | 1 byte ----------------------------------------------- | name-length (value is u) | 2 bytes ----------------------------------------------- | name | u bytes ----------------------------------------------- | value-length (value is 0x0000) | 2 bytes ----------------------------------------------------------- | member-attribute | q bytes |-0 or more ----------------------------------------------------------- | end-value-tag (value is 0x37) | 1 byte ----------------------------------------------- | end-name-length (value is 0x0000) | 2 bytes ----------------------------------------------- | end-value-length (value is 0x0000) | 2 bytes ----------------------------------------------- Figure 6: Collection Attribute Encoding Collection attribute is encoded with eight subfields: o The "value-tag" field specifies the start attribute syntax: 0x34 for the attribute syntax 'begCollection'. o The "name-length" field specifies the length of the "name" field in bytes, e.g., u in the above diagram or 9 for the name "media- col". Additional collection attribute values use a name length of 0x0000. o The "name" field contains the textual name of the attribute, e.g., "media-col". o The "value-length" field specifies a length of 0x0000. o The "member-attribute" field contains member attributes encoded as defined in Section 3.1.7. o The "end-value-tag" field specifies the end attribute syntax: 0x37 for the attribute syntax 'endCollection'. o The "end-name-length" field specifies a length of 0x0000.
o The "end-value-length" field specifies a length of 0x0000.3.1.7. Member Attributes
Each "member-attribute" field is encoded as follows: ----------------------------------------------- | value-tag (value is 0x4a) | 1 byte ----------------------------------------------- | name-length (value is 0x0000) | 2 bytes ----------------------------------------------- | value-length (value is w) | 2 bytes ----------------------------------------------- | value (member-name) | w bytes ----------------------------------------------- | member-value-tag | 1 byte ----------------------------------------------- | name-length (value is 0x0000) | 2 bytes ----------------------------------------------- | member-value-length (value is x) | 2 bytes ----------------------------------------------- | member-value | x bytes ----------------------------------------------- Figure 7: Member Attribute Encoding A "member-attribute" is encoded with eight subfields: o The "value-tag" field specifies 0x4a for the attribute syntax 'memberAttrName'. o The "name-length" field has the value of 0 in order to signify that it is a "member-attribute" contained in the collection. o The "value-length" field specifies the length of the "value" field in bytes, e.g., w in the above diagram or 10 for the member attribute name 'media-type'. Additional member attribute values are specified using a value length of 0. o The "value" field contains the name of the member attribute, e.g., the textual value 'media-type'. o The "member-value-tag" field specifies the attribute syntax for the member attribute, e.g., 0x44 for the attribute syntax 'keyword'.
o The second "name-length" field has the value of 0 in order to signify that it is a "member-attribute" contained in the collection. o The "member-value-length" field specifies the length of the member attribute value, e.g., x in the above diagram or 10 for the value 'stationery'. o The "member-value" field contains the value of the attribute, e.g., the textual value 'stationery'.3.1.8. 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 ----------------------------------------------- Figure 8: Encoding Based on Value Tags The following shows what fields the parser would expect after each type of "tag": o "begin-attribute-group-tag": expect zero or more "attribute" fields o "value-tag": expect the remainder of an "attribute-with-one-value" or an "additional-value" o "end-of-attributes-tag": expect that "attribute" fields are complete and there is optional "data"
3.2. Syntax of Encoding
The ABNF [RFC5234] syntax for an IPP message is shown in Figure 9. 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 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 status-code = SIGNED-SHORT ; mapping from model request-id = SIGNED-INTEGER ; whose value is > 0 attribute-group = begin-attribute-group-tag *attribute 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.5.2 begin-attribute-group-tag = %x00-02 / %x04-0f ; see Section 3.5.1 end-of-attributes-tag = %x03 ; tag of 3 ; see Section 3.5.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 Figure 9: ABNF of IPP Message Format
Figure 10 defines additional terms that are referenced in this document and provides an alternate grouping of the delimiter tags. delimiter-tag = begin-attribute-group-tag / ; see Section 3.5.1 end-of-attributes-tag begin-attribute-group-tag = %x00 / operation-attributes-tag / job-attributes-tag / printer-attributes-tag / unsupported-attributes-tag / future-group-tags operation-attributes-tag = %x01 ; tag of 1 job-attributes-tag = %x02 ; tag of 2 end-of-attributes-tag = %x03 ; tag of 3 printer-attributes-tag = %x04 ; tag of 4 unsupported-attributes-tag = %x05 ; tag of 5 future-group-tags = %x06-0f ; future extensions Figure 10: ABNF for Attribute Group Tags3.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.
Table 1 maps the Model group name to value of the "begin-attribute- group-tag" field: +----------------+--------------------------------------------------+ | Model Document | "begin-attribute-group-tag" field values | | Group | | +----------------+--------------------------------------------------+ | Operation | "operations-attributes-tag" | | Attributes | | +----------------+--------------------------------------------------+ | Job Template | "job-attributes-tag" | | Attributes | | +----------------+--------------------------------------------------+ | Job Object | "job-attributes-tag" | | Attributes | | +----------------+--------------------------------------------------+ | Unsupported | "unsupported-attributes-tag" | | Attributes | | +----------------+--------------------------------------------------+ | Requested | (Get-Job-Attributes) "job-attributes-tag" | | Attributes | | +----------------+--------------------------------------------------+ | Requested | (Get-Printer-Attributes)"printer-attributes-tag" | | Attributes | | +----------------+--------------------------------------------------+ | Document | in a special position at the end of the message | | Content | as described in Section 3.1.1. | +----------------+--------------------------------------------------+ Table 1: Group Values For each operation request and response, the Model prescribes the required and optional attribute groups, along with their order. Within each attribute group, the Model prescribes the required and optional attributes, along with their order. When the Model 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, 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: a. A "begin-attribute-group-tag" field with zero following "attribute" fields. b. A missing, but expected, "begin-attribute-group-tag" field. When the Model 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, 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.