+++ /dev/null
-Caching Code
- Successful 2xx
-c 200 OK
- 201 Created
- 202 Accepted
-c 203 Non-Authoritative Information *
-E 204 No Content
- 205 Reset Content *
- 206 Partial Content *
- Redirection 3xx
-C 300 Multiple Choices
-C 301 Moved Permanently
-t 302 Moved Temporarily
-- 303 See Other *
-- 304 Not Modified
-E 305 Use Proxy (proxy redirect) *
- Client Error 4xx
-E 400 Bad Request
-- 401 Unauthorized
- 402 Payment Required *
-E 403 Forbidden
-E 404 Not Found
-E 405 Method Not Allowed *
- 406 Not Acceptable *
-- 407 Proxy Authentication Required *
- 408 Request Timeout *
- 409 Conflict *
-C 410 Gone *
- 411 Length Required *
- 412 Precondition Failed *
- 413 Request Entity To Large *
-E 414 Request-URI Too Long *
- 415 Unsupported Media Type
- Server Error 5xx
-E 500 Internal Server Error
-E 501 Not Implemented
-E 502 Bad Gateway
-E 503 Service Unavailable
-E 504 Gateway Timeout *
- 505 HTTP Version Not Supported *
-
-Notes:
-* HTTP 1.1
-c Cached unless a query response without expiry information
-C Cached
-E Negatively cached if no expiry headers
-t Cached only if expiry information
-- Not cached
-
-Unless other said, the response code is not cached.
+++ /dev/null
-draft-ietf-radext-digest-auth-06.txt
- RADIUS Extension for Digest Authentication
- A proposed extension to Radius for Digest authentication
- via RADIUS servers.
-
-draft-cooper-webi-wpad-00.txt
-draft-ietf-svrloc-wpad-template-00.txt
- Web Proxy Auto-Discovery Protocol -- WPAD
- documents how MSIE and several other browsers automatically
- find their proxy settings from DHCP and/or DNS
-
-draft-forster-wrec-wccp-v1-00.txt
- WCCP 1.0
-
-draft-wilson-wccp-v2-12-oct-2001.txt
- WCCP 2.0
-
-draft-vinod-carp-v1-03.txt
- Microsoft CARP peering algorithm
-
-proxy-protocol.txt
- The PROXY protocol, Versions 1 & 2
-
-rfc0959.txt
- FTP
-
-rfc1035.txt
- DNS for IPv4
-
-rfc1157.txt
- A Simple Network Management Protocol (SNMP)
- SNMP v1 Specification. SNMP v2 is documented in several RFCs,
- namely, 1902,1903,1904,1905,1906,1907.
-
-rfc1738.txt
- Uniform Resource Locators (URL)
- (updated by RFC 3986, but not obsoleted)
-
-rfc1902.txt
- Structure of Managament Information (SMI) for SNMPv2
- Management information is viewed as a collection of managed objects,
- the Management Information Base (MIB). MIB modules are
- written using an adapted subset of OSI's Abstract Syntax
- Notation One (ASN.1). Purpose is to define that adapted subset.
-
-rfc1905.txt
- Protocol Operations for SNMPv2
- The management protocol provides for the exchange of messages
- which convey management information between the agents and the
- management stations.
-
-rfc1945.txt
- Hypertext Transfer Protocol -- HTTP/1.0
-
-rfc2186.txt
-rfc2187.txt
- Internet Cache Protocol (ICP), version 2
-
-rfc2181.txt
- Clarifications to the DNS Specification
- Squid uses a number of constants from the DNS and Host specifications
- (RFC 1035, RFC 1123) this defines details on their correct usage.
-
-rfc2227.txt
- Simple Hit-Metering and Usage-Limiting for HTTP
-
-rfc2428.txt
- FTP Extensions for IPv6 and NATs
-
-rfc2518.txt
-rfc4918.txt
- HTTP Extensions for Distributed Authoring -- WEBDAV
- Numerous extension methods to HTTP
-
-rfc2617.txt
- HTTP/1.1 Basic and Digest authentication
-
-rfc2756.txt
- Hyper Text Caching Protocol (HTCP/0.0)
- an alternative to ICP which will become more interesting the
- day Squid fully implements Vary + ETag
-
-rfc2817.txt
- Upgrading to TLS Within HTTP/1.1
- Not currently in use, but scheduled to replace https://
- Also Documents the CONNECT method
-
-rfc2818.txt
- HTTP Over TLS
- Documents the https:// scheme
-
-rfc2874.txt
- DNS Extensions to Support IPv6 Address Aggregation and Renumbering
- Documents IPv6 reverse DNS lookups.
-
-rfc2964.txt
- Use of HTTP State Management
- Cookies
-
-rfc2965.txt
- HTTP State Management Mechanism
- Cookies
-
-rfc3162.txt
- RADIUS and IPv6
- Documents the method of authentication for RADIUS when IPv6 addresses
- may be involved. Squid bundles a RADIUS auth helper.
-
-rfc3226.txt
- DNSSEC and IPv6 A6 aware server/resolver message size requirements
- Documents resolver requirements for IPv6 DNS structures and handling
- of advanced IPv6 lookups of A6 and DNAME records.
-
-rfc3310.txt
- Updated Digest specification
- Most likely not in use for HTTP. Title says HTTP but all examples
- is SIP.
-
-rfc3493.txt
- Basic Socket Interface Extensions for IPv6
- defines the socket options squid needs to use under IPv6
-
-rfc3507.txt
- Internet Content Adaptation Protocol (ICAP/1.0)
- Common protocol for plugging into the datastream of a HTTP proxy
-
-rfc3513.txt
- Internet Protocol Version 6 (IPv6) Addressing Architecture
- Documents handling requirements for IP addresses under IPv6
- and also new special case addresses defined by IANA.
-
-rfc3596.txt
- DNS Extensions to Support IP Version 6
- Documents AAAA record details for basic IPv6 DNS resolvers.
-
-rfc3875.txt
- CGI/1.1 specification
- used by cachemgr to get it's request arguments from the
- web server where it is hosted
-
-rfc3986.txt
- Uniform Resource Identifier (URI): Generic Syntax
- defines Syntax for parsing URI of any web protocol.
- updates URL generic syntax (rfc1738) to cover all URI formats
- including IPv6 addressing URL and additional protocols.
-
-rfc4001.txt
- Textual Conventions for Internet Network Addresses
- Details the IP protocol-neutral methods of representing peer
- and connection details for reporting via squid SNMP interface.
-
-rfc4559.txt
- HTTP Authentication: Kerberos Authentication
- Microsoft Negotiate "HTTP" authentication scheme
- Microsoft connection pinning HTTP extension to support
- connection oriented authentication over proxies
-
-rfc6585.txt
- Additional HTTP Status Codes
- 428 (Precondition Required),
- 429 (Too Many Requests),
- 431 (Request Header Fields Too Large),
- 511 (Network Authentication Required)
-
-rfc6762.txt
- Multicast DNS
- Details the DNS requirements on the Squid internal DNS client
- for resolving URLs in the .local domain.
-
-rfc7230.txt
- Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing
- Details the message 'frame' delimiters, first-line, and URL
- syntax, generic parsing rules, connection management, routing,
- and transfer encoding.
-
-rfc7231.txt
- Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
- Details the basic HTTP methods, headers and status code values
- and behaviour requirements imposed by each.
-
-rfc7232.txt
- Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests
- Last-Modified and Etag validator headers,
- If-* conditional headers,
- 304 and 412 status codes.
-
-rfc7233.txt
- Hypertext Transfer Protocol (HTTP/1.1): Range Requests
- Defines range requests and the rules for constructing and
- combining responses to those requests.
-
-rfc7234.txt
- Hypertext Transfer Protocol (HTTP/1.1): Caching
- Defines HTTP caches and the associated header fields that
- control cache behavior or indicate cacheable response messages.
-
-rfc7235.txt
- Hypertext Transfer Protocol (HTTP/1.1): Authentication
-
-rfc7239.txt
- Forwarded HTTP Extension
- Details the Forwarded: header replacement for X-Forwarded-For
- and other X-Forwarded-* variants
-
-rfc7538.txt
- The Hypertext Transfer Protocol Status Code 308 (Permanent Redirect)
-
-rfc7540.txt
- Hypertext Transfer Protocol Version 2 (HTTP/2)
- The PRI method, the 421 status code, and the HTTP2-Settings header
- semantics and syntax for HTTP/1.x messages.
- Details binary frame syntax and semantics for concurrent messaging.
-
-rfc8246.txt
- HTTP Immutable Responses
- Details the Cache-Control:immutable extension which indicates
- responses that can safely ignore client requested revalidation.
+++ /dev/null
-
-
-Network Working Group J. Postel
-Request for Comments: 959 J. Reynolds
- ISI
-Obsoletes RFC: 765 (IEN 149) October 1985
-
- FILE TRANSFER PROTOCOL (FTP)
-
-
-Status of this Memo
-
- This memo is the official specification of the File Transfer
- Protocol (FTP). Distribution of this memo is unlimited.
-
- The following new optional commands are included in this edition of
- the specification:
-
- CDUP (Change to Parent Directory), SMNT (Structure Mount), STOU
- (Store Unique), RMD (Remove Directory), MKD (Make Directory), PWD
- (Print Directory), and SYST (System).
-
- Note that this specification is compatible with the previous edition.
-
-1. INTRODUCTION
-
- The objectives of FTP are 1) to promote sharing of files (computer
- programs and/or data), 2) to encourage indirect or implicit (via
- programs) use of remote computers, 3) to shield a user from
- variations in file storage systems among hosts, and 4) to transfer
- data reliably and efficiently. FTP, though usable directly by a user
- at a terminal, is designed mainly for use by programs.
-
- The attempt in this specification is to satisfy the diverse needs of
- users of maxi-hosts, mini-hosts, personal workstations, and TACs,
- with a simple, and easily implemented protocol design.
-
- This paper assumes knowledge of the Transmission Control Protocol
- (TCP) [2] and the Telnet Protocol [3]. These documents are contained
- in the ARPA-Internet protocol handbook [1].
-
-2. OVERVIEW
-
- In this section, the history, the terminology, and the FTP model are
- discussed. The terms defined in this section are only those that
- have special significance in FTP. Some of the terminology is very
- specific to the FTP model; some readers may wish to turn to the
- section on the FTP model while reviewing the terminology.
-
-
-
-
-
-
-
-Postel & Reynolds [Page 1]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- 2.1. HISTORY
-
- FTP has had a long evolution over the years. Appendix III is a
- chronological compilation of Request for Comments documents
- relating to FTP. These include the first proposed file transfer
- mechanisms in 1971 that were developed for implementation on hosts
- at M.I.T. (RFC 114), plus comments and discussion in RFC 141.
-
- RFC 172 provided a user-level oriented protocol for file transfer
- between host computers (including terminal IMPs). A revision of
- this as RFC 265, restated FTP for additional review, while RFC 281
- suggested further changes. The use of a "Set Data Type"
- transaction was proposed in RFC 294 in January 1982.
-
- RFC 354 obsoleted RFCs 264 and 265. The File Transfer Protocol
- was now defined as a protocol for file transfer between HOSTs on
- the ARPANET, with the primary function of FTP defined as
- transfering files efficiently and reliably among hosts and
- allowing the convenient use of remote file storage capabilities.
- RFC 385 further commented on errors, emphasis points, and
- additions to the protocol, while RFC 414 provided a status report
- on the working server and user FTPs. RFC 430, issued in 1973,
- (among other RFCs too numerous to mention) presented further
- comments on FTP. Finally, an "official" FTP document was
- published as RFC 454.
-
- By July 1973, considerable changes from the last versions of FTP
- were made, but the general structure remained the same. RFC 542
- was published as a new "official" specification to reflect these
- changes. However, many implementations based on the older
- specification were not updated.
-
- In 1974, RFCs 607 and 614 continued comments on FTP. RFC 624
- proposed further design changes and minor modifications. In 1975,
- RFC 686 entitled, "Leaving Well Enough Alone", discussed the
- differences between all of the early and later versions of FTP.
- RFC 691 presented a minor revision of RFC 686, regarding the
- subject of print files.
-
- Motivated by the transition from the NCP to the TCP as the
- underlying protocol, a phoenix was born out of all of the above
- efforts in RFC 765 as the specification of FTP for use on TCP.
-
- This current edition of the FTP specification is intended to
- correct some minor documentation errors, to improve the
- explanation of some protocol features, and to add some new
- optional commands.
-
-
-Postel & Reynolds [Page 2]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- In particular, the following new optional commands are included in
- this edition of the specification:
-
- CDUP - Change to Parent Directory
-
- SMNT - Structure Mount
-
- STOU - Store Unique
-
- RMD - Remove Directory
-
- MKD - Make Directory
-
- PWD - Print Directory
-
- SYST - System
-
- This specification is compatible with the previous edition. A
- program implemented in conformance to the previous specification
- should automatically be in conformance to this specification.
-
- 2.2. TERMINOLOGY
-
- ASCII
-
- The ASCII character set is as defined in the ARPA-Internet
- Protocol Handbook. In FTP, ASCII characters are defined to be
- the lower half of an eight-bit code set (i.e., the most
- significant bit is zero).
-
- access controls
-
- Access controls define users' access privileges to the use of a
- system, and to the files in that system. Access controls are
- necessary to prevent unauthorized or accidental use of files.
- It is the prerogative of a server-FTP process to invoke access
- controls.
-
- byte size
-
- There are two byte sizes of interest in FTP: the logical byte
- size of the file, and the transfer byte size used for the
- transmission of the data. The transfer byte size is always 8
- bits. The transfer byte size is not necessarily the byte size
- in which data is to be stored in a system, nor the logical byte
- size for interpretation of the structure of the data.
-
-
-
-Postel & Reynolds [Page 3]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- control connection
-
- The communication path between the USER-PI and SERVER-PI for
- the exchange of commands and replies. This connection follows
- the Telnet Protocol.
-
- data connection
-
- A full duplex connection over which data is transferred, in a
- specified mode and type. The data transferred may be a part of
- a file, an entire file or a number of files. The path may be
- between a server-DTP and a user-DTP, or between two
- server-DTPs.
-
- data port
-
- The passive data transfer process "listens" on the data port
- for a connection from the active transfer process in order to
- open the data connection.
-
- DTP
-
- The data transfer process establishes and manages the data
- connection. The DTP can be passive or active.
-
- End-of-Line
-
- The end-of-line sequence defines the separation of printing
- lines. The sequence is Carriage Return, followed by Line Feed.
-
- EOF
-
- The end-of-file condition that defines the end of a file being
- transferred.
-
- EOR
-
- The end-of-record condition that defines the end of a record
- being transferred.
-
- error recovery
-
- A procedure that allows a user to recover from certain errors
- such as failure of either host system or transfer process. In
- FTP, error recovery may involve restarting a file transfer at a
- given checkpoint.
-
-
-
-Postel & Reynolds [Page 4]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- FTP commands
-
- A set of commands that comprise the control information flowing
- from the user-FTP to the server-FTP process.
-
- file
-
- An ordered set of computer data (including programs), of
- arbitrary length, uniquely identified by a pathname.
-
- mode
-
- The mode in which data is to be transferred via the data
- connection. The mode defines the data format during transfer
- including EOR and EOF. The transfer modes defined in FTP are
- described in the Section on Transmission Modes.
-
- NVT
-
- The Network Virtual Terminal as defined in the Telnet Protocol.
-
- NVFS
-
- The Network Virtual File System. A concept which defines a
- standard network file system with standard commands and
- pathname conventions.
-
- page
-
- A file may be structured as a set of independent parts called
- pages. FTP supports the transmission of discontinuous files as
- independent indexed pages.
-
- pathname
-
- Pathname is defined to be the character string which must be
- input to a file system by a user in order to identify a file.
- Pathname normally contains device and/or directory names, and
- file name specification. FTP does not yet specify a standard
- pathname convention. Each user must follow the file naming
- conventions of the file systems involved in the transfer.
-
- PI
-
- The protocol interpreter. The user and server sides of the
- protocol have distinct roles implemented in a user-PI and a
- server-PI.
-
-
-Postel & Reynolds [Page 5]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- record
-
- A sequential file may be structured as a number of contiguous
- parts called records. Record structures are supported by FTP
- but a file need not have record structure.
-
- reply
-
- A reply is an acknowledgment (positive or negative) sent from
- server to user via the control connection in response to FTP
- commands. The general form of a reply is a completion code
- (including error codes) followed by a text string. The codes
- are for use by programs and the text is usually intended for
- human users.
-
- server-DTP
-
- The data transfer process, in its normal "active" state,
- establishes the data connection with the "listening" data port.
- It sets up parameters for transfer and storage, and transfers
- data on command from its PI. The DTP can be placed in a
- "passive" state to listen for, rather than initiate a
- connection on the data port.
-
- server-FTP process
-
- A process or set of processes which perform the function of
- file transfer in cooperation with a user-FTP process and,
- possibly, another server. The functions consist of a protocol
- interpreter (PI) and a data transfer process (DTP).
-
- server-PI
-
- The server protocol interpreter "listens" on Port L for a
- connection from a user-PI and establishes a control
- communication connection. It receives standard FTP commands
- from the user-PI, sends replies, and governs the server-DTP.
-
- type
-
- The data representation type used for data transfer and
- storage. Type implies certain transformations between the time
- of data storage and data transfer. The representation types
- defined in FTP are described in the Section on Establishing
- Data Connections.
-
-
-
-
-Postel & Reynolds [Page 6]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- user
-
- A person or a process on behalf of a person wishing to obtain
- file transfer service. The human user may interact directly
- with a server-FTP process, but use of a user-FTP process is
- preferred since the protocol design is weighted towards
- automata.
-
- user-DTP
-
- The data transfer process "listens" on the data port for a
- connection from a server-FTP process. If two servers are
- transferring data between them, the user-DTP is inactive.
-
- user-FTP process
-
- A set of functions including a protocol interpreter, a data
- transfer process and a user interface which together perform
- the function of file transfer in cooperation with one or more
- server-FTP processes. The user interface allows a local
- language to be used in the command-reply dialogue with the
- user.
-
- user-PI
-
- The user protocol interpreter initiates the control connection
- from its port U to the server-FTP process, initiates FTP
- commands, and governs the user-DTP if that process is part of
- the file transfer.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 7]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- 2.3. THE FTP MODEL
-
- With the above definitions in mind, the following model (shown in
- Figure 1) may be diagrammed for an FTP service.
-
- -------------
- |/---------\|
- || User || --------
- ||Interface|<--->| User |
- |\----^----/| --------
- ---------- | | |
- |/------\| FTP Commands |/----V----\|
- ||Server|<---------------->| User ||
- || PI || FTP Replies || PI ||
- |\--^---/| |\----^----/|
- | | | | | |
- -------- |/--V---\| Data |/----V----\| --------
- | File |<--->|Server|<---------------->| User |<--->| File |
- |System| || DTP || Connection || DTP || |System|
- -------- |\------/| |\---------/| --------
- ---------- -------------
-
- Server-FTP USER-FTP
-
- NOTES: 1. The data connection may be used in either direction.
- 2. The data connection need not exist all of the time.
-
- Figure 1 Model for FTP Use
-
- In the model described in Figure 1, the user-protocol interpreter
- initiates the control connection. The control connection follows
- the Telnet protocol. At the initiation of the user, standard FTP
- commands are generated by the user-PI and transmitted to the
- server process via the control connection. (The user may
- establish a direct control connection to the server-FTP, from a
- TAC terminal for example, and generate standard FTP commands
- independently, bypassing the user-FTP process.) Standard replies
- are sent from the server-PI to the user-PI over the control
- connection in response to the commands.
-
- The FTP commands specify the parameters for the data connection
- (data port, transfer mode, representation type, and structure) and
- the nature of file system operation (store, retrieve, append,
- delete, etc.). The user-DTP or its designate should "listen" on
- the specified data port, and the server initiate the data
- connection and data transfer in accordance with the specified
- parameters. It should be noted that the data port need not be in
-
-
-Postel & Reynolds [Page 8]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- the same host that initiates the FTP commands via the control
- connection, but the user or the user-FTP process must ensure a
- "listen" on the specified data port. It ought to also be noted
- that the data connection may be used for simultaneous sending and
- receiving.
-
- In another situation a user might wish to transfer files between
- two hosts, neither of which is a local host. The user sets up
- control connections to the two servers and then arranges for a
- data connection between them. In this manner, control information
- is passed to the user-PI but data is transferred between the
- server data transfer processes. Following is a model of this
- server-server interaction.
-
-
- Control ------------ Control
- ---------->| User-FTP |<-----------
- | | User-PI | |
- | | "C" | |
- V ------------ V
- -------------- --------------
- | Server-FTP | Data Connection | Server-FTP |
- | "A" |<---------------------->| "B" |
- -------------- Port (A) Port (B) --------------
-
-
- Figure 2
-
- The protocol requires that the control connections be open while
- data transfer is in progress. It is the responsibility of the
- user to request the closing of the control connections when
- finished using the FTP service, while it is the server who takes
- the action. The server may abort data transfer if the control
- connections are closed without command.
-
- The Relationship between FTP and Telnet:
-
- The FTP uses the Telnet protocol on the control connection.
- This can be achieved in two ways: first, the user-PI or the
- server-PI may implement the rules of the Telnet Protocol
- directly in their own procedures; or, second, the user-PI or
- the server-PI may make use of the existing Telnet module in the
- system.
-
- Ease of implementaion, sharing code, and modular programming
- argue for the second approach. Efficiency and independence
-
-
-
-Postel & Reynolds [Page 9]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- argue for the first approach. In practice, FTP relies on very
- little of the Telnet Protocol, so the first approach does not
- necessarily involve a large amount of code.
-
-3. DATA TRANSFER FUNCTIONS
-
- Files are transferred only via the data connection. The control
- connection is used for the transfer of commands, which describe the
- functions to be performed, and the replies to these commands (see the
- Section on FTP Replies). Several commands are concerned with the
- transfer of data between hosts. These data transfer commands include
- the MODE command which specify how the bits of the data are to be
- transmitted, and the STRUcture and TYPE commands, which are used to
- define the way in which the data are to be represented. The
- transmission and representation are basically independent but the
- "Stream" transmission mode is dependent on the file structure
- attribute and if "Compressed" transmission mode is used, the nature
- of the filler byte depends on the representation type.
-
- 3.1. DATA REPRESENTATION AND STORAGE
-
- Data is transferred from a storage device in the sending host to a
- storage device in the receiving host. Often it is necessary to
- perform certain transformations on the data because data storage
- representations in the two systems are different. For example,
- NVT-ASCII has different data storage representations in different
- systems. DEC TOPS-20s's generally store NVT-ASCII as five 7-bit
- ASCII characters, left-justified in a 36-bit word. IBM Mainframe's
- store NVT-ASCII as 8-bit EBCDIC codes. Multics stores NVT-ASCII
- as four 9-bit characters in a 36-bit word. It is desirable to
- convert characters into the standard NVT-ASCII representation when
- transmitting text between dissimilar systems. The sending and
- receiving sites would have to perform the necessary
- transformations between the standard representation and their
- internal representations.
-
- A different problem in representation arises when transmitting
- binary data (not character codes) between host systems with
- different word lengths. It is not always clear how the sender
- should send data, and the receiver store it. For example, when
- transmitting 32-bit bytes from a 32-bit word-length system to a
- 36-bit word-length system, it may be desirable (for reasons of
- efficiency and usefulness) to store the 32-bit bytes
- right-justified in a 36-bit word in the latter system. In any
- case, the user should have the option of specifying data
- representation and transformation functions. It should be noted
-
-
-
-Postel & Reynolds [Page 10]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- that FTP provides for very limited data type representations.
- Transformations desired beyond this limited capability should be
- performed by the user directly.
-
- 3.1.1. DATA TYPES
-
- Data representations are handled in FTP by a user specifying a
- representation type. This type may implicitly (as in ASCII or
- EBCDIC) or explicitly (as in Local byte) define a byte size for
- interpretation which is referred to as the "logical byte size."
- Note that this has nothing to do with the byte size used for
- transmission over the data connection, called the "transfer
- byte size", and the two should not be confused. For example,
- NVT-ASCII has a logical byte size of 8 bits. If the type is
- Local byte, then the TYPE command has an obligatory second
- parameter specifying the logical byte size. The transfer byte
- size is always 8 bits.
-
- 3.1.1.1. ASCII TYPE
-
- This is the default type and must be accepted by all FTP
- implementations. It is intended primarily for the transfer
- of text files, except when both hosts would find the EBCDIC
- type more convenient.
-
- The sender converts the data from an internal character
- representation to the standard 8-bit NVT-ASCII
- representation (see the Telnet specification). The receiver
- will convert the data from the standard form to his own
- internal form.
-
- In accordance with the NVT standard, the <CRLF> sequence
- should be used where necessary to denote the end of a line
- of text. (See the discussion of file structure at the end
- of the Section on Data Representation and Storage.)
-
- Using the standard NVT-ASCII representation means that data
- must be interpreted as 8-bit bytes.
-
- The Format parameter for ASCII and EBCDIC types is discussed
- below.
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 11]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- 3.1.1.2. EBCDIC TYPE
-
- This type is intended for efficient transfer between hosts
- which use EBCDIC for their internal character
- representation.
-
- For transmission, the data are represented as 8-bit EBCDIC
- characters. The character code is the only difference
- between the functional specifications of EBCDIC and ASCII
- types.
-
- End-of-line (as opposed to end-of-record--see the discussion
- of structure) will probably be rarely used with EBCDIC type
- for purposes of denoting structure, but where it is
- necessary the <NL> character should be used.
-
- 3.1.1.3. IMAGE TYPE
-
- The data are sent as contiguous bits which, for transfer,
- are packed into the 8-bit transfer bytes. The receiving
- site must store the data as contiguous bits. The structure
- of the storage system might necessitate the padding of the
- file (or of each record, for a record-structured file) to
- some convenient boundary (byte, word or block). This
- padding, which must be all zeros, may occur only at the end
- of the file (or at the end of each record) and there must be
- a way of identifying the padding bits so that they may be
- stripped off if the file is retrieved. The padding
- transformation should be well publicized to enable a user to
- process a file at the storage site.
-
- Image type is intended for the efficient storage and
- retrieval of files and for the transfer of binary data. It
- is recommended that this type be accepted by all FTP
- implementations.
-
- 3.1.1.4. LOCAL TYPE
-
- The data is transferred in logical bytes of the size
- specified by the obligatory second parameter, Byte size.
- The value of Byte size must be a decimal integer; there is
- no default value. The logical byte size is not necessarily
- the same as the transfer byte size. If there is a
- difference in byte sizes, then the logical bytes should be
- packed contiguously, disregarding transfer byte boundaries
- and with any necessary padding at the end.
-
-
-
-Postel & Reynolds [Page 12]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- When the data reaches the receiving host, it will be
- transformed in a manner dependent on the logical byte size
- and the particular host. This transformation must be
- invertible (i.e., an identical file can be retrieved if the
- same parameters are used) and should be well publicized by
- the FTP implementors.
-
- For example, a user sending 36-bit floating-point numbers to
- a host with a 32-bit word could send that data as Local byte
- with a logical byte size of 36. The receiving host would
- then be expected to store the logical bytes so that they
- could be easily manipulated; in this example putting the
- 36-bit logical bytes into 64-bit double words should
- suffice.
-
- In another example, a pair of hosts with a 36-bit word size
- may send data to one another in words by using TYPE L 36.
- The data would be sent in the 8-bit transmission bytes
- packed so that 9 transmission bytes carried two host words.
-
- 3.1.1.5. FORMAT CONTROL
-
- The types ASCII and EBCDIC also take a second (optional)
- parameter; this is to indicate what kind of vertical format
- control, if any, is associated with a file. The following
- data representation types are defined in FTP:
-
- A character file may be transferred to a host for one of
- three purposes: for printing, for storage and later
- retrieval, or for processing. If a file is sent for
- printing, the receiving host must know how the vertical
- format control is represented. In the second case, it must
- be possible to store a file at a host and then retrieve it
- later in exactly the same form. Finally, it should be
- possible to move a file from one host to another and process
- the file at the second host without undue trouble. A single
- ASCII or EBCDIC format does not satisfy all these
- conditions. Therefore, these types have a second parameter
- specifying one of the following three formats:
-
- 3.1.1.5.1. NON PRINT
-
- This is the default format to be used if the second
- (format) parameter is omitted. Non-print format must be
- accepted by all FTP implementations.
-
-
-
-
-Postel & Reynolds [Page 13]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- The file need contain no vertical format information. If
- it is passed to a printer process, this process may
- assume standard values for spacing and margins.
-
- Normally, this format will be used with files destined
- for processing or just storage.
-
- 3.1.1.5.2. TELNET FORMAT CONTROLS
-
- The file contains ASCII/EBCDIC vertical format controls
- (i.e., <CR>, <LF>, <NL>, <VT>, <FF>) which the printer
- process will interpret appropriately. <CRLF>, in exactly
- this sequence, also denotes end-of-line.
-
- 3.1.1.5.2. CARRIAGE CONTROL (ASA)
-
- The file contains ASA (FORTRAN) vertical format control
- characters. (See RFC 740 Appendix C; and Communications
- of the ACM, Vol. 7, No. 10, p. 606, October 1964.) In a
- line or a record formatted according to the ASA Standard,
- the first character is not to be printed. Instead, it
- should be used to determine the vertical movement of the
- paper which should take place before the rest of the
- record is printed.
-
- The ASA Standard specifies the following control
- characters:
-
- Character Vertical Spacing
-
- blank Move paper up one line
- 0 Move paper up two lines
- 1 Move paper to top of next page
- + No movement, i.e., overprint
-
- Clearly there must be some way for a printer process to
- distinguish the end of the structural entity. If a file
- has record structure (see below) this is no problem;
- records will be explicitly marked during transfer and
- storage. If the file has no record structure, the <CRLF>
- end-of-line sequence is used to separate printing lines,
- but these format effectors are overridden by the ASA
- controls.
-
-
-
-
-
-
-Postel & Reynolds [Page 14]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- 3.1.2. DATA STRUCTURES
-
- In addition to different representation types, FTP allows the
- structure of a file to be specified. Three file structures are
- defined in FTP:
-
- file-structure, where there is no internal structure and
- the file is considered to be a
- continuous sequence of data bytes,
-
- record-structure, where the file is made up of sequential
- records,
-
- and page-structure, where the file is made up of independent
- indexed pages.
-
- File-structure is the default to be assumed if the STRUcture
- command has not been used but both file and record structures
- must be accepted for "text" files (i.e., files with TYPE ASCII
- or EBCDIC) by all FTP implementations. The structure of a file
- will affect both the transfer mode of a file (see the Section
- on Transmission Modes) and the interpretation and storage of
- the file.
-
- The "natural" structure of a file will depend on which host
- stores the file. A source-code file will usually be stored on
- an IBM Mainframe in fixed length records but on a DEC TOPS-20
- as a stream of characters partitioned into lines, for example
- by <CRLF>. If the transfer of files between such disparate
- sites is to be useful, there must be some way for one site to
- recognize the other's assumptions about the file.
-
- With some sites being naturally file-oriented and others
- naturally record-oriented there may be problems if a file with
- one structure is sent to a host oriented to the other. If a
- text file is sent with record-structure to a host which is file
- oriented, then that host should apply an internal
- transformation to the file based on the record structure.
- Obviously, this transformation should be useful, but it must
- also be invertible so that an identical file may be retrieved
- using record structure.
-
- In the case of a file being sent with file-structure to a
- record-oriented host, there exists the question of what
- criteria the host should use to divide the file into records
- which can be processed locally. If this division is necessary,
- the FTP implementation should use the end-of-line sequence,
-
-
-Postel & Reynolds [Page 15]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- <CRLF> for ASCII, or <NL> for EBCDIC text files, as the
- delimiter. If an FTP implementation adopts this technique, it
- must be prepared to reverse the transformation if the file is
- retrieved with file-structure.
-
- 3.1.2.1. FILE STRUCTURE
-
- File structure is the default to be assumed if the STRUcture
- command has not been used.
-
- In file-structure there is no internal structure and the
- file is considered to be a continuous sequence of data
- bytes.
-
- 3.1.2.2. RECORD STRUCTURE
-
- Record structures must be accepted for "text" files (i.e.,
- files with TYPE ASCII or EBCDIC) by all FTP implementations.
-
- In record-structure the file is made up of sequential
- records.
-
- 3.1.2.3. PAGE STRUCTURE
-
- To transmit files that are discontinuous, FTP defines a page
- structure. Files of this type are sometimes known as
- "random access files" or even as "holey files". In these
- files there is sometimes other information associated with
- the file as a whole (e.g., a file descriptor), or with a
- section of the file (e.g., page access controls), or both.
- In FTP, the sections of the file are called pages.
-
- To provide for various page sizes and associated
- information, each page is sent with a page header. The page
- header has the following defined fields:
-
- Header Length
-
- The number of logical bytes in the page header
- including this byte. The minimum header length is 4.
-
- Page Index
-
- The logical page number of this section of the file.
- This is not the transmission sequence number of this
- page, but the index used to identify this page of the
- file.
-
-
-Postel & Reynolds [Page 16]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- Data Length
-
- The number of logical bytes in the page data. The
- minimum data length is 0.
-
- Page Type
-
- The type of page this is. The following page types
- are defined:
-
- 0 = Last Page
-
- This is used to indicate the end of a paged
- structured transmission. The header length must
- be 4, and the data length must be 0.
-
- 1 = Simple Page
-
- This is the normal type for simple paged files
- with no page level associated control
- information. The header length must be 4.
-
- 2 = Descriptor Page
-
- This type is used to transmit the descriptive
- information for the file as a whole.
-
- 3 = Access Controlled Page
-
- This type includes an additional header field
- for paged files with page level access control
- information. The header length must be 5.
-
- Optional Fields
-
- Further header fields may be used to supply per page
- control information, for example, per page access
- control.
-
- All fields are one logical byte in length. The logical byte
- size is specified by the TYPE command. See Appendix I for
- further details and a specific case at the page structure.
-
- A note of caution about parameters: a file must be stored and
- retrieved with the same parameters if the retrieved version is to
-
-
-
-
-Postel & Reynolds [Page 17]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- be identical to the version originally transmitted. Conversely,
- FTP implementations must return a file identical to the original
- if the parameters used to store and retrieve a file are the same.
-
- 3.2. ESTABLISHING DATA CONNECTIONS
-
- The mechanics of transferring data consists of setting up the data
- connection to the appropriate ports and choosing the parameters
- for transfer. Both the user and the server-DTPs have a default
- data port. The user-process default data port is the same as the
- control connection port (i.e., U). The server-process default
- data port is the port adjacent to the control connection port
- (i.e., L-1).
-
- The transfer byte size is 8-bit bytes. This byte size is relevant
- only for the actual transfer of the data; it has no bearing on
- representation of the data within a host's file system.
-
- The passive data transfer process (this may be a user-DTP or a
- second server-DTP) shall "listen" on the data port prior to
- sending a transfer request command. The FTP request command
- determines the direction of the data transfer. The server, upon
- receiving the transfer request, will initiate the data connection
- to the port. When the connection is established, the data
- transfer begins between DTP's, and the server-PI sends a
- confirming reply to the user-PI.
-
- Every FTP implementation must support the use of the default data
- ports, and only the USER-PI can initiate a change to non-default
- ports.
-
- It is possible for the user to specify an alternate data port by
- use of the PORT command. The user may want a file dumped on a TAC
- line printer or retrieved from a third party host. In the latter
- case, the user-PI sets up control connections with both
- server-PI's. One server is then told (by an FTP command) to
- "listen" for a connection which the other will initiate. The
- user-PI sends one server-PI a PORT command indicating the data
- port of the other. Finally, both are sent the appropriate
- transfer commands. The exact sequence of commands and replies
- sent between the user-controller and the servers is defined in the
- Section on FTP Replies.
-
- In general, it is the server's responsibility to maintain the data
- connection--to initiate it and to close it. The exception to this
-
-
-
-
-Postel & Reynolds [Page 18]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- is when the user-DTP is sending the data in a transfer mode that
- requires the connection to be closed to indicate EOF. The server
- MUST close the data connection under the following conditions:
-
- 1. The server has completed sending data in a transfer mode
- that requires a close to indicate EOF.
-
- 2. The server receives an ABORT command from the user.
-
- 3. The port specification is changed by a command from the
- user.
-
- 4. The control connection is closed legally or otherwise.
-
- 5. An irrecoverable error condition occurs.
-
- Otherwise the close is a server option, the exercise of which the
- server must indicate to the user-process by either a 250 or 226
- reply only.
-
- 3.3. DATA CONNECTION MANAGEMENT
-
- Default Data Connection Ports: All FTP implementations must
- support use of the default data connection ports, and only the
- User-PI may initiate the use of non-default ports.
-
- Negotiating Non-Default Data Ports: The User-PI may specify a
- non-default user side data port with the PORT command. The
- User-PI may request the server side to identify a non-default
- server side data port with the PASV command. Since a connection
- is defined by the pair of addresses, either of these actions is
- enough to get a different data connection, still it is permitted
- to do both commands to use new ports on both ends of the data
- connection.
-
- Reuse of the Data Connection: When using the stream mode of data
- transfer the end of the file must be indicated by closing the
- connection. This causes a problem if multiple files are to be
- transfered in the session, due to need for TCP to hold the
- connection record for a time out period to guarantee the reliable
- communication. Thus the connection can not be reopened at once.
-
- There are two solutions to this problem. The first is to
- negotiate a non-default port. The second is to use another
- transfer mode.
-
- A comment on transfer modes. The stream transfer mode is
-
-
-Postel & Reynolds [Page 19]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- inherently unreliable, since one can not determine if the
- connection closed prematurely or not. The other transfer modes
- (Block, Compressed) do not close the connection to indicate the
- end of file. They have enough FTP encoding that the data
- connection can be parsed to determine the end of the file.
- Thus using these modes one can leave the data connection open
- for multiple file transfers.
-
- 3.4. TRANSMISSION MODES
-
- The next consideration in transferring data is choosing the
- appropriate transmission mode. There are three modes: one which
- formats the data and allows for restart procedures; one which also
- compresses the data for efficient transfer; and one which passes
- the data with little or no processing. In this last case the mode
- interacts with the structure attribute to determine the type of
- processing. In the compressed mode, the representation type
- determines the filler byte.
-
- All data transfers must be completed with an end-of-file (EOF)
- which may be explicitly stated or implied by the closing of the
- data connection. For files with record structure, all the
- end-of-record markers (EOR) are explicit, including the final one.
- For files transmitted in page structure a "last-page" page type is
- used.
-
- NOTE: In the rest of this section, byte means "transfer byte"
- except where explicitly stated otherwise.
-
- For the purpose of standardized transfer, the sending host will
- translate its internal end of line or end of record denotation
- into the representation prescribed by the transfer mode and file
- structure, and the receiving host will perform the inverse
- translation to its internal denotation. An IBM Mainframe record
- count field may not be recognized at another host, so the
- end-of-record information may be transferred as a two byte control
- code in Stream mode or as a flagged bit in a Block or Compressed
- mode descriptor. End-of-line in an ASCII or EBCDIC file with no
- record structure should be indicated by <CRLF> or <NL>,
- respectively. Since these transformations imply extra work for
- some systems, identical systems transferring non-record structured
- text files might wish to use a binary representation and stream
- mode for the transfer.
-
-
-
-
-
-
-Postel & Reynolds [Page 20]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- The following transmission modes are defined in FTP:
-
- 3.4.1. STREAM MODE
-
- The data is transmitted as a stream of bytes. There is no
- restriction on the representation type used; record structures
- are allowed.
-
- In a record structured file EOR and EOF will each be indicated
- by a two-byte control code. The first byte of the control code
- will be all ones, the escape character. The second byte will
- have the low order bit on and zeros elsewhere for EOR and the
- second low order bit on for EOF; that is, the byte will have
- value 1 for EOR and value 2 for EOF. EOR and EOF may be
- indicated together on the last byte transmitted by turning both
- low order bits on (i.e., the value 3). If a byte of all ones
- was intended to be sent as data, it should be repeated in the
- second byte of the control code.
-
- If the structure is a file structure, the EOF is indicated by
- the sending host closing the data connection and all bytes are
- data bytes.
-
- 3.4.2. BLOCK MODE
-
- The file is transmitted as a series of data blocks preceded by
- one or more header bytes. The header bytes contain a count
- field, and descriptor code. The count field indicates the
- total length of the data block in bytes, thus marking the
- beginning of the next data block (there are no filler bits).
- The descriptor code defines: last block in the file (EOF) last
- block in the record (EOR), restart marker (see the Section on
- Error Recovery and Restart) or suspect data (i.e., the data
- being transferred is suspected of errors and is not reliable).
- This last code is NOT intended for error control within FTP.
- It is motivated by the desire of sites exchanging certain types
- of data (e.g., seismic or weather data) to send and receive all
- the data despite local errors (such as "magnetic tape read
- errors"), but to indicate in the transmission that certain
- portions are suspect). Record structures are allowed in this
- mode, and any representation type may be used.
-
- The header consists of the three bytes. Of the 24 bits of
- header information, the 16 low order bits shall represent byte
- count, and the 8 high order bits shall represent descriptor
- codes as shown below.
-
-
-
-Postel & Reynolds [Page 21]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- Block Header
-
- +----------------+----------------+----------------+
- | Descriptor | Byte Count |
- | 8 bits | 16 bits |
- +----------------+----------------+----------------+
-
-
- The descriptor codes are indicated by bit flags in the
- descriptor byte. Four codes have been assigned, where each
- code number is the decimal value of the corresponding bit in
- the byte.
-
- Code Meaning
-
- 128 End of data block is EOR
- 64 End of data block is EOF
- 32 Suspected errors in data block
- 16 Data block is a restart marker
-
- With this encoding, more than one descriptor coded condition
- may exist for a particular block. As many bits as necessary
- may be flagged.
-
- The restart marker is embedded in the data stream as an
- integral number of 8-bit bytes representing printable
- characters in the language being used over the control
- connection (e.g., default--NVT-ASCII). <SP> (Space, in the
- appropriate language) must not be used WITHIN a restart marker.
-
- For example, to transmit a six-character marker, the following
- would be sent:
-
- +--------+--------+--------+
- |Descrptr| Byte count |
- |code= 16| = 6 |
- +--------+--------+--------+
-
- +--------+--------+--------+
- | Marker | Marker | Marker |
- | 8 bits | 8 bits | 8 bits |
- +--------+--------+--------+
-
- +--------+--------+--------+
- | Marker | Marker | Marker |
- | 8 bits | 8 bits | 8 bits |
- +--------+--------+--------+
-
-
-Postel & Reynolds [Page 22]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- 3.4.3. COMPRESSED MODE
-
- There are three kinds of information to be sent: regular data,
- sent in a byte string; compressed data, consisting of
- replications or filler; and control information, sent in a
- two-byte escape sequence. If n>0 bytes (up to 127) of regular
- data are sent, these n bytes are preceded by a byte with the
- left-most bit set to 0 and the right-most 7 bits containing the
- number n.
-
- Byte string:
-
- 1 7 8 8
- +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
- |0| n | | d(1) | ... | d(n) |
- +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
- ^ ^
- |---n bytes---|
- of data
-
- String of n data bytes d(1),..., d(n)
- Count n must be positive.
-
- To compress a string of n replications of the data byte d, the
- following 2 bytes are sent:
-
- Replicated Byte:
-
- 2 6 8
- +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
- |1 0| n | | d |
- +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
-
- A string of n filler bytes can be compressed into a single
- byte, where the filler byte varies with the representation
- type. If the type is ASCII or EBCDIC the filler byte is <SP>
- (Space, ASCII code 32, EBCDIC code 64). If the type is Image
- or Local byte the filler is a zero byte.
-
- Filler String:
-
- 2 6
- +-+-+-+-+-+-+-+-+
- |1 1| n |
- +-+-+-+-+-+-+-+-+
-
- The escape sequence is a double byte, the first of which is the
-
-
-Postel & Reynolds [Page 23]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- escape byte (all zeros) and the second of which contains
- descriptor codes as defined in Block mode. The descriptor
- codes have the same meaning as in Block mode and apply to the
- succeeding string of bytes.
-
- Compressed mode is useful for obtaining increased bandwidth on
- very large network transmissions at a little extra CPU cost.
- It can be most effectively used to reduce the size of printer
- files such as those generated by RJE hosts.
-
- 3.5. ERROR RECOVERY AND RESTART
-
- There is no provision for detecting bits lost or scrambled in data
- transfer; this level of error control is handled by the TCP.
- However, a restart procedure is provided to protect users from
- gross system failures (including failures of a host, an
- FTP-process, or the underlying network).
-
- The restart procedure is defined only for the block and compressed
- modes of data transfer. It requires the sender of data to insert
- a special marker code in the data stream with some marker
- information. The marker information has meaning only to the
- sender, but must consist of printable characters in the default or
- negotiated language of the control connection (ASCII or EBCDIC).
- The marker could represent a bit-count, a record-count, or any
- other information by which a system may identify a data
- checkpoint. The receiver of data, if it implements the restart
- procedure, would then mark the corresponding position of this
- marker in the receiving system, and return this information to the
- user.
-
- In the event of a system failure, the user can restart the data
- transfer by identifying the marker point with the FTP restart
- procedure. The following example illustrates the use of the
- restart procedure.
-
- The sender of the data inserts an appropriate marker block in the
- data stream at a convenient point. The receiving host marks the
- corresponding data point in its file system and conveys the last
- known sender and receiver marker information to the user, either
- directly or over the control connection in a 110 reply (depending
- on who is the sender). In the event of a system failure, the user
- or controller process restarts the server at the last server
- marker by sending a restart command with server's marker code as
- its argument. The restart command is transmitted over the control
-
-
-
-
-Postel & Reynolds [Page 24]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- connection and is immediately followed by the command (such as
- RETR, STOR or LIST) which was being executed when the system
- failure occurred.
-
-4. FILE TRANSFER FUNCTIONS
-
- The communication channel from the user-PI to the server-PI is
- established as a TCP connection from the user to the standard server
- port. The user protocol interpreter is responsible for sending FTP
- commands and interpreting the replies received; the server-PI
- interprets commands, sends replies and directs its DTP to set up the
- data connection and transfer the data. If the second party to the
- data transfer (the passive transfer process) is the user-DTP, then it
- is governed through the internal protocol of the user-FTP host; if it
- is a second server-DTP, then it is governed by its PI on command from
- the user-PI. The FTP replies are discussed in the next section. In
- the description of a few of the commands in this section, it is
- helpful to be explicit about the possible replies.
-
- 4.1. FTP COMMANDS
-
- 4.1.1. ACCESS CONTROL COMMANDS
-
- The following commands specify access control identifiers
- (command codes are shown in parentheses).
-
- USER NAME (USER)
-
- The argument field is a Telnet string identifying the user.
- The user identification is that which is required by the
- server for access to its file system. This command will
- normally be the first command transmitted by the user after
- the control connections are made (some servers may require
- this). Additional identification information in the form of
- a password and/or an account command may also be required by
- some servers. Servers may allow a new USER command to be
- entered at any point in order to change the access control
- and/or accounting information. This has the effect of
- flushing any user, password, and account information already
- supplied and beginning the login sequence again. All
- transfer parameters are unchanged and any file transfer in
- progress is completed under the old access control
- parameters.
-
-
-
-
-
-
-Postel & Reynolds [Page 25]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- PASSWORD (PASS)
-
- The argument field is a Telnet string specifying the user's
- password. This command must be immediately preceded by the
- user name command, and, for some sites, completes the user's
- identification for access control. Since password
- information is quite sensitive, it is desirable in general
- to "mask" it or suppress typeout. It appears that the
- server has no foolproof way to achieve this. It is
- therefore the responsibility of the user-FTP process to hide
- the sensitive password information.
-
- ACCOUNT (ACCT)
-
- The argument field is a Telnet string identifying the user's
- account. The command is not necessarily related to the USER
- command, as some sites may require an account for login and
- others only for specific access, such as storing files. In
- the latter case the command may arrive at any time.
-
- There are reply codes to differentiate these cases for the
- automation: when account information is required for login,
- the response to a successful PASSword command is reply code
- 332. On the other hand, if account information is NOT
- required for login, the reply to a successful PASSword
- command is 230; and if the account information is needed for
- a command issued later in the dialogue, the server should
- return a 332 or 532 reply depending on whether it stores
- (pending receipt of the ACCounT command) or discards the
- command, respectively.
-
- CHANGE WORKING DIRECTORY (CWD)
-
- This command allows the user to work with a different
- directory or dataset for file storage or retrieval without
- altering his login or accounting information. Transfer
- parameters are similarly unchanged. The argument is a
- pathname specifying a directory or other system dependent
- file group designator.
-
- CHANGE TO PARENT DIRECTORY (CDUP)
-
- This command is a special case of CWD, and is included to
- simplify the implementation of programs for transferring
- directory trees between operating systems having different
-
-
-
-
-Postel & Reynolds [Page 26]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- syntaxes for naming the parent directory. The reply codes
- shall be identical to the reply codes of CWD. See
- Appendix II for further details.
-
- STRUCTURE MOUNT (SMNT)
-
- This command allows the user to mount a different file
- system data structure without altering his login or
- accounting information. Transfer parameters are similarly
- unchanged. The argument is a pathname specifying a
- directory or other system dependent file group designator.
-
- REINITIALIZE (REIN)
-
- This command terminates a USER, flushing all I/O and account
- information, except to allow any transfer in progress to be
- completed. All parameters are reset to the default settings
- and the control connection is left open. This is identical
- to the state in which a user finds himself immediately after
- the control connection is opened. A USER command may be
- expected to follow.
-
- LOGOUT (QUIT)
-
- This command terminates a USER and if file transfer is not
- in progress, the server closes the control connection. If
- file transfer is in progress, the connection will remain
- open for result response and the server will then close it.
- If the user-process is transferring files for several USERs
- but does not wish to close and then reopen connections for
- each, then the REIN command should be used instead of QUIT.
-
- An unexpected close on the control connection will cause the
- server to take the effective action of an abort (ABOR) and a
- logout (QUIT).
-
- 4.1.2. TRANSFER PARAMETER COMMANDS
-
- All data transfer parameters have default values, and the
- commands specifying data transfer parameters are required only
- if the default parameter values are to be changed. The default
- value is the last specified value, or if no value has been
- specified, the standard default value is as stated here. This
- implies that the server must "remember" the applicable default
- values. The commands may be in any order except that they must
- precede the FTP service request. The following commands
- specify data transfer parameters:
-
-
-Postel & Reynolds [Page 27]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- DATA PORT (PORT)
-
- The argument is a HOST-PORT specification for the data port
- to be used in data connection. There are defaults for both
- the user and server data ports, and under normal
- circumstances this command and its reply are not needed. If
- this command is used, the argument is the concatenation of a
- 32-bit internet host address and a 16-bit TCP port address.
- This address information is broken into 8-bit fields and the
- value of each field is transmitted as a decimal number (in
- character string representation). The fields are separated
- by commas. A port command would be:
-
- PORT h1,h2,h3,h4,p1,p2
-
- where h1 is the high order 8 bits of the internet host
- address.
-
- PASSIVE (PASV)
-
- This command requests the server-DTP to "listen" on a data
- port (which is not its default data port) and to wait for a
- connection rather than initiate one upon receipt of a
- transfer command. The response to this command includes the
- host and port address this server is listening on.
-
- REPRESENTATION TYPE (TYPE)
-
- The argument specifies the representation type as described
- in the Section on Data Representation and Storage. Several
- types take a second parameter. The first parameter is
- denoted by a single Telnet character, as is the second
- Format parameter for ASCII and EBCDIC; the second parameter
- for local byte is a decimal integer to indicate Bytesize.
- The parameters are separated by a <SP> (Space, ASCII code
- 32).
-
- The following codes are assigned for type:
-
- \ /
- A - ASCII | | N - Non-print
- |-><-| T - Telnet format effectors
- E - EBCDIC| | C - Carriage Control (ASA)
- / \
- I - Image
-
- L <byte size> - Local byte Byte size
-
-
-Postel & Reynolds [Page 28]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- The default representation type is ASCII Non-print. If the
- Format parameter is changed, and later just the first
- argument is changed, Format then returns to the Non-print
- default.
-
- FILE STRUCTURE (STRU)
-
- The argument is a single Telnet character code specifying
- file structure described in the Section on Data
- Representation and Storage.
-
- The following codes are assigned for structure:
-
- F - File (no record structure)
- R - Record structure
- P - Page structure
-
- The default structure is File.
-
- TRANSFER MODE (MODE)
-
- The argument is a single Telnet character code specifying
- the data transfer modes described in the Section on
- Transmission Modes.
-
- The following codes are assigned for transfer modes:
-
- S - Stream
- B - Block
- C - Compressed
-
- The default transfer mode is Stream.
-
- 4.1.3. FTP SERVICE COMMANDS
-
- The FTP service commands define the file transfer or the file
- system function requested by the user. The argument of an FTP
- service command will normally be a pathname. The syntax of
- pathnames must conform to server site conventions (with
- standard defaults applicable), and the language conventions of
- the control connection. The suggested default handling is to
- use the last specified device, directory or file name, or the
- standard default defined for local users. The commands may be
- in any order except that a "rename from" command must be
- followed by a "rename to" command and the restart command must
- be followed by the interrupted service command (e.g., STOR or
- RETR). The data, when transferred in response to FTP service
-
-
-Postel & Reynolds [Page 29]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- commands, shall always be sent over the data connection, except
- for certain informative replies. The following commands
- specify FTP service requests:
-
- RETRIEVE (RETR)
-
- This command causes the server-DTP to transfer a copy of the
- file, specified in the pathname, to the server- or user-DTP
- at the other end of the data connection. The status and
- contents of the file at the server site shall be unaffected.
-
- STORE (STOR)
-
- This command causes the server-DTP to accept the data
- transferred via the data connection and to store the data as
- a file at the server site. If the file specified in the
- pathname exists at the server site, then its contents shall
- be replaced by the data being transferred. A new file is
- created at the server site if the file specified in the
- pathname does not already exist.
-
- STORE UNIQUE (STOU)
-
- This command behaves like STOR except that the resultant
- file is to be created in the current directory under a name
- unique to that directory. The 250 Transfer Started response
- must include the name generated.
-
- APPEND (with create) (APPE)
-
- This command causes the server-DTP to accept the data
- transferred via the data connection and to store the data in
- a file at the server site. If the file specified in the
- pathname exists at the server site, then the data shall be
- appended to that file; otherwise the file specified in the
- pathname shall be created at the server site.
-
- ALLOCATE (ALLO)
-
- This command may be required by some servers to reserve
- sufficient storage to accommodate the new file to be
- transferred. The argument shall be a decimal integer
- representing the number of bytes (using the logical byte
- size) of storage to be reserved for the file. For files
- sent with record or page structure a maximum record or page
- size (in logical bytes) might also be necessary; this is
- indicated by a decimal integer in a second argument field of
-
-
-Postel & Reynolds [Page 30]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- the command. This second argument is optional, but when
- present should be separated from the first by the three
- Telnet characters <SP> R <SP>. This command shall be
- followed by a STORe or APPEnd command. The ALLO command
- should be treated as a NOOP (no operation) by those servers
- which do not require that the maximum size of the file be
- declared beforehand, and those servers interested in only
- the maximum record or page size should accept a dummy value
- in the first argument and ignore it.
-
- RESTART (REST)
-
- The argument field represents the server marker at which
- file transfer is to be restarted. This command does not
- cause file transfer but skips over the file to the specified
- data checkpoint. This command shall be immediately followed
- by the appropriate FTP service command which shall cause
- file transfer to resume.
-
- RENAME FROM (RNFR)
-
- This command specifies the old pathname of the file which is
- to be renamed. This command must be immediately followed by
- a "rename to" command specifying the new file pathname.
-
- RENAME TO (RNTO)
-
- This command specifies the new pathname of the file
- specified in the immediately preceding "rename from"
- command. Together the two commands cause a file to be
- renamed.
-
- ABORT (ABOR)
-
- This command tells the server to abort the previous FTP
- service command and any associated transfer of data. The
- abort command may require "special action", as discussed in
- the Section on FTP Commands, to force recognition by the
- server. No action is to be taken if the previous command
- has been completed (including data transfer). The control
- connection is not to be closed by the server, but the data
- connection must be closed.
-
- There are two cases for the server upon receipt of this
- command: (1) the FTP service command was already completed,
- or (2) the FTP service command is still in progress.
-
-
-
-Postel & Reynolds [Page 31]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- In the first case, the server closes the data connection
- (if it is open) and responds with a 226 reply, indicating
- that the abort command was successfully processed.
-
- In the second case, the server aborts the FTP service in
- progress and closes the data connection, returning a 426
- reply to indicate that the service request terminated
- abnormally. The server then sends a 226 reply,
- indicating that the abort command was successfully
- processed.
-
- DELETE (DELE)
-
- This command causes the file specified in the pathname to be
- deleted at the server site. If an extra level of protection
- is desired (such as the query, "Do you really wish to
- delete?"), it should be provided by the user-FTP process.
-
- REMOVE DIRECTORY (RMD)
-
- This command causes the directory specified in the pathname
- to be removed as a directory (if the pathname is absolute)
- or as a subdirectory of the current working directory (if
- the pathname is relative). See Appendix II.
-
- MAKE DIRECTORY (MKD)
-
- This command causes the directory specified in the pathname
- to be created as a directory (if the pathname is absolute)
- or as a subdirectory of the current working directory (if
- the pathname is relative). See Appendix II.
-
- PRINT WORKING DIRECTORY (PWD)
-
- This command causes the name of the current working
- directory to be returned in the reply. See Appendix II.
-
- LIST (LIST)
-
- This command causes a list to be sent from the server to the
- passive DTP. If the pathname specifies a directory or other
- group of files, the server should transfer a list of files
- in the specified directory. If the pathname specifies a
- file then the server should send current information on the
- file. A null argument implies the user's current working or
- default directory. The data transfer is over the data
- connection in type ASCII or type EBCDIC. (The user must
-
-
-Postel & Reynolds [Page 32]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- ensure that the TYPE is appropriately ASCII or EBCDIC).
- Since the information on a file may vary widely from system
- to system, this information may be hard to use automatically
- in a program, but may be quite useful to a human user.
-
- NAME LIST (NLST)
-
- This command causes a directory listing to be sent from
- server to user site. The pathname should specify a
- directory or other system-specific file group descriptor; a
- null argument implies the current directory. The server
- will return a stream of names of files and no other
- information. The data will be transferred in ASCII or
- EBCDIC type over the data connection as valid pathname
- strings separated by <CRLF> or <NL>. (Again the user must
- ensure that the TYPE is correct.) This command is intended
- to return information that can be used by a program to
- further process the files automatically. For example, in
- the implementation of a "multiple get" function.
-
- SITE PARAMETERS (SITE)
-
- This command is used by the server to provide services
- specific to his system that are essential to file transfer
- but not sufficiently universal to be included as commands in
- the protocol. The nature of these services and the
- specification of their syntax can be stated in a reply to
- the HELP SITE command.
-
- SYSTEM (SYST)
-
- This command is used to find out the type of operating
- system at the server. The reply shall have as its first
- word one of the system names listed in the current version
- of the Assigned Numbers document [4].
-
- STATUS (STAT)
-
- This command shall cause a status response to be sent over
- the control connection in the form of a reply. The command
- may be sent during a file transfer (along with the Telnet IP
- and Synch signals--see the Section on FTP Commands) in which
- case the server will respond with the status of the
- operation in progress, or it may be sent between file
- transfers. In the latter case, the command may have an
- argument field. If the argument is a pathname, the command
- is analogous to the "list" command except that data shall be
-
-
-Postel & Reynolds [Page 33]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- transferred over the control connection. If a partial
- pathname is given, the server may respond with a list of
- file names or attributes associated with that specification.
- If no argument is given, the server should return general
- status information about the server FTP process. This
- should include current values of all transfer parameters and
- the status of connections.
-
- HELP (HELP)
-
- This command shall cause the server to send helpful
- information regarding its implementation status over the
- control connection to the user. The command may take an
- argument (e.g., any command name) and return more specific
- information as a response. The reply is type 211 or 214.
- It is suggested that HELP be allowed before entering a USER
- command. The server may use this reply to specify
- site-dependent parameters, e.g., in response to HELP SITE.
-
- NOOP (NOOP)
-
- This command does not affect any parameters or previously
- entered commands. It specifies no action other than that the
- server send an OK reply.
-
- The File Transfer Protocol follows the specifications of the Telnet
- protocol for all communications over the control connection. Since
- the language used for Telnet communication may be a negotiated
- option, all references in the next two sections will be to the
- "Telnet language" and the corresponding "Telnet end-of-line code".
- Currently, one may take these to mean NVT-ASCII and <CRLF>. No other
- specifications of the Telnet protocol will be cited.
-
- FTP commands are "Telnet strings" terminated by the "Telnet end of
- line code". The command codes themselves are alphabetic characters
- terminated by the character <SP> (Space) if parameters follow and
- Telnet-EOL otherwise. The command codes and the semantics of
- commands are described in this section; the detailed syntax of
- commands is specified in the Section on Commands, the reply sequences
- are discussed in the Section on Sequencing of Commands and Replies,
- and scenarios illustrating the use of commands are provided in the
- Section on Typical FTP Scenarios.
-
- FTP commands may be partitioned as those specifying access-control
- identifiers, data transfer parameters, or FTP service requests.
- Certain commands (such as ABOR, STAT, QUIT) may be sent over the
- control connection while a data transfer is in progress. Some
-
-
-Postel & Reynolds [Page 34]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- servers may not be able to monitor the control and data connections
- simultaneously, in which case some special action will be necessary
- to get the server's attention. The following ordered format is
- tentatively recommended:
-
- 1. User system inserts the Telnet "Interrupt Process" (IP) signal
- in the Telnet stream.
-
- 2. User system sends the Telnet "Synch" signal.
-
- 3. User system inserts the command (e.g., ABOR) in the Telnet
- stream.
-
- 4. Server PI, after receiving "IP", scans the Telnet stream for
- EXACTLY ONE FTP command.
-
- (For other servers this may not be necessary but the actions listed
- above should have no unusual effect.)
-
- 4.2. FTP REPLIES
-
- Replies to File Transfer Protocol commands are devised to ensure
- the synchronization of requests and actions in the process of file
- transfer, and to guarantee that the user process always knows the
- state of the Server. Every command must generate at least one
- reply, although there may be more than one; in the latter case,
- the multiple replies must be easily distinguished. In addition,
- some commands occur in sequential groups, such as USER, PASS and
- ACCT, or RNFR and RNTO. The replies show the existence of an
- intermediate state if all preceding commands have been successful.
- A failure at any point in the sequence necessitates the repetition
- of the entire sequence from the beginning.
-
- The details of the command-reply sequence are made explicit in
- a set of state diagrams below.
-
- An FTP reply consists of a three digit number (transmitted as
- three alphanumeric characters) followed by some text. The number
- is intended for use by automata to determine what state to enter
- next; the text is intended for the human user. It is intended
- that the three digits contain enough encoded information that the
- user-process (the User-PI) will not need to examine the text and
- may either discard it or pass it on to the user, as appropriate.
- In particular, the text may be server-dependent, so there are
- likely to be varying texts for each reply code.
-
- A reply is defined to contain the 3-digit code, followed by Space
-
-
-Postel & Reynolds [Page 35]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- <SP>, followed by one line of text (where some maximum line length
- has been specified), and terminated by the Telnet end-of-line
- code. There will be cases however, where the text is longer than
- a single line. In these cases the complete text must be bracketed
- so the User-process knows when it may stop reading the reply (i.e.
- stop processing input on the control connection) and go do other
- things. This requires a special format on the first line to
- indicate that more than one line is coming, and another on the
- last line to designate it as the last. At least one of these must
- contain the appropriate reply code to indicate the state of the
- transaction. To satisfy all factions, it was decided that both
- the first and last line codes should be the same.
-
- Thus the format for multi-line replies is that the first line
- will begin with the exact required reply code, followed
- immediately by a Hyphen, "-" (also known as Minus), followed by
- text. The last line will begin with the same code, followed
- immediately by Space <SP>, optionally some text, and the Telnet
- end-of-line code.
-
- For example:
- 123-First line
- Second line
- 234 A line beginning with numbers
- 123 The last line
-
- The user-process then simply needs to search for the second
- occurrence of the same reply code, followed by <SP> (Space), at
- the beginning of a line, and ignore all intermediary lines. If
- an intermediary line begins with a 3-digit number, the Server
- must pad the front to avoid confusion.
-
- This scheme allows standard system routines to be used for
- reply information (such as for the STAT reply), with
- "artificial" first and last lines tacked on. In rare cases
- where these routines are able to generate three digits and a
- Space at the beginning of any line, the beginning of each
- text line should be offset by some neutral text, like Space.
-
- This scheme assumes that multi-line replies may not be nested.
-
- The three digits of the reply each have a special significance.
- This is intended to allow a range of very simple to very
- sophisticated responses by the user-process. The first digit
- denotes whether the response is good, bad or incomplete.
- (Referring to the state diagram), an unsophisticated user-process
- will be able to determine its next action (proceed as planned,
-
-
-Postel & Reynolds [Page 36]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- redo, retrench, etc.) by simply examining this first digit. A
- user-process that wants to know approximately what kind of error
- occurred (e.g. file system error, command syntax error) may
- examine the second digit, reserving the third digit for the finest
- gradation of information (e.g., RNTO command without a preceding
- RNFR).
-
- There are five values for the first digit of the reply code:
-
- 1yz Positive Preliminary reply
-
- The requested action is being initiated; expect another
- reply before proceeding with a new command. (The
- user-process sending another command before the
- completion reply would be in violation of protocol; but
- server-FTP processes should queue any commands that
- arrive while a preceding command is in progress.) This
- type of reply can be used to indicate that the command
- was accepted and the user-process may now pay attention
- to the data connections, for implementations where
- simultaneous monitoring is difficult. The server-FTP
- process may send at most, one 1yz reply per command.
-
- 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 user should send another command
- specifying this information. This reply is used in
- command sequence groups.
-
- 4yz Transient Negative Completion reply
-
- The command was not accepted and the requested action did
- not take place, but the error condition is temporary and
- the action may be requested again. The user should
- return to the beginning of the command sequence, if any.
- It is difficult to assign a meaning to "transient",
- particularly when two distinct sites (Server- and
- User-processes) have to agree on the interpretation.
- Each reply in the 4yz category might have a slightly
- different time value, but the intent is that the
-
-
-Postel & Reynolds [Page 37]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- user-process is encouraged to try again. A rule of thumb
- in determining if a reply fits into the 4yz or the 5yz
- (Permanent Negative) category is that replies are 4yz if
- the commands can be repeated without any change in
- command form or in properties of the User or Server
- (e.g., the command is spelled the same with the same
- arguments used; the user does not change his file access
- or user name; the server does not put up a new
- implementation.)
-
- 5yz Permanent Negative Completion reply
-
- The command was not accepted and the requested action did
- not take place. The User-process 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 his User-process 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 his directory status.)
-
- The following function groupings are encoded in the second
- digit:
-
- x0z Syntax - These replies refer to syntax errors,
- syntactically correct commands that don't fit any
- functional category, unimplemented or superfluous
- commands.
-
- x1z Information - These are replies to requests for
- information, such as status or help.
-
- x2z Connections - Replies referring to the control and
- data connections.
-
- x3z Authentication and accounting - Replies for the login
- process and accounting procedures.
-
- x4z Unspecified as yet.
-
- x5z File system - These replies indicate the status of the
- Server file system vis-a-vis the requested transfer or
- other file system action.
-
- The third digit gives a finer gradation of meaning in each of
- the function categories, specified by the second digit. The
- list of replies below will illustrate this. Note that the text
-
-
-Postel & Reynolds [Page 38]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- associated with each reply is recommended, rather than
- mandatory, and may even change according to the command with
- which it is associated. The reply codes, on the other hand,
- must strictly follow the specifications in the last section;
- that is, Server implementations should not invent new codes for
- situations that are only slightly different from the ones
- described here, but rather should adapt codes already defined.
-
- A command such as TYPE or ALLO whose successful execution
- does not offer the user-process any new information will
- cause a 200 reply to be returned. If the command is not
- implemented by a particular Server-FTP process because it
- has no relevance to that computer system, for example ALLO
- at a TOPS20 site, a Positive Completion reply is still
- desired so that the simple User-process knows it can proceed
- with its course of action. A 202 reply is used in this case
- with, for example, the reply text: "No storage allocation
- necessary." If, on the other hand, the command requests a
- non-site-specific action and is unimplemented, the response
- is 502. A refinement of that is the 504 reply for a command
- that is implemented, but that requests an unimplemented
- parameter.
-
- 4.2.1 Reply Codes by Function Groups
-
- 200 Command okay.
- 500 Syntax error, command unrecognized.
- This may include errors such as command line too long.
- 501 Syntax error in parameters or arguments.
- 202 Command not implemented, superfluous at this site.
- 502 Command not implemented.
- 503 Bad sequence of commands.
- 504 Command not implemented for that parameter.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 39]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- 110 Restart marker reply.
- In this case, the text is exact and not left to the
- particular implementation; it must read:
- MARK yyyy = mmmm
- Where yyyy is User-process data stream marker, and mmmm
- server's equivalent marker (note the spaces between markers
- and "=").
- 211 System status, or system help reply.
- 212 Directory status.
- 213 File status.
- 214 Help message.
- On how to use the server or the meaning of a particular
- non-standard command. This reply is useful only to the
- human user.
- 215 NAME system type.
- Where NAME is an official system name from the list in the
- Assigned Numbers document.
-
- 120 Service ready in nnn minutes.
- 220 Service ready for new user.
- 221 Service closing control connection.
- Logged out if appropriate.
- 421 Service not available, closing control connection.
- This may be a reply to any command if the service knows it
- must shut down.
- 125 Data connection already open; transfer starting.
- 225 Data connection open; no transfer in progress.
- 425 Can't open data connection.
- 226 Closing data connection.
- Requested file action successful (for example, file
- transfer or file abort).
- 426 Connection closed; transfer aborted.
- 227 Entering Passive Mode (h1,h2,h3,h4,p1,p2).
-
- 230 User logged in, proceed.
- 530 Not logged in.
- 331 User name okay, need password.
- 332 Need account for login.
- 532 Need account for storing files.
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 40]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- 150 File status okay; about to open data connection.
- 250 Requested file action okay, completed.
- 257 "PATHNAME" created.
- 350 Requested file action pending further information.
- 450 Requested file action not taken.
- File unavailable (e.g., file busy).
- 550 Requested action not taken.
- File unavailable (e.g., file not found, no access).
- 451 Requested action aborted. Local error in processing.
- 551 Requested action aborted. Page type unknown.
- 452 Requested action not taken.
- Insufficient storage space in system.
- 552 Requested file action aborted.
- Exceeded storage allocation (for current directory or
- dataset).
- 553 Requested action not taken.
- File name not allowed.
-
-
- 4.2.2 Numeric Order List of Reply Codes
-
- 110 Restart marker reply.
- In this case, the text is exact and not left to the
- particular implementation; it must read:
- MARK yyyy = mmmm
- Where yyyy is User-process data stream marker, and mmmm
- server's equivalent marker (note the spaces between markers
- and "=").
- 120 Service ready in nnn minutes.
- 125 Data connection already open; transfer starting.
- 150 File status okay; about to open data connection.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 41]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- 200 Command okay.
- 202 Command not implemented, superfluous at this site.
- 211 System status, or system help reply.
- 212 Directory status.
- 213 File status.
- 214 Help message.
- On how to use the server or the meaning of a particular
- non-standard command. This reply is useful only to the
- human user.
- 215 NAME system type.
- Where NAME is an official system name from the list in the
- Assigned Numbers document.
- 220 Service ready for new user.
- 221 Service closing control connection.
- Logged out if appropriate.
- 225 Data connection open; no transfer in progress.
- 226 Closing data connection.
- Requested file action successful (for example, file
- transfer or file abort).
- 227 Entering Passive Mode (h1,h2,h3,h4,p1,p2).
- 230 User logged in, proceed.
- 250 Requested file action okay, completed.
- 257 "PATHNAME" created.
-
- 331 User name okay, need password.
- 332 Need account for login.
- 350 Requested file action pending further information.
-
- 421 Service not available, closing control connection.
- This may be a reply to any command if the service knows it
- must shut down.
- 425 Can't open data connection.
- 426 Connection closed; transfer aborted.
- 450 Requested file action not taken.
- File unavailable (e.g., file busy).
- 451 Requested action aborted: local error in processing.
- 452 Requested action not taken.
- Insufficient storage space in system.
-
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 42]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- 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.
- 503 Bad sequence of commands.
- 504 Command not implemented for that parameter.
- 530 Not logged in.
- 532 Need account for storing files.
- 550 Requested action not taken.
- File unavailable (e.g., file not found, no access).
- 551 Requested action aborted: page type unknown.
- 552 Requested file action aborted.
- Exceeded storage allocation (for current directory or
- dataset).
- 553 Requested action not taken.
- File name not allowed.
-
-
-5. DECLARATIVE SPECIFICATIONS
-
- 5.1. MINIMUM IMPLEMENTATION
-
- In order to make FTP workable without needless error messages, the
- following minimum implementation is required for all servers:
-
- TYPE - ASCII Non-print
- MODE - Stream
- STRUCTURE - File, Record
- COMMANDS - USER, QUIT, PORT,
- TYPE, MODE, STRU,
- for the default values
- RETR, STOR,
- NOOP.
-
- The default values for transfer parameters are:
-
- TYPE - ASCII Non-print
- MODE - Stream
- STRU - File
-
- All hosts must accept the above as the standard defaults.
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 43]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- 5.2. CONNECTIONS
-
- The server protocol interpreter shall "listen" on Port L. The
- user or user protocol interpreter shall initiate the full-duplex
- control connection. Server- and user- processes should follow the
- conventions of the Telnet protocol as specified in the
- ARPA-Internet Protocol Handbook [1]. Servers are under no
- obligation to provide for editing of command lines and may require
- that it be done in the user host. The control connection shall be
- closed by the server at the user's request after all transfers and
- replies are completed.
-
- The user-DTP must "listen" on the specified data port; this may be
- the default user port (U) or a port specified in the PORT command.
- The server shall initiate the data connection from his own default
- data port (L-1) using the specified user data port. The direction
- of the transfer and the port used will be determined by the FTP
- service command.
-
- Note that all FTP implementation must support data transfer using
- the default port, and that only the USER-PI may initiate the use
- of non-default ports.
-
- When data is to be transferred between two servers, A and B (refer
- to Figure 2), the user-PI, C, sets up control connections with
- both server-PI's. One of the servers, say A, is then sent a PASV
- command telling him to "listen" on his data port rather than
- initiate a connection when he receives a transfer service command.
- When the user-PI receives an acknowledgment to the PASV command,
- which includes the identity of the host and port being listened
- on, the user-PI then sends A's port, a, to B in a PORT command; a
- reply is returned. The user-PI may then send the corresponding
- service commands to A and B. Server B initiates the connection
- and the transfer proceeds. The command-reply sequence is listed
- below where the messages are vertically synchronous but
- horizontally asynchronous:
-
-
-
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 44]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- User-PI - Server A User-PI - Server B
- ------------------ ------------------
-
- C->A : Connect C->B : Connect
- C->A : PASV
- A->C : 227 Entering Passive Mode. A1,A2,A3,A4,a1,a2
- C->B : PORT A1,A2,A3,A4,a1,a2
- B->C : 200 Okay
- C->A : STOR C->B : RETR
- B->A : Connect to HOST-A, PORT-a
-
- Figure 3
-
- The data connection shall be closed by the server under the
- conditions described in the Section on Establishing Data
- Connections. If the data connection is to be closed following a
- data transfer where closing the connection is not required to
- indicate the end-of-file, the server must do so immediately.
- Waiting until after a new transfer command is not permitted
- because the user-process will have already tested the data
- connection to see if it needs to do a "listen"; (remember that the
- user must "listen" on a closed data port BEFORE sending the
- transfer request). To prevent a race condition here, the server
- sends a reply (226) after closing the data connection (or if the
- connection is left open, a "file transfer completed" reply (250)
- and the user-PI should wait for one of these replies before
- issuing a new transfer command).
-
- Any time either the user or server see that the connection is
- being closed by the other side, it should promptly read any
- remaining data queued on the connection and issue the close on its
- own side.
-
- 5.3. COMMANDS
-
- The commands are Telnet character strings transmitted over the
- control connections as described in the Section on FTP Commands.
- The command functions and semantics are described in the Section
- on Access Control Commands, Transfer Parameter Commands, FTP
- Service Commands, and Miscellaneous Commands. The command syntax
- is specified here.
-
- The commands begin with a command code followed by an argument
- field. The command codes are four or fewer alphabetic characters.
- Upper and lower case alphabetic characters are to be treated
- identically. Thus, any of the following may represent the
- retrieve command:
-
-
-Postel & Reynolds [Page 45]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- RETR Retr retr ReTr rETr
-
- This also applies to any symbols representing parameter values,
- such as A or a for ASCII TYPE. The command codes and the argument
- fields are separated by one or more spaces.
-
- The argument field consists of a variable length character string
- ending with the character sequence <CRLF> (Carriage Return, Line
- Feed) for NVT-ASCII representation; for other negotiated languages
- a different end of line character might be used. It should be
- noted that the server is to take no action until the end of line
- code is received.
-
- The syntax is specified below in NVT-ASCII. All characters in the
- argument field are ASCII characters including any ASCII
- represented decimal integers. Square brackets denote an optional
- argument field. If the option is not taken, the appropriate
- default is implied.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 46]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- 5.3.1. FTP COMMANDS
-
- The following are the FTP commands:
-
- USER <SP> <username> <CRLF>
- PASS <SP> <password> <CRLF>
- ACCT <SP> <account-information> <CRLF>
- CWD <SP> <pathname> <CRLF>
- CDUP <CRLF>
- SMNT <SP> <pathname> <CRLF>
- QUIT <CRLF>
- REIN <CRLF>
- PORT <SP> <host-port> <CRLF>
- PASV <CRLF>
- TYPE <SP> <type-code> <CRLF>
- STRU <SP> <structure-code> <CRLF>
- MODE <SP> <mode-code> <CRLF>
- RETR <SP> <pathname> <CRLF>
- STOR <SP> <pathname> <CRLF>
- STOU <CRLF>
- APPE <SP> <pathname> <CRLF>
- ALLO <SP> <decimal-integer>
- [<SP> R <SP> <decimal-integer>] <CRLF>
- REST <SP> <marker> <CRLF>
- RNFR <SP> <pathname> <CRLF>
- RNTO <SP> <pathname> <CRLF>
- ABOR <CRLF>
- DELE <SP> <pathname> <CRLF>
- RMD <SP> <pathname> <CRLF>
- MKD <SP> <pathname> <CRLF>
- PWD <CRLF>
- LIST [<SP> <pathname>] <CRLF>
- NLST [<SP> <pathname>] <CRLF>
- SITE <SP> <string> <CRLF>
- SYST <CRLF>
- STAT [<SP> <pathname>] <CRLF>
- HELP [<SP> <string>] <CRLF>
- NOOP <CRLF>
-
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 47]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- 5.3.2. FTP COMMAND ARGUMENTS
-
- The syntax of the above argument fields (using BNF notation
- where applicable) is:
-
- <username> ::= <string>
- <password> ::= <string>
- <account-information> ::= <string>
- <string> ::= <char> | <char><string>
- <char> ::= any of the 128 ASCII characters except <CR> and
- <LF>
- <marker> ::= <pr-string>
- <pr-string> ::= <pr-char> | <pr-char><pr-string>
- <pr-char> ::= printable characters, any
- ASCII code 33 through 126
- <byte-size> ::= <number>
- <host-port> ::= <host-number>,<port-number>
- <host-number> ::= <number>,<number>,<number>,<number>
- <port-number> ::= <number>,<number>
- <number> ::= any decimal integer 1 through 255
- <form-code> ::= N | T | C
- <type-code> ::= A [<sp> <form-code>]
- | E [<sp> <form-code>]
- | I
- | L <sp> <byte-size>
- <structure-code> ::= F | R | P
- <mode-code> ::= S | B | C
- <pathname> ::= <string>
- <decimal-integer> ::= any decimal integer
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 48]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- 5.4. SEQUENCING OF COMMANDS AND REPLIES
-
- The communication between the user and server is intended to be an
- alternating dialogue. As such, the user issues an FTP command and
- the server responds with a prompt primary reply. The user should
- wait for this initial primary success or failure response before
- sending further commands.
-
- Certain commands require a second reply for which the user should
- also wait. These replies may, for example, report on the progress
- or completion of file transfer or the closing of the data
- connection. They are secondary replies to file transfer commands.
-
- One important group of informational replies is the connection
- greetings. Under normal circumstances, a server will send a 220
- reply, "awaiting input", when the connection is completed. The
- user should wait for this greeting message before sending any
- commands. If the server is unable to accept input right away, a
- 120 "expected delay" reply should be sent immediately and a 220
- reply when ready. The user will then know not to hang up if there
- is a delay.
-
- Spontaneous Replies
-
- Sometimes "the system" spontaneously has a message to be sent
- to a user (usually all users). For example, "System going down
- in 15 minutes". There is no provision in FTP for such
- spontaneous information to be sent from the server to the user.
- It is recommended that such information be queued in the
- server-PI and delivered to the user-PI in the next reply
- (possibly making it a multi-line reply).
-
- The table below lists alternative success and failure replies for
- each command. These must be strictly adhered to; a server 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.
-
- Command-Reply Sequences
-
- In this section, the command-reply sequence is presented. Each
- command is listed with its possible replies; command groups are
- listed together. Preliminary replies are listed first (with
- their succeeding replies indented and under them), then
- positive and negative completion, and finally intermediary
-
-
-
-
-Postel & Reynolds [Page 49]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- replies with the remaining commands from the sequence
- following. This listing forms the basis for the state
- diagrams, which will be presented separately.
-
- Connection Establishment
- 120
- 220
- 220
- 421
- Login
- USER
- 230
- 530
- 500, 501, 421
- 331, 332
- PASS
- 230
- 202
- 530
- 500, 501, 503, 421
- 332
- ACCT
- 230
- 202
- 530
- 500, 501, 503, 421
- CWD
- 250
- 500, 501, 502, 421, 530, 550
- CDUP
- 200
- 500, 501, 502, 421, 530, 550
- SMNT
- 202, 250
- 500, 501, 502, 421, 530, 550
- Logout
- REIN
- 120
- 220
- 220
- 421
- 500, 502
- QUIT
- 221
- 500
-
-
-
-
-Postel & Reynolds [Page 50]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- Transfer parameters
- PORT
- 200
- 500, 501, 421, 530
- PASV
- 227
- 500, 501, 502, 421, 530
- MODE
- 200
- 500, 501, 504, 421, 530
- TYPE
- 200
- 500, 501, 504, 421, 530
- STRU
- 200
- 500, 501, 504, 421, 530
- File action commands
- ALLO
- 200
- 202
- 500, 501, 504, 421, 530
- REST
- 500, 501, 502, 421, 530
- 350
- STOR
- 125, 150
- (110)
- 226, 250
- 425, 426, 451, 551, 552
- 532, 450, 452, 553
- 500, 501, 421, 530
- STOU
- 125, 150
- (110)
- 226, 250
- 425, 426, 451, 551, 552
- 532, 450, 452, 553
- 500, 501, 421, 530
- RETR
- 125, 150
- (110)
- 226, 250
- 425, 426, 451
- 450, 550
- 500, 501, 421, 530
-
-
-
-
-Postel & Reynolds [Page 51]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- LIST
- 125, 150
- 226, 250
- 425, 426, 451
- 450
- 500, 501, 502, 421, 530
- NLST
- 125, 150
- 226, 250
- 425, 426, 451
- 450
- 500, 501, 502, 421, 530
- APPE
- 125, 150
- (110)
- 226, 250
- 425, 426, 451, 551, 552
- 532, 450, 550, 452, 553
- 500, 501, 502, 421, 530
- RNFR
- 450, 550
- 500, 501, 502, 421, 530
- 350
- RNTO
- 250
- 532, 553
- 500, 501, 502, 503, 421, 530
- DELE
- 250
- 450, 550
- 500, 501, 502, 421, 530
- RMD
- 250
- 500, 501, 502, 421, 530, 550
- MKD
- 257
- 500, 501, 502, 421, 530, 550
- PWD
- 257
- 500, 501, 502, 421, 550
- ABOR
- 225, 226
- 500, 501, 502, 421
-
-
-
-
-
-
-Postel & Reynolds [Page 52]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- Informational commands
- SYST
- 215
- 500, 501, 502, 421
- STAT
- 211, 212, 213
- 450
- 500, 501, 502, 421, 530
- HELP
- 211, 214
- 500, 501, 502, 421
- Miscellaneous commands
- SITE
- 200
- 202
- 500, 501, 530
- NOOP
- 200
- 500 421
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 53]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
-6. STATE DIAGRAMS
-
- Here we present state diagrams for a very simple minded FTP
- implementation. Only the first digit of the reply codes is used.
- There is one state diagram for each group of FTP commands or command
- sequences.
-
- The command groupings were determined by constructing a model for
- each command then collecting together the commands with structurally
- identical models.
-
- For each command or command sequence there are three possible
- outcomes: success (S), failure (F), and error (E). In the state
- diagrams below we use the symbol B for "begin", and the symbol W for
- "wait for reply".
-
- We first present the diagram that represents the largest group of FTP
- commands:
-
-
- 1,3 +---+
- ----------->| E |
- | +---+
- |
- +---+ cmd +---+ 2 +---+
- | B |---------->| W |---------->| S |
- +---+ +---+ +---+
- |
- | 4,5 +---+
- ----------->| F |
- +---+
-
-
- This diagram models the commands:
-
- ABOR, ALLO, DELE, CWD, CDUP, SMNT, HELP, MODE, NOOP, PASV,
- QUIT, SITE, PORT, SYST, STAT, RMD, MKD, PWD, STRU, and TYPE.
-
-
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 54]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- The other large group of commands is represented by a very similar
- diagram:
-
-
- 3 +---+
- ----------->| E |
- | +---+
- |
- +---+ cmd +---+ 2 +---+
- | B |---------->| W |---------->| S |
- +---+ --->+---+ +---+
- | | |
- | | | 4,5 +---+
- | 1 | ----------->| F |
- ----- +---+
-
-
- This diagram models the commands:
-
- APPE, LIST, NLST, REIN, RETR, STOR, and STOU.
-
- Note that this second model could also be used to represent the first
- group of commands, the only difference being that in the first group
- the 100 series replies are unexpected and therefore treated as error,
- while the second group expects (some may require) 100 series replies.
- Remember that at most, one 100 series reply is allowed per command.
-
- The remaining diagrams model command sequences, perhaps the simplest
- of these is the rename sequence:
-
-
- +---+ RNFR +---+ 1,2 +---+
- | B |---------->| W |---------->| E |
- +---+ +---+ -->+---+
- | | |
- 3 | | 4,5 |
- -------------- ------ |
- | | | +---+
- | ------------->| S |
- | | 1,3 | | +---+
- | 2| --------
- | | | |
- V | | |
- +---+ RNTO +---+ 4,5 ----->+---+
- | |---------->| W |---------->| F |
- +---+ +---+ +---+
-
-
-
-Postel & Reynolds [Page 55]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- The next diagram is a simple model of the Restart command:
-
-
- +---+ REST +---+ 1,2 +---+
- | B |---------->| W |---------->| E |
- +---+ +---+ -->+---+
- | | |
- 3 | | 4,5 |
- -------------- ------ |
- | | | +---+
- | ------------->| S |
- | | 3 | | +---+
- | 2| --------
- | | | |
- V | | |
- +---+ cmd +---+ 4,5 ----->+---+
- | |---------->| W |---------->| F |
- +---+ -->+---+ +---+
- | |
- | 1 |
- ------
-
-
- Where "cmd" is APPE, STOR, or RETR.
-
- We note that the above three models are similar. The Restart differs
- from the Rename two only in the treatment of 100 series replies at
- the second stage, while the second group expects (some may require)
- 100 series replies. Remember that at most, one 100 series reply is
- allowed per command.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 56]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- The most complicated diagram is for the Login sequence:
-
-
- 1
- +---+ USER +---+------------->+---+
- | B |---------->| W | 2 ---->| E |
- +---+ +---+------ | -->+---+
- | | | | |
- 3 | | 4,5 | | |
- -------------- ----- | | |
- | | | | |
- | | | | |
- | --------- |
- | 1| | | |
- V | | | |
- +---+ PASS +---+ 2 | ------>+---+
- | |---------->| W |------------->| S |
- +---+ +---+ ---------->+---+
- | | | | |
- 3 | |4,5| | |
- -------------- -------- |
- | | | | |
- | | | | |
- | -----------
- | 1,3| | | |
- V | 2| | |
- +---+ ACCT +---+-- | ----->+---+
- | |---------->| W | 4,5 -------->| F |
- +---+ +---+------------->+---+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 57]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- Finally, we present a generalized diagram that could be used to model
- the command and reply interchange:
-
-
- ------------------------------------
- | |
- Begin | |
- | V |
- | +---+ cmd +---+ 2 +---+ |
- -->| |------->| |---------->| | |
- | | | W | | S |-----|
- -->| | -->| |----- | | |
- | +---+ | +---+ 4,5 | +---+ |
- | | | | | | |
- | | | 1| |3 | +---+ |
- | | | | | | | | |
- | | ---- | ---->| F |-----
- | | | | |
- | | | +---+
- -------------------
- |
- |
- V
- End
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 58]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
-7. TYPICAL FTP SCENARIO
-
- User at host U wanting to transfer files to/from host S:
-
- In general, the user will communicate to the server via a mediating
- user-FTP process. The following may be a typical scenario. The
- user-FTP prompts are shown in parentheses, '---->' represents
- commands from host U to host S, and '<----' represents replies from
- host S to host U.
-
- LOCAL COMMANDS BY USER ACTION INVOLVED
-
- ftp (host) multics<CR> Connect to host S, port L,
- establishing control connections.
- <---- 220 Service ready <CRLF>.
- username Doe <CR> USER Doe<CRLF>---->
- <---- 331 User name ok,
- need password<CRLF>.
- password mumble <CR> PASS mumble<CRLF>---->
- <---- 230 User logged in<CRLF>.
- retrieve (local type) ASCII<CR>
- (local pathname) test 1 <CR> User-FTP opens local file in ASCII.
- (for. pathname) test.pl1<CR> RETR test.pl1<CRLF> ---->
- <---- 150 File status okay;
- about to open data
- connection<CRLF>.
- Server makes data connection
- to port U.
-
- <---- 226 Closing data connection,
- file transfer successful<CRLF>.
- type Image<CR> TYPE I<CRLF> ---->
- <---- 200 Command OK<CRLF>
- store (local type) image<CR>
- (local pathname) file dump<CR> User-FTP opens local file in Image.
- (for.pathname) >udd>cn>fd<CR> STOR >udd>cn>fd<CRLF> ---->
- <---- 550 Access denied<CRLF>
- terminate QUIT <CRLF> ---->
- Server closes all
- connections.
-
-8. CONNECTION ESTABLISHMENT
-
- The FTP control connection is established via TCP between the user
- process port U and the server process port L. This protocol is
- assigned the service port 21 (25 octal), that is L=21.
-
-
-
-Postel & Reynolds [Page 59]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
-APPENDIX I - PAGE STRUCTURE
-
- The need for FTP to support page structure derives principally from
- the need to support efficient transmission of files between TOPS-20
- systems, particularly the files used by NLS.
-
- The file system of TOPS-20 is based on the concept of pages. The
- operating system is most efficient at manipulating files as pages.
- The operating system provides an interface to the file system so that
- many applications view files as sequential streams of characters.
- However, a few applications use the underlying page structures
- directly, and some of these create holey files.
-
- A TOPS-20 disk file consists of four things: a pathname, a page
- table, a (possibly empty) set of pages, and a set of attributes.
-
- The pathname is specified in the RETR or STOR command. It includes
- the directory name, file name, file name extension, and generation
- number.
-
- The page table contains up to 2**18 entries. Each entry may be
- EMPTY, or may point to a page. If it is not empty, there are also
- some page-specific access bits; not all pages of a file need have the
- same access protection.
-
- A page is a contiguous set of 512 words of 36 bits each.
-
- The attributes of the file, in the File Descriptor Block (FDB),
- contain such things as creation time, write time, read time, writer's
- byte-size, end-of-file pointer, count of reads and writes, backup
- system tape numbers, etc.
-
- Note that there is NO requirement that entries in the page table be
- contiguous. There may be empty page table slots between occupied
- ones. Also, the end of file pointer is simply a number. There is no
- requirement that it in fact point at the "last" datum in the file.
- Ordinary sequential I/O calls in TOPS-20 will cause the end of file
- pointer to be left after the last datum written, but other operations
- may cause it not to be so, if a particular programming system so
- requires.
-
- In fact, in both of these special cases, "holey" files and
- end-of-file pointers NOT at the end of the file, occur with NLS data
- files.
-
-
-
-
-
-Postel & Reynolds [Page 60]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- The TOPS-20 paged files can be sent with the FTP transfer parameters:
- TYPE L 36, STRU P, and MODE S (in fact, any mode could be used).
-
- Each page of information has a header. Each header field, which is a
- logical byte, is a TOPS-20 word, since the TYPE is L 36.
-
- The header fields are:
-
- Word 0: Header Length.
-
- The header length is 5.
-
- Word 1: Page Index.
-
- If the data is a disk file page, this is the number of that
- page in the file's page map. Empty pages (holes) in the file
- are simply not sent. Note that a hole is NOT the same as a
- page of zeros.
-
- Word 2: Data Length.
-
- The number of data words in this page, following the header.
- Thus, the total length of the transmission unit is the Header
- Length plus the Data Length.
-
- Word 3: Page Type.
-
- A code for what type of chunk this is. A data page is type 3,
- the FDB page is type 2.
-
- Word 4: Page Access Control.
-
- The access bits associated with the page in the file's page
- map. (This full word quantity is put into AC2 of an SPACS by
- the program reading from net to disk.)
-
- After the header are Data Length data words. Data Length is
- currently either 512 for a data page or 31 for an FDB. Trailing
- zeros in a disk file page may be discarded, making Data Length less
- than 512 in that case.
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 61]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
-APPENDIX II - DIRECTORY COMMANDS
-
- Since UNIX has a tree-like directory structure in which directories
- are as easy to manipulate as ordinary files, it is useful to expand
- the FTP servers on these machines to include commands which deal with
- the creation of directories. Since there are other hosts on the
- ARPA-Internet which have tree-like directories (including TOPS-20 and
- Multics), these commands are as general as possible.
-
- Four directory commands have been added to FTP:
-
- MKD pathname
-
- Make a directory with the name "pathname".
-
- RMD pathname
-
- Remove the directory with the name "pathname".
-
- PWD
-
- Print the current working directory name.
-
- CDUP
-
- Change to the parent of the current working directory.
-
- The "pathname" argument should be created (removed) as a
- subdirectory of the current working directory, unless the "pathname"
- string contains sufficient information to specify otherwise to the
- server, e.g., "pathname" is an absolute pathname (in UNIX and
- Multics), or pathname is something like "<abso.lute.path>" to
- TOPS-20.
-
- REPLY CODES
-
- The CDUP command is a special case of CWD, and is included to
- simplify the implementation of programs for transferring directory
- trees between operating systems having different syntaxes for
- naming the parent directory. The reply codes for CDUP be
- identical to the reply codes of CWD.
-
- The reply codes for RMD be identical to the reply codes for its
- file analogue, DELE.
-
- The reply codes for MKD, however, are a bit more complicated. A
- freshly created directory will probably be the object of a future
-
-
-Postel & Reynolds [Page 62]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- CWD command. Unfortunately, the argument to MKD may not always be
- a suitable argument for CWD. This is the case, for example, when
- a TOPS-20 subdirectory is created by giving just the subdirectory
- name. That is, with a TOPS-20 server FTP, the command sequence
-
- MKD MYDIR
- CWD MYDIR
-
- will fail. The new directory may only be referred to by its
- "absolute" name; e.g., if the MKD command above were issued while
- connected to the directory <DFRANKLIN>, the new subdirectory
- could only be referred to by the name <DFRANKLIN.MYDIR>.
-
- Even on UNIX and Multics, however, the argument given to MKD may
- not be suitable. If it is a "relative" pathname (i.e., a pathname
- which is interpreted relative to the current directory), the user
- would need to be in the same current directory in order to reach
- the subdirectory. Depending on the application, this may be
- inconvenient. It is not very robust in any case.
-
- To solve these problems, upon successful completion of an MKD
- command, the server should return a line of the form:
-
- 257<space>"<directory-name>"<space><commentary>
-
- That is, the server will tell the user what string to use when
- referring to the created directory. The directory name can
- contain any character; embedded double-quotes should be escaped by
- double-quotes (the "quote-doubling" convention).
-
- For example, a user connects to the directory /usr/dm, and creates
- a subdirectory, named pathname:
-
- CWD /usr/dm
- 200 directory changed to /usr/dm
- MKD pathname
- 257 "/usr/dm/pathname" directory created
-
- An example with an embedded double quote:
-
- MKD foo"bar
- 257 "/usr/dm/foo""bar" directory created
- CWD /usr/dm/foo"bar
- 200 directory changed to /usr/dm/foo"bar
-
-
-
-
-
-Postel & Reynolds [Page 63]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- The prior existence of a subdirectory with the same name is an
- error, and the server must return an "access denied" error reply
- in that case.
-
- CWD /usr/dm
- 200 directory changed to /usr/dm
- MKD pathname
- 521-"/usr/dm/pathname" directory already exists;
- 521 taking no action.
-
- The failure replies for MKD are analogous to its file creating
- cousin, STOR. Also, an "access denied" return is given if a file
- name with the same name as the subdirectory will conflict with the
- creation of the subdirectory (this is a problem on UNIX, but
- shouldn't be one on TOPS-20).
-
- Essentially because the PWD command returns the same type of
- information as the successful MKD command, the successful PWD
- command uses the 257 reply code as well.
-
- SUBTLETIES
-
- Because these commands will be most useful in transferring
- subtrees from one machine to another, carefully observe that the
- argument to MKD is to be interpreted as a sub-directory of the
- current working directory, unless it contains enough information
- for the destination host to tell otherwise. A hypothetical
- example of its use in the TOPS-20 world:
-
- CWD <some.where>
- 200 Working directory changed
- MKD overrainbow
- 257 "<some.where.overrainbow>" directory created
- CWD overrainbow
- 431 No such directory
- CWD <some.where.overrainbow>
- 200 Working directory changed
-
- CWD <some.where>
- 200 Working directory changed to <some.where>
- MKD <unambiguous>
- 257 "<unambiguous>" directory created
- CWD <unambiguous>
-
- Note that the first example results in a subdirectory of the
- connected directory. In contrast, the argument in the second
- example contains enough information for TOPS-20 to tell that the
-
-
-Postel & Reynolds [Page 64]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- <unambiguous> directory is a top-level directory. Note also that
- in the first example the user "violated" the protocol by
- attempting to access the freshly created directory with a name
- other than the one returned by TOPS-20. Problems could have
- resulted in this case had there been an <overrainbow> directory;
- this is an ambiguity inherent in some TOPS-20 implementations.
- Similar considerations apply to the RMD command. The point is
- this: except where to do so would violate a host's conventions for
- denoting relative versus absolute pathnames, the host should treat
- the operands of the MKD and RMD commands as subdirectories. The
- 257 reply to the MKD command must always contain the absolute
- pathname of the created directory.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 65]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
-APPENDIX III - RFCs on FTP
-
- Bhushan, Abhay, "A File Transfer Protocol", RFC 114 (NIC 5823),
- MIT-Project MAC, 16 April 1971.
-
- Harslem, Eric, and John Heafner, "Comments on RFC 114 (A File
- Transfer Protocol)", RFC 141 (NIC 6726), RAND, 29 April 1971.
-
- Bhushan, Abhay, et al, "The File Transfer Protocol", RFC 172
- (NIC 6794), MIT-Project MAC, 23 June 1971.
-
- Braden, Bob, "Comments on DTP and FTP Proposals", RFC 238 (NIC 7663),
- UCLA/CCN, 29 September 1971.
-
- Bhushan, Abhay, et al, "The File Transfer Protocol", RFC 265
- (NIC 7813), MIT-Project MAC, 17 November 1971.
-
- McKenzie, Alex, "A Suggested Addition to File Transfer Protocol",
- RFC 281 (NIC 8163), BBN, 8 December 1971.
-
- Bhushan, Abhay, "The Use of "Set Data Type" Transaction in File
- Transfer Protocol", RFC 294 (NIC 8304), MIT-Project MAC,
- 25 January 1972.
-
- Bhushan, Abhay, "The File Transfer Protocol", RFC 354 (NIC 10596),
- MIT-Project MAC, 8 July 1972.
-
- Bhushan, Abhay, "Comments on the File Transfer Protocol (RFC 354)",
- RFC 385 (NIC 11357), MIT-Project MAC, 18 August 1972.
-
- Hicks, Greg, "User FTP Documentation", RFC 412 (NIC 12404), Utah,
- 27 November 1972.
-
- Bhushan, Abhay, "File Transfer Protocol (FTP) Status and Further
- Comments", RFC 414 (NIC 12406), MIT-Project MAC, 20 November 1972.
-
- Braden, Bob, "Comments on File Transfer Protocol", RFC 430
- (NIC 13299), UCLA/CCN, 7 February 1973.
-
- Thomas, Bob, and Bob Clements, "FTP Server-Server Interaction",
- RFC 438 (NIC 13770), BBN, 15 January 1973.
-
- Braden, Bob, "Print Files in FTP", RFC 448 (NIC 13299), UCLA/CCN,
- 27 February 1973.
-
- McKenzie, Alex, "File Transfer Protocol", RFC 454 (NIC 14333), BBN,
- 16 February 1973.
-
-
-Postel & Reynolds [Page 66]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- Bressler, Bob, and Bob Thomas, "Mail Retrieval via FTP", RFC 458
- (NIC 14378), BBN-NET and BBN-TENEX, 20 February 1973.
-
- Neigus, Nancy, "File Transfer Protocol", RFC 542 (NIC 17759), BBN,
- 12 July 1973.
-
- Krilanovich, Mark, and George Gregg, "Comments on the File Transfer
- Protocol", RFC 607 (NIC 21255), UCSB, 7 January 1974.
-
- Pogran, Ken, and Nancy Neigus, "Response to RFC 607 - Comments on the
- File Transfer Protocol", RFC 614 (NIC 21530), BBN, 28 January 1974.
-
- Krilanovich, Mark, George Gregg, Wayne Hathaway, and Jim White,
- "Comments on the File Transfer Protocol", RFC 624 (NIC 22054), UCSB,
- Ames Research Center, SRI-ARC, 28 February 1974.
-
- Bhushan, Abhay, "FTP Comments and Response to RFC 430", RFC 463
- (NIC 14573), MIT-DMCG, 21 February 1973.
-
- Braden, Bob, "FTP Data Compression", RFC 468 (NIC 14742), UCLA/CCN,
- 8 March 1973.
-
- Bhushan, Abhay, "FTP and Network Mail System", RFC 475 (NIC 14919),
- MIT-DMCG, 6 March 1973.
-
- Bressler, Bob, and Bob Thomas "FTP Server-Server Interaction - II",
- RFC 478 (NIC 14947), BBN-NET and BBN-TENEX, 26 March 1973.
-
- White, Jim, "Use of FTP by the NIC Journal", RFC 479 (NIC 14948),
- SRI-ARC, 8 March 1973.
-
- White, Jim, "Host-Dependent FTP Parameters", RFC 480 (NIC 14949),
- SRI-ARC, 8 March 1973.
-
- Padlipsky, Mike, "An FTP Command-Naming Problem", RFC 506
- (NIC 16157), MIT-Multics, 26 June 1973.
-
- Day, John, "Memo to FTP Group (Proposal for File Access Protocol)",
- RFC 520 (NIC 16819), Illinois, 25 June 1973.
-
- Merryman, Robert, "The UCSD-CC Server-FTP Facility", RFC 532
- (NIC 17451), UCSD-CC, 22 June 1973.
-
- Braden, Bob, "TENEX FTP Problem", RFC 571 (NIC 18974), UCLA/CCN,
- 15 November 1973.
-
-
-
-
-Postel & Reynolds [Page 67]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
- McKenzie, Alex, and Jon Postel, "Telnet and FTP Implementation -
- Schedule Change", RFC 593 (NIC 20615), BBN and MITRE,
- 29 November 1973.
-
- Sussman, Julie, "FTP Error Code Usage for More Reliable Mail
- Service", RFC 630 (NIC 30237), BBN, 10 April 1974.
-
- Postel, Jon, "Revised FTP Reply Codes", RFC 640 (NIC 30843),
- UCLA/NMC, 5 June 1974.
-
- Harvey, Brian, "Leaving Well Enough Alone", RFC 686 (NIC 32481),
- SU-AI, 10 May 1975.
-
- Harvey, Brian, "One More Try on the FTP", RFC 691 (NIC 32700), SU-AI,
- 28 May 1975.
-
- Lieb, J., "CWD Command of FTP", RFC 697 (NIC 32963), 14 July 1975.
-
- Harrenstien, Ken, "FTP Extension: XSEN", RFC 737 (NIC 42217), SRI-KL,
- 31 October 1977.
-
- Harrenstien, Ken, "FTP Extension: XRSQ/XRCP", RFC 743 (NIC 42758),
- SRI-KL, 30 December 1977.
-
- Lebling, P. David, "Survey of FTP Mail and MLFL", RFC 751, MIT,
- 10 December 1978.
-
- Postel, Jon, "File Transfer Protocol Specification", RFC 765, ISI,
- June 1980.
-
- Mankins, David, Dan Franklin, and Buzz Owen, "Directory Oriented FTP
- Commands", RFC 776, BBN, December 1980.
-
- Padlipsky, Michael, "FTP Unique-Named Store Command", RFC 949, MITRE,
- July 1985.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 68]
-\f
-
-
-RFC 959 October 1985
-File Transfer Protocol
-
-
-REFERENCES
-
- [1] Feinler, Elizabeth, "Internet Protocol Transition Workbook",
- Network Information Center, SRI International, March 1982.
-
- [2] Postel, Jon, "Transmission Control Protocol - DARPA Internet
- Program Protocol Specification", RFC 793, DARPA, September 1981.
-
- [3] Postel, Jon, and Joyce Reynolds, "Telnet Protocol
- Specification", RFC 854, ISI, May 1983.
-
- [4] Reynolds, Joyce, and Jon Postel, "Assigned Numbers", RFC 943,
- ISI, April 1985.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Postel & Reynolds [Page 69]
-\f
+++ /dev/null
-Network Working Group P. Mockapetris
-Request for Comments: 1035 ISI
- November 1987
-Obsoletes: RFCs 882, 883, 973
-
- DOMAIN NAMES - IMPLEMENTATION AND SPECIFICATION
-
-
-1. STATUS OF THIS MEMO
-
-This RFC describes the details of the domain system and protocol, and
-assumes that the reader is familiar with the concepts discussed in a
-companion RFC, "Domain Names - Concepts and Facilities" [RFC-1034].
-
-The domain system is a mixture of functions and data types which are an
-official protocol and functions and data types which are still
-experimental. Since the domain system is intentionally extensible, new
-data types and experimental behavior should always be expected in parts
-of the system beyond the official protocol. The official protocol parts
-include standard queries, responses and the Internet class RR data
-formats (e.g., host addresses). Since the previous RFC set, several
-definitions have changed, so some previous definitions are obsolete.
-
-Experimental or obsolete features are clearly marked in these RFCs, and
-such information should be used with caution.
-
-The reader is especially cautioned not to depend on the values which
-appear in examples to be current or complete, since their purpose is
-primarily pedagogical. Distribution of this memo is unlimited.
-
- Table of Contents
-
- 1. STATUS OF THIS MEMO 1
- 2. INTRODUCTION 3
- 2.1. Overview 3
- 2.2. Common configurations 4
- 2.3. Conventions 7
- 2.3.1. Preferred name syntax 7
- 2.3.2. Data Transmission Order 8
- 2.3.3. Character Case 9
- 2.3.4. Size limits 10
- 3. DOMAIN NAME SPACE AND RR DEFINITIONS 10
- 3.1. Name space definitions 10
- 3.2. RR definitions 11
- 3.2.1. Format 11
- 3.2.2. TYPE values 12
- 3.2.3. QTYPE values 12
- 3.2.4. CLASS values 13
-
-
-
-Mockapetris [Page 1]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
- 3.2.5. QCLASS values 13
- 3.3. Standard RRs 13
- 3.3.1. CNAME RDATA format 14
- 3.3.2. HINFO RDATA format 14
- 3.3.3. MB RDATA format (EXPERIMENTAL) 14
- 3.3.4. MD RDATA format (Obsolete) 15
- 3.3.5. MF RDATA format (Obsolete) 15
- 3.3.6. MG RDATA format (EXPERIMENTAL) 16
- 3.3.7. MINFO RDATA format (EXPERIMENTAL) 16
- 3.3.8. MR RDATA format (EXPERIMENTAL) 17
- 3.3.9. MX RDATA format 17
- 3.3.10. NULL RDATA format (EXPERIMENTAL) 17
- 3.3.11. NS RDATA format 18
- 3.3.12. PTR RDATA format 18
- 3.3.13. SOA RDATA format 19
- 3.3.14. TXT RDATA format 20
- 3.4. ARPA Internet specific RRs 20
- 3.4.1. A RDATA format 20
- 3.4.2. WKS RDATA format 21
- 3.5. IN-ADDR.ARPA domain 22
- 3.6. Defining new types, classes, and special namespaces 24
- 4. MESSAGES 25
- 4.1. Format 25
- 4.1.1. Header section format 26
- 4.1.2. Question section format 28
- 4.1.3. Resource record format 29
- 4.1.4. Message compression 30
- 4.2. Transport 32
- 4.2.1. UDP usage 32
- 4.2.2. TCP usage 32
- 5. MASTER FILES 33
- 5.1. Format 33
- 5.2. Use of master files to define zones 35
- 5.3. Master file example 36
- 6. NAME SERVER IMPLEMENTATION 37
- 6.1. Architecture 37
- 6.1.1. Control 37
- 6.1.2. Database 37
- 6.1.3. Time 39
- 6.2. Standard query processing 39
- 6.3. Zone refresh and reload processing 39
- 6.4. Inverse queries (Optional) 40
- 6.4.1. The contents of inverse queries and responses 40
- 6.4.2. Inverse query and response example 41
- 6.4.3. Inverse query processing 42
-
-
-
-
-
-
-Mockapetris [Page 2]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
- 6.5. Completion queries and responses 42
- 7. RESOLVER IMPLEMENTATION 43
- 7.1. Transforming a user request into a query 43
- 7.2. Sending the queries 44
- 7.3. Processing responses 46
- 7.4. Using the cache 47
- 8. MAIL SUPPORT 47
- 8.1. Mail exchange binding 48
- 8.2. Mailbox binding (Experimental) 48
- 9. REFERENCES and BIBLIOGRAPHY 50
- Index 54
-
-2. INTRODUCTION
-
-2.1. Overview
-
-The goal of domain names is to provide a mechanism for naming resources
-in such a way that the names are usable in different hosts, networks,
-protocol families, internets, and administrative organizations.
-
-From the user's point of view, domain names are useful as arguments to a
-local agent, called a resolver, which retrieves information associated
-with the domain name. Thus a user might ask for the host address or
-mail information associated with a particular domain name. To enable
-the user to request a particular type of information, an appropriate
-query type is passed to the resolver with the domain name. To the user,
-the domain tree is a single information space; the resolver is
-responsible for hiding the distribution of data among name servers from
-the user.
-
-From the resolver's point of view, the database that makes up the domain
-space is distributed among various name servers. Different parts of the
-domain space are stored in different name servers, although a particular
-data item will be stored redundantly in two or more name servers. The
-resolver starts with knowledge of at least one name server. When the
-resolver processes a user query it asks a known name server for the
-information; in return, the resolver either receives the desired
-information or a referral to another name server. Using these
-referrals, resolvers learn the identities and contents of other name
-servers. Resolvers are responsible for dealing with the distribution of
-the domain space and dealing with the effects of name server failure by
-consulting redundant databases in other servers.
-
-Name servers manage two kinds of data. The first kind of data held in
-sets called zones; each zone is the complete database for a particular
-"pruned" subtree of the domain space. This data is called
-authoritative. A name server periodically checks to make sure that its
-zones are up to date, and if not, obtains a new copy of updated zones
-
-
-
-Mockapetris [Page 3]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-from master files stored locally or in another name server. The second
-kind of data is cached data which was acquired by a local resolver.
-This data may be incomplete, but improves the performance of the
-retrieval process when non-local data is repeatedly accessed. Cached
-data is eventually discarded by a timeout mechanism.
-
-This functional structure isolates the problems of user interface,
-failure recovery, and distribution in the resolvers and isolates the
-database update and refresh problems in the name servers.
-
-2.2. Common configurations
-
-A host can participate in the domain name system in a number of ways,
-depending on whether the host runs programs that retrieve information
-from the domain system, name servers that answer queries from other
-hosts, or various combinations of both functions. The simplest, and
-perhaps most typical, configuration is shown below:
-
- Local Host | Foreign
- |
- +---------+ +----------+ | +--------+
- | | user queries | |queries | | |
- | User |-------------->| |---------|->|Foreign |
- | Program | | Resolver | | | Name |
- | |<--------------| |<--------|--| Server |
- | | user responses| |responses| | |
- +---------+ +----------+ | +--------+
- | A |
- cache additions | | references |
- V | |
- +----------+ |
- | cache | |
- +----------+ |
-
-User programs interact with the domain name space through resolvers; the
-format of user queries and user responses is specific to the host and
-its operating system. User queries will typically be operating system
-calls, and the resolver and its cache will be part of the host operating
-system. Less capable hosts may choose to implement the resolver as a
-subroutine to be linked in with every program that needs its services.
-Resolvers answer user queries with information they acquire via queries
-to foreign name servers and the local cache.
-
-Note that the resolver may have to make several queries to several
-different foreign name servers to answer a particular user query, and
-hence the resolution of a user query may involve several network
-accesses and an arbitrary amount of time. The queries to foreign name
-servers and the corresponding responses have a standard format described
-
-
-
-Mockapetris [Page 4]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-in this memo, and may be datagrams.
-
-Depending on its capabilities, a name server could be a stand alone
-program on a dedicated machine or a process or processes on a large
-timeshared host. A simple configuration might be:
-
- Local Host | Foreign
- |
- +---------+ |
- / /| |
- +---------+ | +----------+ | +--------+
- | | | | |responses| | |
- | | | | Name |---------|->|Foreign |
- | Master |-------------->| Server | | |Resolver|
- | files | | | |<--------|--| |
- | |/ | | queries | +--------+
- +---------+ +----------+ |
-
-Here a primary name server acquires information about one or more zones
-by reading master files from its local file system, and answers queries
-about those zones that arrive from foreign resolvers.
-
-The DNS requires that all zones be redundantly supported by more than
-one name server. Designated secondary servers can acquire zones and
-check for updates from the primary server using the zone transfer
-protocol of the DNS. This configuration is shown below:
-
- Local Host | Foreign
- |
- +---------+ |
- / /| |
- +---------+ | +----------+ | +--------+
- | | | | |responses| | |
- | | | | Name |---------|->|Foreign |
- | Master |-------------->| Server | | |Resolver|
- | files | | | |<--------|--| |
- | |/ | | queries | +--------+
- +---------+ +----------+ |
- A |maintenance | +--------+
- | +------------|->| |
- | queries | |Foreign |
- | | | Name |
- +------------------|--| Server |
- maintenance responses | +--------+
-
-In this configuration, the name server periodically establishes a
-virtual circuit to a foreign name server to acquire a copy of a zone or
-to check that an existing copy has not changed. The messages sent for
-
-
-
-Mockapetris [Page 5]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-these maintenance activities follow the same form as queries and
-responses, but the message sequences are somewhat different.
-
-The information flow in a host that supports all aspects of the domain
-name system is shown below:
-
- Local Host | Foreign
- |
- +---------+ +----------+ | +--------+
- | | user queries | |queries | | |
- | User |-------------->| |---------|->|Foreign |
- | Program | | Resolver | | | Name |
- | |<--------------| |<--------|--| Server |
- | | user responses| |responses| | |
- +---------+ +----------+ | +--------+
- | A |
- cache additions | | references |
- V | |
- +----------+ |
- | Shared | |
- | database | |
- +----------+ |
- A | |
- +---------+ refreshes | | references |
- / /| | V |
- +---------+ | +----------+ | +--------+
- | | | | |responses| | |
- | | | | Name |---------|->|Foreign |
- | Master |-------------->| Server | | |Resolver|
- | files | | | |<--------|--| |
- | |/ | | queries | +--------+
- +---------+ +----------+ |
- A |maintenance | +--------+
- | +------------|->| |
- | queries | |Foreign |
- | | | Name |
- +------------------|--| Server |
- maintenance responses | +--------+
-
-The shared database holds domain space data for the local name server
-and resolver. The contents of the shared database will typically be a
-mixture of authoritative data maintained by the periodic refresh
-operations of the name server and cached data from previous resolver
-requests. The structure of the domain data and the necessity for
-synchronization between name servers and resolvers imply the general
-characteristics of this database, but the actual format is up to the
-local implementor.
-
-
-
-
-Mockapetris [Page 6]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-Information flow can also be tailored so that a group of hosts act
-together to optimize activities. Sometimes this is done to offload less
-capable hosts so that they do not have to implement a full resolver.
-This can be appropriate for PCs or hosts which want to minimize the
-amount of new network code which is required. This scheme can also
-allow a group of hosts can share a small number of caches rather than
-maintaining a large number of separate caches, on the premise that the
-centralized caches will have a higher hit ratio. In either case,
-resolvers are replaced with stub resolvers which act as front ends to
-resolvers located in a recursive server in one or more name servers
-known to perform that service:
-
- Local Hosts | Foreign
- |
- +---------+ |
- | | responses |
- | Stub |<--------------------+ |
- | Resolver| | |
- | |----------------+ | |
- +---------+ recursive | | |
- queries | | |
- V | |
- +---------+ recursive +----------+ | +--------+
- | | queries | |queries | | |
- | Stub |-------------->| Recursive|---------|->|Foreign |
- | Resolver| | Server | | | Name |
- | |<--------------| |<--------|--| Server |
- +---------+ responses | |responses| | |
- +----------+ | +--------+
- | Central | |
- | cache | |
- +----------+ |
-
-In any case, note that domain components are always replicated for
-reliability whenever possible.
-
-2.3. Conventions
-
-The domain system has several conventions dealing with low-level, but
-fundamental, issues. While the implementor is free to violate these
-conventions WITHIN HIS OWN SYSTEM, he must observe these conventions in
-ALL behavior observed from other hosts.
-
-2.3.1. Preferred name syntax
-
-The DNS specifications attempt to be as general as possible in the rules
-for constructing domain names. The idea is that the name of any
-existing object can be expressed as a domain name with minimal changes.
-
-
-
-Mockapetris [Page 7]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-However, when assigning a domain name for an object, the prudent user
-will select a name which satisfies both the rules of the domain system
-and any existing rules for the object, whether these rules are published
-or implied by existing programs.
-
-For example, when naming a mail domain, the user should satisfy both the
-rules of this memo and those in RFC-822. When creating a new host name,
-the old rules for HOSTS.TXT should be followed. This avoids problems
-when old software is converted to use domain names.
-
-The following syntax will result in fewer problems with many
-
-applications that use domain names (e.g., mail, TELNET).
-
-<domain> ::= <subdomain> | " "
-
-<subdomain> ::= <label> | <subdomain> "." <label>
-
-<label> ::= <letter> [ [ <ldh-str> ] <let-dig> ]
-
-<ldh-str> ::= <let-dig-hyp> | <let-dig-hyp> <ldh-str>
-
-<let-dig-hyp> ::= <let-dig> | "-"
-
-<let-dig> ::= <letter> | <digit>
-
-<letter> ::= any one of the 52 alphabetic characters A through Z in
-upper case and a through z in lower case
-
-<digit> ::= any one of the ten digits 0 through 9
-
-Note 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.
-
-The labels 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. There are also some
-restrictions on the length. Labels must be 63 characters or less.
-
-For example, the following strings identify hosts in the Internet:
-
-A.ISI.EDU XX.LCS.MIT.EDU SRI-NIC.ARPA
-
-2.3.2. Data Transmission Order
-
-The order of transmission of the header and data described in this
-document is resolved to the octet level. Whenever a diagram shows a
-
-
-
-Mockapetris [Page 8]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-group of octets, the order of transmission of those octets is the normal
-order in which they are read in English. For example, in the following
-diagram, the octets are transmitted in the order they are numbered.
-
- 0 1
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | 1 | 2 |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | 3 | 4 |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | 5 | 6 |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
-Whenever an octet represents a numeric quantity, the left most bit in
-the diagram is the high order or most significant bit. That is, the bit
-labeled 0 is the most significant bit. For example, the following
-diagram represents the value 170 (decimal).
-
- 0 1 2 3 4 5 6 7
- +-+-+-+-+-+-+-+-+
- |1 0 1 0 1 0 1 0|
- +-+-+-+-+-+-+-+-+
-
-Similarly, whenever a multi-octet field represents a numeric quantity
-the left most bit of the whole field is the most significant bit. When
-a multi-octet quantity is transmitted the most significant octet is
-transmitted first.
-
-2.3.3. Character Case
-
-For all parts of the DNS that are part of the official protocol, all
-comparisons between character strings (e.g., labels, domain names, etc.)
-are done in a case-insensitive manner. At present, this rule is in
-force throughout the domain system without exception. However, future
-additions beyond current usage may need to use the full binary octet
-capabilities in names, so attempts to store domain names in 7-bit ASCII
-or use of special bytes to terminate labels, etc., should be avoided.
-
-When data enters the domain system, its original case should be
-preserved whenever possible. In certain circumstances this cannot be
-done. For example, if two RRs are stored in a database, one at x.y and
-one at X.Y, they are actually stored at the same place in the database,
-and hence only one casing would be preserved. The basic rule is that
-case can be discarded only when data is used to define structure in a
-database, and two names are identical when compared in a case
-insensitive manner.
-
-
-
-
-Mockapetris [Page 9]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-Loss of case sensitive data must be minimized. Thus while data for x.y
-and X.Y may both be stored under a single location x.y or X.Y, data for
-a.x and B.X would never be stored under A.x, A.X, b.x, or b.X. In
-general, this preserves the case of the first label of a domain name,
-but forces standardization of interior node labels.
-
-Systems administrators who enter data into the domain database should
-take care to represent the data they supply to the domain system in a
-case-consistent manner if their system is case-sensitive. The data
-distribution system in the domain system will ensure that consistent
-representations are preserved.
-
-2.3.4. Size limits
-
-Various objects and parameters in the DNS have size limits. They are
-listed below. Some could be easily changed, others are more
-fundamental.
-
-labels 63 octets or less
-
-names 255 octets or less
-
-TTL positive values of a signed 32 bit number.
-
-UDP messages 512 octets or less
-
-3. DOMAIN NAME SPACE AND RR DEFINITIONS
-
-3.1. Name space definitions
-
-Domain names in messages are expressed in terms of a sequence of labels.
-Each label is represented as a one octet length field followed by that
-number of octets. Since every domain name ends with the null label of
-the root, a domain name is terminated by a length byte of zero. The
-high order two bits of every length octet must be zero, and the
-remaining six bits of the length field limit the label to 63 octets or
-less.
-
-To simplify implementations, the total length of a domain name (i.e.,
-label octets and label length octets) is restricted to 255 octets or
-less.
-
-Although labels can contain any 8 bit values in octets that make up a
-label, it is strongly recommended that labels follow the preferred
-syntax described elsewhere in this memo, which is compatible with
-existing host naming conventions. Name servers and resolvers must
-compare labels in a case-insensitive manner (i.e., A=a), assuming ASCII
-with zero parity. Non-alphabetic codes must match exactly.
-
-
-
-Mockapetris [Page 10]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-3.2. RR definitions
-
-3.2.1. Format
-
-All RRs have the same top level format shown below:
-
- 1 1 1 1 1 1
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | |
- / /
- / NAME /
- | |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | TYPE |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | CLASS |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | TTL |
- | |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | RDLENGTH |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--|
- / RDATA /
- / /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-
-where:
-
-NAME an owner name, i.e., the name of the node to which this
- resource record pertains.
-
-TYPE two octets containing one of the RR TYPE codes.
-
-CLASS two octets containing one of the RR CLASS codes.
-
-TTL a 32 bit signed integer that specifies the time interval
- that the resource record may be cached before the source
- of the information should again be consulted. Zero
- values are interpreted to mean that the RR can only be
- used for the transaction in progress, and should not be
- cached. For example, SOA records are always distributed
- with a zero TTL to prohibit caching. Zero values can
- also be used for extremely volatile data.
-
-RDLENGTH an unsigned 16 bit integer that specifies the length in
- octets of the RDATA field.
-
-
-
-Mockapetris [Page 11]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-RDATA a variable length string of octets that describes the
- resource. The format of this information varies
- according to the TYPE and CLASS of the resource record.
-
-3.2.2. TYPE values
-
-TYPE fields are used in resource records. Note that these types are a
-subset of QTYPEs.
-
-TYPE value and meaning
-
-A 1 a host address
-
-NS 2 an authoritative name server
-
-MD 3 a mail destination (Obsolete - use MX)
-
-MF 4 a mail forwarder (Obsolete - use MX)
-
-CNAME 5 the canonical name for an alias
-
-SOA 6 marks the start of a zone of authority
-
-MB 7 a mailbox domain name (EXPERIMENTAL)
-
-MG 8 a mail group member (EXPERIMENTAL)
-
-MR 9 a mail rename domain name (EXPERIMENTAL)
-
-NULL 10 a null RR (EXPERIMENTAL)
-
-WKS 11 a well known service description
-
-PTR 12 a domain name pointer
-
-HINFO 13 host information
-
-MINFO 14 mailbox or mail list information
-
-MX 15 mail exchange
-
-TXT 16 text strings
-
-3.2.3. QTYPE values
-
-QTYPE fields appear in the question part of a query. QTYPES are a
-superset of TYPEs, hence all TYPEs are valid QTYPEs. In addition, the
-following QTYPEs are defined:
-
-
-
-Mockapetris [Page 12]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-AXFR 252 A request for a transfer of an entire zone
-
-MAILB 253 A request for mailbox-related records (MB, MG or MR)
-
-MAILA 254 A request for mail agent RRs (Obsolete - see MX)
-
-* 255 A request for all records
-
-3.2.4. CLASS values
-
-CLASS fields appear in resource records. The following CLASS mnemonics
-and values are defined:
-
-IN 1 the Internet
-
-CS 2 the CSNET class (Obsolete - used only for examples in
- some obsolete RFCs)
-
-CH 3 the CHAOS class
-
-HS 4 Hesiod [Dyer 87]
-
-3.2.5. QCLASS values
-
-QCLASS fields appear in the question section of a query. QCLASS values
-are a superset of CLASS values; every CLASS is a valid QCLASS. In
-addition to CLASS values, the following QCLASSes are defined:
-
-* 255 any class
-
-3.3. Standard RRs
-
-The following RR definitions are expected to occur, at least
-potentially, in all classes. In particular, NS, SOA, CNAME, and PTR
-will be used in all classes, and have the same format in all classes.
-Because their RDATA format is known, all domain names in the RDATA
-section of these RRs may be compressed.
-
-<domain-name> is a domain name represented as a series of labels, and
-terminated by a label with zero length. <character-string> is a single
-length octet followed by that number of characters. <character-string>
-is treated as binary information, and can be up to 256 characters in
-length (including the length octet).
-
-
-
-
-
-
-
-
-Mockapetris [Page 13]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-3.3.1. CNAME RDATA format
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / CNAME /
- / /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-CNAME A <domain-name> which specifies the canonical or primary
- name for the owner. The owner name is an alias.
-
-CNAME RRs cause no additional section processing, but name servers may
-choose to restart the query at the canonical name in certain cases. See
-the description of name server logic in [RFC-1034] for details.
-
-3.3.2. HINFO RDATA format
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / CPU /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / OS /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-CPU A <character-string> which specifies the CPU type.
-
-OS A <character-string> which specifies the operating
- system type.
-
-Standard values for CPU and OS can be found in [RFC-1010].
-
-HINFO records are used to acquire general information about a host. The
-main use is for protocols such as FTP that can use special procedures
-when talking between machines or operating systems of the same type.
-
-3.3.3. MB RDATA format (EXPERIMENTAL)
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / MADNAME /
- / /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-MADNAME A <domain-name> which specifies a host which has the
- specified mailbox.
-
-
-
-Mockapetris [Page 14]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-MB records cause additional section processing which looks up an A type
-RRs corresponding to MADNAME.
-
-3.3.4. MD RDATA format (Obsolete)
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / MADNAME /
- / /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-MADNAME A <domain-name> which specifies a host which has a mail
- agent for the domain which should be able to deliver
- mail for the domain.
-
-MD records cause additional section processing which looks up an A type
-record corresponding to MADNAME.
-
-MD is obsolete. See the definition of MX and [RFC-974] for details of
-the new scheme. The recommended policy for dealing with MD RRs found in
-a master file is to reject them, or to convert them to MX RRs with a
-preference of 0.
-
-3.3.5. MF RDATA format (Obsolete)
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / MADNAME /
- / /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-MADNAME A <domain-name> which specifies a host which has a mail
- agent for the domain which will accept mail for
- forwarding to the domain.
-
-MF records cause additional section processing which looks up an A type
-record corresponding to MADNAME.
-
-MF is obsolete. See the definition of MX and [RFC-974] for details ofw
-the new scheme. The recommended policy for dealing with MD RRs found in
-a master file is to reject them, or to convert them to MX RRs with a
-preference of 10.
-
-
-
-
-
-
-
-Mockapetris [Page 15]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-3.3.6. MG RDATA format (EXPERIMENTAL)
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / MGMNAME /
- / /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-MGMNAME A <domain-name> which specifies a mailbox which is a
- member of the mail group specified by the domain name.
-
-MG records cause no additional section processing.
-
-3.3.7. MINFO RDATA format (EXPERIMENTAL)
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / RMAILBX /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / EMAILBX /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-RMAILBX A <domain-name> which specifies a mailbox which is
- responsible for the mailing list or mailbox. If this
- domain name names the root, the owner of the MINFO RR is
- responsible for itself. Note that many existing mailing
- lists use a mailbox X-request for the RMAILBX field of
- mailing list X, e.g., Msgroup-request for Msgroup. This
- field provides a more general mechanism.
-
-
-EMAILBX A <domain-name> which specifies a mailbox which is to
- receive error messages related to the mailing list or
- mailbox specified by the owner of the MINFO RR (similar
- to the ERRORS-TO: field which has been proposed). If
- this domain name names the root, errors should be
- returned to the sender of the message.
-
-MINFO records cause no additional section processing. Although these
-records can be associated with a simple mailbox, they are usually used
-with a mailing list.
-
-
-
-
-
-
-
-
-Mockapetris [Page 16]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-3.3.8. MR RDATA format (EXPERIMENTAL)
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / NEWNAME /
- / /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-NEWNAME A <domain-name> which specifies a mailbox which is the
- proper rename of the specified mailbox.
-
-MR records cause no additional section processing. The main use for MR
-is as a forwarding entry for a user who has moved to a different
-mailbox.
-
-3.3.9. MX RDATA format
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | PREFERENCE |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / EXCHANGE /
- / /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-PREFERENCE A 16 bit integer which specifies the preference given to
- this RR among others at the same owner. Lower values
- are preferred.
-
-EXCHANGE A <domain-name> which specifies a host willing to act as
- a mail exchange for the owner name.
-
-MX records cause type A additional section processing for the host
-specified by EXCHANGE. The use of MX RRs is explained in detail in
-[RFC-974].
-
-3.3.10. NULL RDATA format (EXPERIMENTAL)
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / <anything> /
- / /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-Anything at all may be in the RDATA field so long as it is 65535 octets
-or less.
-
-
-
-
-Mockapetris [Page 17]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-NULL records cause no additional section processing. NULL RRs are not
-allowed in master files. NULLs are used as placeholders in some
-experimental extensions of the DNS.
-
-3.3.11. NS RDATA format
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / NSDNAME /
- / /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-NSDNAME A <domain-name> which specifies a host which should be
- authoritative for the specified class and domain.
-
-NS records cause both the usual additional section processing to locate
-a type A record, and, when used in a referral, a special search of the
-zone in which they reside for glue information.
-
-The NS RR states that the named host should be expected to have a zone
-starting at owner name of the specified class. Note that the class may
-not indicate the protocol family which should be used to communicate
-with the host, although it is typically a strong hint. For example,
-hosts which are name servers for either Internet (IN) or Hesiod (HS)
-class information are normally queried using IN class protocols.
-
-3.3.12. PTR RDATA format
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / PTRDNAME /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-PTRDNAME A <domain-name> which points to some location in the
- domain name space.
-
-PTR records cause no additional section processing. These RRs are used
-in special domains to point to some other location in the domain space.
-These records are simple data, and don't imply any special processing
-similar to that performed by CNAME, which identifies aliases. See the
-description of the IN-ADDR.ARPA domain for an example.
-
-
-
-
-
-
-
-
-Mockapetris [Page 18]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-3.3.13. SOA RDATA format
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / MNAME /
- / /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / RNAME /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | SERIAL |
- | |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | REFRESH |
- | |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | RETRY |
- | |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | EXPIRE |
- | |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | MINIMUM |
- | |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-MNAME The <domain-name> of the name server that was the
- original or primary source of data for this zone.
-
-RNAME A <domain-name> which specifies the mailbox of the
- person responsible for this zone.
-
-SERIAL The unsigned 32 bit version number of the original copy
- of the zone. Zone transfers preserve this value. This
- value wraps and should be compared using sequence space
- arithmetic.
-
-REFRESH A 32 bit time interval before the zone should be
- refreshed.
-
-RETRY A 32 bit time interval that should elapse before a
- failed refresh should be retried.
-
-EXPIRE A 32 bit time value that specifies the upper limit on
- the time interval that can elapse before the zone is no
- longer authoritative.
-
-
-
-
-
-Mockapetris [Page 19]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-MINIMUM The unsigned 32 bit minimum TTL field that should be
- exported with any RR from this zone.
-
-SOA records cause no additional section processing.
-
-All times are in units of seconds.
-
-Most of these fields are pertinent only for name server maintenance
-operations. However, MINIMUM is used in all query operations that
-retrieve RRs from a zone. Whenever a RR is sent in a response to a
-query, the TTL field is set to the maximum of the TTL field from the RR
-and the MINIMUM field in the appropriate SOA. Thus MINIMUM is a lower
-bound on the TTL field for all RRs in a zone. Note that this use of
-MINIMUM should occur when the RRs are copied into the response and not
-when the zone is loaded from a master file or via a zone transfer. The
-reason for this provison is to allow future dynamic update facilities to
-change the SOA RR with known semantics.
-
-
-3.3.14. TXT RDATA format
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- / TXT-DATA /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-TXT-DATA One or more <character-string>s.
-
-TXT RRs are used to hold descriptive text. The semantics of the text
-depends on the domain where it is found.
-
-3.4. Internet specific RRs
-
-3.4.1. A RDATA format
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | ADDRESS |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-ADDRESS A 32 bit Internet address.
-
-Hosts that have multiple Internet addresses will have multiple A
-records.
-
-
-
-
-
-Mockapetris [Page 20]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-A records cause no additional section processing. The RDATA section of
-an A line in a master file is an Internet address expressed as four
-decimal numbers separated by dots without any imbedded spaces (e.g.,
-"10.2.0.52" or "192.0.5.6").
-
-3.4.2. WKS RDATA format
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | ADDRESS |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | PROTOCOL | |
- +--+--+--+--+--+--+--+--+ |
- | |
- / <BIT MAP> /
- / /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-ADDRESS An 32 bit Internet address
-
-PROTOCOL An 8 bit IP protocol number
-
-<BIT MAP> A variable length bit map. The bit map must be a
- multiple of 8 bits long.
-
-The WKS record is used to describe the well known services supported by
-a particular protocol on a particular internet address. The PROTOCOL
-field specifies an IP protocol number, and the bit map has one bit per
-port of the specified protocol. The first bit corresponds to port 0,
-the second to port 1, etc. If the bit map does not include a bit for a
-protocol of interest, that bit is assumed zero. The appropriate values
-and mnemonics for ports and protocols are specified in [RFC-1010].
-
-For example, if PROTOCOL=TCP (6), the 26th bit corresponds to TCP port
-25 (SMTP). If this bit is set, a SMTP server should be listening on TCP
-port 25; if zero, SMTP service is not supported on the specified
-address.
-
-The purpose of WKS RRs is to provide availability information for
-servers for TCP and UDP. If a server supports both TCP and UDP, or has
-multiple Internet addresses, then multiple WKS RRs are used.
-
-WKS RRs cause no additional section processing.
-
-In master files, both ports and protocols are expressed using mnemonics
-or decimal numbers.
-
-
-
-
-Mockapetris [Page 21]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-3.5. IN-ADDR.ARPA domain
-
-The Internet uses a special domain to support gateway location and
-Internet address to host mapping. Other classes may employ a similar
-strategy in other domains. The intent of this domain is to provide a
-guaranteed method to perform host address to host name mapping, and to
-facilitate queries to locate all gateways on a particular network in the
-Internet.
-
-Note that both of these services are similar to functions that could be
-performed by inverse queries; the difference is that this part of the
-domain name space is structured according to address, and hence can
-guarantee that the appropriate data can be located without an exhaustive
-search of the domain space.
-
-The domain begins at IN-ADDR.ARPA and has a substructure which follows
-the Internet addressing structure.
-
-Domain names in the IN-ADDR.ARPA domain are defined to have up to four
-labels in addition to the IN-ADDR.ARPA suffix. Each label represents
-one octet of an Internet address, and is expressed as a character string
-for a decimal value in the range 0-255 (with leading zeros omitted
-except in the case of a zero octet which is represented by a single
-zero).
-
-Host addresses are represented by domain names that have all four labels
-specified. Thus data for Internet address 10.2.0.52 is located at
-domain name 52.0.2.10.IN-ADDR.ARPA. The reversal, though awkward to
-read, allows zones to be delegated which are exactly one network of
-address space. For example, 10.IN-ADDR.ARPA can be a zone containing
-data for the ARPANET, while 26.IN-ADDR.ARPA can be a separate zone for
-MILNET. Address nodes are used to hold pointers to primary host names
-in the normal domain space.
-
-Network numbers correspond to some non-terminal nodes at various depths
-in the IN-ADDR.ARPA domain, since Internet network numbers are either 1,
-2, or 3 octets. Network nodes are used to hold pointers to the primary
-host names of gateways attached to that network. Since a gateway is, by
-definition, on more than one network, it will typically have two or more
-network nodes which point at it. Gateways will also have host level
-pointers at their fully qualified addresses.
-
-Both the gateway pointers at network nodes and the normal host pointers
-at full address nodes use the PTR RR to point back to the primary domain
-names of the corresponding hosts.
-
-For example, the IN-ADDR.ARPA domain will contain information about the
-ISI gateway between net 10 and 26, an MIT gateway from net 10 to MIT's
-
-
-
-Mockapetris [Page 22]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-net 18, and hosts A.ISI.EDU and MULTICS.MIT.EDU. Assuming that ISI
-gateway has addresses 10.2.0.22 and 26.0.0.103, and a name MILNET-
-GW.ISI.EDU, and the MIT gateway has addresses 10.0.0.77 and 18.10.0.4
-and a name GW.LCS.MIT.EDU, the domain database would contain:
-
- 10.IN-ADDR.ARPA. PTR MILNET-GW.ISI.EDU.
- 10.IN-ADDR.ARPA. PTR GW.LCS.MIT.EDU.
- 18.IN-ADDR.ARPA. PTR GW.LCS.MIT.EDU.
- 26.IN-ADDR.ARPA. PTR MILNET-GW.ISI.EDU.
- 22.0.2.10.IN-ADDR.ARPA. PTR MILNET-GW.ISI.EDU.
- 103.0.0.26.IN-ADDR.ARPA. PTR MILNET-GW.ISI.EDU.
- 77.0.0.10.IN-ADDR.ARPA. PTR GW.LCS.MIT.EDU.
- 4.0.10.18.IN-ADDR.ARPA. PTR GW.LCS.MIT.EDU.
- 103.0.3.26.IN-ADDR.ARPA. PTR A.ISI.EDU.
- 6.0.0.10.IN-ADDR.ARPA. PTR MULTICS.MIT.EDU.
-
-Thus a program which wanted to locate gateways on net 10 would originate
-a query of the form QTYPE=PTR, QCLASS=IN, QNAME=10.IN-ADDR.ARPA. It
-would receive two RRs in response:
-
- 10.IN-ADDR.ARPA. PTR MILNET-GW.ISI.EDU.
- 10.IN-ADDR.ARPA. PTR GW.LCS.MIT.EDU.
-
-The program could then originate QTYPE=A, QCLASS=IN queries for MILNET-
-GW.ISI.EDU. and GW.LCS.MIT.EDU. to discover the Internet addresses of
-these gateways.
-
-A resolver which wanted to find the host name corresponding to Internet
-host address 10.0.0.6 would pursue a query of the form QTYPE=PTR,
-QCLASS=IN, QNAME=6.0.0.10.IN-ADDR.ARPA, and would receive:
-
- 6.0.0.10.IN-ADDR.ARPA. PTR MULTICS.MIT.EDU.
-
-Several cautions apply to the use of these services:
- - Since the IN-ADDR.ARPA special domain and the normal domain
- for a particular host or gateway will be in different zones,
- the possibility exists that that the data may be inconsistent.
-
- - Gateways will often have two names in separate domains, only
- one of which can be primary.
-
- - Systems that use the domain database to initialize their
- routing tables must start with enough gateway information to
- guarantee that they can access the appropriate name server.
-
- - The gateway data only reflects the existence of a gateway in a
- manner equivalent to the current HOSTS.TXT file. It doesn't
- replace the dynamic availability information from GGP or EGP.
-
-
-
-Mockapetris [Page 23]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-3.6. Defining new types, classes, and special namespaces
-
-The previously defined types and classes are the ones in use as of the
-date of this memo. New definitions should be expected. This section
-makes some recommendations to designers considering additions to the
-existing facilities. The mailing list NAMEDROPPERS@SRI-NIC.ARPA is the
-forum where general discussion of design issues takes place.
-
-In general, a new type is appropriate when new information is to be
-added to the database about an existing object, or we need new data
-formats for some totally new object. Designers should attempt to define
-types and their RDATA formats that are generally applicable to all
-classes, and which avoid duplication of information. New classes are
-appropriate when the DNS is to be used for a new protocol, etc which
-requires new class-specific data formats, or when a copy of the existing
-name space is desired, but a separate management domain is necessary.
-
-New types and classes need mnemonics for master files; the format of the
-master files requires that the mnemonics for type and class be disjoint.
-
-TYPE and CLASS values must be a proper subset of QTYPEs and QCLASSes
-respectively.
-
-The present system uses multiple RRs to represent multiple values of a
-type rather than storing multiple values in the RDATA section of a
-single RR. This is less efficient for most applications, but does keep
-RRs shorter. The multiple RRs assumption is incorporated in some
-experimental work on dynamic update methods.
-
-The present system attempts to minimize the duplication of data in the
-database in order to insure consistency. Thus, in order to find the
-address of the host for a mail exchange, you map the mail domain name to
-a host name, then the host name to addresses, rather than a direct
-mapping to host address. This approach is preferred because it avoids
-the opportunity for inconsistency.
-
-In defining a new type of data, multiple RR types should not be used to
-create an ordering between entries or express different formats for
-equivalent bindings, instead this information should be carried in the
-body of the RR and a single type used. This policy avoids problems with
-caching multiple types and defining QTYPEs to match multiple types.
-
-For example, the original form of mail exchange binding used two RR
-types one to represent a "closer" exchange (MD) and one to represent a
-"less close" exchange (MF). The difficulty is that the presence of one
-RR type in a cache doesn't convey any information about the other
-because the query which acquired the cached information might have used
-a QTYPE of MF, MD, or MAILA (which matched both). The redesigned
-
-
-
-Mockapetris [Page 24]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-service used a single type (MX) with a "preference" value in the RDATA
-section which can order different RRs. However, if any MX RRs are found
-in the cache, then all should be there.
-
-4. MESSAGES
-
-4.1. Format
-
-All communications inside of the domain protocol are carried in a single
-format called a message. The top level format of message is divided
-into 5 sections (some of which are empty in certain cases) shown below:
-
- +---------------------+
- | Header |
- +---------------------+
- | Question | the question for the name server
- +---------------------+
- | Answer | RRs answering the question
- +---------------------+
- | Authority | RRs pointing toward an authority
- +---------------------+
- | Additional | RRs holding additional information
- +---------------------+
-
-The header section is always present. The header includes fields that
-specify which of the remaining sections are present, and also specify
-whether the message is a query or a response, a standard query or some
-other opcode, etc.
-
-The names of the sections after the header are derived from their use in
-standard queries. The question section contains fields that describe a
-question to a name server. These fields are a query type (QTYPE), a
-query class (QCLASS), and a query domain name (QNAME). The last three
-sections have the same format: a possibly empty list of concatenated
-resource records (RRs). The answer section contains RRs that answer the
-question; the authority section contains RRs that point toward an
-authoritative name server; the additional records section contains RRs
-which relate to the query, but are not strictly answers for the
-question.
-
-
-
-
-
-
-
-
-
-
-
-
-Mockapetris [Page 25]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-4.1.1. Header section format
-
-The header contains the following fields:
-
- 1 1 1 1 1 1
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | ID |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- |QR| Opcode |AA|TC|RD|RA| Z | RCODE |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | QDCOUNT |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | ANCOUNT |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | NSCOUNT |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | ARCOUNT |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-ID A 16 bit identifier assigned by the program that
- generates any kind of query. This identifier is copied
- the corresponding reply and can be used by the requester
- to match up replies to outstanding queries.
-
-QR A one bit field that specifies whether this message is a
- query (0), or a response (1).
-
-OPCODE A four bit field that specifies kind of query in this
- message. This value is set by the originator of a query
- and copied into the response. The values are:
-
- 0 a standard query (QUERY)
-
- 1 an inverse query (IQUERY)
-
- 2 a server status request (STATUS)
-
- 3-15 reserved for future use
-
-AA Authoritative Answer - this bit is valid in responses,
- and specifies that the responding name server is an
- authority for the domain name in question section.
-
- Note that the contents of the answer section may have
- multiple owner names because of aliases. The AA bit
-
-
-
-Mockapetris [Page 26]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
- corresponds to the name which matches the query name, or
- the first owner name in the answer section.
-
-TC TrunCation - specifies that this message was truncated
- due to length greater than that permitted on the
- transmission channel.
-
-RD Recursion Desired - this bit may be set in a query and
- is copied into the response. If RD is set, it directs
- the name server to pursue the query recursively.
- Recursive query support is optional.
-
-RA Recursion Available - this be is set or cleared in a
- response, and denotes whether recursive query support is
- available in the name server.
-
-Z Reserved for future use. Must be zero in all queries
- and responses.
-
-RCODE Response code - this 4 bit field is set as part of
- responses. The values have the following
- interpretation:
-
- 0 No error condition
-
- 1 Format error - The name server was
- unable to interpret the query.
-
- 2 Server failure - The name server was
- unable to process this query due to a
- problem with the name server.
-
- 3 Name Error - Meaningful only for
- responses from an authoritative name
- server, this code signifies that the
- domain name referenced in the query does
- not exist.
-
- 4 Not Implemented - The name server does
- not support the requested kind of query.
-
- 5 Refused - The name server refuses to
- perform the specified operation for
- policy reasons. For example, a name
- server may not wish to provide the
- information to the particular requester,
- or a name server may not wish to perform
- a particular operation (e.g., zone
-
-
-
-Mockapetris [Page 27]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
- transfer) for particular data.
-
- 6-15 Reserved for future use.
-
-QDCOUNT an unsigned 16 bit integer specifying the number of
- entries in the question section.
-
-ANCOUNT an unsigned 16 bit integer specifying the number of
- resource records in the answer section.
-
-NSCOUNT an unsigned 16 bit integer specifying the number of name
- server resource records in the authority records
- section.
-
-ARCOUNT an unsigned 16 bit integer specifying the number of
- resource records in the additional records section.
-
-4.1.2. Question section format
-
-The question section is used to carry the "question" in most queries,
-i.e., the parameters that define what is being asked. The section
-contains QDCOUNT (usually 1) entries, each of the following format:
-
- 1 1 1 1 1 1
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | |
- / QNAME /
- / /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | QTYPE |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | QCLASS |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-QNAME a domain name represented as a sequence of labels, where
- each label consists of a length octet followed by that
- number of octets. The domain name terminates with the
- zero length octet for the null label of the root. Note
- that this field may be an odd number of octets; no
- padding is used.
-
-QTYPE a two octet code which specifies the type of the query.
- The values for this field include all codes valid for a
- TYPE field, together with some more general codes which
- can match more than one type of RR.
-
-
-
-Mockapetris [Page 28]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-QCLASS a two octet code that specifies the class of the query.
- For example, the QCLASS field is IN for the Internet.
-
-4.1.3. Resource record format
-
-The answer, authority, and additional sections all share the same
-format: a variable number of resource records, where the number of
-records is specified in the corresponding count field in the header.
-Each resource record has the following format:
- 1 1 1 1 1 1
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | |
- / /
- / NAME /
- | |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | TYPE |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | CLASS |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | TTL |
- | |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | RDLENGTH |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--|
- / RDATA /
- / /
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-where:
-
-NAME a domain name to which this resource record pertains.
-
-TYPE two octets containing one of the RR type codes. This
- field specifies the meaning of the data in the RDATA
- field.
-
-CLASS two octets which specify the class of the data in the
- RDATA field.
-
-TTL a 32 bit unsigned integer that specifies the time
- interval (in seconds) that the resource record may be
- cached before it should be discarded. Zero values are
- interpreted to mean that the RR can only be used for the
- transaction in progress, and should not be cached.
-
-
-
-
-
-Mockapetris [Page 29]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-RDLENGTH an unsigned 16 bit integer that specifies the length in
- octets of the RDATA field.
-
-RDATA a variable length string of octets that describes the
- resource. The format of this information varies
- according to the TYPE and CLASS of the resource record.
- For example, the if the TYPE is A and the CLASS is IN,
- the RDATA field is a 4 octet ARPA Internet address.
-
-4.1.4. Message compression
-
-In order to reduce the size of messages, the domain system utilizes a
-compression scheme which eliminates the repetition of domain names in a
-message. In this scheme, an entire domain name or a list of labels at
-the end of a domain name is replaced with a pointer to a prior occurance
-of the same name.
-
-The pointer takes the form of a two octet sequence:
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- | 1 1| OFFSET |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-The first two bits are ones. This allows a pointer to be distinguished
-from a label, since the label must begin with two zero bits because
-labels are restricted to 63 octets or less. (The 10 and 01 combinations
-are reserved for future use.) The OFFSET field specifies an offset from
-the start of the message (i.e., the first octet of the ID field in the
-domain header). A zero offset specifies the first byte of the ID field,
-etc.
-
-The compression scheme allows a domain name in a message to be
-represented as either:
-
- - a sequence of labels ending in a zero octet
-
- - a pointer
-
- - a sequence of labels ending with a pointer
-
-Pointers can only be used for occurances of a domain name where the
-format is not class specific. If this were not the case, a name server
-or resolver would be required to know the format of all RRs it handled.
-As yet, there are no such cases, but they may occur in future RDATA
-formats.
-
-If a domain name is contained in a part of the message subject to a
-length field (such as the RDATA section of an RR), and compression is
-
-
-
-Mockapetris [Page 30]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-used, the length of the compressed name is used in the length
-calculation, rather than the length of the expanded name.
-
-Programs are free to avoid using pointers in messages they generate,
-although this will reduce datagram capacity, and may cause truncation.
-However all programs are required to understand arriving messages that
-contain pointers.
-
-For example, a datagram might need to use the domain names F.ISI.ARPA,
-FOO.F.ISI.ARPA, ARPA, and the root. Ignoring the other fields of the
-message, these domain names might be represented as:
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- 20 | 1 | F |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- 22 | 3 | I |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- 24 | S | I |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- 26 | 4 | A |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- 28 | R | P |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- 30 | A | 0 |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- 40 | 3 | F |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- 42 | O | O |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- 44 | 1 1| 20 |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- 64 | 1 1| 26 |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
- 92 | 0 | |
- +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
-
-The domain name for F.ISI.ARPA is shown at offset 20. The domain name
-FOO.F.ISI.ARPA is shown at offset 40; this definition uses a pointer to
-concatenate a label for FOO to the previously defined F.ISI.ARPA. The
-domain name ARPA is defined at offset 64 using a pointer to the ARPA
-component of the name F.ISI.ARPA at 20; note that this pointer relies on
-ARPA being the last label in the string at 20. The root domain name is
-
-
-
-Mockapetris [Page 31]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-defined by a single octet of zeros at 92; the root domain name has no
-labels.
-
-4.2. Transport
-
-The DNS assumes that messages will be transmitted as datagrams or in a
-byte stream carried by a virtual circuit. While virtual circuits can be
-used for any DNS activity, datagrams are preferred for queries due to
-their lower overhead and better performance. Zone refresh activities
-must use virtual circuits because of the need for reliable transfer.
-
-The Internet supports name server access using TCP [RFC-793] on server
-port 53 (decimal) as well as datagram access using UDP [RFC-768] on UDP
-port 53 (decimal).
-
-4.2.1. UDP usage
-
-Messages sent using UDP user server port 53 (decimal).
-
-Messages carried by UDP are restricted to 512 bytes (not counting the IP
-or UDP headers). Longer messages are truncated and the TC bit is set in
-the header.
-
-UDP is not acceptable for zone transfers, but is the recommended method
-for standard queries in the Internet. Queries sent using UDP may be
-lost, and hence a retransmission strategy is required. Queries or their
-responses may be reordered by the network, or by processing in name
-servers, so resolvers should not depend on them being returned in order.
-
-The optimal UDP retransmission policy will vary with performance of the
-Internet and the needs of the client, but the following are recommended:
-
- - The client should try other servers and server addresses
- before repeating a query to a specific address of a server.
-
- - The retransmission interval should be based on prior
- statistics if possible. Too aggressive retransmission can
- easily slow responses for the community at large. Depending
- on how well connected the client is to its expected servers,
- the minimum retransmission interval should be 2-5 seconds.
-
-More suggestions on server selection and retransmission policy can be
-found in the resolver section of this memo.
-
-4.2.2. TCP usage
-
-Messages sent over TCP connections use server port 53 (decimal). The
-message is prefixed with a two byte length field which gives the message
-
-
-
-Mockapetris [Page 32]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-length, excluding the two byte length field. This length field allows
-the low-level processing to assemble a complete message before beginning
-to parse it.
-
-Several connection management policies are recommended:
-
- - The server should not block other activities waiting for TCP
- data.
-
- - The server should support multiple connections.
-
- - The server should assume that the client will initiate
- connection closing, and should delay closing its end of the
- connection until all outstanding client requests have been
- satisfied.
-
- - If the server needs to close a dormant connection to reclaim
- resources, it should wait until the connection has been idle
- for a period on the order of two minutes. In particular, the
- server should allow the SOA and AXFR request sequence (which
- begins a refresh operation) to be made on a single connection.
- Since the server would be unable to answer queries anyway, a
- unilateral close or reset may be used instead of a graceful
- close.
-
-5. MASTER FILES
-
-Master files are text files that contain RRs in text form. Since the
-contents of a zone can be expressed in the form of a list of RRs a
-master file is most often used to define a zone, though it can be used
-to list a cache's contents. Hence, this section first discusses the
-format of RRs in a master file, and then the special considerations when
-a master file is used to create a zone in some name server.
-
-5.1. Format
-
-The format of these files is a sequence of entries. Entries are
-predominantly line-oriented, though parentheses can be used to continue
-a list of items across a line boundary, and text literals can contain
-CRLF within the text. Any combination of tabs and spaces act as a
-delimiter between the separate items that make up an entry. The end of
-any line in the master file can end with a comment. The comment starts
-with a ";" (semicolon).
-
-The following entries are defined:
-
- <blank>[<comment>]
-
-
-
-
-Mockapetris [Page 33]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
- $ORIGIN <domain-name> [<comment>]
-
- $INCLUDE <file-name> [<domain-name>] [<comment>]
-
- <domain-name><rr> [<comment>]
-
- <blank><rr> [<comment>]
-
-Blank lines, with or without comments, are allowed anywhere in the file.
-
-Two control entries are defined: $ORIGIN and $INCLUDE. $ORIGIN is
-followed by a domain name, and resets the current origin for relative
-domain names to the stated name. $INCLUDE inserts the named file into
-the current file, and may optionally specify a domain name that sets the
-relative domain name origin for the included file. $INCLUDE may also
-have a comment. Note that a $INCLUDE entry never changes the relative
-origin of the parent file, regardless of changes to the relative origin
-made within the included file.
-
-The last two forms represent RRs. If an entry for an RR begins with a
-blank, then the RR is assumed to be owned by the last stated owner. If
-an RR entry begins with a <domain-name>, then the owner name is reset.
-
-<rr> contents take one of the following forms:
-
- [<TTL>] [<class>] <type> <RDATA>
-
- [<class>] [<TTL>] <type> <RDATA>
-
-The RR begins with optional TTL and class fields, followed by a type and
-RDATA field appropriate to the type and class. Class and type use the
-standard mnemonics, TTL is a decimal integer. Omitted class and TTL
-values are default to the last explicitly stated values. Since type and
-class mnemonics are disjoint, the parse is unique. (Note that this
-order is different from the order used in examples and the order used in
-the actual RRs; the given order allows easier parsing and defaulting.)
-
-<domain-name>s make up a large share of the data in the master file.
-The labels in the domain name are expressed as character strings and
-separated by dots. Quoting conventions allow arbitrary characters to be
-stored in domain names. Domain names that end in a dot are called
-absolute, and are taken as complete. Domain names which do not end in a
-dot are called relative; the actual domain name is the concatenation of
-the relative part with an origin specified in a $ORIGIN, $INCLUDE, or as
-an argument to the master file loading routine. A relative name is an
-error when no origin is available.
-
-
-
-
-
-Mockapetris [Page 34]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-<character-string> is expressed in one or two ways: as a contiguous set
-of characters without interior spaces, or as a string beginning with a "
-and ending with a ". Inside a " delimited string any character can
-occur, except for a " itself, which must be quoted using \ (back slash).
-
-Because these files are text files several special encodings are
-necessary to allow arbitrary data to be loaded. In particular:
-
- of the root.
-
-@ A free standing @ is used to denote the current origin.
-
-\X where X is any character other than a digit (0-9), is
- used to quote that character so that its special meaning
- does not apply. For example, "\." can be used to place
- a dot character in a label.
-
-\DDD where each D is a digit is the octet corresponding to
- the decimal number described by DDD. The resulting
- octet is assumed to be text and is not checked for
- special meaning.
-
-( ) Parentheses are used to group data that crosses a line
- boundary. In effect, line terminations are not
- recognized within parentheses.
-
-; Semicolon is used to start a comment; the remainder of
- the line is ignored.
-
-5.2. Use of master files to define zones
-
-When a master file is used to load a zone, the operation should be
-suppressed if any errors are encountered in the master file. The
-rationale for this is that a single error can have widespread
-consequences. For example, suppose that the RRs defining a delegation
-have syntax errors; then the server will return authoritative name
-errors for all names in the subzone (except in the case where the
-subzone is also present on the server).
-
-Several other validity checks that should be performed in addition to
-insuring that the file is syntactically correct:
-
- 1. All RRs in the file should have the same class.
-
- 2. Exactly one SOA RR should be present at the top of the zone.
-
- 3. If delegations are present and glue information is required,
- it should be present.
-
-
-
-Mockapetris [Page 35]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
- 4. Information present outside of the authoritative nodes in the
- zone should be glue information, rather than the result of an
- origin or similar error.
-
-5.3. Master file example
-
-The following is an example file which might be used to define the
-ISI.EDU zone.and is loaded with an origin of ISI.EDU:
-
-@ IN SOA VENERA Action\.domains (
- 20 ; SERIAL
- 7200 ; REFRESH
- 600 ; RETRY
- 3600000; EXPIRE
- 60) ; MINIMUM
-
- NS A.ISI.EDU.
- NS VENERA
- NS VAXA
- MX 10 VENERA
- MX 20 VAXA
-
-A A 26.3.0.103
-
-VENERA A 10.1.0.52
- A 128.9.0.32
-
-VAXA A 10.2.0.27
- A 128.9.0.33
-
-
-$INCLUDE <SUBSYS>ISI-MAILBOXES.TXT
-
-Where the file <SUBSYS>ISI-MAILBOXES.TXT is:
-
- MOE MB A.ISI.EDU.
- LARRY MB A.ISI.EDU.
- CURLEY MB A.ISI.EDU.
- STOOGES MG MOE
- MG LARRY
- MG CURLEY
-
-Note the use of the \ character in the SOA RR to specify the responsible
-person mailbox "Action.domains@E.ISI.EDU".
-
-
-
-
-
-
-
-Mockapetris [Page 36]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-6. NAME SERVER IMPLEMENTATION
-
-6.1. Architecture
-
-The optimal structure for the name server will depend on the host
-operating system and whether the name server is integrated with resolver
-operations, either by supporting recursive service, or by sharing its
-database with a resolver. This section discusses implementation
-considerations for a name server which shares a database with a
-resolver, but most of these concerns are present in any name server.
-
-6.1.1. Control
-
-A name server must employ multiple concurrent activities, whether they
-are implemented as separate tasks in the host's OS or multiplexing
-inside a single name server program. It is simply not acceptable for a
-name server to block the service of UDP requests while it waits for TCP
-data for refreshing or query activities. Similarly, a name server
-should not attempt to provide recursive service without processing such
-requests in parallel, though it may choose to serialize requests from a
-single client, or to regard identical requests from the same client as
-duplicates. A name server should not substantially delay requests while
-it reloads a zone from master files or while it incorporates a newly
-refreshed zone into its database.
-
-6.1.2. Database
-
-While name server implementations are free to use any internal data
-structures they choose, the suggested structure consists of three major
-parts:
-
- - A "catalog" data structure which lists the zones available to
- this server, and a "pointer" to the zone data structure. The
- main purpose of this structure is to find the nearest ancestor
- zone, if any, for arriving standard queries.
-
- - Separate data structures for each of the zones held by the
- name server.
-
- - A data structure for cached data. (or perhaps separate caches
- for different classes)
-
-All of these data structures can be implemented an identical tree
-structure format, with different data chained off the nodes in different
-parts: in the catalog the data is pointers to zones, while in the zone
-and cache data structures, the data will be RRs. In designing the tree
-framework the designer should recognize that query processing will need
-to traverse the tree using case-insensitive label comparisons; and that
-
-
-
-Mockapetris [Page 37]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-in real data, a few nodes have a very high branching factor (100-1000 or
-more), but the vast majority have a very low branching factor (0-1).
-
-One way to solve the case problem is to store the labels for each node
-in two pieces: a standardized-case representation of the label where all
-ASCII characters are in a single case, together with a bit mask that
-denotes which characters are actually of a different case. The
-branching factor diversity can be handled using a simple linked list for
-a node until the branching factor exceeds some threshold, and
-transitioning to a hash structure after the threshold is exceeded. In
-any case, hash structures used to store tree sections must insure that
-hash functions and procedures preserve the casing conventions of the
-DNS.
-
-The use of separate structures for the different parts of the database
-is motivated by several factors:
-
- - The catalog structure can be an almost static structure that
- need change only when the system administrator changes the
- zones supported by the server. This structure can also be
- used to store parameters used to control refreshing
- activities.
-
- - The individual data structures for zones allow a zone to be
- replaced simply by changing a pointer in the catalog. Zone
- refresh operations can build a new structure and, when
- complete, splice it into the database via a simple pointer
- replacement. It is very important that when a zone is
- refreshed, queries should not use old and new data
- simultaneously.
-
- - With the proper search procedures, authoritative data in zones
- will always "hide", and hence take precedence over, cached
- data.
-
- - Errors in zone definitions that cause overlapping zones, etc.,
- may cause erroneous responses to queries, but problem
- determination is simplified, and the contents of one "bad"
- zone can't corrupt another.
-
- - Since the cache is most frequently updated, it is most
- vulnerable to corruption during system restarts. It can also
- become full of expired RR data. In either case, it can easily
- be discarded without disturbing zone data.
-
-A major aspect of database design is selecting a structure which allows
-the name server to deal with crashes of the name server's host. State
-information which a name server should save across system crashes
-
-
-
-Mockapetris [Page 38]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-includes the catalog structure (including the state of refreshing for
-each zone) and the zone data itself.
-
-6.1.3. Time
-
-Both the TTL data for RRs and the timing data for refreshing activities
-depends on 32 bit timers in units of seconds. Inside the database,
-refresh timers and TTLs for cached data conceptually "count down", while
-data in the zone stays with constant TTLs.
-
-A recommended implementation strategy is to store time in two ways: as
-a relative increment and as an absolute time. One way to do this is to
-use positive 32 bit numbers for one type and negative numbers for the
-other. The RRs in zones use relative times; the refresh timers and
-cache data use absolute times. Absolute numbers are taken with respect
-to some known origin and converted to relative values when placed in the
-response to a query. When an absolute TTL is negative after conversion
-to relative, then the data is expired and should be ignored.
-
-6.2. Standard query processing
-
-The major algorithm for standard query processing is presented in
-[RFC-1034].
-
-When processing queries with QCLASS=*, or some other QCLASS which
-matches multiple classes, the response should never be authoritative
-unless the server can guarantee that the response covers all classes.
-
-When composing a response, RRs which are to be inserted in the
-additional section, but duplicate RRs in the answer or authority
-sections, may be omitted from the additional section.
-
-When a response is so long that truncation is required, the truncation
-should start at the end of the response and work forward in the
-datagram. Thus if there is any data for the authority section, the
-answer section is guaranteed to be unique.
-
-The MINIMUM value in the SOA should be used to set a floor on the TTL of
-data distributed from a zone. This floor function should be done when
-the data is copied into a response. This will allow future dynamic
-update protocols to change the SOA MINIMUM field without ambiguous
-semantics.
-
-6.3. Zone refresh and reload processing
-
-In spite of a server's best efforts, it may be unable to load zone data
-from a master file due to syntax errors, etc., or be unable to refresh a
-zone within the its expiration parameter. In this case, the name server
-
-
-
-Mockapetris [Page 39]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-should answer queries as if it were not supposed to possess the zone.
-
-If a master is sending a zone out via AXFR, and a new version is created
-during the transfer, the master should continue to send the old version
-if possible. In any case, it should never send part of one version and
-part of another. If completion is not possible, the master should reset
-the connection on which the zone transfer is taking place.
-
-6.4. Inverse queries (Optional)
-
-Inverse queries are an optional part of the DNS. Name servers are not
-required to support any form of inverse queries. If a name server
-receives an inverse query that it does not support, it returns an error
-response with the "Not Implemented" error set in the header. While
-inverse query support is optional, all name servers must be at least
-able to return the error response.
-
-6.4.1. The contents of inverse queries and responses Inverse
-queries reverse the mappings performed by standard query operations;
-while a standard query maps a domain name to a resource, an inverse
-query maps a resource to a domain name. For example, a standard query
-might bind a domain name to a host address; the corresponding inverse
-query binds the host address to a domain name.
-
-Inverse queries take the form of a single RR in the answer section of
-the message, with an empty question section. The owner name of the
-query RR and its TTL are not significant. The response carries
-questions in the question section which identify all names possessing
-the query RR WHICH THE NAME SERVER KNOWS. Since no name server knows
-about all of the domain name space, the response can never be assumed to
-be complete. Thus inverse queries are primarily useful for database
-management and debugging activities. Inverse queries are NOT an
-acceptable method of mapping host addresses to host names; use the IN-
-ADDR.ARPA domain instead.
-
-Where possible, name servers should provide case-insensitive comparisons
-for inverse queries. Thus an inverse query asking for an MX RR of
-"Venera.isi.edu" should get the same response as a query for
-"VENERA.ISI.EDU"; an inverse query for HINFO RR "IBM-PC UNIX" should
-produce the same result as an inverse query for "IBM-pc unix". However,
-this cannot be guaranteed because name servers may possess RRs that
-contain character strings but the name server does not know that the
-data is character.
-
-When a name server processes an inverse query, it either returns:
-
- 1. zero, one, or multiple domain names for the specified
- resource as QNAMEs in the question section
-
-
-
-Mockapetris [Page 40]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
- 2. an error code indicating that the name server doesn't support
- inverse mapping of the specified resource type.
-
-When the response to an inverse query contains one or more QNAMEs, the
-owner name and TTL of the RR in the answer section which defines the
-inverse query is modified to exactly match an RR found at the first
-QNAME.
-
-RRs returned in the inverse queries cannot be cached using the same
-mechanism as is used for the replies to standard queries. One reason
-for this is that a name might have multiple RRs of the same type, and
-only one would appear. For example, an inverse query for a single
-address of a multiply homed host might create the impression that only
-one address existed.
-
-6.4.2. Inverse query and response example The overall structure
-of an inverse query for retrieving the domain name that corresponds to
-Internet address 10.1.0.52 is shown below:
-
- +-----------------------------------------+
- Header | OPCODE=IQUERY, ID=997 |
- +-----------------------------------------+
- Question | <empty> |
- +-----------------------------------------+
- Answer | <anyname> A IN 10.1.0.52 |
- +-----------------------------------------+
- Authority | <empty> |
- +-----------------------------------------+
- Additional | <empty> |
- +-----------------------------------------+
-
-This query asks for a question whose answer is the Internet style
-address 10.1.0.52. Since the owner name is not known, any domain name
-can be used as a placeholder (and is ignored). A single octet of zero,
-signifying the root, is usually used because it minimizes the length of
-the message. The TTL of the RR is not significant. The response to
-this query might be:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Mockapetris [Page 41]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
- +-----------------------------------------+
- Header | OPCODE=RESPONSE, ID=997 |
- +-----------------------------------------+
- Question |QTYPE=A, QCLASS=IN, QNAME=VENERA.ISI.EDU |
- +-----------------------------------------+
- Answer | VENERA.ISI.EDU A IN 10.1.0.52 |
- +-----------------------------------------+
- Authority | <empty> |
- +-----------------------------------------+
- Additional | <empty> |
- +-----------------------------------------+
-
-Note that the QTYPE in a response to an inverse query is the same as the
-TYPE field in the answer section of the inverse query. Responses to
-inverse queries may contain multiple questions when the inverse is not
-unique. If the question section in the response is not empty, then the
-RR in the answer section is modified to correspond to be an exact copy
-of an RR at the first QNAME.
-
-6.4.3. Inverse query processing
-
-Name servers that support inverse queries can support these operations
-through exhaustive searches of their databases, but this becomes
-impractical as the size of the database increases. An alternative
-approach is to invert the database according to the search key.
-
-For name servers that support multiple zones and a large amount of data,
-the recommended approach is separate inversions for each zone. When a
-particular zone is changed during a refresh, only its inversions need to
-be redone.
-
-Support for transfer of this type of inversion may be included in future
-versions of the domain system, but is not supported in this version.
-
-6.5. Completion queries and responses
-
-The optional completion services described in RFC-882 and RFC-883 have
-been deleted. Redesigned services may become available in the future.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Mockapetris [Page 42]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-7. RESOLVER IMPLEMENTATION
-
-The top levels of the recommended resolver algorithm are discussed in
-[RFC-1034]. This section discusses implementation details assuming the
-database structure suggested in the name server implementation section
-of this memo.
-
-7.1. Transforming a user request into a query
-
-The first step a resolver takes is to transform the client's request,
-stated in a format suitable to the local OS, into a search specification
-for RRs at a specific name which match a specific QTYPE and QCLASS.
-Where possible, the QTYPE and QCLASS should correspond to a single type
-and a single class, because this makes the use of cached data much
-simpler. The reason for this is that the presence of data of one type
-in a cache doesn't confirm the existence or non-existence of data of
-other types, hence the only way to be sure is to consult an
-authoritative source. If QCLASS=* is used, then authoritative answers
-won't be available.
-
-Since a resolver must be able to multiplex multiple requests if it is to
-perform its function efficiently, each pending request is usually
-represented in some block of state information. This state block will
-typically contain:
-
- - A timestamp indicating the time the request began.
- The timestamp is used to decide whether RRs in the database
- can be used or are out of date. This timestamp uses the
- absolute time format previously discussed for RR storage in
- zones and caches. Note that when an RRs TTL indicates a
- relative time, the RR must be timely, since it is part of a
- zone. When the RR has an absolute time, it is part of a
- cache, and the TTL of the RR is compared against the timestamp
- for the start of the request.
-
- Note that using the timestamp is superior to using a current
- time, since it allows RRs with TTLs of zero to be entered in
- the cache in the usual manner, but still used by the current
- request, even after intervals of many seconds due to system
- load, query retransmission timeouts, etc.
-
- - Some sort of parameters to limit the amount of work which will
- be performed for this request.
-
- The amount of work which a resolver will do in response to a
- client request must be limited to guard against errors in the
- database, such as circular CNAME references, and operational
- problems, such as network partition which prevents the
-
-
-
-Mockapetris [Page 43]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
- resolver from accessing the name servers it needs. While
- local limits on the number of times a resolver will retransmit
- a particular query to a particular name server address are
- essential, the resolver should have a global per-request
- counter to limit work on a single request. The counter should
- be set to some initial value and decremented whenever the
- resolver performs any action (retransmission timeout,
- retransmission, etc.) If the counter passes zero, the request
- is terminated with a temporary error.
-
- Note that if the resolver structure allows one request to
- start others in parallel, such as when the need to access a
- name server for one request causes a parallel resolve for the
- name server's addresses, the spawned request should be started
- with a lower counter. This prevents circular references in
- the database from starting a chain reaction of resolver
- activity.
-
- - The SLIST data structure discussed in [RFC-1034].
-
- This structure keeps track of the state of a request if it
- must wait for answers from foreign name servers.
-
-7.2. Sending the queries
-
-As described in [RFC-1034], the basic task of the resolver is to
-formulate a query which will answer the client's request and direct that
-query to name servers which can provide the information. The resolver
-will usually only have very strong hints about which servers to ask, in
-the form of NS RRs, and may have to revise the query, in response to
-CNAMEs, or revise the set of name servers the resolver is asking, in
-response to delegation responses which point the resolver to name
-servers closer to the desired information. In addition to the
-information requested by the client, the resolver may have to call upon
-its own services to determine the address of name servers it wishes to
-contact.
-
-In any case, the model used in this memo assumes that the resolver is
-multiplexing attention between multiple requests, some from the client,
-and some internally generated. Each request is represented by some
-state information, and the desired behavior is that the resolver
-transmit queries to name servers in a way that maximizes the probability
-that the request is answered, minimizes the time that the request takes,
-and avoids excessive transmissions. The key algorithm uses the state
-information of the request to select the next name server address to
-query, and also computes a timeout which will cause the next action
-should a response not arrive. The next action will usually be a
-transmission to some other server, but may be a temporary error to the
-
-
-
-Mockapetris [Page 44]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-client.
-
-The resolver always starts with a list of server names to query (SLIST).
-This list will be all NS RRs which correspond to the nearest ancestor
-zone that the resolver knows about. To avoid startup problems, the
-resolver should have a set of default servers which it will ask should
-it have no current NS RRs which are appropriate. The resolver then adds
-to SLIST all of the known addresses for the name servers, and may start
-parallel requests to acquire the addresses of the servers when the
-resolver has the name, but no addresses, for the name servers.
-
-To complete initialization of SLIST, the resolver attaches whatever
-history information it has to the each address in SLIST. This will
-usually consist of some sort of weighted averages for the response time
-of the address, and the batting average of the address (i.e., how often
-the address responded at all to the request). Note that this
-information should be kept on a per address basis, rather than on a per
-name server basis, because the response time and batting average of a
-particular server may vary considerably from address to address. Note
-also that this information is actually specific to a resolver address /
-server address pair, so a resolver with multiple addresses may wish to
-keep separate histories for each of its addresses. Part of this step
-must deal with addresses which have no such history; in this case an
-expected round trip time of 5-10 seconds should be the worst case, with
-lower estimates for the same local network, etc.
-
-Note that whenever a delegation is followed, the resolver algorithm
-reinitializes SLIST.
-
-The information establishes a partial ranking of the available name
-server addresses. Each time an address is chosen and the state should
-be altered to prevent its selection again until all other addresses have
-been tried. The timeout for each transmission should be 50-100% greater
-than the average predicted value to allow for variance in response.
-
-Some fine points:
-
- - The resolver may encounter a situation where no addresses are
- available for any of the name servers named in SLIST, and
- where the servers in the list are precisely those which would
- normally be used to look up their own addresses. This
- situation typically occurs when the glue address RRs have a
- smaller TTL than the NS RRs marking delegation, or when the
- resolver caches the result of a NS search. The resolver
- should detect this condition and restart the search at the
- next ancestor zone, or alternatively at the root.
-
-
-
-
-
-Mockapetris [Page 45]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
- - If a resolver gets a server error or other bizarre response
- from a name server, it should remove it from SLIST, and may
- wish to schedule an immediate transmission to the next
- candidate server address.
-
-7.3. Processing responses
-
-The first step in processing arriving response datagrams is to parse the
-response. This procedure should include:
-
- - Check the header for reasonableness. Discard datagrams which
- are queries when responses are expected.
-
- - Parse the sections of the message, and insure that all RRs are
- correctly formatted.
-
- - As an optional step, check the TTLs of arriving data looking
- for RRs with excessively long TTLs. If a RR has an
- excessively long TTL, say greater than 1 week, either discard
- the whole response, or limit all TTLs in the response to 1
- week.
-
-The next step is to match the response to a current resolver request.
-The recommended strategy is to do a preliminary matching using the ID
-field in the domain header, and then to verify that the question section
-corresponds to the information currently desired. This requires that
-the transmission algorithm devote several bits of the domain ID field to
-a request identifier of some sort. This step has several fine points:
-
- - Some name servers send their responses from different
- addresses than the one used to receive the query. That is, a
- resolver cannot rely that a response will come from the same
- address which it sent the corresponding query to. This name
- server bug is typically encountered in UNIX systems.
-
- - If the resolver retransmits a particular request to a name
- server it should be able to use a response from any of the
- transmissions. However, if it is using the response to sample
- the round trip time to access the name server, it must be able
- to determine which transmission matches the response (and keep
- transmission times for each outgoing message), or only
- calculate round trip times based on initial transmissions.
-
- - A name server will occasionally not have a current copy of a
- zone which it should have according to some NS RRs. The
- resolver should simply remove the name server from the current
- SLIST, and continue.
-
-
-
-
-Mockapetris [Page 46]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-7.4. Using the cache
-
-In general, we expect a resolver to cache all data which it receives in
-responses since it may be useful in answering future client requests.
-However, there are several types of data which should not be cached:
-
- - When several RRs of the same type are available for a
- particular owner name, the resolver should either cache them
- all or none at all. When a response is truncated, and a
- resolver doesn't know whether it has a complete set, it should
- not cache a possibly partial set of RRs.
-
- - Cached data should never be used in preference to
- authoritative data, so if caching would cause this to happen
- the data should not be cached.
-
- - The results of an inverse query should not be cached.
-
- - The results of standard queries where the QNAME contains "*"
- labels if the data might be used to construct wildcards. The
- reason is that the cache does not necessarily contain existing
- RRs or zone boundary information which is necessary to
- restrict the application of the wildcard RRs.
-
- - RR data in responses of dubious reliability. When a resolver
- receives unsolicited responses or RR data other than that
- requested, it should discard it without caching it. The basic
- implication is that all sanity checks on a packet should be
- performed before any of it is cached.
-
-In a similar vein, when a resolver has a set of RRs for some name in a
-response, and wants to cache the RRs, it should check its cache for
-already existing RRs. Depending on the circumstances, either the data
-in the response or the cache is preferred, but the two should never be
-combined. If the data in the response is from authoritative data in the
-answer section, it is always preferred.
-
-8. MAIL SUPPORT
-
-The domain system defines a standard for mapping mailboxes into domain
-names, and two methods for using the mailbox information to derive mail
-routing information. The first method is called mail exchange binding
-and the other method is mailbox binding. The mailbox encoding standard
-and mail exchange binding are part of the DNS official protocol, and are
-the recommended method for mail routing in the Internet. Mailbox
-binding is an experimental feature which is still under development and
-subject to change.
-
-
-
-
-Mockapetris [Page 47]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-The mailbox encoding standard assumes a mailbox name of the form
-"<local-part>@<mail-domain>". While the syntax allowed in each of these
-sections varies substantially between the various mail internets, the
-preferred syntax for the ARPA Internet is given in [RFC-822].
-
-The DNS encodes the <local-part> as a single label, and encodes the
-<mail-domain> as a domain name. The single label from the <local-part>
-is prefaced to the domain name from <mail-domain> to form the domain
-name corresponding to the mailbox. Thus the mailbox HOSTMASTER@SRI-
-NIC.ARPA is mapped into the domain name HOSTMASTER.SRI-NIC.ARPA. If the
-<local-part> contains dots or other special characters, its
-representation in a master file will require the use of backslash
-quoting to ensure that the domain name is properly encoded. For
-example, the mailbox Action.domains@ISI.EDU would be represented as
-Action\.domains.ISI.EDU.
-
-8.1. Mail exchange binding
-
-Mail exchange binding uses the <mail-domain> part of a mailbox
-specification to determine where mail should be sent. The <local-part>
-is not even consulted. [RFC-974] specifies this method in detail, and
-should be consulted before attempting to use mail exchange support.
-
-One of the advantages of this method is that it decouples mail
-destination naming from the hosts used to support mail service, at the
-cost of another layer of indirection in the lookup function. However,
-the addition layer should eliminate the need for complicated "%", "!",
-etc encodings in <local-part>.
-
-The essence of the method is that the <mail-domain> is used as a domain
-name to locate type MX RRs which list hosts willing to accept mail for
-<mail-domain>, together with preference values which rank the hosts
-according to an order specified by the administrators for <mail-domain>.
-
-In this memo, the <mail-domain> ISI.EDU is used in examples, together
-with the hosts VENERA.ISI.EDU and VAXA.ISI.EDU as mail exchanges for
-ISI.EDU. If a mailer had a message for Mockapetris@ISI.EDU, it would
-route it by looking up MX RRs for ISI.EDU. The MX RRs at ISI.EDU name
-VENERA.ISI.EDU and VAXA.ISI.EDU, and type A queries can find the host
-addresses.
-
-8.2. Mailbox binding (Experimental)
-
-In mailbox binding, the mailer uses the entire mail destination
-specification to construct a domain name. The encoded domain name for
-the mailbox is used as the QNAME field in a QTYPE=MAILB query.
-
-Several outcomes are possible for this query:
-
-
-
-Mockapetris [Page 48]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
- 1. The query can return a name error indicating that the mailbox
- does not exist as a domain name.
-
- In the long term, this would indicate that the specified
- mailbox doesn't exist. However, until the use of mailbox
- binding is universal, this error condition should be
- interpreted to mean that the organization identified by the
- global part does not support mailbox binding. The
- appropriate procedure is to revert to exchange binding at
- this point.
-
- 2. The query can return a Mail Rename (MR) RR.
-
- The MR RR carries new mailbox specification in its RDATA
- field. The mailer should replace the old mailbox with the
- new one and retry the operation.
-
- 3. The query can return a MB RR.
-
- The MB RR carries a domain name for a host in its RDATA
- field. The mailer should deliver the message to that host
- via whatever protocol is applicable, e.g., b,SMTP.
-
- 4. The query can return one or more Mail Group (MG) RRs.
-
- This condition means that the mailbox was actually a mailing
- list or mail group, rather than a single mailbox. Each MG RR
- has a RDATA field that identifies a mailbox that is a member
- of the group. The mailer should deliver a copy of the
- message to each member.
-
- 5. The query can return a MB RR as well as one or more MG RRs.
-
- This condition means the the mailbox was actually a mailing
- list. The mailer can either deliver the message to the host
- specified by the MB RR, which will in turn do the delivery to
- all members, or the mailer can use the MG RRs to do the
- expansion itself.
-
-In any of these cases, the response may include a Mail Information
-(MINFO) RR. This RR is usually associated with a mail group, but is
-legal with a MB. The MINFO RR identifies two mailboxes. One of these
-identifies a responsible person for the original mailbox name. This
-mailbox should be used for requests to be added to a mail group, etc.
-The second mailbox name in the MINFO RR identifies a mailbox that should
-receive error messages for mail failures. This is particularly
-appropriate for mailing lists when errors in member names should be
-reported to a person other than the one who sends a message to the list.
-
-
-
-Mockapetris [Page 49]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-New fields may be added to this RR in the future.
-
-
-9. REFERENCES and BIBLIOGRAPHY
-
-[Dyer 87] S. Dyer, F. Hsu, "Hesiod", Project Athena
- Technical Plan - Name Service, April 1987, version 1.9.
-
- Describes the fundamentals of the Hesiod name service.
-
-[IEN-116] J. Postel, "Internet Name Server", IEN-116,
- USC/Information Sciences Institute, August 1979.
-
- A name service obsoleted by the Domain Name System, but
- still in use.
-
-[Quarterman 86] J. Quarterman, and J. Hoskins, "Notable Computer Networks",
- Communications of the ACM, October 1986, volume 29, number
- 10.
-
-[RFC-742] K. Harrenstien, "NAME/FINGER", RFC-742, Network
- Information Center, SRI International, December 1977.
-
-[RFC-768] J. Postel, "User Datagram Protocol", RFC-768,
- USC/Information Sciences Institute, August 1980.
-
-[RFC-793] J. Postel, "Transmission Control Protocol", RFC-793,
- USC/Information Sciences Institute, September 1981.
-
-[RFC-799] D. Mills, "Internet Name Domains", RFC-799, COMSAT,
- September 1981.
-
- Suggests introduction of a hierarchy in place of a flat
- name space for the Internet.
-
-[RFC-805] J. Postel, "Computer Mail Meeting Notes", RFC-805,
- USC/Information Sciences Institute, February 1982.
-
-[RFC-810] E. Feinler, K. Harrenstien, Z. Su, and V. White, "DOD
- Internet Host Table Specification", RFC-810, Network
- Information Center, SRI International, March 1982.
-
- Obsolete. See RFC-952.
-
-[RFC-811] K. Harrenstien, V. White, and E. Feinler, "Hostnames
- Server", RFC-811, Network Information Center, SRI
- International, March 1982.
-
-
-
-
-Mockapetris [Page 50]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
- Obsolete. See RFC-953.
-
-[RFC-812] K. Harrenstien, and V. White, "NICNAME/WHOIS", RFC-812,
- Network Information Center, SRI International, March
- 1982.
-
-[RFC-819] Z. Su, and J. Postel, "The Domain Naming Convention for
- Internet User Applications", RFC-819, Network
- Information Center, SRI International, August 1982.
-
- Early thoughts on the design of the domain system.
- Current implementation is completely different.
-
-[RFC-821] J. Postel, "Simple Mail Transfer Protocol", RFC-821,
- USC/Information Sciences Institute, August 1980.
-
-[RFC-830] Z. Su, "A Distributed System for Internet Name Service",
- RFC-830, Network Information Center, SRI International,
- October 1982.
-
- Early thoughts on the design of the domain system.
- Current implementation is completely different.
-
-[RFC-882] P. Mockapetris, "Domain names - Concepts and
- Facilities," RFC-882, USC/Information Sciences
- Institute, November 1983.
-
- Superceeded by this memo.
-
-[RFC-883] P. Mockapetris, "Domain names - Implementation and
- Specification," RFC-883, USC/Information Sciences
- Institute, November 1983.
-
- Superceeded by this memo.
-
-[RFC-920] J. Postel and J. Reynolds, "Domain Requirements",
- RFC-920, USC/Information Sciences Institute,
- October 1984.
-
- Explains the naming scheme for top level domains.
-
-[RFC-952] K. Harrenstien, M. Stahl, E. Feinler, "DoD Internet Host
- Table Specification", RFC-952, SRI, October 1985.
-
- Specifies the format of HOSTS.TXT, the host/address
- table replaced by the DNS.
-
-
-
-
-
-Mockapetris [Page 51]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-[RFC-953] K. Harrenstien, M. Stahl, E. Feinler, "HOSTNAME Server",
- RFC-953, SRI, October 1985.
-
- This RFC contains the official specification of the
- hostname server protocol, which is obsoleted by the DNS.
- This TCP based protocol accesses information stored in
- the RFC-952 format, and is used to obtain copies of the
- host table.
-
-[RFC-973] P. Mockapetris, "Domain System Changes and
- Observations", RFC-973, USC/Information Sciences
- Institute, January 1986.
-
- Describes changes to RFC-882 and RFC-883 and reasons for
- them.
-
-[RFC-974] C. Partridge, "Mail routing and the domain system",
- RFC-974, CSNET CIC BBN Labs, January 1986.
-
- Describes the transition from HOSTS.TXT based mail
- addressing to the more powerful MX system used with the
- domain system.
-
-[RFC-1001] NetBIOS Working Group, "Protocol standard for a NetBIOS
- service on a TCP/UDP transport: Concepts and Methods",
- RFC-1001, March 1987.
-
- This RFC and RFC-1002 are a preliminary design for
- NETBIOS on top of TCP/IP which proposes to base NetBIOS
- name service on top of the DNS.
-
-[RFC-1002] NetBIOS Working Group, "Protocol standard for a NetBIOS
- service on a TCP/UDP transport: Detailed
- Specifications", RFC-1002, March 1987.
-
-[RFC-1010] J. Reynolds, and J. Postel, "Assigned Numbers", RFC-1010,
- USC/Information Sciences Institute, May 1987.
-
- Contains socket numbers and mnemonics for host names,
- operating systems, etc.
-
-[RFC-1031] W. Lazear, "MILNET Name Domain Transition", RFC-1031,
- November 1987.
-
- Describes a plan for converting the MILNET to the DNS.
-
-[RFC-1032] M. Stahl, "Establishing a Domain - Guidelines for
- Administrators", RFC-1032, November 1987.
-
-
-
-Mockapetris [Page 52]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
- Describes the registration policies used by the NIC to
- administer the top level domains and delegate subzones.
-
-[RFC-1033] M. Lottor, "Domain Administrators Operations Guide",
- RFC-1033, November 1987.
-
- A cookbook for domain administrators.
-
-[Solomon 82] M. Solomon, L. Landweber, and D. Neuhengen, "The CSNET
- Name Server", Computer Networks, vol 6, nr 3, July 1982.
-
- Describes a name service for CSNET which is independent
- from the DNS and DNS use in the CSNET.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Mockapetris [Page 53]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
-Index
-
- * 13
-
- ; 33, 35
-
- <character-string> 35
- <domain-name> 34
-
- @ 35
-
- \ 35
-
- A 12
-
- Byte order 8
-
- CH 13
- Character case 9
- CLASS 11
- CNAME 12
- Completion 42
- CS 13
-
- Hesiod 13
- HINFO 12
- HS 13
-
- IN 13
- IN-ADDR.ARPA domain 22
- Inverse queries 40
-
- Mailbox names 47
- MB 12
- MD 12
- MF 12
- MG 12
- MINFO 12
- MINIMUM 20
- MR 12
- MX 12
-
- NS 12
- NULL 12
-
- Port numbers 32
- Primary server 5
- PTR 12, 18
-
-
-
-Mockapetris [Page 54]
-\f
-RFC 1035 Domain Implementation and Specification November 1987
-
-
- QCLASS 13
- QTYPE 12
-
- RDATA 12
- RDLENGTH 11
-
- Secondary server 5
- SOA 12
- Stub resolvers 7
-
- TCP 32
- TXT 12
- TYPE 11
-
- UDP 32
-
- WKS 12
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Mockapetris [Page 55]
-\f
+++ /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 Working Group T. Berners-Lee
-Request for Comments: 1738 CERN
-Category: Standards Track L. Masinter
- Xerox Corporation
- M. McCahill
- University of Minnesota
- Editors
- December 1994
-
-
- Uniform Resource Locators (URL)
-
-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
-
- This document specifies a Uniform Resource Locator (URL), the syntax
- and semantics of formalized information for location and access of
- resources via the Internet.
-
-1. Introduction
-
- This document describes the syntax and semantics for a compact string
- representation for a resource available via the Internet. These
- strings are called "Uniform Resource Locators" (URLs).
-
- The specification is derived from concepts introduced by the World-
- Wide Web global information initiative, whose use of such objects
- dates from 1990 and is described in "Universal Resource Identifiers
- in WWW", RFC 1630. The specification of URLs is designed to meet the
- requirements laid out in "Functional Requirements for Internet
- Resource Locators" [12].
-
- This document was written by the URI working group of the Internet
- Engineering Task Force. Comments may be addressed to the editors, or
- to the URI-WG <uri@bunyip.com>. Discussions of the group are archived
- at <URL:http://www.acl.lanl.gov/URI/archive/uri-archive.index.html>
-
-
-
-
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 1]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
-2. General URL Syntax
-
- Just as there are many different methods of access to resources,
- there are several schemes for describing the location of such
- resources.
-
- The generic syntax for URLs provides a framework for new schemes to
- be established using protocols other than those defined in this
- document.
-
- URLs are used to `locate' resources, by providing an abstract
- identification of the resource location. Having located a resource,
- a system may perform a variety of operations on the resource, as
- might be characterized by such words as `access', `update',
- `replace', `find attributes'. In general, only the `access' method
- needs to be specified for any URL scheme.
-
-2.1. The main parts of URLs
-
- A full BNF description of the URL syntax is given in Section 5.
-
- In general, URLs are written as follows:
-
- <scheme>:<scheme-specific-part>
-
- A URL contains the name of the scheme being used (<scheme>) followed
- by a colon and then a string (the <scheme-specific-part>) whose
- interpretation depends on the scheme.
-
- Scheme names consist of a sequence of characters. The lower case
- letters "a"--"z", digits, and the characters plus ("+"), period
- ("."), and hyphen ("-") are allowed. For resiliency, programs
- interpreting URLs should treat upper case letters as equivalent to
- lower case in scheme names (e.g., allow "HTTP" as well as "http").
-
-2.2. URL Character Encoding Issues
-
- URLs are sequences of characters, i.e., letters, digits, and special
- characters. A URLs may be represented in a variety of ways: e.g., ink
- on paper, or a sequence of octets in a coded character set. The
- interpretation of a URL depends only on the identity of the
- characters used.
-
- In most URL schemes, the sequences of characters in different parts
- of a URL are used to represent sequences of octets used in Internet
- protocols. For example, in the ftp scheme, the host name, directory
- name and file names are such sequences of octets, represented by
- parts of the URL. Within those parts, an octet may be represented by
-
-
-
-Berners-Lee, Masinter & McCahill [Page 2]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
- the chararacter which has that octet as its code within the US-ASCII
- [20] coded character set.
-
- In addition, octets may be encoded by a character triplet consisting
- of the character "%" followed by the two hexadecimal digits (from
- "0123456789ABCDEF") which forming the hexadecimal value of the octet.
- (The characters "abcdef" may also be used in hexadecimal encodings.)
-
- Octets must be encoded if they have no corresponding graphic
- character within the US-ASCII coded character set, if the use of the
- corresponding character is unsafe, or if the corresponding character
- is reserved for some other interpretation within the particular URL
- scheme.
-
- No corresponding graphic US-ASCII:
-
- URLs are written only with the graphic printable characters of the
- US-ASCII coded character set. The octets 80-FF hexadecimal are not
- used in US-ASCII, and the octets 00-1F and 7F hexadecimal represent
- control characters; these must be encoded.
-
- Unsafe:
-
- Characters can be unsafe for a number of reasons. The space
- character is unsafe because significant spaces may disappear and
- insignificant spaces may be introduced when URLs are transcribed or
- typeset or subjected to the treatment of word-processing programs.
- The characters "<" and ">" are unsafe because they are used as the
- delimiters around URLs in free text; the quote mark (""") is used to
- delimit URLs in some systems. The character "#" is unsafe and should
- always be encoded because it is used in World Wide Web and in other
- systems to delimit a URL from a fragment/anchor identifier that might
- follow it. The character "%" is unsafe because it is used for
- encodings of other characters. Other characters are unsafe because
- gateways and other transport agents are known to sometimes modify
- such characters. These characters are "{", "}", "|", "\", "^", "~",
- "[", "]", and "`".
-
- All unsafe characters must always be encoded within a URL. For
- example, the character "#" must be encoded within URLs even in
- systems that do not normally deal with fragment or anchor
- identifiers, so that if the URL is copied into another system that
- does use them, it will not be necessary to change the URL encoding.
-
-
-
-
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 3]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
- Reserved:
-
- Many URL schemes reserve certain characters for a special meaning:
- their appearance in the scheme-specific part of the URL has a
- designated semantics. If the character corresponding to an octet is
- reserved in a scheme, the octet must be encoded. The characters ";",
- "/", "?", ":", "@", "=" and "&" are the characters which may be
- reserved for special meaning within a scheme. No other characters may
- be reserved within a scheme.
-
- Usually a URL has the same interpretation when an octet is
- represented by a character and when it encoded. However, this is not
- true for reserved characters: encoding a character reserved for a
- particular scheme may change the semantics of a URL.
-
- Thus, only alphanumerics, the special characters "$-_.+!*'(),", and
- reserved characters used for their reserved purposes may be used
- unencoded within a URL.
-
- On the other hand, characters that are not required to be encoded
- (including alphanumerics) may be encoded within the scheme-specific
- part of a URL, as long as they are not being used for a reserved
- purpose.
-
-2.3 Hierarchical schemes and relative links
-
- In some cases, URLs are used to locate resources that contain
- pointers to other resources. In some cases, those pointers are
- represented as relative links where the expression of the location of
- the second resource is in terms of "in the same place as this one
- except with the following relative path". Relative links are not
- described in this document. However, the use of relative links
- depends on the original URL containing a hierarchical structure
- against which the relative link is based.
-
- Some URL schemes (such as the ftp, http, and file schemes) contain
- names that can be considered hierarchical; the components of the
- hierarchy are separated by "/".
-
-
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 4]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
-3. Specific Schemes
-
- The mapping for some existing standard and experimental protocols is
- outlined in the BNF syntax definition. Notes on particular protocols
- follow. The schemes covered are:
-
- ftp File Transfer protocol
- http Hypertext Transfer Protocol
- gopher The Gopher protocol
- mailto Electronic mail address
- news USENET news
- nntp USENET news using NNTP access
- telnet Reference to interactive sessions
- wais Wide Area Information Servers
- file Host-specific file names
- prospero Prospero Directory Service
-
- Other schemes may be specified by future specifications. Section 4 of
- this document describes how new schemes may be registered, and lists
- some scheme names that are under development.
-
-3.1. Common Internet Scheme Syntax
-
- While the syntax for the rest of the URL may vary depending on the
- particular scheme selected, URL schemes that involve the direct use
- of an IP-based protocol to a specified host on the Internet use a
- common syntax for the scheme-specific data:
-
- //<user>:<password>@<host>:<port>/<url-path>
-
- Some or all of the parts "<user>:<password>@", ":<password>",
- ":<port>", and "/<url-path>" may be excluded. The scheme specific
- data start with a double slash "//" to indicate that it complies with
- the common Internet scheme syntax. The different components obey the
- following rules:
-
- user
- An optional user name. Some schemes (e.g., ftp) allow the
- specification of a user name.
-
- password
- An optional password. If present, it follows the user
- name separated from it by a colon.
-
- The user name (and password), if present, are followed by a
- commercial at-sign "@". Within the user and password field, any ":",
- "@", or "/" must be encoded.
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 5]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
- Note that an empty user name or password is different than no user
- name or password; there is no way to specify a password without
- specifying a user name. E.g., <URL:ftp://@host.com/> has an empty
- user name and no password, <URL:ftp://host.com/> has no user name,
- while <URL:ftp://foo:@host.com/> has a user name of "foo" and an
- empty password.
-
- host
- The fully qualified domain name of a network host, or its IP
- address as a set of four decimal digit groups separated by
- ".". Fully qualified domain names take the form as described
- in Section 3.5 of RFC 1034 [13] and Section 2.1 of RFC 1123
- [5]: a sequence of domain labels separated by ".", each domain
- label starting and ending with an alphanumerical character and
- possibly also containing "-" characters. The rightmost domain
- label will never start with a digit, though, which
- syntactically distinguishes all domain names from the IP
- addresses.
-
- port
- The port number to connect to. Most schemes designate
- protocols that have a default port number. Another port number
- may optionally be supplied, in decimal, separated from the
- host by a colon. If the port is omitted, the colon is as well.
-
- url-path
- The rest of the locator consists of data specific to the
- scheme, and is known as the "url-path". It supplies the
- details of how the specified resource can be accessed. Note
- that the "/" between the host (or port) and the url-path is
- NOT part of the url-path.
-
- The url-path syntax depends on the scheme being used, as does the
- manner in which it is interpreted.
-
-3.2. FTP
-
- The FTP URL scheme is used to designate files and directories on
- Internet hosts accessible using the FTP protocol (RFC959).
-
- A FTP URL follow the syntax described in Section 3.1. If :<port> is
- omitted, the port defaults to 21.
-
-
-
-
-
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 6]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
-3.2.1. FTP Name and Password
-
- A user name and password may be supplied; they are used in the ftp
- "USER" and "PASS" commands after first making the connection to the
- FTP server. If no user name or password is supplied and one is
- requested by the FTP server, the conventions for "anonymous" FTP are
- to be used, as follows:
-
- The user name "anonymous" is supplied.
-
- The password is supplied as the Internet e-mail address
- of the end user accessing the resource.
-
- If the URL supplies a user name but no password, and the remote
- server requests a password, the program interpreting the FTP URL
- should request one from the user.
-
-3.2.2. FTP url-path
-
- The url-path of a FTP URL has the following syntax:
-
- <cwd1>/<cwd2>/.../<cwdN>/<name>;type=<typecode>
-
- Where <cwd1> through <cwdN> and <name> are (possibly encoded) strings
- and <typecode> is one of the characters "a", "i", or "d". The part
- ";type=<typecode>" may be omitted. The <cwdx> and <name> parts may be
- empty. The whole url-path may be omitted, including the "/"
- delimiting it from the prefix containing user, password, host, and
- port.
-
- The url-path is interpreted as a series of FTP commands as follows:
-
- Each of the <cwd> elements is to be supplied, sequentially, as the
- argument to a CWD (change working directory) command.
-
- If the typecode is "d", perform a NLST (name list) command with
- <name> as the argument, and interpret the results as a file
- directory listing.
-
- Otherwise, perform a TYPE command with <typecode> as the argument,
- and then access the file whose name is <name> (for example, using
- the RETR command.)
-
- Within a name or CWD component, the characters "/" and ";" are
- reserved and must be encoded. The components are decoded prior to
- their use in the FTP protocol. In particular, if the appropriate FTP
- sequence to access a particular file requires supplying a string
- containing a "/" as an argument to a CWD or RETR command, it is
-
-
-
-Berners-Lee, Masinter & McCahill [Page 7]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
- necessary to encode each "/".
-
- For example, the URL <URL:ftp://myname@host.dom/%2Fetc/motd> is
- interpreted by FTP-ing to "host.dom", logging in as "myname"
- (prompting for a password if it is asked for), and then executing
- "CWD /etc" and then "RETR motd". This has a different meaning from
- <URL:ftp://myname@host.dom/etc/motd> which would "CWD etc" and then
- "RETR motd"; the initial "CWD" might be executed relative to the
- default directory for "myname". On the other hand,
- <URL:ftp://myname@host.dom//etc/motd>, would "CWD " with a null
- argument, then "CWD etc", and then "RETR motd".
-
- FTP URLs may also be used for other operations; for example, it is
- possible to update a file on a remote file server, or infer
- information about it from the directory listings. The mechanism for
- doing so is not spelled out here.
-
-3.2.3. FTP Typecode is Optional
-
- The entire ;type=<typecode> part of a FTP URL is optional. If it is
- omitted, the client program interpreting the URL must guess the
- appropriate mode to use. In general, the data content type of a file
- can only be guessed from the name, e.g., from the suffix of the name;
- the appropriate type code to be used for transfer of the file can
- then be deduced from the data content of the file.
-
-3.2.4 Hierarchy
-
- For some file systems, the "/" used to denote the hierarchical
- structure of the URL corresponds to the delimiter used to construct a
- file name hierarchy, and thus, the filename will look similar to the
- URL path. This does NOT mean that the URL is a Unix filename.
-
-3.2.5. Optimization
-
- Clients accessing resources via FTP may employ additional heuristics
- to optimize the interaction. For some FTP servers, for example, it
- may be reasonable to keep the control connection open while accessing
- multiple URLs from the same server. However, there is no common
- hierarchical model to the FTP protocol, so if a directory change
- command has been given, it is impossible in general to deduce what
- sequence should be given to navigate to another directory for a
- second retrieval, if the paths are different. The only reliable
- algorithm is to disconnect and reestablish the control connection.
-
-
-
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 8]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
-3.3. HTTP
-
- The HTTP URL scheme is used to designate Internet resources
- accessible using HTTP (HyperText Transfer Protocol).
-
- The HTTP protocol is specified elsewhere. This specification only
- describes the syntax of HTTP URLs.
-
- An HTTP URL takes the form:
-
- http://<host>:<port>/<path>?<searchpart>
-
- where <host> and <port> are as described in Section 3.1. If :<port>
- is omitted, the port defaults to 80. No user name or password is
- allowed. <path> is an HTTP selector, and <searchpart> is a query
- string. The <path> is optional, as is the <searchpart> and its
- preceding "?". If neither <path> nor <searchpart> is present, the "/"
- may also be omitted.
-
- Within the <path> and <searchpart> components, "/", ";", "?" are
- reserved. The "/" character may be used within HTTP to designate a
- hierarchical structure.
-
-3.4. GOPHER
-
- The Gopher URL scheme is used to designate Internet resources
- accessible using the Gopher protocol.
-
- The base Gopher protocol is described in RFC 1436 and supports items
- and collections of items (directories). The Gopher+ protocol is a set
- of upward compatible extensions to the base Gopher protocol and is
- described in [2]. Gopher+ supports associating arbitrary sets of
- attributes and alternate data representations with Gopher items.
- Gopher URLs accommodate both Gopher and Gopher+ items and item
- attributes.
-
-3.4.1. Gopher URL syntax
-
- A Gopher URL takes the form:
-
- gopher://<host>:<port>/<gopher-path>
-
- where <gopher-path> is one of
-
- <gophertype><selector>
- <gophertype><selector>%09<search>
- <gophertype><selector>%09<search>%09<gopher+_string>
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 9]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
- If :<port> is omitted, the port defaults to 70. <gophertype> is a
- single-character field to denote the Gopher type of the resource to
- which the URL refers. The entire <gopher-path> may also be empty, in
- which case the delimiting "/" is also optional and the <gophertype>
- defaults to "1".
-
- <selector> is the Gopher selector string. In the Gopher protocol,
- Gopher selector strings are a sequence of octets which may contain
- any octets except 09 hexadecimal (US-ASCII HT or tab) 0A hexadecimal
- (US-ASCII character LF), and 0D (US-ASCII character CR).
-
- Gopher clients specify which item to retrieve by sending the Gopher
- selector string to a Gopher server.
-
- Within the <gopher-path>, no characters are reserved.
-
- Note that some Gopher <selector> strings begin with a copy of the
- <gophertype> character, in which case that character will occur twice
- consecutively. The Gopher selector string may be an empty string;
- this is how Gopher clients refer to the top-level directory on a
- Gopher server.
-
-3.4.2 Specifying URLs for Gopher Search Engines
-
- If the URL refers to a search to be submitted to a Gopher search
- engine, the selector is followed by an encoded tab (%09) and the
- search string. To submit a search to a Gopher search engine, the
- Gopher client sends the <selector> string (after decoding), a tab,
- and the search string to the Gopher server.
-
-3.4.3 URL syntax for Gopher+ items
-
- URLs for Gopher+ items have a second encoded tab (%09) and a Gopher+
- string. Note that in this case, the %09<search> string must be
- supplied, although the <search> element may be the empty string.
-
- The <gopher+_string> is used to represent information required for
- retrieval of the Gopher+ item. Gopher+ items may have alternate
- views, arbitrary sets of attributes, and may have electronic forms
- associated with them.
-
- To retrieve the data associated with a Gopher+ URL, a client will
- connect to the server and send the Gopher selector, followed by a tab
- and the search string (which may be empty), followed by a tab and the
- Gopher+ commands.
-
-
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 10]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
-3.4.4 Default Gopher+ data representation
-
- When a Gopher server returns a directory listing to a client, the
- Gopher+ items are tagged with either a "+" (denoting Gopher+ items)
- or a "?" (denoting Gopher+ items which have a +ASK form associated
- with them). A Gopher URL with a Gopher+ string consisting of only a
- "+" refers to the default view (data representation) of the item
- while a Gopher+ string containing only a "?" refer to an item with a
- Gopher electronic form associated with it.
-
-3.4.5 Gopher+ items with electronic forms
-
- Gopher+ items which have a +ASK associated with them (i.e. Gopher+
- items tagged with a "?") require the client to fetch the item's +ASK
- attribute to get the form definition, and then ask the user to fill
- out the form and return the user's responses along with the selector
- string to retrieve the item. Gopher+ clients know how to do this but
- depend on the "?" tag in the Gopher+ item description to know when to
- handle this case. The "?" is used in the Gopher+ string to be
- consistent with Gopher+ protocol's use of this symbol.
-
-3.4.6 Gopher+ item attribute collections
-
- To refer to the Gopher+ attributes of an item, the Gopher URL's
- Gopher+ string consists of "!" or "$". "!" refers to the all of a
- Gopher+ item's attributes. "$" refers to all the item attributes for
- all items in a Gopher directory.
-
-3.4.7 Referring to specific Gopher+ attributes
-
- To refer to specific attributes, the URL's gopher+_string is
- "!<attribute_name>" or "$<attribute_name>". For example, to refer to
- the attribute containing the abstract of an item, the gopher+_string
- would be "!+ABSTRACT".
-
- To refer to several attributes, the gopher+_string consists of the
- attribute names separated by coded spaces. For example,
- "!+ABSTRACT%20+SMELL" refers to the +ABSTRACT and +SMELL attributes
- of an item.
-
-3.4.8 URL syntax for Gopher+ alternate views
-
- Gopher+ allows for optional alternate data representations (alternate
- views) of items. To retrieve a Gopher+ alternate view, a Gopher+
- client sends the appropriate view and language identifier (found in
- the item's +VIEW attribute). To refer to a specific Gopher+ alternate
- view, the URL's Gopher+ string would be in the form:
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 11]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
- +<view_name>%20<language_name>
-
- For example, a Gopher+ string of "+application/postscript%20Es_ES"
- refers to the Spanish language postscript alternate view of a Gopher+
- item.
-
-3.4.9 URL syntax for Gopher+ electronic forms
-
- The gopher+_string for a URL that refers to an item referenced by a
- Gopher+ electronic form (an ASK block) filled out with specific
- values is a coded version of what the client sends to the server.
- The gopher+_string is of the form:
-
-+%091%0D%0A+-1%0D%0A<ask_item1_value>%0D%0A<ask_item2_value>%0D%0A.%0D%0A
-
- To retrieve this item, the Gopher client sends:
-
- <a_gopher_selector><tab>+<tab>1<cr><lf>
- +-1<cr><lf>
- <ask_item1_value><cr><lf>
- <ask_item2_value><cr><lf>
- .<cr><lf>
-
- to the Gopher server.
-
-3.5. MAILTO
-
- The mailto URL scheme is used to designate the Internet mailing
- address of an individual or service. No additional information other
- than an Internet mailing address is present or implied.
-
- A mailto URL takes the form:
-
- mailto:<rfc822-addr-spec>
-
- where <rfc822-addr-spec> is (the encoding of an) addr-spec, as
- specified in RFC 822 [6]. Within mailto URLs, there are no reserved
- characters.
-
- Note that the percent sign ("%") is commonly used within RFC 822
- addresses and must be encoded.
-
- Unlike many URLs, the mailto scheme does not represent a data object
- to be accessed directly; there is no sense in which it designates an
- object. It has a different use than the message/external-body type in
- MIME.
-
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 12]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
-3.6. NEWS
-
- The news URL scheme is used to refer to either news groups or
- individual articles of USENET news, as specified in RFC 1036.
-
- A news URL takes one of two forms:
-
- news:<newsgroup-name>
- news:<message-id>
-
- A <newsgroup-name> is a period-delimited hierarchical name, such as
- "comp.infosystems.www.misc". A <message-id> corresponds to the
- Message-ID of section 2.1.5 of RFC 1036, without the enclosing "<"
- and ">"; it takes the form <unique>@<full_domain_name>. A message
- identifier may be distinguished from a news group name by the
- presence of the commercial at "@" character. No additional characters
- are reserved within the components of a news URL.
-
- If <newsgroup-name> is "*" (as in <URL:news:*>), it is used to refer
- to "all available news groups".
-
- The news URLs are unusual in that by themselves, they do not contain
- sufficient information to locate a single resource, but, rather, are
- location-independent.
-
-3.7. NNTP
-
- The nntp URL scheme is an alternative method of referencing news
- articles, useful for specifying news articles from NNTP servers (RFC
- 977).
-
- A nntp URL take the form:
-
- nntp://<host>:<port>/<newsgroup-name>/<article-number>
-
- where <host> and <port> are as described in Section 3.1. If :<port>
- is omitted, the port defaults to 119.
-
- The <newsgroup-name> is the name of the group, while the <article-
- number> is the numeric id of the article within that newsgroup.
-
- Note that while nntp: URLs specify a unique location for the article
- resource, most NNTP servers currently on the Internet today are
- configured only to allow access from local clients, and thus nntp
- URLs do not designate globally accessible resources. Thus, the news:
- form of URL is preferred as a way of identifying news articles.
-
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 13]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
-3.8. TELNET
-
- The Telnet URL scheme is used to designate interactive services that
- may be accessed by the Telnet protocol.
-
- A telnet URL takes the form:
-
- telnet://<user>:<password>@<host>:<port>/
-
- as specified in Section 3.1. The final "/" character may be omitted.
- If :<port> is omitted, the port defaults to 23. The :<password> can
- be omitted, as well as the whole <user>:<password> part.
-
- This URL does not designate a data object, but rather an interactive
- service. Remote interactive services vary widely in the means by
- which they allow remote logins; in practice, the <user> and
- <password> supplied are advisory only: clients accessing a telnet URL
- merely advise the user of the suggested username and password.
-
-3.9. WAIS
-
- The WAIS URL scheme is used to designate WAIS databases, searches, or
- individual documents available from a WAIS database. WAIS is
- described in [7]. The WAIS protocol is described in RFC 1625 [17];
- Although the WAIS protocol is based on Z39.50-1988, the WAIS URL
- scheme is not intended for use with arbitrary Z39.50 services.
-
- A WAIS URL takes one of the following forms:
-
- wais://<host>:<port>/<database>
- wais://<host>:<port>/<database>?<search>
- wais://<host>:<port>/<database>/<wtype>/<wpath>
-
- where <host> and <port> are as described in Section 3.1. If :<port>
- is omitted, the port defaults to 210. The first form designates a
- WAIS database that is available for searching. The second form
- designates a particular search. <database> is the name of the WAIS
- database being queried.
-
- The third form designates a particular document within a WAIS
- database to be retrieved. In this form <wtype> is the WAIS
- designation of the type of the object. Many WAIS implementations
- require that a client know the "type" of an object prior to
- retrieval, the type being returned along with the internal object
- identifier in the search response. The <wtype> is included in the
- URL in order to allow the client interpreting the URL adequate
- information to actually retrieve the document.
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 14]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
- The <wpath> of a WAIS URL consists of the WAIS document-id, encoded
- as necessary using the method described in Section 2.2. The WAIS
- document-id should be treated opaquely; it may only be decomposed by
- the server that issued it.
-
-3.10 FILES
-
- The file URL scheme is used to designate files accessible on a
- particular host computer. This scheme, unlike most other URL schemes,
- does not designate a resource that is universally accessible over the
- Internet.
-
- A file URL takes the form:
-
- file://<host>/<path>
-
- where <host> is the fully qualified domain name of the system on
- which the <path> is accessible, and <path> is a hierarchical
- directory path of the form <directory>/<directory>/.../<name>.
-
- For example, a VMS file
-
- DISK$USER:[MY.NOTES]NOTE123456.TXT
-
- might become
-
- <URL:file://vms.host.edu/disk$user/my/notes/note12345.txt>
-
- As a special case, <host> can be the string "localhost" or the empty
- string; this is interpreted as `the machine from which the URL is
- being interpreted'.
-
- The file URL scheme is unusual in that it does not specify an
- Internet protocol or access method for such files; as such, its
- utility in network protocols between hosts is limited.
-
-3.11 PROSPERO
-
- The Prospero URL scheme is used to designate resources that are
- accessed via the Prospero Directory Service. The Prospero protocol is
- described elsewhere [14].
-
- A prospero URLs takes the form:
-
- prospero://<host>:<port>/<hsoname>;<field>=<value>
-
- where <host> and <port> are as described in Section 3.1. If :<port>
- is omitted, the port defaults to 1525. No username or password is
-
-
-
-Berners-Lee, Masinter & McCahill [Page 15]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
- allowed.
-
- The <hsoname> is the host-specific object name in the Prospero
- protocol, suitably encoded. This name is opaque and interpreted by
- the Prospero server. The semicolon ";" is reserved and may not
- appear without quoting in the <hsoname>.
-
- Prospero URLs are interpreted by contacting a Prospero directory
- server on the specified host and port to determine appropriate access
- methods for a resource, which might themselves be represented as
- different URLs. External Prospero links are represented as URLs of
- the underlying access method and are not represented as Prospero
- URLs.
-
- Note that a slash "/" may appear in the <hsoname> without quoting and
- no significance may be assumed by the application. Though slashes
- may indicate hierarchical structure on the server, such structure is
- not guaranteed. Note that many <hsoname>s begin with a slash, in
- which case the host or port will be followed by a double slash: the
- slash from the URL syntax, followed by the initial slash from the
- <hsoname>. (E.g., <URL:prospero://host.dom//pros/name> designates a
- <hsoname> of "/pros/name".)
-
- In addition, after the <hsoname>, optional fields and values
- associated with a Prospero link may be specified as part of the URL.
- When present, each field/value pair is separated from each other and
- from the rest of the URL by a ";" (semicolon). The name of the field
- and its value are separated by a "=" (equal sign). If present, these
- fields serve to identify the target of the URL. For example, the
- OBJECT-VERSION field can be specified to identify a specific version
- of an object.
-
-4. REGISTRATION OF NEW SCHEMES
-
- A new scheme may be introduced by defining a mapping onto a
- conforming URL syntax, using a new prefix. URLs for experimental
- schemes may be used by mutual agreement between parties. Scheme names
- starting with the characters "x-" are reserved for experimental
- purposes.
-
- The Internet Assigned Numbers Authority (IANA) will maintain a
- registry of URL schemes. Any submission of a new URL scheme must
- include a definition of an algorithm for accessing of resources
- within that scheme and the syntax for representing such a scheme.
-
- URL schemes must have demonstrable utility and operability. One way
- to provide such a demonstration is via a gateway which provides
- objects in the new scheme for clients using an existing protocol. If
-
-
-
-Berners-Lee, Masinter & McCahill [Page 16]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
- the new scheme does not locate resources that are data objects, the
- properties of names in the new space must be clearly defined.
-
- New schemes should try to follow the same syntactic conventions of
- existing schemes, where appropriate. It is likewise recommended
- that, where a protocol allows for retrieval by URL, that the client
- software have provision for being configured to use specific gateway
- locators for indirect access through new naming schemes.
-
- The following scheme have been proposed at various times, but this
- document does not define their syntax or use at this time. It is
- suggested that IANA reserve their scheme names for future definition:
-
- afs Andrew File System global file names.
- mid Message identifiers for electronic mail.
- cid Content identifiers for MIME body parts.
- nfs Network File System (NFS) file names.
- tn3270 Interactive 3270 emulation sessions.
- mailserver Access to data available from mail servers.
- z39.50 Access to ANSI Z39.50 services.
-
-5. BNF for specific URL schemes
-
- This is a BNF-like description of the Uniform Resource Locator
- syntax, using the conventions of RFC822, except that "|" is used to
- designate alternatives, and brackets [] are used around optional or
- repeated elements. Briefly, literals are quoted with "", optional
- elements are enclosed in [brackets], and elements may be preceded
- with <n>* to designate n or more repetitions of the following
- element; n defaults to 0.
-
-; The generic form of a URL is:
-
-genericurl = scheme ":" schemepart
-
-; Specific predefined schemes are defined here; new schemes
-; may be registered with IANA
-
-url = httpurl | ftpurl | newsurl |
- nntpurl | telneturl | gopherurl |
- waisurl | mailtourl | fileurl |
- prosperourl | otherurl
-
-; new schemes follow the general syntax
-otherurl = genericurl
-
-; the scheme is in lower case; interpreters should use case-ignore
-scheme = 1*[ lowalpha | digit | "+" | "-" | "." ]
-
-
-
-Berners-Lee, Masinter & McCahill [Page 17]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
-schemepart = *xchar | ip-schemepart
-
-
-; URL schemeparts for ip based protocols:
-
-ip-schemepart = "//" login [ "/" urlpath ]
-
-login = [ user [ ":" password ] "@" ] hostport
-hostport = host [ ":" port ]
-host = hostname | hostnumber
-hostname = *[ domainlabel "." ] toplabel
-domainlabel = alphadigit | alphadigit *[ alphadigit | "-" ] alphadigit
-toplabel = alpha | alpha *[ alphadigit | "-" ] alphadigit
-alphadigit = alpha | digit
-hostnumber = digits "." digits "." digits "." digits
-port = digits
-user = *[ uchar | ";" | "?" | "&" | "=" ]
-password = *[ uchar | ";" | "?" | "&" | "=" ]
-urlpath = *xchar ; depends on protocol see section 3.1
-
-; The predefined schemes:
-
-; FTP (see also RFC959)
-
-ftpurl = "ftp://" login [ "/" fpath [ ";type=" ftptype ]]
-fpath = fsegment *[ "/" fsegment ]
-fsegment = *[ uchar | "?" | ":" | "@" | "&" | "=" ]
-ftptype = "A" | "I" | "D" | "a" | "i" | "d"
-
-; FILE
-
-fileurl = "file://" [ host | "localhost" ] "/" fpath
-
-; HTTP
-
-httpurl = "http://" hostport [ "/" hpath [ "?" search ]]
-hpath = hsegment *[ "/" hsegment ]
-hsegment = *[ uchar | ";" | ":" | "@" | "&" | "=" ]
-search = *[ uchar | ";" | ":" | "@" | "&" | "=" ]
-
-; GOPHER (see also RFC1436)
-
-gopherurl = "gopher://" hostport [ / [ gtype [ selector
- [ "%09" search [ "%09" gopher+_string ] ] ] ] ]
-gtype = xchar
-selector = *xchar
-gopher+_string = *xchar
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 18]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
-; MAILTO (see also RFC822)
-
-mailtourl = "mailto:" encoded822addr
-encoded822addr = 1*xchar ; further defined in RFC822
-
-; NEWS (see also RFC1036)
-
-newsurl = "news:" grouppart
-grouppart = "*" | group | article
-group = alpha *[ alpha | digit | "-" | "." | "+" | "_" ]
-article = 1*[ uchar | ";" | "/" | "?" | ":" | "&" | "=" ] "@" host
-
-; NNTP (see also RFC977)
-
-nntpurl = "nntp://" hostport "/" group [ "/" digits ]
-
-; TELNET
-
-telneturl = "telnet://" login [ "/" ]
-
-; WAIS (see also RFC1625)
-
-waisurl = waisdatabase | waisindex | waisdoc
-waisdatabase = "wais://" hostport "/" database
-waisindex = "wais://" hostport "/" database "?" search
-waisdoc = "wais://" hostport "/" database "/" wtype "/" wpath
-database = *uchar
-wtype = *uchar
-wpath = *uchar
-
-; PROSPERO
-
-prosperourl = "prospero://" hostport "/" ppath *[ fieldspec ]
-ppath = psegment *[ "/" psegment ]
-psegment = *[ uchar | "?" | ":" | "@" | "&" | "=" ]
-fieldspec = ";" fieldname "=" fieldvalue
-fieldname = *[ uchar | "?" | ":" | "@" | "&" ]
-fieldvalue = *[ uchar | "?" | ":" | "@" | "&" ]
-
-; Miscellaneous definitions
-
-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"
-
-
-
-Berners-Lee, Masinter & McCahill [Page 19]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
-alpha = lowalpha | hialpha
-digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" |
- "8" | "9"
-safe = "$" | "-" | "_" | "." | "+"
-extra = "!" | "*" | "'" | "(" | ")" | ","
-national = "{" | "}" | "|" | "\" | "^" | "~" | "[" | "]" | "`"
-punctuation = "<" | ">" | "#" | "%" | <">
-
-
-reserved = ";" | "/" | "?" | ":" | "@" | "&" | "="
-hex = digit | "A" | "B" | "C" | "D" | "E" | "F" |
- "a" | "b" | "c" | "d" | "e" | "f"
-escape = "%" hex hex
-
-unreserved = alpha | digit | safe | extra
-uchar = unreserved | escape
-xchar = unreserved | reserved | escape
-digits = 1*digit
-
-6. Security Considerations
-
- The URL scheme does not in itself pose a security threat. Users
- should beware that there is no general guarantee that a URL which at
- one time points to a given object continues to do so, and does not
- even at some later time point to a different object due to the
- movement of objects on servers.
-
- A URL-related security threat is that it is sometimes possible to
- construct a URL such that an attempt to perform a harmless idempotent
- operation such as the retrieval of the object will in fact cause a
- possibly damaging remote operation to occur. The unsafe URL is
- typically constructed by specifying a port number other than that
- reserved for the network protocol in question. The client
- unwittingly contacts a server which is in fact running a different
- protocol. The content of the URL contains instructions which when
- interpreted according to this other protocol cause an unexpected
- operation. An example has been the use of gopher URLs to cause a rude
- message to be sent via a SMTP server. Caution should be used when
- using any URL which specifies a port number other than the default
- for the protocol, especially when it is a number within the reserved
- space.
-
- Care should be taken when URLs contain embedded encoded delimiters
- for a given protocol (for example, CR and LF characters for telnet
- protocols) that these are not unencoded before transmission. This
- would violate the protocol but could be used to simulate an extra
- operation or parameter, again causing an unexpected and possible
- harmful remote operation to be performed.
-
-
-
-Berners-Lee, Masinter & McCahill [Page 20]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
- The use of URLs containing passwords that should be secret is clearly
- unwise.
-
-7. Acknowledgements
-
- This paper builds on the basic WWW design (RFC 1630) and much
- discussion of these issues by many people on the network. The
- discussion was particularly stimulated by articles by Clifford Lynch,
- Brewster Kahle [10] and Wengyik Yeong [18]. Contributions from John
- Curran, Clifford Neuman, Ed Vielmetti and later the IETF URL BOF and
- URI working group were incorporated.
-
- Most recently, careful readings and comments by Dan Connolly, Ned
- Freed, Roy Fielding, Guido van Rossum, Michael Dolan, Bert Bos, John
- Kunze, Olle Jarnefors, Peter Svanberg and many others have helped
- refine this RFC.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 21]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
-APPENDIX: Recommendations for URLs in Context
-
- URIs, including URLs, are intended to be transmitted through
- protocols which provide a context for their interpretation.
-
- In some cases, it will be necessary to distinguish URLs from other
- possible data structures in a syntactic structure. In this case, is
- recommended that URLs be preceeded with a prefix consisting of the
- characters "URL:". For example, this prefix may be used to
- distinguish URLs from other kinds of URIs.
-
- In addition, there are many occasions when URLs are included in other
- kinds of text; examples include electronic mail, USENET news
- messages, or printed on paper. In such cases, it is convenient to
- have a separate syntactic wrapper that delimits the URL and separates
- it from the rest of the text, and in particular from punctuation
- marks that might be mistaken for part of the URL. For this purpose,
- is recommended that angle brackets ("<" and ">"), along with the
- prefix "URL:", be used to delimit the boundaries of the URL. This
- wrapper does not form part of the URL and should not be used in
- contexts in which delimiters are already specified.
-
- In the case where a fragment/anchor identifier is associated with a
- URL (following a "#"), the identifier would be placed within the
- brackets as well.
-
- In some cases, extra whitespace (spaces, linebreaks, tabs, etc.) may
- need to be added to break long URLs across lines. The whitespace
- should be ignored when extracting the URL.
-
- 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 a line, the interpreter of a
- URL containing a line break immediately after a hyphen should ignore
- all unencoded whitespace around the line break, and should be aware
- that the hyphen may or may not actually be part of the URL.
-
- Examples:
-
- Yes, Jim, I found it under <URL:ftp://info.cern.ch/pub/www/doc;
- type=d> but you can probably pick it up from <URL:ftp://ds.in
- ternic.net/rfc>. Note the warning in <URL:http://ds.internic.
- net/instructions/overview.html#WARNING>.
-
-
-
-
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 22]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
-References
-
- [1] 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, University of Minnesota, March 1993.
- <URL:ftp://ds.internic.net/rfc/rfc1436.txt;type=a>
-
- [2] Anklesaria, F., Lindner, P., McCahill, M., Torrey, D.,
- Johnson, D., and B. Alberti, "Gopher+: Upward compatible
- enhancements to the Internet Gopher protocol",
- University of Minnesota, July 1993.
- <URL:ftp://boombox.micro.umn.edu/pub/gopher/gopher_protocol
- /Gopher+/Gopher+.txt>
-
- [3] 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, CERN, June 1994.
- <URL:ftp://ds.internic.net/rfc/rfc1630.txt>
-
- [4] Berners-Lee, T., "Hypertext Transfer Protocol (HTTP)",
- CERN, November 1993.
- <URL:ftp://info.cern.ch/pub/www/doc/http-spec.txt.Z>
-
- [5] Braden, R., Editor, "Requirements for Internet Hosts --
- Application and Support", STD 3, RFC 1123, IETF, October 1989.
- <URL:ftp://ds.internic.net/rfc/rfc1123.txt>
-
- [6] Crocker, D. "Standard for the Format of ARPA Internet Text
- Messages", STD 11, RFC 822, UDEL, April 1982.
- <URL:ftp://ds.internic.net/rfc/rfc822.txt>
-
- [7] 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.
- <URL:ftp://quake.think.com/pub/wais/doc/protspec.txt>
-
- [8] Horton, M. and R. Adams, "Standard For Interchange of USENET
- Messages", RFC 1036, AT&T Bell Laboratories, Center for Seismic
- Studies, December 1987.
- <URL:ftp://ds.internic.net/rfc/rfc1036.txt>
-
- [9] Huitema, C., "Naming: Strategies and Techniques", Computer
- Networks and ISDN Systems 23 (1991) 107-110.
-
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 23]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
- [10] Kahle, B., "Document Identifiers, or International Standard
- Book Numbers for the Electronic Age", 1991.
- <URL:ftp://quake.think.com/pub/wais/doc/doc-ids.txt>
-
- [11] Kantor, B. and P. Lapsley, "Network News Transfer Protocol:
- A Proposed Standard for the Stream-Based Transmission of News",
- RFC 977, UC San Diego & UC Berkeley, February 1986.
- <URL:ftp://ds.internic.net/rfc/rfc977.txt>
-
- [12] Kunze, J., "Functional Requirements for Internet Resource
- Locators", Work in Progress, December 1994.
- <URL:ftp://ds.internic.net/internet-drafts
- /draft-ietf-uri-irl-fun-req-02.txt>
-
- [13] Mockapetris, P., "Domain Names - Concepts and Facilities",
- STD 13, RFC 1034, USC/Information Sciences Institute,
- November 1987.
- <URL:ftp://ds.internic.net/rfc/rfc1034.txt>
-
- [14] Neuman, B., and S. Augart, "The Prospero Protocol",
- USC/Information Sciences Institute, June 1993.
- <URL:ftp://prospero.isi.edu/pub/prospero/doc
- /prospero-protocol.PS.Z>
-
- [15] Postel, J. and J. Reynolds, "File Transfer Protocol (FTP)",
- STD 9, RFC 959, USC/Information Sciences Institute,
- October 1985.
- <URL:ftp://ds.internic.net/rfc/rfc959.txt>
-
- [16] Sollins, K. and L. Masinter, "Functional Requirements for
- Uniform Resource Names", RFC 1737, MIT/LCS, Xerox Corporation,
- December 1994.
- <URL:ftp://ds.internic.net/rfc/rfc1737.txt>
-
- [17] St. Pierre, M, Fullton, J., Gamiel, K., Goldman, J., Kahle, B.,
- Kunze, J., Morris, H., and F. Schiettecatte, "WAIS over
- Z39.50-1988", RFC 1625, WAIS, Inc., CNIDR, Thinking Machines
- Corp., UC Berkeley, FS Consulting, June 1994.
- <URL:ftp://ds.internic.net/rfc/rfc1625.txt>
-
- [18] Yeong, W. "Towards Networked Information Retrieval", Technical
- report 91-06-25-01, Performance Systems International, Inc.
- <URL:ftp://uu.psi.com/wp/nir.txt>, June 1991.
-
- [19] Yeong, W., "Representing Public Archives in the Directory",
- Work in Progress, November 1991.
-
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 24]
-\f
-RFC 1738 Uniform Resource Locators (URL) December 1994
-
-
- [20] "Coded Character Set -- 7-bit American Standard Code for
- Information Interchange", ANSI X3.4-1986.
-
-Editors' Addresses
-
-Tim Berners-Lee
-World-Wide Web project
-CERN,
-1211 Geneva 23,
-Switzerland
-
-Phone: +41 (22)767 3755
-Fax: +41 (22)767 7155
-EMail: timbl@info.cern.ch
-
-
-Larry Masinter
-Xerox PARC
-3333 Coyote Hill Road
-Palo Alto, CA 94034
-
-Phone: (415) 812-4365
-Fax: (415) 812-4333
-EMail: masinter@parc.xerox.com
-
-
-Mark McCahill
-Computer and Information Services,
-University of Minnesota
-Room 152 Shepherd Labs
-100 Union Street SE
-Minneapolis, MN 55455
-
-Phone: (612) 625 1300
-EMail: mpm@boombox.micro.umn.edu
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, Masinter & McCahill [Page 25]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group SNMPv2 Working Group
-Request for Comments: 1902 J. Case
-Obsoletes: 1442 SNMP Research, Inc.
-Category: Standards Track K. McCloghrie
- Cisco Systems, Inc.
- M. Rose
- Dover Beach Consulting, Inc.
- S. Waldbusser
- International Network Services
- January 1996
-
-
- Structure of Management Information
- for Version 2 of the
- Simple Network Management Protocol (SNMPv2)
-
-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.
-
-1. Introduction
-
- A management system contains: several (potentially many) nodes, each
- with a processing entity, termed an agent, which has access to
- management instrumentation; at least one management station; and, a
- management protocol, used to convey management information between
- the agents and management stations. Operations of the protocol are
- carried out under an administrative framework which defines
- authentication, authorization, access control, and privacy policies.
-
- Management stations execute management applications which monitor and
- control managed elements. Managed elements are devices such as
- hosts, routers, terminal servers, etc., which are monitored and
- controlled via access to their management information.
-
- 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) [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.
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 1]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- 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.
-
-1.1. A Note on Terminology
-
- For the purpose of exposition, the original Internet-standard Network
- Management Framework, as described in RFCs 1155 (STD 16), 1157 (STD
- 15), and 1212 (STD 16), is termed the SNMP version 1 framework
- (SNMPv1). The current framework is termed the SNMP version 2
- framework (SNMPv2).
-
-2. Definitions
-
-SNMPv2-SMI DEFINITIONS ::= BEGIN
-
-
--- the path to the root
-
-org OBJECT IDENTIFIER ::= { iso 3 }
-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 Working Group Standards Track [Page 2]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
-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 }
-
-
--- definitions for information modules
-
-MODULE-IDENTITY MACRO ::=
-BEGIN
- TYPE NOTATION ::=
- "LAST-UPDATED" value(Update UTCTime)
- "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 UTCTime)
- "DESCRIPTION" Text
-
- -- uses the NVT ASCII character set
- Text ::= """" string """"
-END
-
-
-OBJECT-IDENTITY MACRO ::=
-BEGIN
- TYPE NOTATION ::=
- "STATUS" Status
- "DESCRIPTION" Text
- ReferPart
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 3]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- VALUE NOTATION ::=
- value(VALUE OBJECT IDENTIFIER)
-
- Status ::=
- "current"
- | "deprecated"
- | "obsolete"
-
- ReferPart ::=
- "REFERENCE" Text
- | empty
-
- Text ::= """" string """"
-END
-
-
--- names of objects
-
-ObjectName ::=
- OBJECT IDENTIFIER
-
-NotificationName ::=
- OBJECT IDENTIFIER
-
--- syntax of objects
-
-ObjectSyntax ::=
- CHOICE {
- simple
- SimpleSyntax,
-
- -- note that SEQUENCEs for conceptual tables and
- -- rows are not mentioned here...
-
- application-wide
- ApplicationSyntax
- }
-
-
--- built-in ASN.1 types
-
-SimpleSyntax ::=
- CHOICE {
- -- INTEGERs with a more restrictive range
- -- may also be used
- integer-value -- includes Integer32
- INTEGER (-2147483648..2147483647),
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 4]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- -- 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 ::=
- [UNIVERSAL 2]
- IMPLICIT 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
--- (this is a tagged type for historical reasons)
-IpAddress ::=
- [APPLICATION 0]
- IMPLICIT OCTET STRING (SIZE (4))
-
--- this wraps
-Counter32 ::=
-
-
-
-SNMPv2 Working Group Standards Track [Page 5]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- [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
- IndexPart
- DefValPart
-
- VALUE NOTATION ::=
- value(VALUE ObjectName)
-
- Syntax ::=
-
-
-
-SNMPv2 Working Group Standards Track [Page 6]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- type(ObjectSyntax)
- | "BITS" "{" Kibbles "}"
- Kibbles ::=
- Kibble
- | Kibbles "," Kibble
- Kibble ::=
- identifier "(" nonNegativeNumber ")"
-
- 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
- Index ::=
- -- use the SYNTAX value of the
- -- correspondent OBJECT-TYPE invocation
- value(Indexobject ObjectName)
- Entry ::=
- -- use the INDEX value of the
- -- correspondent OBJECT-TYPE invocation
- value(Entryobject ObjectName)
-
- DefValPart ::=
-
-
-
-SNMPv2 Working Group Standards Track [Page 7]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- "DEFVAL" "{" value(Defval Syntax) "}"
- | empty
-
- -- uses the NVT ASCII character set
- Text ::= """" string """"
-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
- | Objects "," Object
- Object ::=
- value(Name ObjectName)
-
- Status ::=
- "current"
- | "deprecated"
- | "obsolete"
-
- ReferPart ::=
- "REFERENCE" Text
- | empty
-
- -- uses the NVT ASCII character set
- Text ::= """" string """"
-END
-
--- definitions of administrative identifiers
-
-zeroDotZero OBJECT-IDENTITY
- STATUS current
- DESCRIPTION
-
-
-
-SNMPv2 Working Group Standards Track [Page 8]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- "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 a subset of ASN.1 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].
-
- 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 SNMPv2 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
- SNMPv2, and instances of ASN.1 macros defined in this document and in
- other documents [2, 3] of the SNMPv2 framework. Additional ASN.1
- macros may not be defined in SNMPv2 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
-
-
-
-SNMPv2 Working Group Standards Track [Page 9]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- 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.
-
- 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].)
-
- 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, even though hyphen is allowed by [1]. This
- restriction enables arithmetic expressions in languages which use the
- minus sign to reference these descriptors without ambiguity.)
-
- 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 Clauses
-
- Some clauses in a macro invocation may take a textual value (e.g.,
- the DESCRIPTION clause). Note that, in order to conform to the ASN.1
- syntax, the entire value of these clauses must be enclosed in double
- quotation marks, and therefore cannot itself contain double quotation
-
-
-
-SNMPv2 Working Group Standards Track [Page 10]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- marks, although the value may be multi-line.
-
-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 even when there is no collision
- when IMPORTing symbols.
-
- Finally, the IMPORTS statement may not be used to import an ASN.1
- named type which corresponds to either the SEQUENCE or SEQUENCE OF
- type.
-
-3.3. Exporting Symbols
-
- The ASN.1 EXPORTS statement is not allowed in SNMPv2 information
- modules. All items defined in an information module are
- automatically exported.
-
-3.4. ASN.1 Comments
-
- Comments in ASN.1 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.
-
-3.5. OBJECT IDENTIFIER values
-
- An OBJECT IDENTIFIER value is an ordered list of non-negative
- numbers. For the SNMPv2 framework, 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:
-
-
-
-SNMPv2 Working Group Standards Track [Page 11]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- Value Name
- 0 ccitt
- 1 iso
- 2 joint-iso-ccitt
-
-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:
-
- 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.
-
-
-
-SNMPv2 Working Group Standards Track [Page 12]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- Note that reference in an IMPORTS clause or in clauses of SNMPv2
- 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. The date and time
- are represented in UTC Time format (see Appendix B).
-
-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.
-
-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. The date and time are represented in UTC Time format
- (see Appendix B).
-
-5.5.1. Mapping of the DESCRIPTION sub-clause
-
- The DESCRIPTION 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
-
-
-
-SNMPv2 Working Group Standards Track [Page 13]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- specifying an OBJECT IDENTIFIER value to refer to the information
- module containing the invocation.
-
-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
- FROM SNMPv2-SMI;
-
-
-fizbin MODULE-IDENTITY
- LAST-UPDATED "9505241811Z"
- 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."
--- contact IANA for actual number
- ::= { experimental xx }
-
-
-END
-
-
-
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 14]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
-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.
-
- The values "current", and "obsolete" are self-explanatory. The
- "deprecated" value indicates that the definition is obsolete, but
- that an implementor may wish to support it to foster interoperability
- with older 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 an object assignment defined in some other
- information module.
-
-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 }
-
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 15]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
-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.
-
-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].
-
- A extended subset of the full capabilities of ASN.1 sub-typing is
- allowed, as appropriate to the underingly ASN.1 type. Any such
- restriction on size, range, enumerations or repertoire 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 C 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 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.
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 16]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- Finally, a label for a named-number enumeration must consist of one
- or more letters or digits (no hyphens), 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.)
-
-7.1.2. OCTET STRING
-
- The OCTET STRING type represents arbitrary binary or textual data.
- Although there is no SMI-specified size limitation for this type, MIB
- designers should realize that there may be implementation and
- interoperability limitations for sizes in excess of 255 octets.
-
-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 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.)
-
- Although there is no SMI-specified limitation on the number of
- enumerations (and therefore on the length of a value), 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 (no hyphens), 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.)
-
-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.
-
- 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].
-
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 17]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
-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 a SYNTAX clause value of TimeStamp (a
- textual convention defined in [3]) indicating the time of the last
- discontinuity.
-
- 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. The
- maximum value can not be greater than 2^32-1 (4294967295 decimal).
- The value of a Gauge has its maximum value whenever the information
- being modeled is greater or equal to that maximum value; if the
- information being modeled subsequently decreases below the maximum
- value, the Gauge also decreases.
-
-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.
-
-
-
-SNMPv2 Working Group Standards Track [Page 18]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
-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 a SYNTAX clause value of TimeStamp (a
- textual convention defined in [3]) indicating the time of the last
- discontinuity.
-
- 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.
-
-
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 19]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
-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,
- normally omitting the sub-typing information. Further, these ASN.1
- types are always present (the 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.
-
-
-
-SNMPv2 Working Group Standards Track [Page 20]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
-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".)
-
-7.4. Mapping of the STATUS clause
-
- The STATUS clause, which must be present, indicates whether this
- definition is current or historic.
-
- The values "current", and "obsolete" are self-explanatory. The
- "deprecated" value indicates that the definition is obsolete, but
- that an implementor may wish to support that object to foster
- interoperability with older 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.
-
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 21]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
-7.6. Mapping of the REFERENCE clause
-
- The REFERENCE clause, which need not be present, contains a textual
- cross-reference to an object defined in some other information
- module. This is useful when de-osifying a MIB module produced by
- some other organization.
-
-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 syntax of those
- objects indicate how to form the instance-identifier:
-
-(1) integer-valued: a single sub-identifier taking the integer value
- (this works only for non-negative integers);
-
-(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
-
-
-
-SNMPv2 Working Group Standards Track [Page 22]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- 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.
-
- 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:
-
-(1) within a MIB module originally written to conform to the SNMPv1
- framework, and later converted to conform to the SNMPv2 framework;
- 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
-
-
-
-SNMPv2 Working Group Standards Track [Page 23]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- 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 1573's ifTable
- and the many media-specific MIBs which extend it for specific media
- (e.g., the dot3Table in RFC 1650), 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 1573's ifTable and a
- media-specific MIB which extends the ifTable for a specific media
- (e.g., the dot3Table in RFC 1650), 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 a SNMPv2 entity
- acting in an agent role when an object instance is created.
-
-
-
-SNMPv2 Working Group Standards Track [Page 24]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- 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 a SNMPv2 entity
- acting in an agent role might use.
-
- 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 a SNMPv2 entity acting in an agent
- role 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 }
- OBJECT IDENTIFIER DEFVAL { sysDescr }
- BITS DEFVAL { { primary, secondary } }
- -- enumerated values that are set
- IpAddress DEFVAL { 'c0210415'H } -- 192.33.4.21
-
- 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
- "1" to the administratively assigned name for the conceptual table.
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 25]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
-(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.
-
- Further note that although conceptual tables and rows are given
- administratively assigned names, these conceptual objects may not be
- manipulated in aggregate form by the management protocol.
-
-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 INTEGER
- MAX-ACCESS read-only
- STATUS current
- DESCRIPTION
- "The index number of the first unassigned entry in the
- evaluation table.
-
- 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
-
-
-
-SNMPv2 Working Group Standards Track [Page 26]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- "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
- 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 executed."
- DEFVAL { 0 }
- ::= { evalEntry 3 }
-
-evalStatus OBJECT-TYPE
- SYNTAX RowStatus
-
-
-
-SNMPv2 Working Group Standards Track [Page 27]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- 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 the ordered
- sequence of MIB object types which are contained within every
- instance of the notification. An object type specified in this
- clause may not have an MAX-ACCESS clause of "not-accessible".
-
-8.2. Mapping of the STATUS clause
-
- The STATUS clause, which must be present, indicates whether this
- definition is current or historic.
-
- The values "current", and "obsolete" are self-explanatory. The
- "deprecated" value indicates that the definition is obsolete, but
- that an implementor may wish to support the notification to foster
- interoperability with older 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.
-
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 28]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
-8.4. Mapping of the REFERENCE clause
-
- The REFERENCE clause, which need not be present, contains a textual
- cross-reference to a notification defined in some other information
- module. This is useful when de-osifying a MIB module produced by
- some other organization.
-
-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 the procedures employed by proxy agents (see Section 3.1.2 of
- [7]), 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 linkUp trap might be described:
-
-linkUp NOTIFICATION-TYPE
- OBJECTS { ifIndex }
- STATUS current
- DESCRIPTION
- "A linkUp trap signifies that the SNMPv2 entity, acting in
- an agent role, recognizes that one of the communication
- links represented in its configuration has come up."
- ::= { snmpTraps 4 }
-
-According to this invocation, the trap authoritatively identified as
-
- { snmpTraps 4 }
-
-is used to report a link coming up.
-
-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.
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 29]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- Further, the following restrictions apply:
-
- Restrictions to Refinement on
- object syntax range enumeration size repertoire
- ----------------- ----- ----------- ---- ----------
- INTEGER (1) (2) - -
- Integer32 (1) - - -
- Unsigned32 (1) - - -
- OCTET STRING - - (3) (4)
- OBJECT IDENTIFIER - - - -
- BITS - (2) - -
- IpAddress - - - -
- Counter32 - - - -
- Counter64 - - - -
- Gauge32 (1) - - -
- TimeTicks - - - -
-
-where:
-
-(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);
-
-(3) the size in characters of the value may be refined by raising the
- lower-bounds, by reducing the upper-bounds, and/or by reducing the
- alternative size choices; or,
-
-(4) the repertoire of characters in the value may be reduced by further
- sub-typing.
-
- Otherwise no refinements are possible. Further details on sub-typing
- are provided in Appendix C.
-
-10. Extending an Information Module
-
- As experience is gained with a published information module, it may
- be desirable to revise that information module.
-
- To begin, the invocation of the MODULE-IDENTITY macro should be
- updated to include information about the revision. Usually, this
- consists of updating the LAST-UPDATED clause and adding a pair of
- REVISION and DESCRIPTION clauses. However, other existing clauses in
- the invocation may be updated.
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 30]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- Note that the module's label (e.g., "FIZBIN-MIB" from the example in
- Section 5.8), is not changed when the information module is revised.
-
-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.
-
-(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".
-
-(3) A DEFVAL clause may be added or updated.
-
-(4) A REFERENCE clause may be added or updated.
-
-(5) A UNITS clause may be added.
-
-(6) A conceptual row may be augmented by adding new columnar objects at
- the end of the row.
-
-(7) 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
- those specifically allowed above), then the OBJECT IDENTIFIER value
- associated with that object must also be changed.
-
- 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.
-
- Finally, note that if an object has the value of its STATUS clause
- changed, then the value of its DESCRIPTION clause should be updated
- accordingly.
-
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 31]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
-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.
-
- 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.
-
- Finally, note that if an object has the value of its STATUS clause
- changed, then the value of its DESCRIPTION clause should be updated
- accordingly.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 32]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
-11. Appendix A: de-OSIfying a MIB module
-
- There has been an increasing amount of work recently on taking MIBs
- defined by other organizations (e.g., the IEEE) and de-osifying them
- for use with the Internet-standard network management framework. The
- steps to achieve this are straight-forward, though tedious. Of
- course, it is helpful to already be experienced in writing MIB
- modules for use with the Internet-standard network management
- framework.
-
- The first step is to construct a skeletal MIB module, as shown
- earlier in Section 5.8. The next step is to categorize the objects
- into groups. Optional objects are not permitted. Thus, when a MIB
- module is created, optional objects must be placed in a additional
- groups, which, if implemented, all objects in the group must be
- implemented. For the first pass, it is wisest to simply ignore any
- optional objects in the original MIB: experience shows it is better
- to define a core MIB module first, containing only essential objects;
- later, if experience demands, other objects can be added.
-
-11.1. Managed Object Mapping
-
- Next for each managed object class, determine whether there can exist
- multiple instances of that managed object class. If not, then for
- each of its attributes, use the OBJECT-TYPE macro to make an
- equivalent definition.
-
- Otherwise, if multiple instances of the managed object class can
- exist, then define a conceptual table having conceptual rows each
- containing a columnar object for each of the managed object class's
- attributes. If the managed object class is contained within the
- containment tree of another managed object class, then the assignment
- of an object is normally required for each of the "distinguished
- attributes" of the containing managed object class. If they do not
- already exist within the MIB module, then they can be added via the
- definition of additional columnar objects in the conceptual row
- corresponding to the contained managed object class.
-
- In defining a conceptual row, it is useful to consider the
- optimization of network management operations which will act upon its
- columnar objects. In particular, it is wisest to avoid defining more
- columnar objects within a conceptual row, than can fit in a single
- PDU. As a rule of thumb, a conceptual row should contain no more
- than approximately 20 objects. Similarly, or as a way to abide by
- the "20 object guideline", columnar objects should be grouped into
- tables according to the expected grouping of network management
- operations upon them. As such, the content of conceptual rows should
- reflect typical access scenarios, e.g., they should be organized
-
-
-
-SNMPv2 Working Group Standards Track [Page 33]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- along functional lines such as one row for statistics and another row
- for parameters, or along usage lines such as commonly-needed objects
- versus rarely-needed objects.
-
- On the other hand, the definition of conceptual rows where the number
- of columnar objects used as indexes outnumbers the number used to
- hold information, should also be avoided. In particular, the
- splitting of a managed object class's attributes into many conceptual
- tables should not be used as a way to obtain the same degree of
- flexibility/complexity as is often found in MIBs with a myriad of
- optionals.
-
-11.1.1. Mapping to the SYNTAX clause
-
- When mapping to the SYNTAX clause of the OBJECT-TYPE macro:
-
-(1) An object with BOOLEAN syntax becomes a TruthValue [3].
-
-(2) An object with INTEGER syntax becomes an Integer32.
-
-(3) An object with ENUMERATED syntax becomes an INTEGER with
- enumerations, taking any of the values given which can be
- represented with an Integer32.
-
-(4) An object with BIT STRING syntax having enumerations becomes a BITS
- construct.
-
-(5) An object with BIT STRING syntax but no enumerations becomes an
- OCTET STRING.
-
-(6) An object with a character string syntax becomes either an OCTET
- STRING, or a DisplayString [3], depending on the repertoire of the
- character string.
-
-(7) A non-tabular object with a complex syntax, such as REAL or
- EXTERNAL, must be decomposed, usually into an OCTET STRING (if
- sensible). As a rule, any object with a complicated syntax should
- be avoided.
-
-(8) Tabular objects must be decomposed into rows of columnar objects.
-
-11.1.2. Mapping to the UNITS clause
-
- If the description of this managed object defines a unit-basis, then
- mapping to this clause is straight-forward.
-
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 34]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
-11.1.3. Mapping to the MAX-ACCESS clause
-
- This is straight-forward.
-
-11.1.4. Mapping to the STATUS clause
-
- This is straight-forward.
-
-11.1.5. Mapping to the DESCRIPTION clause
-
- This is straight-forward: simply copy the text, making sure that any
- embedded double quotation marks are sanitized (i.e., replaced with
- single-quotes or removed).
-
-11.1.6. Mapping to the REFERENCE clause
-
- This is straight-forward: simply include a textual reference to the
- object being mapped, the document which defines the object, and
- perhaps a page number in the document.
-
-11.1.7. Mapping to the INDEX clause
-
- If necessary, decide how instance-identifiers for columnar objects
- are to be formed and define this clause accordingly.
-
-11.1.8. Mapping to the DEFVAL clause
-
- Decide if a meaningful default value can be assigned to the object
- being mapped, and if so, define the DEFVAL clause accordingly.
-
-11.2. Action Mapping
-
- Actions are modeled as read-write objects, in which writing a
- particular value results in a state change. (Usually, as a part of
- this state change, some action might take place.)
-
-11.2.1. Mapping to the SYNTAX clause
-
- Usually the Integer32 syntax is used with a distinguished value
- provided for each action that the object provides access to. In
- addition, there is usually one other distinguished value, which is
- the one returned when the object is read.
-
-11.2.2. Mapping to the MAX-ACCESS clause
-
- Always use read-write or read-create.
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 35]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
-11.2.3. Mapping to the STATUS clause
-
- This is straight-forward.
-
-11.2.4. Mapping to the DESCRIPTION clause
-
- This is straight-forward: simply copy the text, making sure that any
- embedded double quotation marks are sanitized (i.e., replaced with
- single-quotes or removed).
-
-11.2.5. Mapping to the REFERENCE clause
-
- This is straight-forward: simply include a textual reference to the
- action being mapped, the document which defines the action, and
- perhaps a page number in the document.
-
-11.3. Event Mapping
-
- Events are modeled as SNMPv2 notifications using NOTIFICATION-TYPE
- macro. However, recall that SNMPv2 emphasizes trap-directed polling.
- As such, few, and usually no, notifications, need be defined for any
- MIB module.
-
-11.3.1. Mapping to the STATUS clause
-
- This is straight-forward.
-
-11.3.2. Mapping to the DESCRIPTION clause
-
- This is straight-forward: simply copy the text, making sure that any
- embedded double quotation marks are sanitized (i.e., replaced with
- single-quotes or removed).
-
-11.3.3. Mapping to the REFERENCE clause
-
- This is straight-forward: simply include a textual reference to the
- notification being mapped, the document which defines the
- notification, and perhaps a page number in the document.
-
-
-
-
-
-
-
-
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 36]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
-12. Appendix B: UTC Time Format
-
- Several clauses defined in this document use the UTC Time format:
-
- YYMMDDHHMMZ
-
- where: YY - last two digits of year
- MM - month (01 through 12)
- DD - day of month (01 through 31)
- HH - hours (00 through 23)
- MM - minutes (00 through 59)
- Z - the character "Z" denotes Greenwich Mean Time (GMT).
-
- For example, "9502192015Z" represents 8:15pm GMT on 19 February 1995.
-
-13. Appendix C: Detailed Sub-typing Rules
-
-13.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 (i.e. 'xxxx'H)
- <binString> is a binary string (i.e. 'xxxx'B)
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 37]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- <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.
-
-13.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))
-
-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
-
-13.3. Rules for Textual Conventions
-
- Sub-typing of Textual Conventions (see [3]) is allowed but must be
- valid. In particular, each range specified for the textual
- convention must be a subset of a range specified for the base type.
- For example,
-
- Tc1 ::= INTEGER (1..10 | 11..20)
- Tc2 ::= Tc1 (2..10 | 12..15) -- is valid
- Tc3 ::= Tc1 (4..8) -- is valid
- Tc4 ::= Tc1 (8..12) -- is invalid
-
-14. Security Considerations
-
- Security issues are not discussed in this memo.
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 38]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
-15. Editor's Address
-
- Keith McCloghrie
- Cisco Systems, Inc.
- 170 West Tasman Drive
- San Jose, CA 95134-1706
- US
-
- Phone: +1 408 526 5260
- EMail: kzm@cisco.com
-
-16. Acknowledgements
-
- This document is the result of significant work by the four major
- contributors:
-
- Jeffrey D. Case (SNMP Research, case@snmp.com)
- Keith McCloghrie (Cisco Systems, kzm@cisco.com)
- Marshall T. Rose (Dover Beach Consulting, mrose@dbc.mtview.ca.us)
- Steven Waldbusser (International Network Services, stevew@uni.ins.com)
-
- In addition, the contributions of the SNMPv2 Working Group are
- acknowledged. In particular, a special thanks is extended for the
- contributions of:
-
- Alexander I. Alten (Novell)
- Dave Arneson (Cabletron)
- Uri Blumenthal (IBM)
- Doug Book (Chipcom)
- Kim Curran (Bell-Northern Research)
- Jim Galvin (Trusted Information Systems)
- Maria Greene (Ascom Timeplex)
- Iain Hanson (Digital)
- Dave Harrington (Cabletron)
- Nguyen Hien (IBM)
- Jeff Johnson (Cisco Systems)
- Michael Kornegay (Object Quest)
- Deirdre Kostick (AT&T Bell Labs)
- David Levi (SNMP Research)
- Daniel Mahoney (Cabletron)
- Bob Natale (ACE*COMM)
- Brian O'Keefe (Hewlett Packard)
- Andrew Pearson (SNMP Research)
- Dave Perkins (Peer Networks)
- Randy Presuhn (Peer Networks)
- Aleksey Romanov (Quality Quorum)
- Shawn Routhier (Epilogue)
- Jon Saperia (BGS Systems)
-
-
-
-SNMPv2 Working Group Standards Track [Page 39]
-\f
-RFC 1902 SMI for SNMPv2 January 1996
-
-
- Bob Stewart (Cisco Systems, bstewart@cisco.com), chair
- Kaj Tesink (Bellcore)
- Glenn Waters (Bell-Northern Research)
- Bert Wijnen (IBM)
-
-17. 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] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and
- S. Waldbusser, "Conformance Statements for Version 2 of the Simple
- Network Management Protocol (SNMPv2)", RFC 1904, January 1996.
-
-[3] SNMPv2 Working Group, 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.
-
-[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] 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] 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.
-
-[7] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and
- S. Waldbusser, "Coexistence between Version 1 and Version 2 of the
- Internet-standard Network Management Framework", RFC 1908,
- January 1996.
-
-
-
-
-
-
-
-
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 40]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group SNMPv2 Working Group
-Request for Comments: 1905 J. Case
-Obsoletes: 1448 SNMP Research, Inc.
-Category: Standards Track K. McCloghrie
- Cisco Systems, Inc.
- M. Rose
- Dover Beach Consulting, Inc.
- S. Waldbusser
- International Network Services
- January 1996
-
-
- Protocol Operations
- for Version 2 of the
- Simple Network Management Protocol (SNMPv2)
-
-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.
-
-1. Introduction
-
- A management system contains: several (potentially many) nodes, each
- with a processing entity, termed an agent, which has access to
- management instrumentation; at least one management station; and, a
- management protocol, used to convey management information between
- the agents and management stations. Operations of the protocol are
- carried out under an administrative framework which defines
- authentication, authorization, access control, and privacy policies.
-
- Management stations execute management applications which monitor and
- control managed elements. Managed elements are devices such as
- hosts, routers, terminal servers, etc., which are monitored and
- controlled via access to their management information.
-
- 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 a subset of OSI's
- Abstract Syntax Notation One (ASN.1) [1], termed the Structure of
- Management Information (SMI) [2].
-
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 1]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- The management protocol, version 2 of the Simple Network Management
- Protocol, provides for the exchange of messages which convey
- management information between the agents and the management
- stations. The form of these messages is a message "wrapper" which
- encapsulates a Protocol Data Unit (PDU). The form and meaning of the
- "wrapper" is determined by an administrative framework which defines
- both authentication and authorization policies.
-
- It is the purpose of this document, Protocol Operations for SNMPv2,
- to define the operations of the protocol with respect to the sending
- and receiving of the PDUs.
-
-1.1. A Note on Terminology
-
- For the purpose of exposition, the original Internet-standard Network
- Management Framework, as described in RFCs 1155 (STD 16), 1157 (STD
- 15), and 1212 (STD 16), is termed the SNMP version 1 framework
- (SNMPv1). The current framework is termed the SNMP version 2
- framework (SNMPv2).
-
-2. Overview
-
-2.1. Roles of Protocol Entities
-
- A SNMPv2 entity may operate in a manager role or an agent role.
-
- A SNMPv2 entity acts in an agent role when it performs SNMPv2
- management operations in response to received SNMPv2 protocol
- messages (other than an inform notification) or when it sends trap
- notifications.
-
- A SNMPv2 entity acts in a manager role when it initiates SNMPv2
- management operations by the generation of SNMPv2 protocol messages
- or when it performs SNMPv2 management operations in response to
- received trap or inform notifications.
-
- A SNMPv2 entity may support either or both roles, as dictated by its
- implementation and configuration. Further, a SNMPv2 entity can also
- act in the role of a proxy agent, in which it appears to be acting in
- an agent role, but satisfies management requests by acting in a
- manager role with a remote entity.
-
-2.2. Management Information
-
- The term, variable, refers to an instance of a non-aggregate object
- type defined according to the conventions set forth in the SMI [2] or
- the textual conventions based on the SMI [3]. The term, variable
- binding, normally refers to the pairing of the name of a variable and
-
-
-
-SNMPv2 Working Group Standards Track [Page 2]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- its associated value. However, if certain kinds of exceptional
- conditions occur during processing of a retrieval request, a variable
- binding will pair a name and an indication of that exception.
-
- A variable-binding list is a simple list of variable bindings.
-
- The name of a variable is an OBJECT IDENTIFIER which is the
- concatenation of the OBJECT IDENTIFIER of the corresponding object-
- type together with an OBJECT IDENTIFIER fragment identifying the
- instance. The OBJECT IDENTIFIER of the corresponding object-type is
- called the OBJECT IDENTIFIER prefix of the variable.
-
-2.3. Access to Management Information
-
- Three types of access to management information are provided by the
- protocol. One type is a request-response interaction, in which a
- SNMPv2 entity, acting in a manager role, sends a request to a SNMPv2
- entity, acting in an agent role, and the latter SNMPv2 entity then
- responds to the request. This type is used to retrieve or modify
- management information associated with the managed device.
-
- A second type is also a request-response interaction, in which a
- SNMPv2 entity, acting in a manager role, sends a request to a SNMPv2
- entity, also acting in a manager role, and the latter SNMPv2 entity
- then responds to the request. This type is used to notify a SNMPv2
- entity, acting in a manager role, of management information
- associated with another SNMPv2 entity, also acting in a manager role.
-
- The third type of access is an unconfirmed interaction, in which a
- SNMPv2 entity, acting in an agent role, sends a unsolicited message,
- termed a trap, to a SNMPv2 entity, acting in a manager role, and no
- response is returned. This type is used to notify a SNMPv2 entity,
- acting in a manager role, of an exceptional situation, which has
- resulted in changes to management information associated with the
- managed device.
-
-2.4. Retransmission of Requests
-
- For all types of request in this protocol, the receiver is required
- under normal circumstances, to generate and transmit a response to
- the originator of the request. Whether or not a request should be
- retransmitted if no corresponding response is received in an
- appropriate time interval, is at the discretion of the application
- originating the request. This will normally depend on the urgency of
- the request. However, such an application needs to act responsibly
- in respect to the frequency and duration of re-transmissions.
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 3]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
-2.5. Message Sizes
-
- The maximum size of a SNMPv2 message is limited to the minimum of:
-
-(1) the maximum message size which the destination SNMPv2 entity can
- accept; and,
-
-(2) the maximum message size which the source SNMPv2 entity can
- generate.
-
- The former may be known on a per-recipient basis; and in the absence
- of such knowledge, is indicated by transport domain used when sending
- the message. The latter is imposed by implementation-specific local
- constraints.
-
- Each transport mapping for the SNMPv2 indicates the minimum message
- size which a SNMPv2 implementation must be able to produce or
- consume. Although implementations are encouraged to support larger
- values whenever possible, a conformant implementation must never
- generate messages larger than allowed by the receiving SNMPv2 entity.
-
- One of the aims of the GetBulkRequest-PDU, specified in this
- protocol, is to minimize the number of protocol exchanges required to
- retrieve a large amount of management information. As such, this PDU
- type allows a SNMPv2 entity acting in a manager role to request that
- the response be as large as possible given the constraints on message
- sizes. These constraints include the limits on the size of messages
- which the SNMPv2 entity acting in an agent role can generate, and the
- SNMPv2 entity acting in a manager role can receive.
-
- However, it is possible that such maximum sized messages may be
- larger than the Path MTU of the path across the network traversed by
- the messages. In this situation, such messages are subject to
- fragmentation. Fragmentation is generally considered to be harmful
- [4], since among other problems, it leads to a decrease in the
- reliability of the transfer of the messages. Thus, a SNMPv2 entity
- which sends a GetBulkRequest-PDU must take care to set its parameters
- accordingly, so as to reduce the risk of fragmentation. In
- particular, under conditions of network stress, only small values
- should be used for max-repetitions.
-
-2.6. Transport Mappings
-
- It is important to note that the exchange of SNMPv2 messages requires
- only an unreliable datagram service, with every message being
- entirely and independently contained in a single transport datagram.
- Specific transport mappings and encoding rules are specified
- elsewhere [5]. However, the preferred mapping is the use of the User
-
-
-
-SNMPv2 Working Group Standards Track [Page 4]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- Datagram Protocol [6].
-
-3. Definitions
-
- SNMPv2-PDU DEFINITIONS ::= BEGIN
-
- IMPORTS
- ObjectName, ObjectSyntax, Integer32
- FROM SNMPv2-SMI;
-
-
- -- protocol data units
-
- PDUs ::=
- CHOICE {
- get-request
- GetRequest-PDU,
-
- get-next-request
- GetNextRequest-PDU,
-
- get-bulk-request
- GetBulkRequest-PDU,
-
- response
- Response-PDU,
-
- set-request
- SetRequest-PDU,
-
- inform-request
- InformRequest-PDU,
-
- snmpV2-trap
- SNMPv2-Trap-PDU,
-
- report
- Report-PDU,
- }
-
-
- -- PDUs
-
- GetRequest-PDU ::=
- [0]
- IMPLICIT PDU
-
- GetNextRequest-PDU ::=
-
-
-
-SNMPv2 Working Group Standards Track [Page 5]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- [1]
- IMPLICIT PDU
-
- Response-PDU ::=
- [2]
- IMPLICIT PDU
-
- SetRequest-PDU ::=
- [3]
- IMPLICIT PDU
-
- -- [4] is obsolete
-
- GetBulkRequest-PDU ::=
- [5]
- IMPLICIT BulkPDU
-
- InformRequest-PDU ::=
- [6]
- IMPLICIT PDU
-
- SNMPv2-Trap-PDU ::=
- [7]
- IMPLICIT PDU
-
- -- Usage and precise semantics of Report-PDU are not presently
- -- defined. Any SNMP administrative framework making use of
- -- this PDU must define its usage and semantics.
- Report-PDU ::=
- [8]
- IMPLICIT PDU
-
- max-bindings
- INTEGER ::= 2147483647
-
- PDU ::=
- SEQUENCE {
- request-id
- Integer32,
-
- error-status -- sometimes ignored
- INTEGER {
- noError(0),
- tooBig(1),
- noSuchName(2), -- for proxy compatibility
- badValue(3), -- for proxy compatibility
- readOnly(4), -- for proxy compatibility
- genErr(5),
-
-
-
-SNMPv2 Working Group Standards Track [Page 6]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- noAccess(6),
- wrongType(7),
- wrongLength(8),
- wrongEncoding(9),
- wrongValue(10),
- noCreation(11),
- inconsistentValue(12),
- resourceUnavailable(13),
- commitFailed(14),
- undoFailed(15),
- authorizationError(16),
- notWritable(17),
- inconsistentName(18)
- },
-
- error-index -- sometimes ignored
- INTEGER (0..max-bindings),
-
- variable-bindings -- values are sometimes ignored
- VarBindList
- }
-
-
- BulkPDU ::= -- MUST be identical in
- SEQUENCE { -- structure to PDU
- request-id
- Integer32,
-
- non-repeaters
- INTEGER (0..max-bindings),
-
- max-repetitions
- INTEGER (0..max-bindings),
-
- variable-bindings -- values are ignored
- VarBindList
- }
-
-
- -- variable binding
-
- VarBind ::=
- SEQUENCE {
- name
- ObjectName,
-
- CHOICE {
- value
-
-
-
-SNMPv2 Working Group Standards Track [Page 7]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- ObjectSyntax,
-
- unSpecified -- in retrieval requests
- NULL,
-
- -- exceptions in responses
- noSuchObject[0]
- IMPLICIT NULL,
-
- noSuchInstance[1]
- IMPLICIT NULL,
-
- endOfMibView[2]
- IMPLICIT NULL
- }
- }
-
-
- -- variable-binding list
-
- VarBindList ::=
- SEQUENCE (SIZE (0..max-bindings)) OF
- VarBind
-
-
- END
-
-
-4. Protocol Specification
-
-4.1. Common Constructs
-
- The value of the request-id field in a Response-PDU takes the value
- of the request-id field in the request PDU to which it is a response.
- By use of the request-id value, a SNMPv2 application can distinguish
- the (potentially multiple) outstanding requests, and thereby
- correlate incoming responses with outstanding requests. In cases
- where an unreliable datagram service is used, the request-id also
- provides a simple means of identifying messages duplicated by the
- network. Use of the same request-id on a retransmission of a request
- allows the response to either the original transmission or the
- retransmission to satisfy the request. However, in order to
- calculate the round trip time for transmission and processing of a
- request-response transaction, the SNMPv2 application needs to use a
- different request-id value on a retransmitted request. The latter
- strategy is recommended for use in the majority of situations.
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 8]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- A non-zero value of the error-status field in a Response-PDU is used
- to indicate that an exception occurred to prevent the processing of
- the request. In these cases, a non-zero value of the Response-PDU's
- error-index field provides additional information by identifying
- which variable binding in the list caused the exception. A variable
- binding is identified by its index value. The first variable binding
- in a variable-binding list is index one, the second is index two,
- etc.
-
- SNMPv2 limits OBJECT IDENTIFIER values to a maximum of 128 sub-
- identifiers, where each sub-identifier has a maximum value of 2**32-
- 1.
-
-4.2. PDU Processing
-
- It is mandatory that all SNMPv2 entities acting in an agent role be
- able to generate the following PDU types: Response-PDU and SNMPv2-
- Trap-PDU; further, all such implementations must be able to receive
- the following PDU types: GetRequest-PDU, GetNextRequest-PDU,
- GetBulkRequest-PDU, and SetRequest-PDU.
-
- It is mandatory that all SNMPv2 entities acting in a manager role be
- able to generate the following PDU types: GetRequest-PDU,
- GetNextRequest-PDU, GetBulkRequest-PDU, SetRequest-PDU,
- InformRequest-PDU, and Response-PDU; further, all such
- implementations must be able to receive the following PDU types:
- Response-PDU, SNMPv2-Trap-PDU,
-
- InformRequest-PDU;
-
- In the elements of procedure below, any field of a PDU which is not
- referenced by the relevant procedure is ignored by the receiving
- SNMPv2 entity. However, all components of a PDU, including those
- whose values are ignored by the receiving SNMPv2 entity, must have
- valid ASN.1 syntax and encoding. For example, some PDUs (e.g., the
- GetRequest-PDU) are concerned only with the name of a variable and
- not its value. In this case, the value portion of the variable
- binding is ignored by the receiving SNMPv2 entity. The unSpecified
- value is defined for use as the value portion of such bindings.
-
- On generating a management communication, the message "wrapper" to
- encapsulate the PDU is generated according to the "Elements of
- Procedure" of the administrative framework in use is followed. While
- the definition of "max-bindings" does impose an upper-bound on the
- number of variable bindings, in practice, the size of a message is
- limited only by constraints on the maximum message size -- it is not
- limited by the number of variable bindings.
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 9]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- On receiving a management communication, the "Elements of Procedure"
- of the administrative framework in use is followed, and if those
- procedures indicate that the operation contained within the message
- is to be performed locally, then those procedures also indicate the
- MIB view which is visible to the operation.
-
-4.2.1. The GetRequest-PDU
-
- A GetRequest-PDU is generated and transmitted at the request of a
- SNMPv2 application.
-
- Upon receipt of a GetRequest-PDU, the receiving SNMPv2 entity
- processes each variable binding in the variable-binding list to
- produce a Response-PDU. All fields of the Response-PDU have the same
- values as the corresponding fields of the received request except as
- indicated below. Each variable binding is processed as follows:
-
-(1) If the variable binding's name exactly matches the name of a
- variable accessible by this request, then the variable binding's
- value field is set to the value of the named variable.
-
-(2) Otherwise, if the variable binding's name does not have an OBJECT
- IDENTIFIER prefix which exactly matches the OBJECT IDENTIFIER
- prefix of any (potential) variable accessible by this request, then
- its value field is set to `noSuchObject'.
-
-(3) Otherwise, the variable binding's value field is set to
- `noSuchInstance'.
-
- If the processing of any variable binding fails for a reason other
- than listed above, then the Response-PDU is re-formatted with the
- same values in its request-id and variable-bindings fields as the
- received GetRequest-PDU, with the value of its error-status field set
- to `genErr', and the value of its error-index field is set to the
- index of the failed variable binding.
-
- Otherwise, the value of the Response-PDU's error-status field is set
- to `noError', and the value of its error-index field is zero.
-
- The generated Response-PDU is then encapsulated into a message. If
- the size of the resultant message is less than or equal to both a
- local constraint and the maximum message size of the originator, it
- is transmitted to the originator of the GetRequest-PDU.
-
- Otherwise, an alternate Response-PDU is generated. This alternate
- Response-PDU is formatted with the same value in its request-id field
- as the received GetRequest-PDU, with the value of its error-status
- field set to `tooBig', the value of its error-index field set to
-
-
-
-SNMPv2 Working Group Standards Track [Page 10]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- zero, and an empty variable-bindings field. This alternate
- Response-PDU is then encapsulated into a message. If the size of the
- resultant message is less than or equal to both a local constraint
- and the maximum message size of the originator, it is transmitted to
- the originator of the GetRequest-PDU. Otherwise, the snmpSilentDrops
- [9] counter is incremented and the resultant message is discarded.
-
-4.2.2. The GetNextRequest-PDU
-
- A GetNextRequest-PDU is generated and transmitted at the request of a
- SNMPv2 application.
-
- Upon receipt of a GetNextRequest-PDU, the receiving SNMPv2 entity
- processes each variable binding in the variable-binding list to
- produce a Response-PDU. All fields of the Response-PDU have the same
- values as the corresponding fields of the received request except as
- indicated below. Each variable binding is processed as follows:
-
-(1) The variable is located which is in the lexicographically ordered
- list of the names of all variables which are accessible by this
- request and whose name is the first lexicographic successor of the
- variable binding's name in the incoming GetNextRequest-PDU. The
- corresponding variable binding's name and value fields in the
- Response-PDU are set to the name and value of the located variable.
-
-(2) If the requested variable binding's name does not lexicographically
- precede the name of any variable accessible by this request, i.e.,
- there is no lexicographic successor, then the corresponding
- variable binding produced in the Response-PDU has its value field
- set to `endOfMibView', and its name field set to the variable
- binding's name in the request.
-
- If the processing of any variable binding fails for a reason other
- than listed above, then the Response-PDU is re-formatted with the
- same values in its request-id and variable-bindings fields as the
- received GetNextRequest-PDU, with the value of its error-status field
- set to `genErr', and the value of its error-index field is set to the
- index of the failed variable binding.
-
- Otherwise, the value of the Response-PDU's error-status field is set
- to `noError', and the value of its error-index field is zero.
-
- The generated Response-PDU is then encapsulated into a message. If
- the size of the resultant message is less than or equal to both a
- local constraint and the maximum message size of the originator, it
- is transmitted to the originator of the GetNextRequest-PDU.
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 11]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- Otherwise, an alternate Response-PDU is generated. This alternate
- Response-PDU is formatted with the same values in its request-id
- field as the received GetNextRequest-PDU, with the value of its
- error-status field set to `tooBig', the value of its error-index
- field set to zero, and an empty variable-bindings field. This
- alternate Response-PDU is then encapsulated into a message. If the
- size of the resultant message is less than or equal to both a local
- constraint and the maximum message size of the originator, it is
- transmitted to the originator of the GetNextRequest-PDU. Otherwise,
- the snmpSilentDrops [9] counter is incremented and the resultant
- message is discarded.
-
-4.2.2.1. Example of Table Traversal
-
- An important use of the GetNextRequest-PDU is the traversal of
- conceptual tables of information within a MIB. The semantics of this
- type of request, together with the method of identifying individual
- instances of objects in the MIB, provides access to related objects
- in the MIB as if they enjoyed a tabular organization.
-
- In the protocol exchange sketched below, a SNMPv2 application
- retrieves the media-dependent physical address and the address-
- mapping type for each entry in the IP net-to-media Address
- Translation Table [7] of a particular network element. It also
- retrieves the value of sysUpTime [9], at which the mappings existed.
- Suppose that the agent's IP net-to-media table has three entries:
-
- Interface-Number Network-Address Physical-Address Type
-
- 1 10.0.0.51 00:00:10:01:23:45 static
- 1 9.2.3.4 00:00:10:54:32:10 dynamic
- 2 10.0.0.15 00:00:10:98:76:54 dynamic
-
- The SNMPv2 entity acting in a manager role begins by sending a
- GetNextRequest-PDU containing the indicated OBJECT IDENTIFIER values
- as the requested variable names:
-
- GetNextRequest ( sysUpTime,
- ipNetToMediaPhysAddress,
- ipNetToMediaType )
-
- The SNMPv2 entity acting in an agent role responds with a Response-
- PDU:
-
- Response (( sysUpTime.0 = "123456" ),
- ( ipNetToMediaPhysAddress.1.9.2.3.4 =
- "000010543210" ),
- ( ipNetToMediaType.1.9.2.3.4 = "dynamic" ))
-
-
-
-SNMPv2 Working Group Standards Track [Page 12]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- The SNMPv2 entity acting in a manager role continues with:
-
- GetNextRequest ( sysUpTime,
- ipNetToMediaPhysAddress.1.9.2.3.4,
- ipNetToMediaType.1.9.2.3.4 )
-
- The SNMPv2 entity acting in an agent role responds with:
-
- Response (( sysUpTime.0 = "123461" ),
- ( ipNetToMediaPhysAddress.1.10.0.0.51 =
- "000010012345" ),
- ( ipNetToMediaType.1.10.0.0.51 = "static" ))
-
- The SNMPv2 entity acting in a manager role continues with:
-
- GetNextRequest ( sysUpTime,
- ipNetToMediaPhysAddress.1.10.0.0.51,
- ipNetToMediaType.1.10.0.0.51 )
-
- The SNMPv2 entity acting in an agent role responds with:
-
- Response (( sysUpTime.0 = "123466" ),
- ( ipNetToMediaPhysAddress.2.10.0.0.15 =
- "000010987654" ),
- ( ipNetToMediaType.2.10.0.0.15 = "dynamic" ))
-
- The SNMPv2 entity acting in a manager role continues with:
-
- GetNextRequest ( sysUpTime,
- ipNetToMediaPhysAddress.2.10.0.0.15,
- ipNetToMediaType.2.10.0.0.15 )
-
- As there are no further entries in the table, the SNMPv2 entity
- acting in an agent role responds with the variables that are next in
- the lexicographical ordering of the accessible object names, for
- example:
-
- Response (( sysUpTime.0 = "123471" ),
- ( ipNetToMediaNetAddress.1.9.2.3.4 =
- "9.2.3.4" ),
- ( ipRoutingDiscards.0 = "2" ))
-
- This response signals the end of the table to the SNMPv2 entity
- acting in a manager role.
-
-
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 13]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
-4.2.3. The GetBulkRequest-PDU
-
- A GetBulkRequest-PDU is generated and transmitted at the request of a
- SNMPv2 application. The purpose of the GetBulkRequest-PDU is to
- request the transfer of a potentially large amount of data,
- including, but not limited to, the efficient and rapid retrieval of
- large tables.
-
- Upon receipt of a GetBulkRequest-PDU, the receiving SNMPv2 entity
- processes each variable binding in the variable-binding list to
- produce a Response-PDU with its request-id field having the same
- value as in the request. Processing begins by examining the values
- in the non-repeaters and max-repetitions fields. If the value in the
- non-repeaters field is less than zero, then the value of the field is
- set to zero. Similarly, if the value in the max-repetitions field is
- less than zero, then the value of the field is set to zero.
-
- For the GetBulkRequest-PDU type, the successful processing of each
- variable binding in the request generates zero or more variable
- bindings in the Response-PDU. That is, the one-to-one mapping
- between the variable bindings of the GetRequest-PDU, GetNextRequest-
- PDU, and SetRequest-PDU types and the resultant Response-PDUs does
- not apply for the mapping between the variable bindings of a
- GetBulkRequest-PDU and the resultant Response-PDU.
-
- The values of the non-repeaters and max-repetitions fields in the
- request specify the processing requested. One variable binding in
- the Response-PDU is requested for the first N variable bindings in
- the request and M variable bindings are requested for each of the R
- remaining variable bindings in the request. Consequently, the total
- number of requested variable bindings communicated by the request is
- given by N + (M * R), where N is the minimum of: a) the value of the
- non-repeaters field in the request, and b) the number of variable
- bindings in the request; M is the value of the max-repetitions field
- in the request; and R is the maximum of: a) number of variable
- bindings in the request - N, and b) zero.
-
- The receiving SNMPv2 entity produces a Response-PDU with up to the
- total number of requested variable bindings communicated by the
- request. The request-id shall have the same value as the received
- GetBulkRequest-PDU.
-
- If N is greater than zero, the first through the (N)-th variable
- bindings of the Response-PDU are each produced as follows:
-
-(1) The variable is located which is in the lexicographically ordered
- list of the names of all variables which are accessible by this
- request and whose name is the first lexicographic successor of the
-
-
-
-SNMPv2 Working Group Standards Track [Page 14]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- variable binding's name in the incoming GetBulkRequest-PDU. The
- corresponding variable binding's name and value fields in the
- Response-PDU are set to the name and value of the located variable.
-
-(2) If the requested variable binding's name does not lexicographically
- precede the name of any variable accessible by this request, i.e.,
- there is no lexicographic successor, then the corresponding
- variable binding produced in the Response-PDU has its value field
- set to `endOfMibView', and its name field set to the variable
- binding's name in the request.
-
- If M and R are non-zero, the (N + 1)-th and subsequent variable
- bindings of the Response-PDU are each produced in a similar manner.
- For each iteration i, such that i is greater than zero and less than
- or equal to M, and for each repeated variable, r, such that r is
- greater than zero and less than or equal to R, the (N + ( (i-1) * R )
- + r)-th variable binding of the Response-PDU is produced as follows:
-
-(1) The variable which is in the lexicographically ordered list of the
- names of all variables which are accessible by this request and
- whose name is the (i)-th lexicographic successor of the (N + r)-th
- variable binding's name in the incoming GetBulkRequest-PDU is
- located and the variable binding's name and value fields are set to
- the name and value of the located variable.
-
-(2) If there is no (i)-th lexicographic successor, then the
- corresponding variable binding produced in the Response-PDU has its
- value field set to `endOfMibView', and its name field set to either
- the last lexicographic successor, or if there are no lexicographic
- successors, to the (N + r)-th variable binding's name in the
- request.
-
- While the maximum number of variable bindings in the Response-PDU is
- bounded by N + (M * R), the response may be generated with a lesser
- number of variable bindings (possibly zero) for either of three
- reasons.
-
-(1) If the size of the message encapsulating the Response-PDU
- containing the requested number of variable bindings would be
- greater than either a local constraint or the maximum message size
- of the originator, then the response is generated with a lesser
- number of variable bindings. This lesser number is the ordered set
- of variable bindings with some of the variable bindings at the end
- of the set removed, such that the size of the message encapsulating
- the Response-PDU is approximately equal to but no greater than
- either a local constraint or the maximum message size of the
- originator. Note that the number of variable bindings removed has
- no relationship to the values of N, M, or R.
-
-
-
-SNMPv2 Working Group Standards Track [Page 15]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
-(2) The response may also be generated with a lesser number of variable
- bindings if for some value of iteration i, such that i is greater
- than zero and less than or equal to M, that all of the generated
- variable bindings have the value field set to the `endOfMibView'.
- In this case, the variable bindings may be truncated after the (N +
- (i * R))-th variable binding.
-
-(3) In the event that the processing of a request with many repetitions
- requires a significantly greater amount of processing time than a
- normal request, then an agent may terminate the request with less
- than the full number of repetitions, providing at least one
- repetition is completed.
-
- If the processing of any variable binding fails for a reason other
- than listed above, then the Response-PDU is re-formatted with the
- same values in its request-id and variable-bindings fields as the
- received GetBulkRequest-PDU, with the value of its error-status field
- set to `genErr', and the value of its error-index field is set to the
- index of the variable binding in the original request which
- corresponds to the failed variable binding.
-
- Otherwise, the value of the Response-PDU's error-status field is set
- to `noError', and the value of its error-index field to zero.
-
- The generated Response-PDU (possibly with an empty variable-bindings
- field) is then encapsulated into a message. If the size of the
- resultant message is less than or equal to both a local constraint
- and the maximum message size of the originator, it is transmitted to
- the originator of the GetBulkRequest-PDU. Otherwise, the
- snmpSilentDrops [9] counter is incremented and the resultant message
- is discarded.
-
-4.2.3.1. Another Example of Table Traversal
-
- This example demonstrates how the GetBulkRequest-PDU can be used as
- an alternative to the GetNextRequest-PDU. The same traversal of the
- IP net-to-media table as shown in Section 4.2.2.1 is achieved with
- fewer exchanges.
-
- The SNMPv2 entity acting in a manager role begins by sending a
- GetBulkRequest-PDU with the modest max-repetitions value of 2, and
- containing the indicated OBJECT IDENTIFIER values as the requested
- variable names:
-
- GetBulkRequest [ non-repeaters = 1, max-repetitions = 2 ]
- ( sysUpTime,
- ipNetToMediaPhysAddress,
- ipNetToMediaType )
-
-
-
-SNMPv2 Working Group Standards Track [Page 16]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- The SNMPv2 entity acting in an agent role responds with a Response-PDU:
-
- Response (( sysUpTime.0 = "123456" ),
- ( ipNetToMediaPhysAddress.1.9.2.3.4 =
- "000010543210" ),
- ( ipNetToMediaType.1.9.2.3.4 = "dynamic" ),
- ( ipNetToMediaPhysAddress.1.10.0.0.51 =
- "000010012345" ),
- ( ipNetToMediaType.1.10.0.0.51 = "static" ))
-
- The SNMPv2 entity acting in a manager role continues with:
-
- GetBulkRequest [ non-repeaters = 1, max-repetitions = 2 ]
- ( sysUpTime,
- ipNetToMediaPhysAddress.1.10.0.0.51,
- ipNetToMediaType.1.10.0.0.51 )
-
- The SNMPv2 entity acting in an agent role responds with:
-
- Response (( sysUpTime.0 = "123466" ),
- ( ipNetToMediaPhysAddress.2.10.0.0.15 =
- "000010987654" ),
- ( ipNetToMediaType.2.10.0.0.15 =
- "dynamic" ),
- ( ipNetToMediaNetAddress.1.9.2.3.4 =
- "9.2.3.4" ),
- ( ipRoutingDiscards.0 = "2" ))
-
- This response signals the end of the table to the SNMPv2 entity
- acting in a manager role.
-
-4.2.4. The Response-PDU
-
- The Response-PDU is generated by a SNMPv2 entity only upon receipt of
- a GetRequest-PDU, GetNextRequest-PDU, GetBulkRequest-PDU,
- SetRequest-PDU, or InformRequest-PDU, as described elsewhere in this
- document.
-
- If the error-status field of the Response-PDU is non-zero, the value
- fields of the variable bindings in the variable binding list are
- ignored.
-
- If both the error-status field and the error-index field of the
- Response-PDU are non-zero, then the value of the error-index field is
- the index of the variable binding (in the variable-binding list of
- the corresponding request) for which the request failed. The first
- variable binding in a request's variable-binding list is index one,
- the second is index two, etc.
-
-
-
-SNMPv2 Working Group Standards Track [Page 17]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- A compliant SNMPv2 entity acting in a manager role must be able to
- properly receive and handle a Response-PDU with an error-status field
- equal to `noSuchName', `badValue', or `readOnly'. (See Section 3.1.2
- of [8].)
-
- Upon receipt of a Response-PDU, the receiving SNMPv2 entity presents
- its contents to the SNMPv2 application which generated the request
- with the same request-id value.
-
-4.2.5. The SetRequest-PDU
-
- A SetRequest-PDU is generated and transmitted at the request of a
- SNMPv2 application.
-
- Upon receipt of a SetRequest-PDU, the receiving SNMPv2 entity
- determines the size of a message encapsulating a Response-PDU having
- the same values in its request-id and variable-bindings fields as the
- received SetRequest-PDU, and the largest possible sizes of the
- error-status and error-index fields. If the determined message size
- is greater than either a local constraint or the maximum message size
- of the originator, then an alternate Response-PDU is generated,
- transmitted to the originator of the SetRequest-PDU, and processing
- of the SetRequest-PDU terminates immediately thereafter. This
- alternate Response-PDU is formatted with the same values in its
- request-id field as the received SetRequest-PDU, with the value of
- its error-status field set to `tooBig', the value of its error-index
- field set to zero, and an empty variable-bindings field. This
- alternate Response-PDU is then encapsulated into a message. If the
- size of the resultant message is less than or equal to both a local
- constraint and the maximum message size of the originator, it is
- transmitted to the originator of the SetRequest-PDU. Otherwise, the
- snmpSilentDrops [9] counter is incremented and the resultant message
- is discarded. Regardless, processing of the SetRequest-PDU
- terminates.
-
- Otherwise, the receiving SNMPv2 entity processes each variable
- binding in the variable-binding list to produce a Response-PDU. All
- fields of the Response-PDU have the same values as the corresponding
- fields of the received request except as indicated below.
-
- The variable bindings are conceptually processed as a two phase
- operation. In the first phase, each variable binding is validated;
- if all validations are successful, then each variable is altered in
- the second phase. Of course, implementors are at liberty to
- implement either the first, or second, or both, of these conceptual
- phases as multiple implementation phases. Indeed, such multiple
- implementation phases may be necessary in some cases to ensure
- consistency.
-
-
-
-SNMPv2 Working Group Standards Track [Page 18]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- The following validations are performed in the first phase on each
- variable binding until they are all successful, or until one fails:
-
-(1) If the variable binding's name specifies an existing or non-
- existent variable to which this request is/would be denied access
- because it is/would not be in the appropriate MIB view, then the
- value of the Response-PDU's error-status field is set to
- `noAccess', and the value of its error-index field is set to the
- index of the failed variable binding.
-
-(2) Otherwise, if there are no variables which share the same OBJECT
- IDENTIFIER prefix as the variable binding's name, and which are
- able to be created or modified no matter what new value is
- specified, then the value of the Response-PDU's error-status field
- is set to `notWritable', and the value of its error-index field is
- set to the index of the failed variable binding.
-
-(3) Otherwise, if the variable binding's value field specifies,
- according to the ASN.1 language, a type which is inconsistent with
- that required for all variables which share the same OBJECT
- IDENTIFIER prefix as the variable binding's name, then the value of
- the Response-PDU's error-status field is set to `wrongType', and
- the value of its error-index field is set to the index of the
- failed variable binding.
-
-(4) Otherwise, if the variable binding's value field specifies,
- according to the ASN.1 language, a length which is inconsistent
- with that required for all variables which share the same OBJECT
- IDENTIFIER prefix as the variable binding's name, then the value of
- the Response-PDU's error-status field is set to `wrongLength', and
- the value of its error-index field is set to the index of the
- failed variable binding.
-
-(5) Otherwise, if the variable binding's value field contains an ASN.1
- encoding which is inconsistent with that field's ASN.1 tag, then
- the value of the Response-PDU's error-status field is set to
- `wrongEncoding', and the value of its error-index field is set to
- the index of the failed variable binding. (Note that not all
- implementation strategies will generate this error.)
-
-(6) Otherwise, if the variable binding's value field specifies a value
- which could under no circumstances be assigned to the variable,
- then the value of the Response-PDU's error-status field is set to
- `wrongValue', and the value of its error-index field is set to the
- index of the failed variable binding.
-
-(7) Otherwise, if the variable binding's name specifies a variable
- which does not exist and could not ever be created (even though
-
-
-
-SNMPv2 Working Group Standards Track [Page 19]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- some variables sharing the same OBJECT IDENTIFIER prefix might
- under some circumstances be able to be created), then the value of
- the Response-PDU's error-status field is set to `noCreation', and
- the value of its error-index field is set to the index of the
- failed variable binding.
-
-(8) Otherwise, if the variable binding's name specifies a variable
- which does not exist but can not be created under the present
- circumstances (even though it could be created under other
- circumstances), then the value of the Response-PDU's error-status
- field is set to `inconsistentName', and the value of its error-
- index field is set to the index of the failed variable binding.
-
-(9) Otherwise, if the variable binding's name specifies a variable
- which exists but can not be modified no matter what new value is
- specified, then the value of the Response-PDU's error-status field
- is set to `notWritable', and the value of its error-index field is
- set to the index of the failed variable binding.
-
-(10) Otherwise, if the variable binding's value field specifies a value
- that could under other circumstances be held by the variable, but
- is presently inconsistent or otherwise unable to be assigned to the
- variable, then the value of the Response-PDU's error-status field
- is set to `inconsistentValue', and the value of its error-index
- field is set to the index of the failed variable binding.
-
-(11) When, during the above steps, the assignment of the value specified
- by the variable binding's value field to the specified variable
- requires the allocation of a resource which is presently
- unavailable, then the value of the Response-PDU's error-status
- field is set to `resourceUnavailable', and the value of its error-
- index field is set to the index of the failed variable binding.
-
-(12) If the processing of the variable binding fails for a reason other
- than listed above, then the value of the Response-PDU's error-
- status field is set to `genErr', and the value of its error-index
- field is set to the index of the failed variable binding.
-
-(13) Otherwise, the validation of the variable binding succeeds.
-
- At the end of the first phase, if the validation of all variable
- bindings succeeded, then the value of the Response-PDU's error-status
- field is set to `noError' and the value of its error-index field is
- zero, and processing continues as follows.
-
- For each variable binding in the request, the named variable is
- created if necessary, and the specified value is assigned to it.
- Each of these variable assignments occurs as if simultaneously with
-
-
-
-SNMPv2 Working Group Standards Track [Page 20]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- respect to all other assignments specified in the same request.
- However, if the same variable is named more than once in a single
- request, with different associated values, then the actual assignment
- made to that variable is implementation-specific.
-
- If any of these assignments fail (even after all the previous
- validations), then all other assignments are undone, and the
- Response-PDU is modified to have the value of its error-status field
- set to `commitFailed', and the value of its error-index field set to
- the index of the failed variable binding.
-
- If and only if it is not possible to undo all the assignments, then
- the Response-PDU is modified to have the value of its error-status
- field set to `undoFailed', and the value of its error-index field is
- set to zero. Note that implementations are strongly encouraged to
- take all possible measures to avoid use of either `commitFailed' or
- `undoFailed' - these two error-status codes are not to be taken as
- license to take the easy way out in an implementation.
-
- Finally, the generated Response-PDU is encapsulated into a message,
- and transmitted to the originator of the SetRequest-PDU.
-
-4.2.6. The SNMPv2-Trap-PDU
-
- A SNMPv2-Trap-PDU is generated and transmitted by a SNMPv2 entity
- acting in an agent role when an exceptional situation occurs.
-
- The destination(s) to which a SNMPv2-Trap-PDU is sent is determined
- in an implementation-dependent fashion by the SNMPv2 entity. The
- first two variable bindings in the variable binding list of an
- SNMPv2-Trap-PDU are sysUpTime.0 [9] and snmpTrapOID.0 [9]
- respectively. If the OBJECTS clause is present in the invocation of
- the corresponding NOTIFICATION-TYPE macro, then each corresponding
- variable, as instantiated by this notification, is copied, in order,
- to the variable-bindings field. If any additional variables are
- being included (at the option of the generating SNMPv2 entity), then
- each is copied to the variable-bindings field.
-
-4.2.7. The InformRequest-PDU
-
- An InformRequest-PDU is generated and transmitted at the request of
- an application in a SNMPv2 entity acting in a manager role, that
- wishes to notify another application (in a SNMPv2 entity also acting
- in a manager role) of information in a MIB view which is remote to
- the receiving application.
-
- The destination(s) to which an InformRequest-PDU is sent is specified
- by the requesting application. The first two variable bindings in
-
-
-
-SNMPv2 Working Group Standards Track [Page 21]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- the variable binding list of an InformRequest-PDU are sysUpTime.0 [9]
- and snmpTrapOID.0 [9] respectively. If the OBJECTS clause is present
- in the invocation of the corresponding NOTIFICATION-TYPE macro, then
- each corresponding variable, as instantiated by this notification, is
- copied, in order, to the variable-bindings field.
-
- Upon receipt of an InformRequest-PDU, the receiving SNMPv2 entity
- determines the size of a message encapsulating a Response-PDU with
- the same values in its request-id, error-status, error-index and
- variable-bindings fields as the received InformRequest-PDU. If the
- determined message size is greater than either a local constraint or
- the maximum message size of the originator, then an alternate
- Response-PDU is generated, transmitted to the originator of the
- InformRequest-PDU, and processing of the InformRequest-PDU terminates
- immediately thereafter. This alternate Response-PDU is formatted
- with the same values in its request-id field as the received
- InformRequest-PDU, with the value of its error-status field set to
- `tooBig', the value of its error-index field set to zero, and an
- empty variable-bindings field. This alternate Response-PDU is then
- encapsulated into a message. If the size of the resultant message is
- less than or equal to both a local constraint and the maximum message
- size of the originator, it is transmitted to the originator of the
- InformRequest-PDU. Otherwise, the snmpSilentDrops [9] counter is
- incremented and the resultant message is discarded. Regardless,
- processing of the InformRequest-PDU terminates.
-
- Otherwise, the receiving SNMPv2 entity:
-
-(1) presents its contents to the appropriate SNMPv2 application;
-
-(2) generates a Response-PDU with the same values in its request-id and
- variable-bindings fields as the received InformRequest-PDU, with
- the value of its error-status field is set to `noError' and the
- value of its error-index field is zero; and
-
-(3) transmits the generated Response-PDU to the originator of the
- InformRequest-PDU.
-
-5. Security Considerations
-
- Security issues are not discussed in this memo.
-
-
-
-
-
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 22]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
-6. Editor's Address
-
- Keith McCloghrie
- Cisco Systems, Inc.
- 170 West Tasman Drive
- San Jose, CA 95134-1706
- US
-
- Phone: +1 408 526 5260
- EMail: kzm@cisco.com
-
-7. Acknowledgements
-
- This document is the result of significant work by the four major
- contributors:
-
- Jeffrey D. Case (SNMP Research, case@snmp.com)
- Keith McCloghrie (Cisco Systems, kzm@cisco.com)
- Marshall T. Rose (Dover Beach Consulting, mrose@dbc.mtview.ca.us)
- Steven Waldbusser (International Network Services, stevew@uni.ins.com)
-
- In addition, the contributions of the SNMPv2 Working Group are
- acknowledged. In particular, a special thanks is extended for the
- contributions of:
-
- Alexander I. Alten (Novell)
- Dave Arneson (Cabletron)
- Uri Blumenthal (IBM)
- Doug Book (Chipcom)
- Kim Curran (Bell-Northern Research)
- Jim Galvin (Trusted Information Systems)
- Maria Greene (Ascom Timeplex)
- Iain Hanson (Digital)
- Dave Harrington (Cabletron)
- Nguyen Hien (IBM)
- Jeff Johnson (Cisco Systems)
- Michael Kornegay (Object Quest)
- Deirdre Kostick (AT&T Bell Labs)
- David Levi (SNMP Research)
- Daniel Mahoney (Cabletron)
- Bob Natale (ACE*COMM)
- Brian O'Keefe (Hewlett Packard)
- Andrew Pearson (SNMP Research)
- Dave Perkins (Peer Networks)
- Randy Presuhn (Peer Networks)
- Aleksey Romanov (Quality Quorum)
- Shawn Routhier (Epilogue)
- Jon Saperia (BGS Systems)
-
-
-
-SNMPv2 Working Group Standards Track [Page 23]
-\f
-RFC 1905 Protocol Operations for SNMPv2 January 1996
-
-
- Bob Stewart (Cisco Systems, bstewart@cisco.com), chair
- Kaj Tesink (Bellcore)
- Glenn Waters (Bell-Northern Research)
- Bert Wijnen (IBM)
-
-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] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and
- S. Waldbusser, "Structure of Management Information for Version 2
- of the Simple Network Management Protocol (SNMPv2)", RFC 1902,
- January 1996.
-
-[3] SNMPv2 Working Group, 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.
-
-[4] Kent, C., and J. Mogul, Fragmentation Considered Harmful,
- Proceedings, ACM SIGCOMM '87, Stowe, VT, (August 1987).
-
-[5] SNMPv2 Working Group, 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.
-
-[6] Postel, J., "User Datagram Protocol", STD 6, RFC 768,
- USC/Information Sciences Institute, August 1980.
-
-[7] McCloghrie, K., and M. Rose, Editors, "Management Information
- Base for Network Management of TCP/IP-based internets:
- MIB-II", STD 17, RFC 1213, March 1991.
-
-[8] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and
- S. Waldbusser, "Coexistence between Version 1 and Version 2
- of the Internet-standard Network Management Framework", RFC 1908,
- January 1996.
-
-[9] 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.
-
-
-
-
-
-
-
-SNMPv2 Working Group Standards Track [Page 24]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group T. Berners-Lee
-Request for Comments: 1945 MIT/LCS
-Category: Informational R. Fielding
- UC Irvine
- H. Frystyk
- MIT/LCS
- May 1996
-
-
- Hypertext Transfer Protocol -- HTTP/1.0
-
-Status of This Memo
-
- This memo provides information for the Internet community. This memo
- does not specify an Internet standard of any kind. Distribution of
- this memo is unlimited.
-
-IESG Note:
-
- The IESG has concerns about this protocol, and expects this document
- to be replaced relatively soon by a standards track document.
-
-Abstract
-
- The Hypertext Transfer Protocol (HTTP) is an application-level
- protocol with the lightness and speed necessary for distributed,
- collaborative, hypermedia information systems. It is a generic,
- stateless, object-oriented protocol which can be used for many tasks,
- such as name servers and distributed object management systems,
- through extension of its request methods (commands). A feature of
- HTTP is the typing 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 reflects common usage of
- the protocol referred to as "HTTP/1.0".
-
-Table of Contents
-
- 1. Introduction .............................................. 4
- 1.1 Purpose .............................................. 4
- 1.2 Terminology .......................................... 4
- 1.3 Overall Operation .................................... 6
- 1.4 HTTP and MIME ........................................ 8
- 2. Notational Conventions and Generic Grammar ................ 8
- 2.1 Augmented BNF ........................................ 8
- 2.2 Basic Rules .......................................... 10
- 3. Protocol Parameters ....................................... 12
-
-
-
-Berners-Lee, et al Informational [Page 1]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- 3.1 HTTP Version ......................................... 12
- 3.2 Uniform Resource Identifiers ......................... 14
- 3.2.1 General Syntax ................................ 14
- 3.2.2 http URL ...................................... 15
- 3.3 Date/Time Formats .................................... 15
- 3.4 Character Sets ....................................... 17
- 3.5 Content Codings ...................................... 18
- 3.6 Media Types .......................................... 19
- 3.6.1 Canonicalization and Text Defaults ............ 19
- 3.6.2 Multipart Types ............................... 20
- 3.7 Product Tokens ....................................... 20
- 4. HTTP Message .............................................. 21
- 4.1 Message Types ........................................ 21
- 4.2 Message Headers ...................................... 22
- 4.3 General Header Fields ................................ 23
- 5. Request ................................................... 23
- 5.1 Request-Line ......................................... 23
- 5.1.1 Method ........................................ 24
- 5.1.2 Request-URI ................................... 24
- 5.2 Request Header Fields ................................ 25
- 6. Response .................................................. 25
- 6.1 Status-Line .......................................... 26
- 6.1.1 Status Code and Reason Phrase ................. 26
- 6.2 Response Header Fields ............................... 28
- 7. Entity .................................................... 28
- 7.1 Entity Header Fields ................................. 29
- 7.2 Entity Body .......................................... 29
- 7.2.1 Type .......................................... 29
- 7.2.2 Length ........................................ 30
- 8. Method Definitions ........................................ 30
- 8.1 GET .................................................. 31
- 8.2 HEAD ................................................. 31
- 8.3 POST ................................................. 31
- 9. Status Code Definitions ................................... 32
- 9.1 Informational 1xx .................................... 32
- 9.2 Successful 2xx ....................................... 32
- 9.3 Redirection 3xx ...................................... 34
- 9.4 Client Error 4xx ..................................... 35
- 9.5 Server Error 5xx ..................................... 37
- 10. Header Field Definitions .................................. 37
- 10.1 Allow ............................................... 38
- 10.2 Authorization ....................................... 38
- 10.3 Content-Encoding .................................... 39
- 10.4 Content-Length ...................................... 39
- 10.5 Content-Type ........................................ 40
- 10.6 Date ................................................ 40
- 10.7 Expires ............................................. 41
- 10.8 From ................................................ 42
-
-
-
-Berners-Lee, et al Informational [Page 2]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- 10.9 If-Modified-Since ................................... 42
- 10.10 Last-Modified ....................................... 43
- 10.11 Location ............................................ 44
- 10.12 Pragma .............................................. 44
- 10.13 Referer ............................................. 44
- 10.14 Server .............................................. 45
- 10.15 User-Agent .......................................... 46
- 10.16 WWW-Authenticate .................................... 46
- 11. Access Authentication ..................................... 47
- 11.1 Basic Authentication Scheme ......................... 48
- 12. Security Considerations ................................... 49
- 12.1 Authentication of Clients ........................... 49
- 12.2 Safe Methods ........................................ 49
- 12.3 Abuse of Server Log Information ..................... 50
- 12.4 Transfer of Sensitive Information ................... 50
- 12.5 Attacks Based On File and Path Names ................ 51
- 13. Acknowledgments ........................................... 51
- 14. References ................................................ 52
- 15. Authors' Addresses ........................................ 54
- Appendix A. Internet Media Type message/http ................ 55
- Appendix B. Tolerant Applications ........................... 55
- Appendix C. Relationship to MIME ............................ 56
- C.1 Conversion to Canonical Form ......................... 56
- C.2 Conversion of Date Formats ........................... 57
- C.3 Introduction of Content-Encoding ..................... 57
- C.4 No Content-Transfer-Encoding ......................... 57
- C.5 HTTP Header Fields in Multipart Body-Parts ........... 57
- Appendix D. Additional Features ............................. 57
- D.1 Additional Request Methods ........................... 58
- D.1.1 PUT ........................................... 58
- D.1.2 DELETE ........................................ 58
- D.1.3 LINK .......................................... 58
- D.1.4 UNLINK ........................................ 58
- D.2 Additional Header Field Definitions .................. 58
- D.2.1 Accept ........................................ 58
- D.2.2 Accept-Charset ................................ 59
- D.2.3 Accept-Encoding ............................... 59
- D.2.4 Accept-Language ............................... 59
- D.2.5 Content-Language .............................. 59
- D.2.6 Link .......................................... 59
- D.2.7 MIME-Version .................................. 59
- D.2.8 Retry-After ................................... 60
- D.2.9 Title ......................................... 60
- D.2.10 URI ........................................... 60
-
-
-
-
-
-
-
-Berners-Lee, et al Informational [Page 3]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-1. Introduction
-
-1.1 Purpose
-
- The Hypertext Transfer Protocol (HTTP) is an application-level
- protocol with the lightness and speed necessary for distributed,
- collaborative, hypermedia information systems. HTTP has been in use
- by the World-Wide Web global information initiative since 1990. This
- specification reflects common usage of the protocol referred too as
- "HTTP/1.0". This specification describes the features that seem to be
- consistently implemented in most HTTP/1.0 clients and servers. The
- specification is split into two sections. Those features of HTTP for
- which implementations are usually consistent are described in the
- main body of this document. Those features which have few or
- inconsistent implementations are listed in Appendix D.
-
- Practical information systems require more functionality than simple
- retrieval, including search, front-end update, and annotation. HTTP
- allows an open-ended set of methods to be used to indicate the
- purpose of a request. It builds on the discipline of reference
- provided by the Uniform Resource Identifier (URI) [2], as a location
- (URL) [4] or name (URN) [16], for indicating the resource on which a
- method is to be applied. Messages are passed in a format similar to
- that used by Internet Mail [7] and the Multipurpose Internet Mail
- Extensions (MIME) [5].
-
- HTTP is also used as a generic protocol for communication between
- user agents and proxies/gateways to other Internet protocols, such as
- SMTP [12], NNTP [11], FTP [14], Gopher [1], and WAIS [8], allowing
- basic hypermedia access to resources available from diverse
- applications and simplifying the implementation of user agents.
-
-1.2 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
- application 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.
-
-
-
-
-Berners-Lee, et al Informational [Page 4]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- request
-
- An HTTP request message (as defined in Section 5).
-
- response
-
- An HTTP response message (as defined in Section 6).
-
- resource
-
- A network data object or service which can be identified by a
- URI (Section 3.2).
-
- entity
-
- A particular representation or rendition of a data resource, or
- reply from a service resource, that may be enclosed within a
- request or response message. An entity consists of
- metainformation in the form of entity headers and content in the
- form of an entity body.
-
- client
-
- An application 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.
-
- 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, with
- possible translation, on to other servers. A proxy must
- interpret and, if necessary, rewrite a request message before
-
-
-
-Berners-Lee, et al Informational [Page 5]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- forwarding it. Proxies are often used as client-side portals
- through network firewalls and as helper applications for
- handling requests via protocols not implemented by the user
- agent.
-
- 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.
- Gateways are often used as server-side portals through network
- firewalls and as protocol translators for access to resources
- stored on non-HTTP systems.
-
- tunnel
-
- A tunnel is 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.
- Tunnels are used when a portal is necessary and the intermediary
- cannot, or should not, interpret the relayed communication.
-
- cache
-
- A program's local store of response messages and the subsystem
- that controls its message storage, retrieval, and deletion. A
- cache stores cachable 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 while it is acting as a tunnel.
-
- 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.
-
-1.3 Overall Operation
-
- The HTTP protocol is based on a request/response paradigm. A client
- establishes a connection with a server and 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. The server responds with a
-
-
-
-Berners-Lee, et al Informational [Page 6]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- 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 body content.
-
- 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 parts 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 must pass through four separate connections.
- This distinction is important because some HTTP communication options
- 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
-
-
-
-Berners-Lee, et al Informational [Page 7]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- 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 cachable, and some requests may contain
- modifiers which place special requirements on cache behavior. Some
- HTTP/1.0 applications use heuristics to describe what is or is not a
- "cachable" response, but these rules are not standardized.
-
- On the Internet, HTTP communication generally takes place over TCP/IP
- connections. The default port is TCP 80 [15], 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, and the mapping of the HTTP/1.0 request and
- response structures onto the transport data units of the protocol in
- question is outside the scope of this specification.
-
- Except for experimental applications, current practice requires that
- the connection be established by the client prior to each request and
- closed by the server after sending the response. Both clients and
- servers should be aware that either party may close the connection
- prematurely, due to user action, automated time-out, or program
- failure, and should handle such closing in a predictable fashion. In
- any case, the closing of the connection by either or both parties
- always terminates the current request, regardless of its status.
-
-1.4 HTTP and MIME
-
- HTTP/1.0 uses many of the constructs defined for MIME, as defined in
- RFC 1521 [5]. Appendix C describes the ways in which the context of
- HTTP allows for different use of Internet Media Types than is
- typically found in Internet mail, and gives the rationale for those
- differences.
-
-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 [7]. Implementors will need to be familiar with the
- notation in order to understand this specification. The augmented BNF
- includes the following constructs:
-
-
-
-
-Berners-Lee, et al Informational [Page 8]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- 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 "=". Whitespace 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 ("I") 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)".
-
- 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.
-
-
-
-
-Berners-Lee, et al Informational [Page 9]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- #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 whitespace (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 whitespace (LWS) can be
- included between any two adjacent words (token or
- quoted-string), and between adjacent tokens and delimiters
- (tspecials), without changing the interpretation of a field. At
- least one delimiter (tspecials) must exist between any two
- tokens, since they would otherwise be interpreted as a single
- token. However, applications should attempt to follow "common
- form" when generating HTTP constructs, since there exist some
- implementations that fail to accept anything beyond the common
- forms.
-
-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 [17].
-
- 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">
-
-
-
-Berners-Lee, et al Informational [Page 10]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- 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.0 defines the octet sequence CR LF as the end-of-line marker
- for all protocol elements except the Entity-Body (see Appendix B for
- tolerant applications). The end-of-line marker within an Entity-Body
- is defined by its associated media type, as described in Section 3.6.
-
- CRLF = CR LF
-
- HTTP/1.0 headers may be folded onto multiple lines if each
- continuation line begins with a space or horizontal tab. All linear
- whitespace, including folding, has the same semantics as SP.
-
- LWS = [CRLF] 1*( SP | HT )
-
- However, folding of header lines is not expected by some
- applications, and should not be generated by HTTP/1.0 applications.
-
- 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 octets from character sets other than US-ASCII.
-
- TEXT = <any OCTET except CTLs,
- but including LWS>
-
- Recipients of header field TEXT containing octets outside the US-
- ASCII character set may assume that they represent ISO-8859-1
- characters.
-
- Hexadecimal numeric characters are used in several protocol elements.
-
- HEX = "A" | "B" | "C" | "D" | "E" | "F"
- | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT
-
- Many HTTP/1.0 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.
-
- word = token | quoted-string
-
-
-
-
-Berners-Lee, et al Informational [Page 11]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- token = 1*<any CHAR except CTLs or tspecials>
-
- tspecials = "(" | ")" | "<" | ">" | "@"
- | "," | ";" | ":" | "\" | <">
- | "/" | "[" | "]" | "?" | "="
- | "{" | "}" | SP | HT
-
- Comments may 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 | 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) <"> )
-
- qdtext = <any CHAR except <"> and CTLs,
- but including LWS>
-
- Single-character quoting using the backslash ("\") character is not
- permitted in HTTP/1.0.
-
-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.
-
- The version of an HTTP message is indicated by an HTTP-Version field
- in the first line of the message. If the protocol version is not
- specified, the recipient must assume that the message is in the
-
-
-
-Berners-Lee, et al Informational [Page 12]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- simple HTTP/0.9 format.
-
- HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT
-
- Note that the major and minor numbers should 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 should be ignored by recipients
- and never generated by senders.
-
- This document defines both the 0.9 and 1.0 versions of the HTTP
- protocol. Applications sending Full-Request or Full-Response
- messages, as defined by this specification, must include an HTTP-
- Version of "HTTP/1.0".
-
- HTTP/1.0 servers must:
-
- o recognize the format of the Request-Line for HTTP/0.9 and
- HTTP/1.0 requests;
-
- o understand any valid request in the format of HTTP/0.9 or
- HTTP/1.0;
-
- o respond appropriately with a message in the same protocol
- version used by the client.
-
- HTTP/1.0 clients must:
-
- o recognize the format of the Status-Line for HTTP/1.0 responses;
-
- o understand any valid response in the format of HTTP/0.9 or
- HTTP/1.0.
-
- Proxy and gateway applications must be careful in forwarding requests
- that are received in a format different than that of the
- application's native HTTP version. Since the protocol version
- indicates the protocol capability of the sender, a proxy/gateway must
- never send a message with a version indicator which is greater than
- its native version; if a higher version request is received, the
- proxy/gateway must either downgrade the request version or respond
- with an error. Requests with a version lower than that of the
- application's native format may be upgraded before being forwarded;
- the proxy/gateway's response to that request must follow the server
- requirements listed above.
-
-
-
-
-
-
-
-Berners-Lee, et al Informational [Page 13]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-3.2 Uniform Resource Identifiers
-
- URIs have been known by many names: WWW addresses, Universal Document
- Identifiers, Universal Resource Identifiers [2], and finally the
- combination of Uniform Resource Locators (URL) [4] and Names (URN)
- [16]. As far as HTTP is concerned, Uniform Resource Identifiers are
- simply formatted strings which identify--via name, location, or any
- other characteristic--a network resource.
-
-3.2.1 General Syntax
-
- URIs in HTTP can be represented in absolute form or relative to some
- known base URI [9], 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.
-
- URI = ( absoluteURI | relativeURI ) [ "#" fragment ]
-
- absoluteURI = scheme ":" *( uchar | reserved )
-
- relativeURI = net_path | abs_path | rel_path
-
- net_path = "//" net_loc [ abs_path ]
- abs_path = "/" rel_path
- rel_path = [ path ] [ ";" params ] [ "?" query ]
-
- path = fsegment *( "/" segment )
- fsegment = 1*pchar
- segment = *pchar
-
- params = param *( ";" param )
- param = *( pchar | "/" )
-
- scheme = 1*( ALPHA | DIGIT | "+" | "-" | "." )
- net_loc = *( pchar | ";" | "?" )
- query = *( uchar | reserved )
- fragment = *( uchar | reserved )
-
- pchar = uchar | ":" | "@" | "&" | "=" | "+"
- uchar = unreserved | escape
- unreserved = ALPHA | DIGIT | safe | extra | national
-
- escape = "%" HEX HEX
- reserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+"
- extra = "!" | "*" | "'" | "(" | ")" | ","
- safe = "$" | "-" | "_" | "."
- unsafe = CTL | SP | <"> | "#" | "%" | "<" | ">"
- national = <any OCTET excluding ALPHA, DIGIT,
-
-
-
-Berners-Lee, et al Informational [Page 14]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- reserved, extra, safe, and unsafe>
-
- For definitive information on URL syntax and semantics, see RFC 1738
- [4] and RFC 1808 [9]. The BNF above includes national characters not
- allowed in valid URLs as specified by RFC 1738, since HTTP servers
- are not restricted in the set of unreserved characters allowed to
- represent the rel_path part of addresses, and HTTP proxies may
- receive requests for URIs not defined by RFC 1738.
-
-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 ]
-
- host = <A legal Internet host domain name
- or IP address (in dotted-decimal form),
- as defined by Section 2.1 of RFC 1123>
-
- port = *DIGIT
-
- 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. If the abs_path is not present in the
- URL, it must be given as "/" when used as a Request-URI (Section
- 5.1.2).
-
- Note: Although the HTTP protocol is independent of the transport
- layer protocol, the http URL only identifies resources by their
- TCP location, and thus non-TCP resources must be identified by
- some other URI scheme.
-
- The canonical form for "http" URLs is obtained by converting any
- UPALPHA characters in host to their LOALPHA equivalent (hostnames are
- case-insensitive), eliding the [ ":" port ] if the port is 80, and
- replacing an empty abs_path with "/".
-
-3.3 Date/Time Formats
-
- HTTP/1.0 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
-
-
-
-Berners-Lee, et al Informational [Page 15]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- The first format is preferred as an Internet standard and represents
- a fixed-length subset of that defined by RFC 1123 [6] (an update to
- RFC 822 [7]). The second format is in common use, but is based on the
- obsolete RFC 850 [10] date format and lacks a four-digit year.
- HTTP/1.0 clients and servers that parse the date value should accept
- all three formats, though they must never generate the third
- (asctime) format.
-
- Note: Recipients of date values are encouraged to be robust in
- accepting date values that may have been generated by non-HTTP
- applications, as is sometimes the case when retrieving or posting
- messages via proxies/gateways to SMTP or NNTP.
-
- All HTTP/1.0 date/time stamps must be represented in Universal Time
- (UT), also known as Greenwich Mean Time (GMT), without exception.
- This is indicated in the first two formats by the inclusion of "GMT"
- as the three-letter abbreviation for time zone, and should be assumed
- when reading the asctime format.
-
- 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
-
-
-
-Berners-Lee, et al Informational [Page 16]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- presentation, request logging, etc.
-
-3.4 Character Sets
-
- HTTP uses the same definition of the term "character set" as that
- described for MIME:
-
- 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 encodings, 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 are defined by the IANA Character Set registry
- [15]. However, because that registry does not define a single,
- consistent token for each character set, we define here the preferred
- names for those character sets most likely to be used with HTTP
- entities. These character sets include those registered by RFC 1521
- [5] -- the US-ASCII [17] and ISO-8859 [18] character sets -- and
- other names specifically recommended for use within MIME charset
- parameters.
-
- charset = "US-ASCII"
- | "ISO-8859-1" | "ISO-8859-2" | "ISO-8859-3"
- | "ISO-8859-4" | "ISO-8859-5" | "ISO-8859-6"
- | "ISO-8859-7" | "ISO-8859-8" | "ISO-8859-9"
- | "ISO-2022-JP" | "ISO-2022-JP-2" | "ISO-2022-KR"
- | "UNICODE-1-1" | "UNICODE-1-1-UTF-7" | "UNICODE-1-1-UTF-8"
- | 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 [15] must represent the character set defined
-
-
-
-Berners-Lee, et al Informational [Page 17]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- by that registry. Applications should limit their use of character
- sets to those defined by the IANA registry.
-
- The character set of an entity body should be labelled as the lowest
- common denominator of the character codes used within that body, with
- the exception that no label is preferred over the labels US-ASCII or
- ISO-8859-1.
-
-3.5 Content Codings
-
- Content coding values are used to indicate an encoding transformation
- that has been applied to a resource. Content codings are primarily
- used to allow a document to be compressed or encrypted without losing
- the identity of its underlying media type. Typically, the resource is
- stored in this encoding and only decoded before rendering or
- analogous usage.
-
- content-coding = "x-gzip" | "x-compress" | token
-
- Note: For future compatibility, HTTP/1.0 applications should
- consider "gzip" and "compress" to be equivalent to "x-gzip"
- and "x-compress", respectively.
-
- All content-coding values are case-insensitive. HTTP/1.0 uses
- content-coding values in the Content-Encoding (Section 10.3) header
- field. 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. Note that a single program may be
- capable of decoding multiple content-coding formats. Two values are
- defined by this specification:
-
- x-gzip
- An encoding format produced by the file compression program
- "gzip" (GNU zip) developed by Jean-loup Gailly. This format is
- typically a Lempel-Ziv coding (LZ77) with a 32 bit CRC.
-
- x-compress
- The encoding format produced by the file compression program
- "compress". This format is an adaptive Lempel-Ziv-Welch coding
- (LZW).
-
- Note: Use of program names for the identification of
- encoding formats is not desirable and should be discouraged
- for future encodings. Their use here is representative of
- historical practice, not good design.
-
-
-
-
-
-
-Berners-Lee, et al Informational [Page 18]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-3.6 Media Types
-
- HTTP uses Internet Media Types [13] in the Content-Type header field
- (Section 10.5) in order to provide open and extensible data typing.
-
- media-type = type "/" subtype *( ";" parameter )
- type = token
- subtype = token
-
- Parameters may follow the type/subtype in the form of attribute/value
- pairs.
-
- parameter = attribute "=" value
- attribute = token
- value = token | quoted-string
-
- The type, subtype, and parameter attribute names are case-
- insensitive. Parameter values may or may not be case-sensitive,
- depending on the semantics of the parameter name. LWS must not be
- generated between the type and subtype, nor between an attribute and
- its value. Upon receipt of a media type with an unrecognized
- parameter, a user agent should treat the media type as if the
- unrecognized parameter and its value were not present.
-
- Some older HTTP applications do not recognize media type parameters.
- HTTP/1.0 applications should only use media type parameters when they
- are necessary to define the content of a message.
-
- Media-type values are registered with the Internet Assigned Number
- Authority (IANA [15]). The media type registration process is
- outlined in RFC 1590 [13]. Use of non-registered media types is
- discouraged.
-
-3.6.1 Canonicalization and Text Defaults
-
- Internet media types are registered with a canonical form. In
- general, an Entity-Body transferred via HTTP must be represented in
- the appropriate canonical form prior to its transmission. If the body
- has been encoded with a Content-Encoding, the underlying data should
- be in canonical form prior to being encoded.
-
- Media subtypes of the "text" type use CRLF as the text line break
- when in canonical form. However, HTTP allows the transport of text
- media with plain CR or LF alone representing a line break when used
- consistently within the 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.
-
-
-
-
-Berners-Lee, et al Informational [Page 19]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- In addition, if the text media 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 should not be substituted for CRLF
- within any of the HTTP control structures (such as header fields and
- multipart boundaries).
-
- 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 labelled with an appropriate charset value in
- order to be consistently interpreted by the recipient.
-
- Note: Many current HTTP servers provide data using charsets other
- than "ISO-8859-1" without proper labelling. This situation reduces
- interoperability and is not recommended. To compensate for this,
- some HTTP user agents provide a configuration option to allow the
- user to change the default interpretation of the media type
- character set when no charset parameter is given.
-
-3.6.2 Multipart Types
-
- MIME provides for a number of "multipart" types -- encapsulations of
- several entities within a single message's Entity-Body. The multipart
- types registered by IANA [15] do not have any special meaning for
- HTTP/1.0, though user agents may need to understand each type in
- order to correctly interpret the purpose of each body-part. An HTTP
- user agent should follow the same or similar behavior as a MIME user
- agent does upon receipt of a multipart type. HTTP servers should not
- assume that all HTTP clients are prepared to handle multipart types.
-
- All multipart types share a common syntax 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. Multipart body-parts may contain HTTP
- header fields which are significant to the meaning of that part.
-
-3.7 Product Tokens
-
- Product tokens are used to allow communicating applications to
- identify themselves via a simple product token, with an optional
- slash and version designator. Most fields using product tokens also
- allow subproducts which form a significant part of the application to
-
-
-
-Berners-Lee, et al Informational [Page 20]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- be listed, separated by whitespace. 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
-
- Product tokens should be short and to the point -- use of them for
- advertizing or other non-essential information is explicitly
- forbidden. 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).
-
-4. HTTP Message
-
-4.1 Message Types
-
- HTTP messages consist of requests from client to server and responses
- from server to client.
-
- HTTP-message = Simple-Request ; HTTP/0.9 messages
- | Simple-Response
- | Full-Request ; HTTP/1.0 messages
- | Full-Response
-
- Full-Request and Full-Response use the generic message format of RFC
- 822 [7] for transferring entities. Both messages may include optional
- header fields (also known as "headers") and an entity body. The
- entity body is separated from the headers by a null line (i.e., a
- line with nothing preceding the CRLF).
-
- Full-Request = Request-Line ; Section 5.1
- *( General-Header ; Section 4.3
- | Request-Header ; Section 5.2
- | Entity-Header ) ; Section 7.1
- CRLF
- [ Entity-Body ] ; Section 7.2
-
- Full-Response = Status-Line ; Section 6.1
- *( General-Header ; Section 4.3
- | Response-Header ; Section 6.2
-
-
-
-Berners-Lee, et al Informational [Page 21]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- | Entity-Header ) ; Section 7.1
- CRLF
- [ Entity-Body ] ; Section 7.2
-
- Simple-Request and Simple-Response do not allow the use of any header
- information and are limited to a single request method (GET).
-
- Simple-Request = "GET" SP Request-URI CRLF
-
- Simple-Response = [ Entity-Body ]
-
- Use of the Simple-Request format is discouraged because it prevents
- the server from identifying the media type of the returned entity.
-
-4.2 Message Headers
-
- HTTP header fields, which include General-Header (Section 4.3),
- Request-Header (Section 5.2), 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 [7]. Each header field consists
- of a name followed immediately by a colon (":"), a single space (SP)
- character, and the field value. Field names are case-insensitive.
- Header fields can be extended over multiple lines by preceding each
- extra line with at least one SP or HT, though this is not
- recommended.
-
- HTTP-header = field-name ":" [ field-value ] CRLF
-
- 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, tspecials, and quoted-string>
-
- The order in which header fields are received is not significant.
- However, it is "good practice" to send General-Header fields first,
- followed by Request-Header or Response-Header fields prior to the
- Entity-Header fields.
-
- Multiple HTTP-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.
-
-
-
-
-Berners-Lee, et al Informational [Page 22]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-4.3 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 headers apply only to the message
- being transmitted.
-
- General-Header = Date ; Section 10.6
- | Pragma ; Section 10.12
-
- 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. For
- backwards compatibility with the more limited HTTP/0.9 protocol,
- there are two valid formats for an HTTP request:
-
- Request = Simple-Request | Full-Request
-
- Simple-Request = "GET" SP Request-URI CRLF
-
- Full-Request = Request-Line ; Section 5.1
- *( General-Header ; Section 4.3
- | Request-Header ; Section 5.2
- | Entity-Header ) ; Section 7.1
- CRLF
- [ Entity-Body ] ; Section 7.2
-
- If an HTTP/1.0 server receives a Simple-Request, it must respond with
- an HTTP/0.9 Simple-Response. An HTTP/1.0 client capable of receiving
- a Full-Response should never generate a Simple-Request.
-
-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 are allowed
- except in the final CRLF sequence.
-
- Request-Line = Method SP Request-URI SP HTTP-Version CRLF
-
-
-
-Berners-Lee, et al Informational [Page 23]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- Note that the difference between a Simple-Request and the Request-
- Line of a Full-Request is the presence of the HTTP-Version field and
- the availability of methods other than GET.
-
-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 = "GET" ; Section 8.1
- | "HEAD" ; Section 8.2
- | "POST" ; Section 8.3
- | extension-method
-
- extension-method = token
-
- The list of methods acceptable by a specific resource can change
- dynamically; the client is notified through the return code of the
- response if a method is not allowed on a resource. Servers should
- return the status code 501 (not implemented) if the method is
- unrecognized or not implemented.
-
- The methods commonly used by HTTP/1.0 applications are fully defined
- in Section 8.
-
-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
-
- The two options for Request-URI are dependent on the nature of the
- request.
-
- The absoluteURI form is only allowed when the request is being made
- to a proxy. The proxy is requested to forward the request and return
- the response. If the request is GET or HEAD and a prior response is
- cached, the proxy may use the cached message if it passes any
- restrictions in the Expires header field. Note that the proxy may
- forward the request on to another proxy or directly to the server
- 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.0
-
-
-
-
-Berners-Lee, et al Informational [Page 24]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- The most common form of Request-URI is that used to identify a
- resource on an origin server or gateway. In this case, only the
- absolute path of the URI is transmitted (see Section 3.2.1,
- abs_path). 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 line:
-
- GET /pub/WWW/TheProject.html HTTP/1.0
-
- followed by the remainder of the Full-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 as an encoded string, where some
- characters may be escaped using the "% HEX HEX" encoding defined by
- RFC 1738 [4]. The origin server must decode the Request-URI in order
- to properly interpret the request.
-
-5.2 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
- (procedure) invocation.
-
- Request-Header = Authorization ; Section 10.2
- | From ; Section 10.8
- | If-Modified-Since ; Section 10.9
- | Referer ; Section 10.13
- | User-Agent ; Section 10.15
-
- 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
- in the form of an HTTP response message.
-
- Response = Simple-Response | Full-Response
-
- Simple-Response = [ Entity-Body ]
-
-
-
-
-Berners-Lee, et al Informational [Page 25]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- Full-Response = Status-Line ; Section 6.1
- *( General-Header ; Section 4.3
- | Response-Header ; Section 6.2
- | Entity-Header ) ; Section 7.1
- CRLF
- [ Entity-Body ] ; Section 7.2
-
- A Simple-Response should only be sent in response to an HTTP/0.9
- Simple-Request or if the server only supports the more limited
- HTTP/0.9 protocol. If a client sends an HTTP/1.0 Full-Request and
- receives a response that does not begin with a Status-Line, it should
- assume that the response is a Simple-Response and parse it
- accordingly. Note that the Simple-Response consists only of the
- entity body and is terminated by the server closing the connection.
-
-6.1 Status-Line
-
- The first line of a Full-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
-
- Since a status line always begins with the protocol version and
- status code
-
- "HTTP/" 1*DIGIT "." 1*DIGIT SP 3DIGIT SP
-
- (e.g., "HTTP/1.0 200 "), the presence of that expression is
- sufficient to differentiate a Full-Response from a Simple-Response.
- Although the Simple-Response format may allow such an expression to
- occur at the beginning of an entity body, and thus cause a
- misinterpretation of the message if it was given in response to a
- Full-Request, most HTTP/0.9 servers are limited to responses of type
- "text/html" and therefore would never generate such a response.
-
-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. 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.
-
-
-
-
-
-
-Berners-Lee, et al Informational [Page 26]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- 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:
-
- o 1xx: Informational - Not used, but reserved for future use
-
- o 2xx: Success - The action was successfully received,
- understood, and accepted.
-
- o 3xx: Redirection - Further action must be taken in order to
- complete the request
-
- o 4xx: Client Error - The request contains bad syntax or cannot
- be fulfilled
-
- o 5xx: Server Error - The server failed to fulfill an apparently
- valid request
-
- The individual values of the numeric status codes defined for
- HTTP/1.0, and an example set of corresponding Reason-Phrase's, are
- presented below. The reason phrases listed here are only recommended
- -- they may be replaced by local equivalents without affecting the
- protocol. These codes are fully defined in Section 9.
-
- Status-Code = "200" ; OK
- | "201" ; Created
- | "202" ; Accepted
- | "204" ; No Content
- | "301" ; Moved Permanently
- | "302" ; Moved Temporarily
- | "304" ; Not Modified
- | "400" ; Bad Request
- | "401" ; Unauthorized
- | "403" ; Forbidden
- | "404" ; Not Found
- | "500" ; Internal Server Error
- | "501" ; Not Implemented
- | "502" ; Bad Gateway
- | "503" ; Service Unavailable
- | extension-code
-
- extension-code = 3DIGIT
-
- Reason-Phrase = *<TEXT, excluding CR, LF>
-
- HTTP status codes are extensible, but the above codes are the only
- ones generally recognized in current practice. HTTP applications are
- not required to understand the meaning of all registered status
-
-
-
-Berners-Lee, et al Informational [Page 27]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- 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 = Location ; Section 10.11
- | Server ; Section 10.14
- | WWW-Authenticate ; Section 10.16
-
- 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
-
- Full-Request and Full-Response messages may transfer an entity within
- some requests and responses. An entity consists of Entity-Header
- fields and (usually) an Entity-Body. In this section, both sender and
- recipient refer to either the client or the server, depending on who
- sends and who receives the entity.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al Informational [Page 28]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-7.1 Entity Header Fields
-
- Entity-Header fields define optional metainformation about the
- Entity-Body or, if no body is present, about the resource identified
- by the request.
-
- Entity-Header = Allow ; Section 10.1
- | Content-Encoding ; Section 10.3
- | Content-Length ; Section 10.4
- | Content-Type ; Section 10.5
- | Expires ; Section 10.7
- | Last-Modified ; Section 10.10
- | extension-header
-
- extension-header = HTTP-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 forwarded by proxies.
-
-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 included with a request message only when the
- request method calls for one. The presence of an entity body in a
- request is signaled by the inclusion of a Content-Length header field
- in the request message headers. HTTP/1.0 requests containing an
- entity body must include a valid Content-Length header field.
-
- For response messages, whether or not an entity body is included with
- a message is dependent on both the request method and the response
- code. All responses to the HEAD request method must not include a
- body, even though the presence of entity header fields may lead one
- to believe they do. All 1xx (informational), 204 (no content), and
- 304 (not modified) responses must not include a body. All other
- responses must include an entity body or a Content-Length header
- field defined with a value of zero (0).
-
-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:
-
-
-
-Berners-Lee, et al Informational [Page 29]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- entity-body := Content-Encoding( Content-Type( data ) )
-
- A Content-Type specifies the media type of the underlying data. A
- Content-Encoding may be used to indicate any additional content
- coding applied to the type, usually for the purpose of data
- compression, that is a property of the resource requested. The
- default for the content encoding is none (i.e., the identity
- function).
-
- Any HTTP/1.0 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 header, as
- is the case for Simple-Response messages, the recipient may attempt
- to guess the media type via inspection of its content and/or the name
- extension(s) of the URL used to identify the resource. If the media
- type remains unknown, the recipient should treat it as type
- "application/octet-stream".
-
-7.2.2 Length
-
- When an Entity-Body is included with a message, the length of that
- body may be determined in one of two ways. If a Content-Length header
- field is present, its value in bytes represents the length of the
- Entity-Body. Otherwise, the body length is determined by the closing
- of the connection by the server.
-
- Closing the connection cannot be used to indicate the end of a
- request body, since it leaves no possibility for the server to send
- back a response. Therefore, HTTP/1.0 requests containing an entity
- body must include a valid Content-Length header field. If a request
- contains an entity body and Content-Length is not specified, and the
- server does not recognize or cannot calculate the length from other
- fields, then the server should send a 400 (bad request) response.
-
- Note: Some older servers supply an invalid Content-Length when
- sending a document that contains server-side includes dynamically
- inserted into the data stream. It must be emphasized that this
- will not be tolerated by future versions of HTTP. Unless the
- client knows that it is receiving a response from a compliant
- server, it should not depend on the Content-Length value being
- correct.
-
-8. Method Definitions
-
- The set of common methods for HTTP/1.0 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.
-
-
-
-
-Berners-Lee, et al Informational [Page 30]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-8.1 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 changes to a "conditional GET" if the
- request message includes an If-Modified-Since header field. A
- conditional GET method requests that the identified resource be
- transferred only if it has been modified since the date given by the
- If-Modified-Since header, as described in Section 10.9. The
- conditional GET method is intended to reduce network usage by
- allowing cached entities to be refreshed without requiring multiple
- requests or transferring unnecessary data.
-
-8.2 HEAD
-
- The HEAD method is identical to GET except that the server must not
- return any Entity-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 resource identified
- by the Request-URI without transferring the Entity-Body itself. This
- method is often used for testing hypertext links for validity,
- accessibility, and recent modification.
-
- There is no "conditional HEAD" request analogous to the conditional
- GET. If an If-Modified-Since header field is included with a HEAD
- request, it should be ignored.
-
-8.3 POST
-
- The POST method is used to request that the destination 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:
-
- o Annotation of existing resources;
-
- o Posting a message to a bulletin board, newsgroup, mailing list,
- or similar group of articles;
-
- o Providing a block of data, such as the result of submitting a
- form [3], to a data-handling process;
-
- o Extending a database through an append operation.
-
-
-
-Berners-Lee, et al Informational [Page 31]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- 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.
-
- A successful POST does not require that the entity be created as a
- resource on the origin server or made accessible for future
- reference. That is, 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.
-
- If a resource has been created on the origin server, the response
- should be 201 (created) and contain an entity (preferably of type
- "text/html") which describes the status of the request and refers to
- the new resource.
-
- A valid Content-Length is required on all HTTP/1.0 POST requests. An
- HTTP/1.0 server should respond with a 400 (bad request) message if it
- cannot determine the length of the request message's content.
-
- Applications must not cache responses to a POST request because the
- application has no way of knowing that the server would return an
- equivalent response on some future request.
-
-9. 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.
-
-9.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. HTTP/1.0 does not define any 1xx status
- codes and they are not a valid response to a HTTP/1.0 request.
- However, they may be useful for experimental applications which are
- outside the scope of this specification.
-
-9.2 Successful 2xx
-
- This class of status code indicates that the client's request was
- successfully received, understood, and accepted.
-
-
-
-
-Berners-Lee, et al Informational [Page 32]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- 200 OK
-
- The request has succeeded. The information returned with the
- response is dependent on the method used in the request, as follows:
-
- GET an entity corresponding to the requested resource is sent
- in the response;
-
- HEAD the response must only contain the header information and
- no Entity-Body;
-
- POST an entity describing or containing the result of the action.
-
- 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. The origin server should
- create the resource before using this Status-Code. If the action
- cannot be carried out immediately, the server must include in the
- response body a description of when the resource will be available;
- otherwise, the server should respond with 202 (accepted).
-
- Of the methods defined by this specification, only POST can create a
- resource.
-
- 202 Accepted
-
- The request has been accepted for processing, but the processing
- has not been completed. The request may or may not eventually be
- acted upon, as it may 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.
-
- 204 No Content
-
- The server has fulfilled the request but there is no new
- information to send back. If the client is a user agent, it should
- not change its document view from that which caused the request to
-
-
-
-Berners-Lee, et al Informational [Page 33]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- be generated. This response is primarily intended to allow input
- for scripts or other actions to take place without causing a change
- to the user agent's active document view. The response may include
- new metainformation in the form of entity headers, which should
- apply to the document currently in the user agent's active view.
-
-9.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 subsequent
- request is GET or HEAD. A user agent should never automatically
- redirect a request more than 5 times, since such redirections usually
- indicate an infinite loop.
-
- 300 Multiple Choices
-
- This response code is not directly used by HTTP/1.0 applications,
- but serves as the default for interpreting the 3xx class of
- responses.
-
- The requested resource is available at one or more locations.
- Unless it was a HEAD request, the response should include an entity
- containing a list of resource characteristics and locations from
- which the user or user agent can choose the one most appropriate.
- If the server has a preferred choice, it should include the URL in
- a Location field; user agents may use this field value for
- automatic redirection.
-
- 301 Moved Permanently
-
- The requested resource has been assigned a new permanent URL and
- any future references to this resource should be done using that
- URL. Clients with link editing capabilities should automatically
- relink references to the Request-URI to the new reference returned
- by the server, where possible.
-
- The new URL must be given by the Location field in the response.
- Unless it was a HEAD request, the Entity-Body of the response
- should contain a short note with a hyperlink to the new URL.
-
- If the 301 status code is received in response to a request using
- the POST method, 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.
-
-
-
-
-
-Berners-Lee, et al Informational [Page 34]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- Note: When automatically redirecting a POST request after
- receiving a 301 status code, some existing user agents will
- erroneously change it into a GET request.
-
- 302 Moved Temporarily
-
- The requested resource resides temporarily under a different URL.
- Since the redirection may be altered on occasion, the client should
- continue to use the Request-URI for future requests.
-
- The URL must be given by the Location field in the response. Unless
- it was a HEAD request, the Entity-Body of the response should
- contain a short note with a hyperlink to the new URI(s).
-
- If the 302 status code is received in response to a request using
- the POST method, 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 302 status code, some existing user agents will
- erroneously change it into a GET request.
-
- 304 Not Modified
-
- If the client has performed a conditional GET request and access is
- allowed, but the document has not been modified since the date and
- time specified in the If-Modified-Since field, the server must
- respond with this status code and not send an Entity-Body to the
- client. Header fields contained in the response should only include
- information which is relevant to cache managers or which may have
- changed independently of the entity's Last-Modified date. Examples
- of relevant header fields include: Date, Server, and Expires. A
- cache should update its cached entity to reflect any new field
- values given in the 304 response.
-
-9.4 Client Error 4xx
-
- The 4xx class of status code is intended for cases in which the
- client seems to have erred. If the client has not completed the
- request when a 4xx code is received, it should immediately cease
- sending data to the server. 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.
-
-
-
-
-
-
-Berners-Lee, et al Informational [Page 35]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- Note: If the client is sending data, server implementations on TCP
- should be careful to ensure that the client acknowledges receipt
- of the packet(s) containing the response prior to closing the
- input connection. If the client continues sending data to the
- server after the close, the server's controller 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.
-
- 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.
-
- 401 Unauthorized
-
- The request requires user authentication. The response must include
- a WWW-Authenticate header field (Section 10.16) containing a
- challenge applicable to the requested resource. The client may
- repeat the request with a suitable Authorization header field
- (Section 10.2). 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 may include relevant diagnostic information. HTTP
- access authentication is explained in Section 11.
-
- 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 body. 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.
-
- 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. If the server does not wish to make this information
- available to the client, the status code 403 (forbidden) can be
- used instead.
-
-
-
-Berners-Lee, et al Informational [Page 36]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-9.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. If the client has not completed the request
- when a 5xx code is received, it should immediately cease sending data
- to the server. 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 response codes are applicable to any request method and there
- are no required header fields.
-
- 500 Internal Server Error
-
- The server encountered an unexpected condition which prevented it
- from fulfilling the request.
-
- 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.
-
- 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.
-
- 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.
-
- 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.
-
-10. Header Field Definitions
-
- This section defines the syntax and semantics of all commonly used
- HTTP/1.0 header fields. For general and entity header fields, both
- sender and recipient refer to either the client or the server,
- depending on who sends and who receives the message.
-
-
-
-
-Berners-Lee, et al Informational [Page 37]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-10.1 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. The Allow header field is not permitted in a request
- using the POST method, and thus should be ignored if it is received
- as part of a POST entity.
-
- Allow = "Allow" ":" 1#method
-
- Example of use:
-
- Allow: GET, HEAD
-
- 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.
-
- A proxy must not modify the Allow header field even if it does not
- understand all the methods specified, since the user agent may have
- other means of communicating with the origin server.
-
- The Allow header field does not indicate what methods are implemented
- by the server.
-
-10.2 Authorization
-
- A user agent that wishes to authenticate itself with a server--
- usually, but not necessarily, after receiving a 401 response--may do
- 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 Section 11. If a request
- is authenticated and a realm specified, the same credentials should
- be valid for all other requests within this realm.
-
- Responses to requests containing an Authorization field are not
- cachable.
-
-
-
-
-
-
-
-Berners-Lee, et al Informational [Page 38]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-10.3 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
- coding has been applied to the resource, and thus what decoding
- mechanism must be applied in order to obtain the media-type
- referenced by the Content-Type header field. The 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" ":" content-coding
-
- Content codings are defined in Section 3.5. An example of its use is
-
- Content-Encoding: x-gzip
-
- The Content-Encoding is a characteristic of the resource identified
- by the Request-URI. Typically, the resource is stored with this
- encoding and is only decoded before rendering or analogous usage.
-
-10.4 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 size of the
- Entity-Body to be transferred, regardless of the media type of the
- entity. A valid Content-Length field value is required on all
- HTTP/1.0 request messages containing an entity body.
-
- Any Content-Length greater than or equal to zero is a valid value.
- Section 7.2.2 describes how to determine the length of a response
- entity body if a Content-Length is not given.
-
- Note: 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 used whenever the entity's length can be
- determined prior to being transferred.
-
-
-
-
-Berners-Lee, et al Informational [Page 39]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-10.5 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.6. An example of the field is
-
- Content-Type: text/html
-
- Further discussion of methods for identifying the media type of an
- entity is provided in Section 7.2.1.
-
-10.6 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.
-
- Date = "Date" ":" HTTP-date
-
- An example is
-
- Date: Tue, 15 Nov 1994 08:12:31 GMT
-
- If a message is received via direct connection with the user agent
- (in the case of requests) or the origin server (in the case of
- responses), then the date can be assumed to be the current date at
- the receiving end. However, since the date--as it is believed by the
- origin--is important for evaluating cached responses, origin servers
- should always include a Date header. Clients should only send a Date
- header field in messages that include an entity body, as in the case
- of the POST request, and even then it is optional. A received message
- which does not have a Date header field should be assigned one by the
- recipient if the message will be cached by that recipient or
- gatewayed via a protocol which requires a Date.
-
- In theory, the date should 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.
-
- Note: An earlier version of this document incorrectly specified
- that this field should contain the creation date of the enclosed
- Entity-Body. This has been changed to reflect actual (and proper)
-
-
-
-Berners-Lee, et al Informational [Page 40]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- usage.
-
-10.7 Expires
-
- The Expires entity-header field gives the date/time after which the
- entity should be considered stale. This allows information providers
- to suggest the volatility of the resource, or a date after which the
- information may no longer be valid. Applications must not cache this
- entity beyond the date given. 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. However, information providers that
- know or even suspect that a resource will change by a certain date
- should include an Expires header with that date. The format is an
- absolute date and time as defined by HTTP-date in Section 3.3.
-
- Expires = "Expires" ":" HTTP-date
-
- An example of its use is
-
- Expires: Thu, 01 Dec 1994 16:00:00 GMT
-
- If the date given is equal to or earlier than the value of the Date
- header, the recipient must not cache the enclosed entity. If a
- resource is dynamic by nature, as is the case with many data-
- producing processes, entities from that resource should be given an
- appropriate Expires value which reflects that dynamism.
-
- The Expires field 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.
-
- 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. By default, the Expires field 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.
-
- Note: Applications are encouraged to be tolerant of bad or
- misinformed implementations of the Expires header. A value of zero
- (0) or an invalid date format should be considered equivalent to
- an "expires immediately." Although these values are not legitimate
- for HTTP/1.0, a robust implementation is always desirable.
-
-
-
-
-
-
-Berners-Lee, et al Informational [Page 41]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-10.8 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 [7] (as updated by RFC 1123 [6]):
-
- 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.
-
- Note: The client should not send the From header field without the
- user's approval, as it may 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.
-
-10.9 If-Modified-Since
-
- The If-Modified-Since request-header field is used with the GET
- method to make it conditional: if the requested resource has not been
- modified since the time specified in this field, a copy of the
- resource will not be returned from the server; instead, a 304 (not
- modified) response will be returned without any Entity-Body.
-
- If-Modified-Since = "If-Modified-Since" ":" HTTP-date
-
- An example of the field is:
-
- If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT
-
-
-
-
-
-Berners-Lee, et al Informational [Page 42]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- A conditional GET method requests that the identified resource 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 resource has been modified since the
- If-Modified-Since date, the response is exactly the same as
- for a normal GET.
-
- c) If the resource has not been modified since a valid
- If-Modified-Since date, the server shall 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.
-
-10.10 Last-Modified
-
- The Last-Modified entity-header field indicates the date and time at
- which the sender believes the resource was last modified. The exact
- semantics of this field are defined in terms of how the recipient
- should interpret it: if the recipient has a copy of this resource
- which is older than the date given by the Last-Modified field, that
- copy should be considered stale.
-
- Last-Modified = "Last-Modified" ":" HTTP-date
-
- 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 sender 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 timestamp 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
-
-
-
-Berners-Lee, et al Informational [Page 43]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- future, the server must replace that date with the message
- origination date.
-
-10.11 Location
-
- The Location response-header field defines the exact location of the
- resource that was identified by the Request-URI. For 3xx responses,
- the location must indicate the server's preferred URL for automatic
- redirection to the resource. Only one absolute URL is allowed.
-
- Location = "Location" ":" absoluteURI
-
- An example is
-
- Location: http://www.w3.org/hypertext/WWW/NewLocation.html
-
-10.12 Pragma
-
- The Pragma general-header field is used to include implementation-
- specific directives that may 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 [ "=" word ]
-
- 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 allows a
- client to insist upon receiving an authoritative response to its
- request. It also allows a client to refresh a cached copy which is
- known to be corrupted or stale.
-
- Pragma directives must be passed through by a proxy or gateway
- application, regardless of their significance to that application,
- since the directives may 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.
-
-10.13 Referer
-
- The Referer 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. This allows a server to generate lists
-
-
-
-Berners-Lee, et al Informational [Page 44]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- 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
-
- If a partial URI is given, it should be interpreted relative to the
- Request-URI. The URI must not include a fragment.
-
- Note: Because the source of a link may be private information or
- may 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.
-
-10.14 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.7) and comments
- identifying the server and any significant subproducts. By
- convention, 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 add its data to the product list.
-
- Note: Revealing the specific software version of the server may
- 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.
-
-
-
-
-
-Berners-Lee, et al Informational [Page 45]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- Note: Some existing servers fail to restrict themselves to the
- product token syntax within the Server field.
-
-10.15 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. Although it is not required, user agents should
- include this field with requests. The field can contain multiple
- product tokens (Section 3.7) 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
-
- Note: Some current proxy applications append their product
- information to the list in the User-Agent field. This is not
- recommended, since it makes machine interpretation of these
- fields ambiguous.
-
- Note: Some existing clients fail to restrict themselves to
- the product token syntax within the User-Agent field.
-
-10.16 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 Section 11.
- User agents must take special care in parsing the WWW-Authenticate
- 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.
-
-
-
-
-
-
-Berners-Lee, et al Informational [Page 46]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-11. Access Authentication
-
- HTTP provides a simple challenge-response authentication mechanism
- which 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 "=" 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.
-
- challenge = auth-scheme 1*SP realm *( "," auth-param )
-
- realm = "realm" "=" realm-value
- realm-value = quoted-string
-
- The realm attribute (case-insensitive) is required for all
- authentication schemes which issue a challenge. The realm value
- (case-sensitive), in combination with the canonical root URL 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.
-
- A user agent that wishes to authenticate itself with a server--
- usually, but not necessarily, after receiving a 401 response--may do
- so by including an Authorization 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.
-
- credentials = basic-credentials
- | ( auth-scheme #auth-param )
-
- The domain over which credentials can be automatically applied by a
- user agent is determined by the protection space. 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
-
-
-
-Berners-Lee, et al Informational [Page 47]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- 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 server does not wish to accept the credentials sent with a
- request, it should return a 403 (forbidden) response.
-
- 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. That is, they must forward the WWW-Authenticate and
- Authorization headers untouched, and must not cache the response to a
- request containing Authorization. HTTP/1.0 does not provide a means
- for a client to be authenticated with a proxy.
-
-11.1 Basic Authentication Scheme
-
- The "basic" authentication scheme is based on the model that the user
- agent 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 authorize 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.
-
- Upon receipt of an unauthorized request for a URI within the
- protection space, the server should 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.
-
- To receive authorization, the client sends the user-ID and password,
- separated by a single colon (":") character, within a base64 [5]
- encoded string in the credentials.
-
- basic-credentials = "Basic" SP basic-cookie
-
- basic-cookie = <base64 [5] encoding of userid-password,
- except not limited to 76 char/line>
-
-
-
-
-Berners-Lee, et al Informational [Page 48]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- userid-password = [ token ] ":" *TEXT
-
- If the user agent wishes to send the user-ID "Aladdin" and password
- "open sesame", it would use the following header field:
-
- Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
-
- The basic authentication scheme is a non-secure method of filtering
- unauthorized access to resources on an HTTP server. It is based on
- the assumption that the connection between the client and the server
- can be regarded as a trusted carrier. As this is not generally true
- on an open network, the basic authentication scheme should be used
- accordingly. In spite of this, clients should implement the scheme in
- order to communicate with servers that use it.
-
-12. Security Considerations
-
- This section is meant to inform application developers, information
- providers, and users of the security limitations in HTTP/1.0 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.
-
-12.1 Authentication of Clients
-
- As mentioned in Section 11.1, the Basic authentication scheme is not
- a secure method of user authentication, nor does it prevent the
- Entity-Body from being transmitted in clear text across the physical
- network used as the carrier. HTTP/1.0 does not prevent additional
- authentication schemes and encryption mechanisms from being employed
- to increase security.
-
-12.2 Safe Methods
-
- The writers of client software 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
- may 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 never have the significance of taking an action
- other than retrieval. These methods should be considered "safe." This
- allows user agents to represent other methods, such as POST, in a
- special way, so that the user is made aware of the fact that a
- possibly unsafe action is being requested.
-
-
-
-
-
-Berners-Lee, et al Informational [Page 49]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- 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.
-
-12.3 Abuse of Server Log Information
-
- A server is in the position to save personal data about a user's
- requests which may identify their reading patterns or subjects of
- interest. This information is clearly confidential in nature and its
- handling may 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.
-
-12.4 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. Three header fields are
- worth special mention in this context: Server, Referer and From.
-
- Revealing the specific software version of the server may 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.
-
- The Referer field 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
- the Referer. Even when the personal information has been removed, the
- Referer field may 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.
-
-
-
-Berners-Lee, et al Informational [Page 50]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-12.5 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.
-
-13. Acknowledgments
-
- This specification makes heavy use of the augmented BNF and generic
- constructs defined by David H. Crocker for RFC 822 [7]. Similarly, it
- reuses many of the definitions provided by Nathaniel Borenstein and
- Ned Freed for MIME [5]. We hope that their inclusion in this
- specification will help reduce past confusion over the relationship
- between HTTP/1.0 and Internet mail message formats.
-
- The HTTP protocol has evolved considerably over the past four 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, 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 aspects of the
- protocol for early versions of this specification.
-
- Paul Hoffman contributed sections regarding the informational status
- of this document and Appendices C and D.
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al Informational [Page 51]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- 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:
-
- Gary Adams Harald Tveit Alvestrand
- Keith Ball Brian Behlendorf
- Paul Burchard Maurizio Codogno
- Mike Cowlishaw Roman Czyborra
- Michael A. Dolan John Franks
- Jim Gettys Marc Hedlund
- Koen Holtman Alex Hopmann
- Bob Jernigan Shel Kaphan
- Martijn Koster Dave Kristol
- Daniel LaLiberte Paul Leach
- Albert Lunde John C. Mallery
- Larry Masinter Mitra
- Jeffrey Mogul Gavin Nicol
- Bill Perry Jeffrey Perry
- Owen Rees Luigi Rizzo
- David Robinson Marc Salomon
- Rich Salz Jim Seidman
- Chuck Shotton Eric W. Sink
- Simon E. Spero Robert S. Thau
- Francois Yergeau Mary Ellen Zurko
- Jean-Philippe Martin-Flatin
-
-14. References
-
- [1] 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,
- University of Minnesota, March 1993.
-
- [2] 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, CERN, June 1994.
-
- [3] Berners-Lee, T., and D. Connolly, "Hypertext Markup Language -
- 2.0", RFC 1866, MIT/W3C, November 1995.
-
- [4] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform
- Resource Locators (URL)", RFC 1738, CERN, Xerox PARC,
- University of Minnesota, December 1994.
-
-
-
-
-
-
-
-Berners-Lee, et al Informational [Page 52]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- [5] Borenstein, N., and N. Freed, "MIME (Multipurpose Internet Mail
- Extensions) Part One: Mechanisms for Specifying and Describing
- the Format of Internet Message Bodies", RFC 1521, Bellcore,
- Innosoft, September 1993.
-
- [6] Braden, R., "Requirements for Internet hosts - Application and
- Support", STD 3, RFC 1123, IETF, October 1989.
-
- [7] Crocker, D., "Standard for the Format of ARPA Internet Text
- Messages", STD 11, RFC 822, UDEL, August 1982.
-
- [8] F. Davis, B. Kahle, H. Morris, J. Salem, T. Shen, R. Wang,
- J. Sui, and M. Grinbaum. "WAIS Interface Protocol Prototype
- Functional Specification." (v1.5), Thinking Machines
- Corporation, April 1990.
-
- [9] Fielding, R., "Relative Uniform Resource Locators", RFC 1808,
- UC Irvine, June 1995.
-
- [10] Horton, M., and R. Adams, "Standard for interchange of USENET
- Messages", RFC 1036 (Obsoletes RFC 850), AT&T Bell
- Laboratories, Center for Seismic Studies, December 1987.
-
- [11] Kantor, B., and P. Lapsley, "Network News Transfer Protocol:
- A Proposed Standard for the Stream-Based Transmission of News",
- RFC 977, UC San Diego, UC Berkeley, February 1986.
-
- [12] Postel, J., "Simple Mail Transfer Protocol." STD 10, RFC 821,
- USC/ISI, August 1982.
-
- [13] Postel, J., "Media Type Registration Procedure." RFC 1590,
- USC/ISI, March 1994.
-
- [14] Postel, J., and J. Reynolds, "File Transfer Protocol (FTP)",
- STD 9, RFC 959, USC/ISI, October 1985.
-
- [15] Reynolds, J., and J. Postel, "Assigned Numbers", STD 2, RFC
- 1700, USC/ISI, October 1994.
-
- [16] Sollins, K., and L. Masinter, "Functional Requirements for
- Uniform Resource Names", RFC 1737, MIT/LCS, Xerox Corporation,
- December 1994.
-
- [17] US-ASCII. Coded Character Set - 7-Bit American Standard Code
- for Information Interchange. Standard ANSI X3.4-1986, ANSI,
- 1986.
-
-
-
-
-
-Berners-Lee, et al Informational [Page 53]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- [18] 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.
-
-15. Authors' Addresses
-
- Tim Berners-Lee
- Director, W3 Consortium
- MIT Laboratory for Computer Science
- 545 Technology Square
- Cambridge, MA 02139, U.S.A.
-
- Fax: +1 (617) 258 8682
- EMail: timbl@w3.org
-
-
- Roy T. Fielding
- Department of Information and Computer Science
- University of California
- Irvine, CA 92717-3425, U.S.A.
-
- Fax: +1 (714) 824-4056
- EMail: fielding@ics.uci.edu
-
-
- Henrik Frystyk Nielsen
- W3 Consortium
- MIT Laboratory for Computer Science
- 545 Technology Square
- Cambridge, MA 02139, U.S.A.
-
- Fax: +1 (617) 258 8682
- EMail: frystyk@w3.org
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al Informational [Page 54]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-Appendices
-
- These appendices are provided for informational reasons only -- they
- do not form a part of the HTTP/1.0 specification.
-
-A. Internet Media Type message/http
-
- In addition to defining the HTTP/1.0 protocol, this document serves
- as the specification for the Internet media type "message/http". The
- following is to be registered with IANA [13].
-
- 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.0"). 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
-
-B. Tolerant Applications
-
- Although this document specifies the requirements for the generation
- of HTTP/1.0 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 HTTP-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.
-
-
-
-Berners-Lee, et al Informational [Page 55]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-C. Relationship to MIME
-
- HTTP/1.0 uses many of the constructs defined for Internet Mail (RFC
- 822 [7]) and the Multipurpose Internet Mail Extensions (MIME [5]) to
- allow entities to be transmitted in an open variety of
- representations and with extensible mechanisms. However, RFC 1521
- discusses mail, and HTTP has a few features that are different than
- those described in RFC 1521. 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.
-
- At the time of this writing, it is expected that RFC 1521 will be
- revised. The revisions may include some of the practices found in
- HTTP/1.0 but not in RFC 1521.
-
- This appendix describes specific areas where HTTP differs from RFC
- 1521. 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 may
- be required.
-
-C.1 Conversion to Canonical Form
-
- RFC 1521 requires that an Internet mail entity be converted to
- canonical form prior to being transferred, as described in Appendix G
- of RFC 1521 [5]. Section 3.6.1 of this document describes the forms
- allowed for subtypes of the "text" media type when transmitted over
- HTTP.
-
- RFC 1521 requires that content with a Content-Type of "text"
- represent line breaks as CRLF and forbids the use of CR or LF outside
- of line 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 RFC
- 1521 environment should translate all line breaks within the text
- media types described in Section 3.6.1 of this document to the RFC
- 1521 canonical form of CRLF. Note, however, that this may 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.
-
-
-
-
-
-Berners-Lee, et al Informational [Page 56]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-C.2 Conversion of Date Formats
-
- HTTP/1.0 uses a restricted set of date formats (Section 3.3) 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.0 formats and rewrite the date
- if necessary.
-
-C.3 Introduction of Content-Encoding
-
- RFC 1521 does not include any concept equivalent to HTTP/1.0'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
- an equivalent function as Content-Encoding. However, this parameter
- is not part of RFC 1521.)
-
-C.4 No Content-Transfer-Encoding
-
- HTTP does not use the Content-Transfer-Encoding (CTE) field of RFC
- 1521. 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
- 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.
-
-C.5 HTTP Header Fields in Multipart Body-Parts
-
- In RFC 1521, most header fields in multipart body-parts are generally
- ignored unless the field name begins with "Content-". In HTTP/1.0,
- multipart body-parts may contain any HTTP header fields which are
- significant to the meaning of that part.
-
-D. Additional Features
-
- This appendix documents protocol elements used by some existing HTTP
- implementations, but not consistently and correctly across most
- HTTP/1.0 applications. Implementors should be aware of these
- features, but cannot rely upon their presence in, or interoperability
-
-
-
-Berners-Lee, et al Informational [Page 57]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- with, other HTTP/1.0 applications.
-
-D.1 Additional Request Methods
-
-D.1.1 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.
-
- 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 as data to be processed. That resource may 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 should not apply the request to some other
- resource.
-
-D.1.2 DELETE
-
- The DELETE method requests that the origin server delete the resource
- identified by the Request-URI.
-
-D.1.3 LINK
-
- The LINK method establishes one or more Link relationships between
- the existing resource identified by the Request-URI and other
- existing resources.
-
-D.1.4 UNLINK
-
- The UNLINK method removes one or more Link relationships from the
- existing resource identified by the Request-URI.
-
-D.2 Additional Header Field Definitions
-
-D.2.1 Accept
-
- The Accept request-header field can be used to indicate a list of
- media ranges which are acceptable as a response to the request. The
- asterisk "*" character is used to group media types into ranges, with
- "*/*" indicating all media types and "type/*" indicating all subtypes
-
-
-
-Berners-Lee, et al Informational [Page 58]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
- of that type. The set of ranges given by the client should represent
- what types are acceptable given the context of the request.
-
-D.2.2 Accept-Charset
-
- The Accept-Charset request-header field can be used to indicate a
- list of preferred character sets other than the default US-ASCII and
- ISO-8859-1. 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.
-
-D.2.3 Accept-Encoding
-
- The Accept-Encoding request-header field is similar to Accept, but
- restricts the content-coding values which are acceptable in the
- response.
-
-D.2.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.
-
-D.2.5 Content-Language
-
- The Content-Language entity-header field describes the natural
- language(s) of the intended audience for the enclosed entity. Note
- that this may not be equivalent to all the languages used within the
- entity.
-
-D.2.6 Link
-
- The Link entity-header field provides a means for describing a
- relationship between the entity and some other resource. An entity
- may include multiple Link values. Links at the metainformation level
- typically indicate relationships like hierarchical structure and
- navigation paths.
-
-D.2.7 MIME-Version
-
- HTTP 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, as defined by RFC
- 1521 [5], should indicate that the message is MIME-conformant.
- Unfortunately, some older HTTP/1.0 servers send it indiscriminately,
- and thus this field should be ignored.
-
-
-
-
-Berners-Lee, et al Informational [Page 59]
-\f
-RFC 1945 HTTP/1.0 May 1996
-
-
-D.2.8 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. 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.
-
-D.2.9 Title
-
- The Title entity-header field indicates the title of the entity.
-
-D.2.10 URI
-
- The URI entity-header field may contain some or all of the Uniform
- Resource Identifiers (Section 3.2) by which the Request-URI resource
- can be identified. There is no guarantee that the resource can be
- accessed using the URI(s) specified.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Berners-Lee, et al Informational [Page 60]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group R. Elz
-Request for Comments: 2181 University of Melbourne
-Updates: 1034, 1035, 1123 R. Bush
-Category: Standards Track RGnet, Inc.
- July 1997
-
-
- Clarifications to the DNS Specification
-
-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.
-
-1. Abstract
-
- This document considers some areas that have been identified as
- problems with the specification of the Domain Name System, and
- proposes remedies for the defects identified. Eight separate issues
- are considered:
-
- + IP packet header address usage from multi-homed servers,
- + TTLs in sets of records with the same name, class, and type,
- + correct handling of zone cuts,
- + three minor issues concerning SOA records and their use,
- + the precise definition of the Time to Live (TTL)
- + Use of the TC (truncated) header bit
- + the issue of what is an authoritative, or canonical, name,
- + and the issue of what makes a valid DNS label.
-
- The first six of these are areas where the correct behaviour has been
- somewhat unclear, we seek to rectify that. The other two are already
- adequately specified, however the specifications seem to be sometimes
- ignored. We seek to reinforce the existing specifications.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Elz & Bush Standards Track [Page 1]
-\f
-RFC 2181 Clarifications to the DNS Specification July 1997
-
-
-
-
-Contents
-
- 1 Abstract ................................................... 1
- 2 Introduction ............................................... 2
- 3 Terminology ................................................ 3
- 4 Server Reply Source Address Selection ...................... 3
- 5 Resource Record Sets ....................................... 4
- 6 Zone Cuts .................................................. 8
- 7 SOA RRs .................................................... 10
- 8 Time to Live (TTL) ......................................... 10
- 9 The TC (truncated) header bit .............................. 11
- 10 Naming issues .............................................. 11
- 11 Name syntax ................................................ 13
- 12 Security Considerations .................................... 14
- 13 References ................................................. 14
- 14 Acknowledgements ........................................... 15
- 15 Authors' Addresses ......................................... 15
-
-
-
-
-2. Introduction
-
- Several problem areas in the Domain Name System specification
- [RFC1034, RFC1035] have been noted through the years [RFC1123]. This
- document addresses several additional problem areas. The issues here
- are independent. Those issues are the question of which source
- address a multi-homed DNS server should use when replying to a query,
- the issue of differing TTLs for DNS records with the same label,
- class and type, and the issue of canonical names, what they are, how
- CNAME records relate, what names are legal in what parts of the DNS,
- and what is the valid syntax of a DNS name.
-
- Clarifications to the DNS specification to avoid these problems are
- made in this memo. A minor ambiguity in RFC1034 concerned with SOA
- records is also corrected, as is one in the definition of the TTL
- (Time To Live) and some possible confusion in use of the TC bit.
-
-
-
-
-
-
-
-
-
-
-
-
-Elz & Bush Standards Track [Page 2]
-\f
-RFC 2181 Clarifications to the DNS Specification July 1997
-
-
-3. Terminology
-
- This memo does not use the oft used expressions MUST, SHOULD, MAY, or
- their negative forms. In some sections it may seem that a
- specification is worded mildly, and hence some may infer that the
- specification is optional. That is not correct. Anywhere that this
- memo suggests that some action should be carried out, or must be
- carried out, or that some behaviour is acceptable, or not, that is to
- be considered as a fundamental aspect of this specification,
- regardless of the specific words used. If some behaviour or action
- is truly optional, that will be clearly specified by the text.
-
-4. Server Reply Source Address Selection
-
- Most, if not all, DNS clients, expect the address from which a reply
- is received to be the same address as that to which the query
- eliciting the reply was sent. This is true for servers acting as
- clients for the purposes of recursive query resolution, as well as
- simple resolver clients. The address, along with the identifier (ID)
- in the reply is used for disambiguating replies, and filtering
- spurious responses. This may, or may not, have been intended when
- the DNS was designed, but is now a fact of life.
-
- Some multi-homed hosts running DNS servers generate a reply using a
- source address that is not the same as the destination address from
- the client's request packet. Such replies will be discarded by the
- client because the source address of the reply does not match that of
- a host to which the client sent the original request. That is, it
- appears to be an unsolicited response.
-
-4.1. UDP Source Address Selection
-
- To avoid these problems, servers when responding to queries using UDP
- must cause the reply to be sent with the source address field in the
- IP header set to the address that was in the destination address
- field of the IP header of the packet containing the query causing the
- response. If this would cause the response to be sent from an IP
- address that is not permitted for this purpose, then the response may
- be sent from any legal IP address allocated to the server. That
- address should be chosen to maximise the possibility that the client
- will be able to use it for further queries. Servers configured in
- such a way that not all their addresses are equally reachable from
- all potential clients need take particular care when responding to
- queries sent to anycast, multicast, or similar, addresses.
-
-
-
-
-
-
-
-Elz & Bush Standards Track [Page 3]
-\f
-RFC 2181 Clarifications to the DNS Specification July 1997
-
-
-4.2. Port Number Selection
-
- Replies to all queries must be directed to the port from which they
- were sent. When queries are received via TCP this is an inherent
- part of the transport protocol. For queries received by UDP the
- server must take note of the source port and use that as the
- destination port in the response. Replies should always be sent from
- the port to which they were directed. Except in extraordinary
- circumstances, this will be the well known port assigned for DNS
- queries [RFC1700].
-
-5. Resource Record Sets
-
- Each DNS Resource Record (RR) has a label, class, type, and data. It
- is meaningless for two records to ever have label, class, type and
- data all equal - servers should suppress such duplicates if
- encountered. It is however possible for most record types to exist
- with the same label, class and type, but with different data. Such a
- group of records is hereby defined to be a Resource Record Set
- (RRSet).
-
-5.1. Sending RRs from an RRSet
-
- A query for a specific (or non-specific) label, class, and type, will
- always return all records in the associated RRSet - whether that be
- one or more RRs. The response must be marked as "truncated" if the
- entire RRSet will not fit in the response.
-
-5.2. TTLs of RRs in an RRSet
-
- Resource Records also have a time to live (TTL). It is possible for
- the RRs in an RRSet to have different TTLs. No uses for this have
- been found that cannot be better accomplished in other ways. This
- can, however, cause partial replies (not marked "truncated") from a
- caching server, where the TTLs for some but not all the RRs in the
- RRSet have expired.
-
- Consequently the use of differing TTLs in an RRSet is hereby
- deprecated, the TTLs of all RRs in an RRSet must be the same.
-
- Should a client receive a response containing RRs from an RRSet with
- differing TTLs, it should treat this as an error. If the RRSet
- concerned is from a non-authoritative source for this data, the
- client should simply ignore the RRSet, and if the values were
- required, seek to acquire them from an authoritative source. Clients
- that are configured to send all queries to one, or more, particular
- servers should treat those servers as authoritative for this purpose.
- Should an authoritative source send such a malformed RRSet, the
-
-
-
-Elz & Bush Standards Track [Page 4]
-\f
-RFC 2181 Clarifications to the DNS Specification July 1997
-
-
- client should treat the RRs for all purposes as if all TTLs in the
- RRSet had been set to the value of the lowest TTL in the RRSet. In
- no case may a server send an RRSet with TTLs not all equal.
-
-5.3. DNSSEC Special Cases
-
- Two of the record types added by DNS Security (DNSSEC) [RFC2065]
- require special attention when considering the formation of Resource
- Record Sets. Those are the SIG and NXT records. It should be noted
- that DNS Security is still very new, and there is, as yet, little
- experience with it. Readers should be prepared for the information
- related to DNSSEC contained in this document to become outdated as
- the DNS Security specification matures.
-
-5.3.1. SIG records and RRSets
-
- A SIG record provides signature (validation) data for another RRSet
- in the DNS. Where a zone has been signed, every RRSet in the zone
- will have had a SIG record associated with it. The data type of the
- RRSet is included in the data of the SIG RR, to indicate with which
- particular RRSet this SIG record is associated. Were the rules above
- applied, whenever a SIG record was included with a response to
- validate that response, the SIG records for all other RRSets
- associated with the appropriate node would also need to be included.
- In some cases, this could be a very large number of records, not
- helped by their being rather large RRs.
-
- Thus, it is specifically permitted for the authority section to
- contain only those SIG RRs with the "type covered" field equal to the
- type field of an answer being returned. However, where SIG records
- are being returned in the answer section, in response to a query for
- SIG records, or a query for all records associated with a name
- (type=ANY) the entire SIG RRSet must be included, as for any other RR
- type.
-
- Servers that receive responses containing SIG records in the
- authority section, or (probably incorrectly) as additional data, must
- understand that the entire RRSet has almost certainly not been
- included. Thus, they must not cache that SIG record in a way that
- would permit it to be returned should a query for SIG records be
- received at that server. RFC2065 actually requires that SIG queries
- be directed only to authoritative servers to avoid the problems that
- could be caused here, and while servers exist that do not understand
- the special properties of SIG records, this will remain necessary.
- However, careful design of SIG record processing in new
- implementations should permit this restriction to be relaxed in the
- future, so resolvers do not need to treat SIG record queries
- specially.
-
-
-
-Elz & Bush Standards Track [Page 5]
-\f
-RFC 2181 Clarifications to the DNS Specification July 1997
-
-
- It has been occasionally stated that a received request for a SIG
- record should be forwarded to an authoritative server, rather than
- being answered from data in the cache. This is not necessary - a
- server that has the knowledge of SIG as a special case for processing
- this way would be better to correctly cache SIG records, taking into
- account their characteristics. Then the server can determine when it
- is safe to reply from the cache, and when the answer is not available
- and the query must be forwarded.
-
-5.3.2. NXT RRs
-
- Next Resource Records (NXT) are even more peculiar. There will only
- ever be one NXT record in a zone for a particular label, so
- superficially, the RRSet problem is trivial. However, at a zone cut,
- both the parent zone, and the child zone (superzone and subzone in
- RFC2065 terminology) will have NXT records for the same name. Those
- two NXT records do not form an RRSet, even where both zones are
- housed at the same server. NXT RRSets always contain just a single
- RR. Where both NXT records are visible, two RRSets exist. However,
- servers are not required to treat this as a special case when
- receiving NXT records in a response. They may elect to notice the
- existence of two different NXT RRSets, and treat that as they would
- two different RRSets of any other type. That is, cache one, and
- ignore the other. Security aware servers will need to correctly
- process the NXT record in the received response though.
-
-5.4. Receiving RRSets
-
- Servers must never merge RRs from a response with RRs in their cache
- to form an RRSet. If a response contains data that would form an
- RRSet with data in a server's cache the server must either ignore the
- RRs in the response, or discard the entire RRSet currently in the
- cache, as appropriate. Consequently the issue of TTLs varying
- between the cache and a response does not cause concern, one will be
- ignored. That is, one of the data sets is always incorrect if the
- data from an answer differs from the data in the cache. The
- challenge for the server is to determine which of the data sets is
- correct, if one is, and retain that, while ignoring the other. Note
- that if a server receives an answer containing an RRSet that is
- identical to that in its cache, with the possible exception of the
- TTL value, it may, optionally, update the TTL in its cache with the
- TTL of the received answer. It should do this if the received answer
- would be considered more authoritative (as discussed in the next
- section) than the previously cached answer.
-
-
-
-
-
-
-
-Elz & Bush Standards Track [Page 6]
-\f
-RFC 2181 Clarifications to the DNS Specification July 1997
-
-
-5.4.1. Ranking data
-
- When considering whether to accept an RRSet in a reply, or retain an
- RRSet already in its cache instead, a server should consider the
- relative likely trustworthiness of the various data. An
- authoritative answer from a reply should replace cached data that had
- been obtained from additional information in an earlier reply.
- However additional information from a reply will be ignored if the
- cache contains data from an authoritative answer or a zone file.
-
- The accuracy of data available is assumed from its source.
- Trustworthiness shall be, in order from most to least:
-
- + Data from a primary zone file, other than glue data,
- + Data from a zone transfer, other than glue,
- + The authoritative data included in the answer section of an
- authoritative reply.
- + Data from the authority section of an authoritative answer,
- + Glue from a primary zone, or glue from a zone transfer,
- + Data from the answer section of a non-authoritative answer, and
- non-authoritative data from the answer section of authoritative
- answers,
- + Additional information from an authoritative answer,
- Data from the authority section of a non-authoritative answer,
- Additional information from non-authoritative answers.
-
- Note that the answer section of an authoritative answer normally
- contains only authoritative data. However when the name sought is an
- alias (see section 10.1.1) only the record describing that alias is
- necessarily authoritative. Clients should assume that other records
- may have come from the server's cache. Where authoritative answers
- are required, the client should query again, using the canonical name
- associated with the alias.
-
- Unauthenticated RRs received and cached from the least trustworthy of
- those groupings, that is data from the additional data section, and
- data from the authority section of a non-authoritative answer, should
- not be cached in such a way that they would ever be returned as
- answers to a received query. They may be returned as additional
- information where appropriate. Ignoring this would allow the
- trustworthiness of relatively untrustworthy data to be increased
- without cause or excuse.
-
- When DNS security [RFC2065] is in use, and an authenticated reply has
- been received and verified, the data thus authenticated shall be
- considered more trustworthy than unauthenticated data of the same
- type. Note that throughout this document, "authoritative" means a
- reply with the AA bit set. DNSSEC uses trusted chains of SIG and KEY
-
-
-
-Elz & Bush Standards Track [Page 7]
-\f
-RFC 2181 Clarifications to the DNS Specification July 1997
-
-
- records to determine the authenticity of data, the AA bit is almost
- irrelevant. However DNSSEC aware servers must still correctly set
- the AA bit in responses to enable correct operation with servers that
- are not security aware (almost all currently).
-
- Note that, glue excluded, it is impossible for data from two
- correctly configured primary zone files, two correctly configured
- secondary zones (data from zone transfers) or data from correctly
- configured primary and secondary zones to ever conflict. Where glue
- for the same name exists in multiple zones, and differs in value, the
- nameserver should select data from a primary zone file in preference
- to secondary, but otherwise may choose any single set of such data.
- Choosing that which appears to come from a source nearer the
- authoritative data source may make sense where that can be
- determined. Choosing primary data over secondary allows the source
- of incorrect glue data to be discovered more readily, when a problem
- with such data exists. Where a server can detect from two zone files
- that one or more are incorrectly configured, so as to create
- conflicts, it should refuse to load the zones determined to be
- erroneous, and issue suitable diagnostics.
-
- "Glue" above includes any record in a zone file that is not properly
- part of that zone, including nameserver records of delegated sub-
- zones (NS records), address records that accompany those NS records
- (A, AAAA, etc), and any other stray data that might appear.
-
-5.5. Sending RRSets (reprise)
-
- A Resource Record Set should only be included once in any DNS reply.
- It may occur in any of the Answer, Authority, or Additional
- Information sections, as required. However it should not be repeated
- in the same, or any other, section, except where explicitly required
- by a specification. For example, an AXFR response requires the SOA
- record (always an RRSet containing a single RR) be both the first and
- last record of the reply. Where duplicates are required this way,
- the TTL transmitted in each case must be the same.
-
-6. Zone Cuts
-
- The DNS tree is divided into "zones", which are collections of
- domains that are treated as a unit for certain management purposes.
- Zones are delimited by "zone cuts". Each zone cut separates a
- "child" zone (below the cut) from a "parent" zone (above the cut).
- The domain name that appears at the top of a zone (just below the cut
- that separates the zone from its parent) is called the zone's
- "origin". The name of the zone is the same as the name of the domain
- at the zone's origin. Each zone comprises that subset of the DNS
- tree that is at or below the zone's origin, and that is above the
-
-
-
-Elz & Bush Standards Track [Page 8]
-\f
-RFC 2181 Clarifications to the DNS Specification July 1997
-
-
- cuts that separate the zone from its children (if any). The
- existence of a zone cut is indicated in the parent zone by the
- existence of NS records specifying the origin of the child zone. A
- child zone does not contain any explicit reference to its parent.
-
-6.1. Zone authority
-
- The authoritative servers for a zone are enumerated in the NS records
- for the origin of the zone, which, along with a Start of Authority
- (SOA) record are the mandatory records in every zone. Such a server
- is authoritative for all resource records in a zone that are not in
- another zone. The NS records that indicate a zone cut are the
- property of the child zone created, as are any other records for the
- origin of that child zone, or any sub-domains of it. A server for a
- zone should not return authoritative answers for queries related to
- names in another zone, which includes the NS, and perhaps A, records
- at a zone cut, unless it also happens to be a server for the other
- zone.
-
- Other than the DNSSEC cases mentioned immediately below, servers
- should ignore data other than NS records, and necessary A records to
- locate the servers listed in the NS records, that may happen to be
- configured in a zone at a zone cut.
-
-6.2. DNSSEC issues
-
- The DNS security mechanisms [RFC2065] complicate this somewhat, as
- some of the new resource record types added are very unusual when
- compared with other DNS RRs. In particular the NXT ("next") RR type
- contains information about which names exist in a zone, and hence
- which do not, and thus must necessarily relate to the zone in which
- it exists. The same domain name may have different NXT records in
- the parent zone and the child zone, and both are valid, and are not
- an RRSet. See also section 5.3.2.
-
- Since NXT records are intended to be automatically generated, rather
- than configured by DNS operators, servers may, but are not required
- to, retain all differing NXT records they receive regardless of the
- rules in section 5.4.
-
- For a secure parent zone to securely indicate that a subzone is
- insecure, DNSSEC requires that a KEY RR indicating that the subzone
- is insecure, and the parent zone's authenticating SIG RR(s) be
- present in the parent zone, as they by definition cannot be in the
- subzone. Where a subzone is secure, the KEY and SIG records will be
- present, and authoritative, in that zone, but should also always be
- present in the parent zone (if secure).
-
-
-
-
-Elz & Bush Standards Track [Page 9]
-\f
-RFC 2181 Clarifications to the DNS Specification July 1997
-
-
- Note that in none of these cases should a server for the parent zone,
- not also being a server for the subzone, set the AA bit in any
- response for a label at a zone cut.
-
-7. SOA RRs
-
- Three minor issues concerning the Start of Zone of Authority (SOA)
- Resource Record need some clarification.
-
-7.1. Placement of SOA RRs in authoritative answers
-
- RFC1034, in section 3.7, indicates that the authority section of an
- authoritative answer may contain the SOA record for the zone from
- which the answer was obtained. When discussing negative caching,
- RFC1034 section 4.3.4 refers to this technique but mentions the
- additional section of the response. The former is correct, as is
- implied by the example shown in section 6.2.5 of RFC1034. SOA
- records, if added, are to be placed in the authority section.
-
-7.2. TTLs on SOA RRs
-
- It may be observed that in section 3.2.1 of RFC1035, which defines
- the format of a Resource Record, that the definition of the TTL field
- contains a throw away line which states that the TTL of an SOA record
- should always be sent as zero to prevent caching. This is mentioned
- nowhere else, and has not generally been implemented.
- Implementations should not assume that SOA records will have a TTL of
- zero, nor are they required to send SOA records with a TTL of zero.
-
-7.3. The SOA.MNAME field
-
- It is quite clear in the specifications, yet seems to have been
- widely ignored, that the MNAME field of the SOA record should contain
- the name of the primary (master) server for the zone identified by
- the SOA. It should not contain the name of the zone itself. That
- information would be useless, as to discover it, one needs to start
- with the domain name of the SOA record - that is the name of the
- zone.
-
-8. Time to Live (TTL)
-
- The definition of values appropriate to the TTL field in STD 13 is
- not as clear as it could be, with respect to how many significant
- bits exist, and whether the value is signed or unsigned. It is
- hereby specified that a TTL value is an unsigned number, with a
- minimum value of 0, and a maximum value of 2147483647. That is, a
- maximum of 2^31 - 1. When transmitted, this value shall be encoded
- in the less significant 31 bits of the 32 bit TTL field, with the
-
-
-
-Elz & Bush Standards Track [Page 10]
-\f
-RFC 2181 Clarifications to the DNS Specification July 1997
-
-
- most significant, or sign, bit set to zero.
-
- Implementations should treat TTL values received with the most
- significant bit set as if the entire value received was zero.
-
- Implementations are always free to place an upper bound on any TTL
- received, and treat any larger values as if they were that upper
- bound. The TTL specifies a maximum time to live, not a mandatory
- time to live.
-
-9. The TC (truncated) header bit
-
- The TC bit should be set in responses only when an RRSet is required
- as a part of the response, but could not be included in its entirety.
- The TC bit should not be set merely because some extra information
- could have been included, but there was insufficient room. This
- includes the results of additional section processing. In such cases
- the entire RRSet that will not fit in the response should be omitted,
- and the reply sent as is, with the TC bit clear. If the recipient of
- the reply needs the omitted data, it can construct a query for that
- data and send that separately.
-
- Where TC is set, the partial RRSet that would not completely fit may
- be left in the response. When a DNS client receives a reply with TC
- set, it should ignore that response, and query again, using a
- mechanism, such as a TCP connection, that will permit larger replies.
-
-10. Naming issues
-
- It has sometimes been inferred from some sections of the DNS
- specification [RFC1034, RFC1035] that a host, or perhaps an interface
- of a host, is permitted exactly one authoritative, or official, name,
- called the canonical name. There is no such requirement in the DNS.
-
-10.1. CNAME resource records
-
- The DNS CNAME ("canonical name") record exists to provide the
- canonical name associated with an alias name. There may be only one
- such canonical name for any one alias. That name should generally be
- a name that exists elsewhere in the DNS, though there are some rare
- applications for aliases with the accompanying canonical name
- undefined in the DNS. An alias name (label of a CNAME record) may,
- if DNSSEC is in use, have SIG, NXT, and KEY RRs, but may have no
- other data. That is, for any label in the DNS (any domain name)
- exactly one of the following is true:
-
-
-
-
-
-
-Elz & Bush Standards Track [Page 11]
-\f
-RFC 2181 Clarifications to the DNS Specification July 1997
-
-
- + one CNAME record exists, optionally accompanied by SIG, NXT, and
- KEY RRs,
- + one or more records exist, none being CNAME records,
- + the name exists, but has no associated RRs of any type,
- + the name does not exist at all.
-
-10.1.1. CNAME terminology
-
- It has been traditional to refer to the label of a CNAME record as "a
- CNAME". This is unfortunate, as "CNAME" is an abbreviation of
- "canonical name", and the label of a CNAME record is most certainly
- not a canonical name. It is, however, an entrenched usage. Care
- must therefore be taken to be very clear whether the label, or the
- value (the canonical name) of a CNAME resource record is intended.
- In this document, the label of a CNAME resource record will always be
- referred to as an alias.
-
-10.2. PTR records
-
- Confusion about canonical names has lead to a belief that a PTR
- record should have exactly one RR in its RRSet. This is incorrect,
- the relevant section of RFC1034 (section 3.6.2) indicates that the
- value of a PTR record should be a canonical name. That is, it should
- not be an alias. There is no implication in that section that only
- one PTR record is permitted for a name. No such restriction should
- be inferred.
-
- Note that while the value of a PTR record must not be an alias, there
- is no requirement that the process of resolving a PTR record not
- encounter any aliases. The label that is being looked up for a PTR
- value might have a CNAME record. That is, it might be an alias. The
- value of that CNAME RR, if not another alias, which it should not be,
- will give the location where the PTR record is found. That record
- gives the result of the PTR type lookup. This final result, the
- value of the PTR RR, is the label which must not be an alias.
-
-10.3. MX and NS records
-
- The domain name used as the value of a NS resource record, or part of
- the value of a MX resource record must not be an alias. Not only is
- the specification clear on this point, but using an alias in either
- of these positions neither works as well as might be hoped, nor well
- fulfills the ambition that may have led to this approach. This
- domain name must have as its value one or more address records.
- Currently those will be A records, however in the future other record
- types giving addressing information may be acceptable. It can also
- have other RRs, but never a CNAME RR.
-
-
-
-
-Elz & Bush Standards Track [Page 12]
-\f
-RFC 2181 Clarifications to the DNS Specification July 1997
-
-
- Searching for either NS or MX records causes "additional section
- processing" in which address records associated with the value of the
- record sought are appended to the answer. This helps avoid needless
- extra queries that are easily anticipated when the first was made.
-
- Additional section processing does not include CNAME records, let
- alone the address records that may be associated with the canonical
- name derived from the alias. Thus, if an alias is used as the value
- of an NS or MX record, no address will be returned with the NS or MX
- value. This can cause extra queries, and extra network burden, on
- every query. It is trivial for the DNS administrator to avoid this
- by resolving the alias and placing the canonical name directly in the
- affected record just once when it is updated or installed. In some
- particular hard cases the lack of the additional section address
- records in the results of a NS lookup can cause the request to fail.
-
-11. Name syntax
-
- Occasionally it is assumed that the Domain Name System serves only
- the purpose of mapping Internet host names to data, and mapping
- Internet addresses to host names. This is not correct, the DNS is a
- general (if somewhat limited) hierarchical database, and can store
- almost any kind of data, for almost any purpose.
-
- The DNS itself places only one restriction on the particular labels
- that can be used to identify resource records. That one restriction
- relates to the length of the label and the full name. The length of
- any one label is limited to between 1 and 63 octets. A full domain
- name is limited to 255 octets (including the separators). The zero
- length full name is defined as representing the root of the DNS tree,
- and is typically written and displayed as ".". Those restrictions
- aside, any binary string whatever can be used as the label of any
- resource record. Similarly, any binary string can serve as the value
- of any record that includes a domain name as some or all of its value
- (SOA, NS, MX, PTR, CNAME, and any others that may be added).
- Implementations of the DNS protocols must not place any restrictions
- on the labels that can be used. In particular, DNS servers must not
- refuse to serve a zone because it contains labels that might not be
- acceptable to some DNS client programs. A DNS server may be
- configurable to issue warnings when loading, or even to refuse to
- load, a primary zone containing labels that might be considered
- questionable, however this should not happen by default.
-
- Note however, that the various applications that make use of DNS data
- can have restrictions imposed on what particular values are
- acceptable in their environment. For example, that any binary label
- can have an MX record does not imply that any binary name can be used
- as the host part of an e-mail address. Clients of the DNS can impose
-
-
-
-Elz & Bush Standards Track [Page 13]
-\f
-RFC 2181 Clarifications to the DNS Specification July 1997
-
-
- whatever restrictions are appropriate to their circumstances on the
- values they use as keys for DNS lookup requests, and on the values
- returned by the DNS. If the client has such restrictions, it is
- solely responsible for validating the data from the DNS to ensure
- that it conforms before it makes any use of that data.
-
- See also [RFC1123] section 6.1.3.5.
-
-12. Security Considerations
-
- This document does not consider security.
-
- In particular, nothing in section 4 is any way related to, or useful
- for, any security related purposes.
-
- Section 5.4.1 is also not related to security. Security of DNS data
- will be obtained by the Secure DNS [RFC2065], which is mostly
- orthogonal to this memo.
-
- It is not believed that anything in this document adds to any
- security issues that may exist with the DNS, nor does it do anything
- to that will necessarily lessen them. Correct implementation of the
- clarifications in this document might play some small part in
- limiting the spread of non-malicious bad data in the DNS, but only
- DNSSEC can help with deliberate attempts to subvert DNS data.
-
-13. References
-
- [RFC1034] Mockapetris, P., "Domain Names - Concepts and Facilities",
- STD 13, RFC 1034, November 1987.
-
- [RFC1035] Mockapetris, P., "Domain Names - Implementation and
- Specification", STD 13, RFC 1035, November 1987.
-
- [RFC1123] Braden, R., "Requirements for Internet Hosts - application
- and support", STD 3, RFC 1123, January 1989.
-
- [RFC1700] Reynolds, J., Postel, J., "Assigned Numbers",
- STD 2, RFC 1700, October 1994.
-
- [RFC2065] Eastlake, D., Kaufman, C., "Domain Name System Security
- Extensions", RFC 2065, January 1997.
-
-
-
-
-
-
-
-
-
-Elz & Bush Standards Track [Page 14]
-\f
-RFC 2181 Clarifications to the DNS Specification July 1997
-
-
-14. Acknowledgements
-
- This memo arose from discussions in the DNSIND working group of the
- IETF in 1995 and 1996, the members of that working group are largely
- responsible for the ideas captured herein. Particular thanks to
- Donald E. Eastlake, 3rd, and Olafur Gudmundsson, for help with the
- DNSSEC issues in this document, and to John Gilmore for pointing out
- where the clarifications were not necessarily clarifying. Bob Halley
- suggested clarifying the placement of SOA records in authoritative
- answers, and provided the references. Michael Patton, as usual, and
- Mark Andrews, Alan Barrett and Stan Barber provided much assistance
- with many details. Josh Littlefield helped make sure that the
- clarifications didn't cause problems in some irritating corner cases.
-
-15. Authors' Addresses
-
- Robert Elz
- Computer Science
- University of Melbourne
- Parkville, Victoria, 3052
- Australia.
-
- EMail: kre@munnari.OZ.AU
-
-
- Randy Bush
- RGnet, Inc.
- 5147 Crystal Springs Drive NE
- Bainbridge Island, Washington, 98110
- United States.
-
- EMail: randy@psg.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Elz & Bush Standards Track [Page 15]
+++ /dev/null
-
-
-
-
-
-
-Network Working Group D. Wessels
-Request for Comments: 2186 K. Claffy
-Category: Informational National Laboratory for Applied
- Network Research/UCSD
- September 1997
-
- Internet Cache Protocol (ICP), version 2
-
-Status of this Memo
-
- This memo provides information for the Internet community. This memo
- does not specify an Internet standard of any kind. Distribution of
- this memo is unlimited.
-
-Abstract
-
- This document describes version 2 of the Internet Cache Protocol
- (ICPv2) as currently implemented in two World-Wide Web proxy cache
- packages[3,5]. ICP is a lightweight message format used for
- communicating among Web caches. ICP is used to exchange hints about
- the existence of URLs in neighbor caches. Caches exchange ICP
- queries and replies to gather information to use in selecting the
- most appropriate location from which to retrieve an object.
-
- This document describes only the format and fields of ICP messages.
- A companion document (RFC2187) describes the application of ICP to
- Web caches. Several independent caching implementations now use ICP,
- and we consider it important to codify the existing practical uses of
- ICP for those trying to implement, deploy, and extend its use for
- their own purposes.
-
-1. Introduction
-
- ICP is a message format used for communicating between Web caches.
- Although Web caches use HTTP[1] for the transfer of object data,
- caches benefit from a simpler, lighter communication protocol. ICP
- is primarily used in a cache mesh to locate specific Web objects in
- neighboring caches. One cache sends an ICP query to its neighbors.
- The neighbors send back ICP replies indicating a "HIT" or a "MISS."
-
-
-
-
-
-
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 1]
-\f
-RFC 2186 ICP September 1997
-
-
- In current practice, ICP is implemented on top of UDP, but there is
- no requirement that it be limited to UDP. We feel that ICP over UDP
- offers features important to Web caching applications. An ICP
- query/reply exchange needs to occur quickly, typically within a
- second or two. A cache cannot wait longer than that before beginning
- to retrieve an object. Failure to receive a reply message most
- likely means the network path is either congested or broken. In
- either case we would not want to select that neighbor. As an
- indication of immediate network conditions between neighbor caches,
- ICP over a lightweight protocol such as UDP is better than one with
- the overhead of TCP.
-
- In addition to its use as an object location protocol, ICP messages
- can be used for cache selection. Failure to receive a reply from a
- cache may indicate a network or system failure. The ICP reply may
- include information that could assist selection of the most
- appropriate source from which to retrieve an object.
-
- ICP was initially developed by Peter Danzig, et. al. at the
- University of Southern California as a central part of hierarchical
- caching in the Harvest research project[3].
-
-ICP Message Format
-
- The ICP message format consists of a 20-octet fixed header plus a
- variable sized payload (see Figure 1).
-
- NOTE: All fields must be represented in network byte order.
-
- Opcode
- One of the opcodes defined below.
-
- Version
- The ICP protocol version number. At the time of this writing,
- both versions two and three are in use. This document describes
- only version two. The version number field allows for future
- development of this protocol.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 2]
-\f
-RFC 2186 ICP September 1997
-
-
- Message Length
-
- 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
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Opcode | Version | Message Length |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Request Number |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Options |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Option Data |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Sender Host Address |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | |
- | Payload |
- / /
- / /
- | |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- FIGURE 1: ICP message format.
-
- The total length (octets) of the ICP message. ICP messages MUST
- not exceed 16,384 octets in length.
-
- Request Number
- An opaque identifier. When responding to a query, this value must
- be copied into the reply message.
-
- Options
- A 32-bit field of option flags that allows extension of this
- version of the protocol in certain, limited ways. See "ICP Option
- Flags" below.
-
- Option Data
- A four-octet field to support optional features. The following
- ICP features make use of this field:
-
- The ICP_FLAG_SRC_RTT option uses the low 16-bits of Option Data to
- return RTT measurements. The ICP_FLAG_SRC_RTT option is further
- described below.
-
-
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 3]
-\f
-RFC 2186 ICP September 1997
-
-
- Sender Host Address
- The IPv4 address of the host sending the ICP message. This field
- should probably not be trusted over what is provided by getpeer-
- name(), accept(), and recvfrom(). There is some ambiguity over
- the original purpose of this field. In practice it is not used.
-
- Payload
- The contents of the Payload field vary depending on the Opcode,
- but most often it contains a null-terminated URL string.
-
-2. ICP Opcodes
-
- The following table shows currently defined ICP opcodes:
-
- Value Name
- ----- -----------------
- 0 ICP_OP_INVALID
- 1 ICP_OP_QUERY
- 2 ICP_OP_HIT
- 3 ICP_OP_MISS
- 4 ICP_OP_ERR
- 5-9 UNUSED
- 10 ICP_OP_SECHO
- 11 ICP_OP_DECHO
- 12-20 UNUSED
- 21 ICP_OP_MISS_NOFETCH
- 22 ICP_OP_DENIED
- 23 ICP_OP_HIT_OBJ
-
- ICP_OP_INVALID
- A place holder to detect zero-filled or malformed messages. A
- cache must never intentionally send an ICP_OP_INVALID message.
- ICP_OP_ERR should be used instead.
-
- ICP_OP_QUERY
- A query message. NOTE this opcode has a different payload format
- than most of the others. First is the requester's IPv4 address,
- followed by a URL. The Requester Host Address is not that of the
- cache generating the ICP message, but rather the address of the
- caches's client that originated the request. The Requester Host
- Address is often zero filled. An ICP message with an all-zero
- Requester Host Address address should be taken as one where the
- requester address is not specified; it does not indicate a valid
- IPv4 address.
-
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 4]
-\f
-RFC 2186 ICP September 1997
-
-
- ICP_OP_QUERY payload format:
-
- 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
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Requester Host Address |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | |
- / Null-Terminated URL /
- / /
- | |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- In response to an ICP_OP_QUERY, the recipient must return one of:
- ICP_OP_HIT, ICP_OP_MISS, ICP_OP_ERR, ICP_OP_MISS_NOFETCH,
- ICP_OP_DENIED, or ICP_OP_HIT_OBJ.
-
- ICP_OP_SECHO
- Similar to ICP_OP_QUERY, but for use in simulating a query to an
- origin server. When ICP is used to select the closest neighbor,
- the origin server can be included in the algorithm by bouncing an
- ICP_OP_SECHO message off it's echo port. The payload is simply
- the null-terminated URL.
-
- NOTE: the echo server will not interpret the data (i.e. we could
- send it anything). This opcode is used to tell the difference
- between a legitimate query or response, random garbage, and an
- echo response.
-
- ICP_OP_DECHO
- Similar to ICP_OP_QUERY, but for use in simulating a query to a
- cache which does not use ICP. When ICP is used to choose the
- closest neighbor, a non-ICP cache can be included in the algorithm
- by bouncing an ICP_OP_DECHO message off it's echo port. The
- payload is simply the null-terminated URL.
-
- NOTE: one problem with this approach is that while a system's echo
- port may be functioning perfectly, the cache software may not be
- running at all.
-
- One of the following six ICP opcodes are sent in response to an
- ICP_OP_QUERY message. Unless otherwise noted, the payload must be
- the null-terminated URL string. Both the URL string and the Request
- Number field must be exactly the same as from the ICP_OP_QUERY
- message.
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 5]
-\f
-RFC 2186 ICP September 1997
-
-
- ICP_OP_HIT
- An ICP_OP_HIT response indicates that the requested URL exists in
- this cache and that the requester is allowed to retrieve it.
-
- ICP_OP_MISS
- An ICP_OP_MISS response indicates that the requested URL does not
- exist in this cache. The querying cache may still choose to fetch
- the URL from the replying cache.
-
- ICP_OP_ERR
- An ICP_OP_ERR response indicates some kind of error in parsing or
- handling the query message (e.g. invalid URL).
-
- ICP_OP_MISS_NOFETCH
- An ICP_OP_MISS_NOFETCH response indicates that this cache is up,
- but is in a state where it does not want to handle cache misses.
- An example of such a state is during a startup phase where a cache
- might be rebuilding its object store. A cache in such a mode may
- wish to return ICP_OP_HIT for cache hits, but not ICP_OP_MISS for
- misses. ICP_OP_MISS_NOFETCH essentially means "I am up and
- running, but please don't fetch this URL from me now."
-
- Note, ICP_OP_MISS_NOFETCH has a different meaning than
- ICP_OP_MISS. The ICP_OP_MISS reply is an invitation to fetch the
- URL from the replying cache (if their relationship allows it), but
- ICP_OP_MISS_NOFETCH is a request to NOT fetch the URL from the
- replying cache.
-
- ICP_OP_DENIED
- An ICP_OP_DENIED response indicates that the querying site is not
- allowed to retrieve the named object from this cache. Caches and
- proxies may implement complex access controls. This reply must be
- be interpreted to mean "you are not allowed to request this
- particular URL from me at this particular time."
-
- Caches receiving a high percentage of ICP_OP_DENIED replies are
- probably misconfigured. Caches should track percentage of all
- replies which are ICP_OP_DENIED and disable a neighbor which
- exceeds a certain threshold (e.g. 95% of 100 or more queries).
-
- Similarly, a cache should track the percent of ICP_OP_DENIED
- messages that are sent to a given address. If the percent of
- denied messages exceeds a certain threshold (e.g. 95% of 100 or
- more), the cache may choose to ignore all subsequent ICP_OP_QUERY
- messages from that address until some sort of administrative
- intervention occurs.
-
-
-
-
-
-Wessels & Claffy Informational [Page 6]
-\f
-RFC 2186 ICP September 1997
-
-
- ICP_OP_HIT_OBJ
- Just like an ICP_OP_HIT response, but the actual object data has
- been included in this reply message. Many requested objects are
- small enough that it is possible to include them in the query
- response and avoid the need to make a subsequent HTTP request for
- the object.
-
- CAVEAT: ICP_OP_HIT_OBJ has some negative side effects which make
- its use undesirable. It transfers object data without HTTP and
- therefore bypasses the standard HTTP processing, including
- authorization and age validation. Another negative side effect is
- that ICP_OP_HIT_OBJ messages will often be much larger than the
- path MTU, thereby causing fragmentation to occur on the UDP
- packet. For these reasons, use of ICP_OP_HIT_OBJ is NOT
- recommended.
-
- A cache must not send an ICP_OP_HIT_OBJ unless the
- ICP_FLAG_HIT_OBJ flag is set in the query message Options field.
-
- ICP_OP_HIT_OBJ payload format:
-
- 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
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | |
- / Null-Terminated URL /
- / /
- | |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Object Size | |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
- | |
- / Object Data /
- / /
- | |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
-
- The receiving application must check to make sure it actually
- receives Object Size octets of data. If it does not, then it
- should treat the ICP_OP_HIT_OBJ reply as though it were a normal
- ICP_OP_HIT.
-
- NOTE: the Object Size field does not necessarily begin on a 32-bit
- boundary as shown in the diagram above. It begins immediately
- following the NULL byte of the URL string.
-
-
-
-
-
-Wessels & Claffy Informational [Page 7]
-\f
-RFC 2186 ICP September 1997
-
-
- UNRECOGNIZED OPCODES
- ICP messages with unrecognized or unused opcodes should be
- ignored, i.e. no reply generated. The application may choose to
- note the anomalous behaviour in a log file.
-
-3. ICP Option Flags
-
- 0x80000000 ICP_FLAG_HIT_OBJ
- This flag is set in an ICP_OP_QUERY message indicating that it is
- okay to respond with an ICP_OP_HIT_OBJ message if the object data
- will fit in the reply.
-
- 0x40000000 ICP_FLAG_SRC_RTT
- This flag is set in an ICP_OP_QUERY message indicating that the
- requester would like the ICP reply to include the responder's
- measured RTT to the origin server.
-
- Upon receipt of an ICP_OP_QUERY with ICP_FLAG_SRC_RTT bit set, a
- cache should check an internal database of RTT measurements. If
- available, the RTT value MUST be expressed as a 16-bit integer, in
- units of milliseconds. If unavailable, the responder may either
- set the RTT value to zero, or clear the ICP_FLAG_SRC_RTT bit in
- the ICP reply. The ICP reply MUST not be delayed while waiting
- for the RTT measurement to occur.
-
- This flag is set in an ICP reply message (ICP_OP_HIT, ICP_OP_MISS,
- ICP_OP_MISS_NOFETCH, or ICP_OP_HIT_OBJ) to indicate that the low
- 16-bits of the Option Data field contain the measured RTT to the
- host given in the requested URL. If ICP_FLAG_SRC_RTT is clear in
- the query then it MUST also be clear in the reply. If
- ICP_FLAG_SRC_RTT is set in the query, then it may or may not be
- set in the reply.
-
-4. Security Considerations
-
- The security issues relating to ICP are discussed in the companion
- document, RFC2187.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 8]
-\f
-RFC 2186 ICP September 1997
-
-
-5. References
-
- [1] Fielding, R., et. al, "Hypertext Transfer Protocol -- HTTP/1.1",
- RFC 2068, UC Irvine, January 1997.
-
- [2] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform Resource
- Locators (URL)", RFC 1738, CERN, Xerox PARC, University of Minnesota,
- December 1994.
-
- [3] Bowman M., Danzig P., Hardy D., Manber U., Schwartz M., and
- Wessels D., "The Harvest Information Discovery and Access System",
- Internet Research Task Force - Resource Discovery,
- http://harvest.transarc.com/.
-
- [4] Wessels D., Claffy K., "ICP and the Squid Web Cache", National
- Laboratory for Applied Network Research,
- http://www.nlanr.net/~wessels/Papers/icp-squid.ps.gz
-
- [5] Wessels D., "The Squid Internet Object Cache", National
- Laboratory for Applied Network Research,
- http://squid.nlanr.net/Squid/
-
-6. Acknowledgments
-
- The authors wish to thank Paul A Vixie <paul@vix.com> for providing
- excellent feedback on this document.
-
-7. Authors' Addresses
-
- Duane Wessels
- National Laboratory for Applied Network Research
- 10100 Hopkins Drive
- La Jolla, CA 92093
-
- EMail: wessels@nlanr.net
-
-
- K. Claffy
- National Laboratory for Applied Network Research
- 10100 Hopkins Drive
- La Jolla, CA 92093
-
- EMail: kc@nlanr.net
-
-
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 9]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group D. Wessels
-Request for Comments: 2187 K. Claffy
-Category: Informational National Laboratory for Applied
- Network Research/UCSD
- September 1997
-
- Application of Internet Cache Protocol (ICP), version 2
-
-Status of this Memo
-
- This memo provides information for the Internet community. This memo
- does not specify an Internet standard of any kind. Distribution of
- this memo is unlimited.
-
-Abstract
-
- This document describes the application of ICPv2 (Internet Cache
- Protocol version 2, RFC2186) to Web caching. ICPv2 is a lightweight
- message format used for communication among Web caches. Several
- independent caching implementations now use ICP[3,5], making it
- important to codify the existing practical uses of ICP for those
- trying to implement, deploy, and extend its use.
-
- ICP queries and replies refer to the existence of URLs (or objects)
- in neighbor caches. Caches exchange ICP messages and use the
- gathered information to select the most appropriate location from
- which to retrieve an object. A companion document (RFC2186)
- describes the format and syntax of the protocol itself. In this
- document we focus on issues of ICP deployment, efficiency, security,
- and interaction with other aspects of Web traffic behavior.
-
-Table of Contents
-
- 1. Introduction................................................. 2
- 2. Web Cache Hierarchies........................................ 3
- 3. What is the Added Value of ICP?.............................. 5
- 4. Example Configuration of ICP Hierarchy....................... 5
- 4.1. Configuring the `proxy.customer.org' cache................. 6
- 4.2. Configuring the `cache.isp.com' cache...................... 6
- 5. Applying the Protocol........................................ 7
- 5.1. Sending ICP Queries........................................ 8
- 5.2. Receiving ICP Queries and Sending Replies.................. 10
- 5.3. Receiving ICP Replies...................................... 11
- 5.4. ICP Options................................................ 13
- 6. Firewalls.................................................... 14
- 7. Multicast.................................................... 14
- 8. Lessons Learned.............................................. 16
- 8.1. Differences Between ICP and HTTP........................... 16
-
-
-
-Wessels & Claffy Informational [Page 1]
-\f
-RFC 2187 ICP September 1997
-
-
- 8.2. Parents, Siblings, Hits and Misses......................... 16
- 8.3. Different Roles of ICP..................................... 17
- 8.4. Protocol Design Flaws of ICPv2............................. 17
- 9. Security Considerations...................................... 18
- 9.1. Inserting Bogus ICP Queries................................ 19
- 9.2. Inserting Bogus ICP Replies................................ 19
- 9.3. Eavesdropping.............................................. 20
- 9.4. Blocking ICP Messages...................................... 20
- 9.5. Delaying ICP Messages...................................... 20
- 9.6. Denial of Service.......................................... 20
- 9.7. Altering ICP Fields........................................ 21
- 9.8. Summary.................................................... 22
- 10. References................................................... 23
- 11. Acknowledgments.............................................. 24
- 12. Authors' Addresses........................................... 24
-
-1. Introduction
-
- ICP is a lightweight message format used for communicating among Web
- caches. ICP is used to exchange hints about the existence of URLs in
- neighbor caches. Caches exchange ICP queries and replies to gather
- information for use in selecting the most appropriate location from
- which to retrieve an object.
-
- This document describes the implementation of ICP in software. For a
- description of the protocol and message format, please refer to the
- companion document (RFC2186). We avoid making judgments about
- whether or how ICP should be used in particular Web caching
- configurations. ICP may be a "net win" in some situations, and a
- "net loss" in others. We recognize that certain practices described
- in this document are suboptimal. Some of these exist for historical
- reasons. Some aspects have been improved in later versions. Since
- this document only serves to describe current practices, we focus on
- documenting rather than evaluating. However, we do address known
- security problems and other shortcomings.
-
- The remainder of this document is written as follows. We first
- describe Web cache hierarchies, explain motivation for using ICP, and
- demonstrate how to configure its use in cache hierarchies. We then
- provide a step-by-step description of an ICP query-response
- transaction. We then discuss ICP interaction with firewalls, and
- briefly touch on multicasting ICP. We end with lessons with have
- learned during the protocol development and deployement thus far, and
- the canonical security considerations.
-
- ICP was initially developed by Peter Danzig, et. al. at the
- University of Southern California as a central part of hierarchical
- caching in the Harvest research project[3].
-
-
-
-Wessels & Claffy Informational [Page 2]
-\f
-RFC 2187 ICP September 1997
-
-
-2. Web Cache Hierarchies
-
- A single Web cache will reduce the amount of traffic generated by the
- clients behind it. Similarly, a group of Web caches can benefit by
- sharing another cache in much the same way. Researchers on the
- Harvest project envisioned that it would be important to connect Web
- caches hierarchically. In a cache hierarchy (or mesh) one cache
- establishes peering relationships with its neighbor caches. There
- are two types of relationship: parent and sibling. A parent cache is
- essentially one level up in a cache hierarchy. A sibling cache is on
- the same level. The terms "neighbor" and "peer" are used to refer to
- either parents or siblings which are a single "cache-hop" away.
- Figure 1 shows a simple hierarchy configuration.
-
- But what does it mean to be "on the same level" or "one level up?"
- The general flow of document requests is up the hierarchy. When a
- cache does not hold a requested object, it may ask via ICP whether
- any of its neighbor caches has the object. If any of the neighbors
- does have the requested object (i.e., a "neighbor hit"), then the
- cache will request it from them. If none of the neighbors has the
- object (a "neighbor miss"), then the cache must forward the request
- either to a parent, or directly to the origin server. The essential
- difference between a parent and sibling is that a "neighbor hit" may
- be fetched from either one, but a "neighbor miss" may NOT be fetched
- from a sibling. In other words, in a sibling relationship, a cache
- can only ask to retrieve objects that the sibling already has cached,
- whereas the same cache can ask a parent to retrieve any object
- regardless of whether or not it is cached. A parent cache's role is
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 3]
-\f
-RFC 2187 ICP September 1997
-
-
- T H E I N T E R N E T
- ===========================
- | ||
- | ||
- | ||
- | ||
- | +----------------------+
- | | |
- | | PARENT |
- | | CACHE |
- | | |
- | +----------------------+
- | ||
- DIRECT ||
- RETRIEVALS ||
- | ||
- | HITS
- | AND
- | MISSES
- | RESOLVED
- | ||
- | ||
- | ||
- V \/
- +------------------+ +------------------+
- | | | |
- | LOCAL |/--------HITS-------| SIBLING |
- | CACHE |\------RESOLVED-----| CACHE |
- | | | |
- +------------------+ +------------------+
- | | | | |
- | | | | |
- | | | | |
- V V V V V
- ===================
- CACHE CLIENTS
-
- FIGURE 1: A Simple Web cache hierarchy. The local cache can retrieve
- hits from sibling caches, hits and misses from parent caches, and
- some requests directly from origin servers.
-
- to provide "transit" for the request if necessary, and accordingly
- parent caches are ideally located within or on the way to a transit
- Internet service provider (ISP).
-
- Squid and Harvest allow for complex hierarchical configurations. For
- example, one could specify that a given neighbor be used for only a
- certain class of requests, such as URLs from a specific DNS domain.
-
-
-
-Wessels & Claffy Informational [Page 4]
-\f
-RFC 2187 ICP September 1997
-
-
- Additionally, it is possible to treat a neighbor as a sibling for
- some requests and as a parent for others.
-
- The cache hierarchy model described here includes a number of
- features to prevent top-level caches from becoming choke points. One
- is the ability to restrict parents as just described previously (by
- domains). Another optimization is that the cache only forwards
- cachable requests to its neighbors. A large class of Web requests
- are inherently uncachable, including: requests requiring certain
- types of authentication, session-encrypted data, highly personalized
- responses, and certain types of database queries. Lower level caches
- should handle these requests directly rather than burdening parent
- caches.
-
-3. What is the Added Value of ICP?
-
- Although it is possible to maintain cache hierarchies without using
- ICP, the lack of ICP or something similar prohibits the existence of
- sibling meta-communicative relationships, i.e., mechanisms to query
- nearby caches about a given document.
-
- One concern over the use of ICP is the additional delay that an ICP
- query/reply exchange contributes to an HTTP transaction. However, if
- the ICP query can locate the object in a nearby neighbor cache, then
- the ICP delay may be more than offset by the faster delivery of the
- data from the neighbor. In order to minimize ICP delays, the caches
- (as well as the protocol itself) are designed to return ICP requests
- quickly. Indeed, the application does minimal processing of the ICP
- request, most ICP-related delay is due to transmission on the
- network.
-
- ICP also serves to provide an indication of neighbor reachability.
- If ICP replies from a neighbor fail to arrive, then either the
- network path is congested (or down), or the cache application is not
- running on the ICP-queried neighbor machine. In either case, the
- cache should not use this neighbor at this time. Additionally,
- because an idle cache can turn around the replies faster than a busy
- one, all other things being equal, ICP provides some form of load
- balancing.
-
-4. Example Configuration of ICP Hierarchy
-
- Configuring caches within a hierarchy requires establishing peering
- relationships, which currently involves manual configuration at both
- peering endpoints. One cache must indicate that the other is a
- parent or sibling. The other cache will most likely have to add the
- first cache to its access control lists.
-
-
-
-
-Wessels & Claffy Informational [Page 5]
-\f
-RFC 2187 ICP September 1997
-
-
- Below we show some sample configuration lines for a hypothetical
- situation. We have two caches, one operated by an ISP, and another
- operated by a customer. First we describe how the customer would
- configure his cache to peer with the ISP. Second, we describe how
- the ISP would allow the customer access to its cache.
-
-4.1. Configuring the `proxy.customer.org' cache
-
- In Squid, to configure parents and siblings in a hierarchy, a
- `cache_host' directive is entered into the configuration file. The
- format is:
-
- cache_host hostname type http-port icp-port [options]
-
- Where type is either `parent', `sibling', or `multicast'. For our
- example, it would be:
-
- cache_host cache.isp.com parent 8080 3130
-
- This configuration will cause the customer cache to resolve most
- cache misses through the parent (`cgi-bin' and non-GET requests would
- be resolved directly). Utilizing the parent may be undesirable for
- certain servers, such as servers also in the customer.org domain. To
- always handle such local domains directly, the customer would add
- this to his configuration file:
-
- local_domain customer.org
-
- It may also be the case that the customer wants to use the ISP cache
- only for a specific subset of DNS domains. The need to limit
- requests this way is actually more common for higher levels of cache
- hierarchies, but it is illustrated here nonetheless. To limit the
- ISP cache to a subset of DNS domains, the customer would use:
-
- cache_host_domain cache.isp.com com net org
-
- Then, any requests which are NOT in the .com, .net, or .org domains
- would be handled directly.
-
-4.2. Configuring the `cache.isp.com' cache
-
- To configure the query-receiving side of the cache peer
- relationship one uses access lists, similar to those used in routing
- peers. The access lists support a large degree of customization in
- the peering relationship. If there are no access lines present, the
- cache allows the request by default.
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 6]
-\f
-RFC 2187 ICP September 1997
-
-
- Note that the cache.isp.com cache need not explicitly specify the
- customer cache as a peer, nor is the type of relationship encoded
- within the ICP query itself. The access control entries regulate the
- relationships between this cache and its neighbors. For our example,
- the ISP would use:
-
- acl src Customer proxy.customer.org
- http_access allow Customer
- icp_access allow Customer
-
- This defines an access control entry named `Customer' which specifies
- a source IP address of the customer cache machine. The customer
- cache would then be allowed to make any request to both the HTTP and
- ICP ports (including cache misses). This configuration implies that
- the ISP cache is a parent of the customer.
-
- If the ISP wanted to enforce a sibling relationship, it would need to
- deny access to cache misses. This would be done as follows:
-
- miss_access deny Customer
-
- Of course the ISP should also communicate this to the customer, so
- that the customer will change his configuration from parent to
- sibling. Otherwise, if the customer requests an object not in the
- ISP cache, an error message is generated.
-
-5. Applying the Protocol
-
- The following sections describe the ICP implementation in the
- Harvest[3] (research version) and Squid Web cache[5] packages. In
- terms of version numbers, this means version 1.4pl2 for Harvest and
- version 1.1.10 for Squid.
-
- The basic sequence of events in an ICP transaction is as follows:
-
- 1. Local cache receives an HTTP[1] request from a cache client.
-
- 2. The local cache sends ICP queries (section 5.1).
-
- 3. The peer cache(s) receive the queries and send ICP replies
- (section 5.2).
-
- 4. The local cache receives the ICP replies and decides where to
- forward the request (section 5.3).
-
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 7]
-\f
-RFC 2187 ICP September 1997
-
-
-5.1. Sending ICP Queries
-
-5.1.1. Determine whether to use ICP at all
-
- Not every HTTP request requires an ICP query to be sent. Obviously,
- cache hits will not need ICP because the request is satisfied
- immediately. For origin servers very close to the cache, we do not
- want to use any neighbor caches. In Squid and Harvest, the
- administrator specifies what constitutes a `local' server with the
- `local_domain' and `local_ip' configuration options. The cache
- always contacts a local server directly, never querying a peer cache.
-
- There are other classes of requests that the cache (or the
- administrator) may prefer to forward directly to the origin server.
- In Squid and Harvest, one such class includes all non-GET request
- methods. A Squid cache can also be configured to not use peers for
- URLs matching the `hierarchy_stoplist'.
-
- In order for an HTTP request to yield an ICP transaction, it must:
-
- o not be a cache hit
-
- o not be to a local server
-
- o be a GET request, and
-
- o not match the `hierarchy_stoplist' configuration.
-
- We call this a "hierarchical" request. A "non-hierarchical" request
- is one that doesn't generate any ICP traffic. To avoid processing
- requests that are likely to lower cache efficiency, one can configure
- the cache to not consult the hierarchy for URLs that contain certain
- strings (e.g. `cgi_bin').
-
-5.1.2. Determine which peers to query
-
- By default, a cache sends an ICP_OP_QUERY message to each peer,
- unless any one of the following are true:
-
- o Restrictions prevent querying a peer for this request, based on
- the configuration directive `cache_host_domain', which specifies
- a set of DNS domains (from the URLs) for which the peer should
- or should not be queried. In Squid, a more flexible directive
- ('cache_host_acl') supports restrictions on other parts of the
- request (method, port number, source, etc.).
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 8]
-\f
-RFC 2187 ICP September 1997
-
-
- o The peer is a sibling, and the HTTP request includes a "Pragma:
- no-cache" header. This is because the sibling would be asked to
- transit the request, which is not allowed.
-
- o The peer is configured to never be sent ICP queries (i.e. with
- the `no-query' option).
-
- If the determination yields only one queryable ICP peer, and the
- Squid configuration directive `single_parent_bypass' is set, then one
- can bypass waiting for the single ICP response and just send the HTTP
- request directly to the peer cache.
-
- The Squid configuration option `source_ping' configures a Squid cache
- to send a ping to the original source simultaneous with its ICP
- queries, in case the origin is closer than any of the caches.
-
-5.1.3. Calculate the expected number of ICP replies
-
- Harvest and Squid want to maximize the chance to get a HIT reply from
- one of the peers. Therefore, the cache waits for all ICP replies to
- be received. Normally, we expect to receive an ICP reply for each
- query sent, except:
-
- o When the peer is believed to be down. If the peer is down Squid
- and Harvest continue to send it ICP queries, but do not expect
- the peer to reply. When an ICP reply is again received from the
- peer, its status will be changed to up.
-
- The determination of up/down status has varied a little bit as
- the Harvest and Squid software evolved. Both Harvest and Squid
- mark a peer down when it fails to reply to 20 consecutive ICP
- queries. Squid also marks a peer down when a TCP connection
- fails, and up again when a diagnostic TCP connection succeeds.
-
- o When sending to a multicast address. In this case we'll
- probably expect to receive more than one reply, and have no way
- to definitively determine how many to expect. We discuss
- multicast issues in section 7 below.
-
-
-5.1.4. Install timeout event
-
- Because ICP uses UDP as underlying transport, ICP queries and replies
- may sometimes be dropped by the network. The cache installs a
- timeout event in case not all of the expected replies arrive. By
- default Squid and Harvest use a two-second timeout. If object
- retrieval has not commenced when the timeout occurs, a source is
- selected as described in section 5.3.9 below.
-
-
-
-Wessels & Claffy Informational [Page 9]
-\f
-RFC 2187 ICP September 1997
-
-
-5.2. Receiving ICP Queries and Sending Replies
-
- When an ICP_OP_QUERY message is received, the cache examines it and
- decides which reply message is to be sent. It will send one of the
- following reply opcodes, tested for use in the order listed:
-
-5.2.1. ICP_OP_ERR
-
- The URL is extracted from the payload and parsed. If parsing fails,
- an ICP_OP_ERR message is returned.
-
-5.2.2. ICP_OP_DENIED
-
- The access controls are checked. If the peer is not allowed to make
- this request, ICP_OP_DENIED is returned. Squid counts the number of
- ICP_OP_DENIED messages sent to each peer. If more than 95% of more
- than 100 replies have been denied, then no reply is sent at all.
- This prevents misconfigured caches from endlessly sending unnecessary
- ICP messages back and forth.
-
-5.2.3. ICP_OP_HIT
-
- If the cache reaches this point without already matching one of the
- previous opcodes, it means the request is allowed and we must
- determine if it will be HIT or MISS, so we check if the URL exists in
- the local cache. If so, and if the cached entry is fresh for at
- least the next 30 seconds, we can return an ICP_OP_HIT message. The
- stale/fresh determination uses the local refresh (or TTL) rules.
-
- Note that a race condition exists for ICP_OP_HIT replies to sibling
- peers. The ICP_OP_HIT means that a subsequent HTTP request for the
- named URL would result in a cache hit. We assume that the HTTP
- request will come very quickly after the ICP_OP_HIT. However, there
- is a slight chance that the object might be purged from this cache
- before the HTTP request is received. If this happens, and the
- replying peer has applied Squid's `miss_access' configuration then
- the user will receive a very confusing access denied message.
-
-5.2.3.1. ICP_OP_HIT_OBJ
-
- Before returning the ICP_OP_HIT message, we see if we can send an
- ICP_OP_HIT_OBJ message instead. We can use ICP_OP_HIT_OBJ if:
-
- o The ICP_OP_QUERY message had the ICP_FLAG_HIT_OBJ flag set.
-
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 10]
-\f
-RFC 2187 ICP September 1997
-
-
- o The entire object (plus URL) will fit in an ICP message. The
- maximum ICP message size is 16 Kbytes, but an application may
- choose to set a smaller maximum value for ICP_OP_HIT_OBJ
- replies.
-
- Normally ICP replies are sent immediately after the query is
- received, but the ICP_OP_HIT_OBJ message cannot be sent until the
- object data is available to copy into the reply message. For Squid
- and Harvest this means the object must be "swapped in" from disk if
- it is not already in memory. Therefore, on average, an
- ICP_OP_HIT_OBJ reply will have higher latency than ICP_OP_HIT.
-
-5.2.4. ICP_OP_MISS_NOFETCH
-
- At this point we have a cache miss. ICP has two types of miss
- replies. If the cache does not want the peer to request the object
- from it, it sends an ICP_OP_MISS_NOFETCH message.
-
-5.2.5. ICP_OP_MISS
-
- Finally, an ICP_OP_MISS reply is returned as the default. If the
- replying cache is a parent of the querying cache, the ICP_OP_MISS
- indicates an invitation to fetch the URL through the replying cache.
-
-5.3. Receiving ICP Replies
-
- Some ICP replies will be ignored; specifically, when any of the
- following are true:
-
- o The reply message originated from an unknown peer.
-
- o The object named by the URL does not exist.
-
- o The object is already being fetched.
-
-5.3.1. ICP_OP_DENIED
-
- If more than 95% of more than 100 replies from a peer cache have been
- ICP_OP_DENIED, then such a high denial rate most likely indicates a
- configuration error, either locally or at the peer. For this reason,
- no further queries will be sent to the peer for the duration of the
- cache process.
-
-5.3.2. ICP_OP_HIT
-
- Object retrieval commences immediately from the replying peer.
-
-
-
-
-
-Wessels & Claffy Informational [Page 11]
-\f
-RFC 2187 ICP September 1997
-
-
-5.3.3. ICP_OP_HIT_OBJ
-
- The object data is extracted from the ICP message and the retrieval
- is complete. If there is some problem with the ICP_OP_HIT_OBJ
- message (e.g. missing data) the reply will be treated like a standard
- ICP_OP_HIT.
-
-5.3.4. ICP_OP_SECHO
-
- Object retrieval commences immediately from the origin server because
- the ICP_OP_SECHO reply arrived prior to any ICP_OP_HIT's. If an
- ICP_OP_HIT had arrived prior, this ICP_OP_SECHO reply would be
- ignored because the retrieval has already started.
-
-5.3.5. ICP_OP_DECHO
-
- An ICP_OP_DECHO reply is handled like an ICP_OP_MISS. Non-ICP peers
- must always be configured as parents; a non-ICP sibling makes no
- sense. One serious problem with the ICP_OP_DECHO feature is that
- since it bounces messages off the peer's UDP echo port, it does not
- indicate that the peer cache is actually running -- only that network
- connectivity exists between the pair.
-
-5.3.6. ICP_OP_MISS
-
- If the peer is a sibling, the ICP_OP_MISS reply is ignored.
- Otherwise, the peer may be "remembered" for future use in case no HIT
- replies are received later (section 5.3.9).
-
- Harvest and Squid remember the first parent to return an ICP_OP_MISS
- message. With Squid, the parents may be weighted so that the "first
- parent to miss" may not actually be the first reply received. We
- call this the FIRST_PARENT_MISS. Remember that sibling misses are
- entirely ignored, we only care about misses from parents. The parent
- miss RTT's can be weighted because sometimes the closest parent is
- not the one people want to use.
-
- Also, recent versions of Squid may remember the parent with the
- lowest RTT to the origin server, using the ICP_FLAG_SRC_RTT option.
- We call this the CLOSEST_PARENT_MISS.
-
-5.3.7. ICP_OP_MISS_NOFETCH
-
- This reply is essentially ignored. A cache must not forward a
- request to a peer that returns ICP_OP_MISS_NOFETCH.
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 12]
-\f
-RFC 2187 ICP September 1997
-
-
-5.3.8. ICP_OP_ERR
-
- Silently ignored.
-
-5.3.9. When all peers MISS.
-
- For ICP_OP_HIT and ICP_OP_SECHO the request is forwarded immediately.
- For ICP_OP_HIT_OBJ there is no need to forward the request. For all
- other reply opcodes, we wait until the expected number of replies
- have been received. When we have all of the expected replies, or
- when the query timeout occurs, it is time to forward the request.
-
- Since MISS replies were received from all peers, we must either
- select a parent cache or the origin server.
-
- o If the peers are using the ICP_FLAG_SRC_RTT feature, we forward
- the request to the peer with the lowest RTT to the origin
- server. If the local cache is also measuring RTT's to origin
- servers, and is closer than any of the parents, the request is
- forwarded directly to the origin server.
-
- o If there is a FIRST_PARENT_MISS parent available, the request
- will be forwarded there.
-
- o If the ICP query/reply exchange did not produce any appropriate
- parents, the request will be sent directly to the origin server
- (unless firewall restrictions prevent it).
-
-5.4. ICP Options
-
- The following options were added to Squid to support some new
- features while maintaining backward compatibility with the Harvest
- implementation.
-
-5.4.1. ICP_FLAG_HIT_OBJ
-
- This flag is off by default and will be set in an ICP_OP_QUERY
- message only if these three criteria are met:
-
- o It is enabled in the cache configuration file with `udp_hit_obj
- on'.
-
- o The peer must be using ICP version 2.
-
- o The HTTP request must not include the "Pragma: no-cache" header.
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 13]
-\f
-RFC 2187 ICP September 1997
-
-
-5.4.2. ICP_FLAG_SRC_RTT
-
- This flag is off by default and will be set in an ICP_OP_QUERY
- message only if these two criteria are met:
-
- o It is enabled in the cache configuration file with `query_icmp
- on'.
-
- o The peer must be using ICP version 2.
-
-
-6. Firewalls
-
- Operating a Web cache behind a firewall or in a private network poses
- some interesting problems. The hard part is figuring out whether the
- cache is able to connect to the origin server. Harvest and Squid
- provide an `inside_firewall' configuration directive to list DNS
- domains on the near side of a firewall. Everything else is assumed
- to be on the far side of a firewall. Squid also has a `firewall_ip'
- directive so that inside hosts can be specified by IP addresses as
- well.
-
- In a simple configuration, a Squid cache behind a firewall will have
- only one parent cache (which is on the firewall itself). In this
- case, Squid must use that parent for all servers beyond the firewall,
- so there is no need to utilize ICP.
-
- In a more complex configuration, there may be a number of peer caches
- also behind the firewall. Here, ICP may be used to check for cache
- hits in the peers. Occasionally, when ICP is being used, there may
- not be any replies received. If the cache were not behind a
- firewall, the request would be forwarded directly to the origin
- server. But in this situation, the cache must pick a parent cache,
- either randomly or due to configuration information. For example,
- Squid allows a parent cache to be designated as a default choice when
- no others are available.
-
-7. Multicast
-
- For efficient distribution, a cache may deliver ICP queries to a
- multicast address, and neighbor caches may join the multicast group
- to receive such queries.
-
- Current practice is that caches send ICP replies only to unicast
- addresses, for several reasons:
-
- o Multicasting ICP replies would not reduce the number of packets
- sent.
-
-
-
-Wessels & Claffy Informational [Page 14]
-\f
-RFC 2187 ICP September 1997
-
-
- o It prevents other group members from receiving unexpected
- replies.
-
- o The reply should follow unicast routing paths to indicate
- (unicast) connectivity between the receiver and the sender since
- the subsequent HTTP request will be unicast routed.
-
- Trust is an important aspect of inter-cache relationships. A Web
- cache should not automatically trust any cache which replies to a
- multicast ICP query. Caches should ignore ICP messages from
- addresses not specifically configured as neighbors. Otherwise, one
- could easily pollute a cache mesh by running an illegitimate cache
- and having it join a group, return ICP_OP_HIT for all requests, and
- then deliver bogus content.
-
- When sending to multicast groups, cache administrators must be
- careful to use the minimum multicast TTL required to reach all group
- members. Joining a multicast group requires no special privileges
- and there is no way to prevent anyone from joining "your" group. Two
- groups of caches utilizing the same multicast address could overlap,
- which would cause a cache to receive ICP replies from unknown
- neighbors. The unknown neighbors would not be used to retrieve the
- object data, but the cache would constantly receive ICP replies that
- it must always ignore.
-
- To prevent an overlapping cache mesh, caches should thus limit the
- scope of their ICP queries with appropriate TTLs; an application such
- as mtrace[6] can determine appropriate multicast TTLs.
-
- As mentioned in section 5.1.3, we need to estimate the number of
- expected replies for an ICP_OP_QUERY message. For unicast we expect
- one reply for each query if the peer is up. However, for multicast
- we generally expect more than one reply, but have no way of knowing
- exactly how many replies to expect. Squid regularly (every 15
- minutes) sends out test ICP_OP_QUERY messages to only the multicast
- group peers. As with a real ICP query, a timeout event is installed
- and the replies are counted until the timeout occurs. We have found
- that the received count varies considerably. Therefore, the number
- of replies to expect is calculated as a moving average, rounded down
- to the nearest integer.
-
-
-
-
-
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 15]
-\f
-RFC 2187 ICP September 1997
-
-
-8. Lessons Learned
-
-8.1. Differences Between ICP and HTTP
-
- ICP is notably different from HTTP. HTTP supports a rich and
- sophisticated set of features. In contrast, ICP was designed to be
- simple, small, and efficient. HTTP request and reply headers consist
- of lines of ASCII text delimited by a CRLF pair, whereas ICP uses a
- fixed size header and represents numbers in binary. The only thing
- ICP and HTTP have in common is the URL.
-
- Note that the ICP message does not even include the HTTP request
- method. The original implementation assumed that only GET requests
- would be cachable and there would be no need to locate non-GET
- requests in neighbor caches. Thus, the current version of ICP does
- not accommodate non-GET requests, although the next version of this
- protocol will likely include a field for the request method.
-
- HTTP defines features that are important for caching but not
- expressible with the current ICP protocol. Among these are Pragma:
- no-cache, If-Modified-Since, and all of the Cache-Control features of
- HTTP/1.1. An ICP_OP_HIT_OBJ message may deliver an object which may
- not obey all of the request header constraints. These differences
- between ICP and HTTP are the reason we discourage the use of the
- ICP_OP_HIT_OBJ feature.
-
-8.2. Parents, Siblings, Hits and Misses
-
- Note that the ICP message does not have a field to indicate the
- intent of the querying cache. That is, nowhere in the ICP request or
- reply does it say that the two caches have a sibling or parent
- relationship. A sibling cache can only respond with HIT or MISS, not
- "you can retrieve this from me" or "you can not retrieve this from
- me." The querying cache must apply the HIT or MISS reply to its
- local configuration to prevent it from resolving misses through a
- sibling cache. This constraint is awkward, because this aspect of
- the relationship can be configured only in the cache originating the
- requests, and indirectly via the access controls configured in the
- queried cache as described earlier in section 4.2.
-
-
-
-
-
-
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 16]
-\f
-RFC 2187 ICP September 1997
-
-
-8.3. Different Roles of ICP
-
- There are two different understandings of what exactly the role of
- ICP is in a cache mesh. One understanding is that ICP's role is only
- object location, specifically, to provide hints about whether or not
- a named object exists in a neighbor cache. An implied assumption is
- that cache hits are highly desirable, and ICP is used to maximize the
- chance of getting them. If an ICP message is lost due to congestion,
- then nothing significant is lost; the request will be satisfied
- regardless.
-
- ICP is increasingly being tasked to fill a more complex role:
- conveying cache usage policy. For example, many organizations (e.g.
- universities) will install a Web cache on the border of their
- network. Such organizations may be happy to establish sibling
- relationships with other, nearby caches, subject to the following
- terms:
-
- o Any of the organization's customers or users may request any
- object (cached or not).
-
- o Anyone may request an object already in the cache.
-
- o Anyone may request any object from the organization's servers
- behind the cache.
-
- o All other requests are denied; specifically, the organization
- will not provide transit for requests in which neither the
- client nor the server falls within its domain.
-
- To successfully convey policy the ICP exchange must very accurately
- predict the result (hit, miss) of a subsequent HTTP request. The
- result may often depend on other request fields, such as Cache-
- Control. So it's not possible for ICP to accurately predict the
- result without more, or perhaps all, of the HTTP request.
-
-8.4. Protocol Design Flaws of ICPv2
-
- We recognize certain flaws with the original design of ICP, and make
- note of them so that future versions can avoid the same mistakes.
-
- o The NULL-terminated URL in the payload field requires stepping
- through the message an octet at a time to find some of the
- fields (i.e. the beginning of object data in an ICP_OP_HIT_OBJ
- message).
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 17]
-\f
-RFC 2187 ICP September 1997
-
-
- o Two fields (Sender Host Address and Requester Host Address) are
- IPv4 specific. However, neither of these fields are used in
- practice; they are normally zero-filled. If IP addresses have a
- role in the ICP message, there needs to be an address family
- descriptor for each address, and clients need to be able to say
- whether they want to hear IPv6 responses or not.
-
- o Options are limited to 32 option flags and 32 bits of option
- data. This should be more like TCP, with an option descriptor
- followed by option data.
-
- o Although currently used as the cache key, the URL string no
- longer serves this role adequately. Some HTTP responses now
- vary according to the requestor's User-Agent and other headers.
- A cache key must incorporate all non-transport headers present
- in the client's request. All non-hop-by-hop request headers
- should be sent in an ICP query.
-
- o ICPv2 uses different opcode values for queries and responses.
- ICP should use the same opcode for both sides of a two-sided
- transaction, with a "query/response" indicator telling which
- side is which.
-
- o ICPv2 does not include any authentication fields.
-
-9. Security Considerations
-
- Security is an issue with ICP over UDP because of its connectionless
- nature. Below we consider various vulnerabilities and methods of
- attack, and their implications.
-
- Our first line of defense is to check the source IP address of the
- ICP message, e.g. as given by recvfrom(2). ICP query messages should
- be processed if the access control rules allow the querying address
- access to the cache. However, ICP reply messages must only be
- accepted from known neighbors; a cache must ignore replies from
- unknown addresses.
-
- Because we trust the validity of an address in an IP packet, ICP is
- susceptible to IP address spoofing. In this document we address some
- consequences of IP address spoofing. Normally, spoofed addresses can
- only be detected by routers, not by hosts. However, the IP
- Authentication Header[7,8] can be used underneath ICP to provide
- cryptographic authentication of the entire IP packet containing the
- ICP protocol, thus eliminating the risk of IP address spoofing.
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 18]
-\f
-RFC 2187 ICP September 1997
-
-
-9.1. Inserting Bogus ICP Queries
-
- Processing an ICP_OP_QUERY message has no known security
- implications, so long as the requesting address is granted access to
- the cache.
-
-9.2. Inserting Bogus ICP Replies
-
- Here we are concerned with a third party generating ICP reply
- messages which are returned to the querying cache before the real
- reply arrives, or before any replies arrive. The third party may
- insert bogus ICP replies which appear to come from legitimate
- neighbors. There are three vulnerabilities:
-
- o Preventing a certain neighbor from being used
-
- If a third-party could send an ICP_OP_MISS_NOFETCH reply back
- before the real reply arrived, the (falsified) neighbor would
- not be used.
-
- A third-party could blast a cache with ICP_OP_DENIED messages
- until the threshold described in section 5.3.1 is reached,
- thereby causing the neighbor relationship to be temporarily
- terminated.
-
- o Forcing a certain neighbor to be used
-
- If a third-party could send an ICP_OP_HIT reply back before the
- real reply arrived, the (falsified) neighbor would be used.
- This may violate the terms of a sibling relationship; ICP_OP_HIT
- replies mean a subsequent HTTP request will also be a hit.
-
- Similarly, if bogus ICP_OP_SECHO messages can be generated, the
- cache would retrieve requests directly from the origin server.
-
-o Cache poisoning
-
- The ICP_OP_HIT_OBJ message is especially sensitive to security
- issues since it contains actual object data. In combination
- with IP address spoofing, this option opens up the likely
- possibility of having the cache polluted with invalid objects.
-
-
-
-
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 19]
-\f
-RFC 2187 ICP September 1997
-
-
-9.3. Eavesdropping
-
- Multicasting ICP queries provides a very simple method for others to
- "snoop" on ICP messages. If enabling multicast, cache administrators
- should configure the application to use the minimum required
- multicast TTL, using a tool such as mtrace[6]. Note that the IP
- Encapsulating Security Payload [7,9] mechanism can be used to provide
- protection against eavesdropping of ICP messages.
-
- Eavesdropping on ICP traffic can provide third parties with a list of
- URLs being browsed by cache users. Because the Requestor Host
- Address is zero-filled by Squid and Harvest, the URLs cannot be
- mapped back to individual host systems.
-
- By default, Squid and Harvest do not send ICP messages for URLs
- containing `cgi-bin' or `?'. These URLs sometimes contain sensitive
- information as argument parameters. Cache administrators need to be
- aware that altering the configuration to make ICP queries for such
- URLs may expose sensitive information to outsiders, especially when
- multicast is used.
-
-9.4. Blocking ICP Messages
-
- Intentionally blocked (or discarded) ICP queries or replies will
- appear to reflect link failure or congestion, and will prevent the
- use of a neighbor as well as lead to timeouts (see section 5.1.4).
- If all messages are blocked, the cache will assume the neighbor is
- down and remove it from the selection algorithm. However, if, for
- example, every other query is blocked, the neighbor will remain
- "alive," but every other request will suffer the ICP timeout.
-
-9.5. Delaying ICP Messages
-
- The neighbor selection algorithm normally waits for all ICP MISS
- replies to arrive. Delaying queries or replies, so that they arrive
- later than they normally would, will cause additional delay for the
- subsequent HTTP request. Of course, if messages are delayed so that
- they arrive after the timeout, the behavior is the same as "blocking"
- above.
-
-9.6. Denial of Service
-
- A denial-of-service attack, where the ICP port is flooded with a
- continuous stream of bogus messages has three vulnerabilities:
-
- o The application may log every bogus ICP message and eventually
- fill up a disk partition.
-
-
-
-
-Wessels & Claffy Informational [Page 20]
-\f
-RFC 2187 ICP September 1997
-
-
- o The socket receive queue may fill up, causing legitimate
- messages to be dropped.
-
- o The host may waste some CPU cycles receiving the bogus messages.
-
-9.7. Altering ICP Fields
-
- Here we assume a third party is able to change one or more of the ICP
- reply message fields.
-
- Opcode
-
- Changing the opcode field is much like inserting bogus messages
- described above. Changing a hit to a miss would prevent the peer
- from being used. Changing a miss to a hit would force the peer to
- be used.
-
- Version
-
- Altering the ICP version field may have unpredictable consequences
- if the new version number is recognized and supported. The
- receiving application should ignore messages with invalid version
- numbers. At the time of this writing, both version numbers 2 and
- 3 are in use. These two versions use some fields (e.g. Options)
- in a slightly different manner.
-
- Message Length
-
- An incorrect message length should be detected by the receiving
- application as an invalid ICP message.
-
- Request Number
-
- The request number is often used as a part of the cache key.
- Harvest does not use the request number. Squid uses the request
- number in conjunction with the URL to create a cache key.
- Altering the request number will cause a lookup of the cache key
- to fail. This is similar to blocking the ICP reply altogether.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 21]
-\f
-RFC 2187 ICP September 1997
-
-
- There is no requirement that a cache use both the URL and the
- request number to locate HTTP requests with outstanding ICP
- queries (however both Squid and Harvest do). The request number
- must always be the same in the query and the reply. However, if
- the querying cache uses only the request number to locate pending
- requests, there is some possibility that a replying cache might
- increment the request number in the reply to give the false
- impression that the two caches are closer than they really are.
- In other words, assuming that there are a few ICP requests "in
- flight" at any given time, incrementing the reply request number
- trick the querying cache into seeing a smaller round-trip time
- than really exists.
-
- Options
-
- There is little risk in having the Options bitfields altered. Any
- option bit must only be set in a reply if it was also set in a
- query. Changing a bit from clear to set is detectable by the
- querying cache, and such a message must be ignored. Changing a
- bit from set to clear is allowed and has no negative side effects.
-
- Option Data
-
- ICP_FLAG_SRC_RTT is the only option which uses the Option Data
- field. Altering the RTT values returned here can affect the
- neighbor selection algorithm, either forcing or preventing the use
- of a neighbor.
-
- URL
-
- The URL and Request Number are used to generate the cache key.
- Altering the URL will cause a lookup of the cache key to fail, and
- the ICP reply to be entirely ignored. This is similar to blocking
- the ICP reply altogether.
-
-9.8. Summary
-
- o ICP_OP_HIT_OBJ is particularly vulnerable to security problems
- because it includes object data. For this, and other reasons,
- its use is discouraged.
-
- o Falsifying, altering, inserting, or blocking ICP messages can
- cause an HTTP request to fail only in two situations:
-
- - If the cache is behind a firewall and cannot directly
- connect to the origin server.
-
-
-
-
-
-Wessels & Claffy Informational [Page 22]
-\f
-RFC 2187 ICP September 1997
-
-
- - If a false ICP_OP_HIT reply causes the HTTP request to be
- forwarded to a sibling, where the request is a cache miss
- and the sibling refuses to continue forwarding the request
- on behalf of the originating cache.
-
- o Falsifying, altering, inserting, or blocking ICP messages can
- easily cause HTTP requests to be forwarded (or not forwarded) to
- certain neighbors. If the neighbor cache has also been
- compromised, then it could serve bogus content and pollute a
- cache hierarchy.
-
- o Blocking or delaying ICP messages can cause HTTP request to be
- further delayed, but still satisfied.
-
-
-10. References
-
- [1] Fielding, R., et. al, "Hypertext Transfer Protocol -- HTTP/1.1",
- RFC 2068, UC Irvine, January 1997.
-
- [2] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform Resource
- Locators (URL)", RFC 1738, CERN, Xerox PARC, University of Minnesota,
- December 1994.
-
- [3] Bowman M., Danzig P., Hardy D., Manber U., Schwartz M., and
- Wessels D., "The Harvest Information Discovery and Access System",
- Internet Research Task Force - Resource Discovery,
- http://harvest.transarc.com/.
-
- [4] Wessels D., Claffy K., "ICP and the Squid Web Cache", National
- Laboratory for Applied Network Research,
- http://www.nlanr.net/~wessels/Papers/icp-squid.ps.gz.
-
- [5] Wessels D., "The Squid Internet Object Cache", National
- Laboratory for Applied Network Research,
- http://squid.nlanr.net/Squid/
-
- [6] mtrace, Xerox PARC, ftp://ftp.parc.xerox.com/pub/net-
- research/ipmulti/.
-
- [7] Atkinson, R., "Security Architecture for the Internet Protocol",
- RFC 1825, NRL, August 1995.
-
- [8] Atkinson, R., "IP Authentication Header", RFC 1826, NRL, August
- 1995.
-
- [9] Atkinson, R., "IP Encapsulating Security Payload (ESP)", RFC
- 1827, NRL, August 1995.
-
-
-
-Wessels & Claffy Informational [Page 23]
-\f
-RFC 2187 ICP September 1997
-
-
-11. Acknowledgments
-
- The authors wish to thank Paul A Vixie <paul@vix.com> for providing
- excellent feedback on this document, Martin Hamilton
- <martin@mrrl.lut.ac.uk> for pushing the development of multicast ICP,
- Eric Rescorla <ekr@terisa.com> and Randall Atkinson <rja@home.net>
- for assisting with security issues, and especially Allyn Romanow for
- keeping us on the right track.
-
-
-12. Authors' Addresses
-
- Duane Wessels
- National Laboratory for Applied Network Research
- 10100 Hopkins Drive
- La Jolla, CA 92093
-
- EMail: wessels@nlanr.net
-
-
- K. Claffy
- National Laboratory for Applied Network Research
- 10100 Hopkins Drive
- La Jolla, CA 92093
-
- EMail: kc@nlanr.net
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Wessels & Claffy Informational [Page 24]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group J. Mogul
-Request for Comments: 2227 DECWRL
-Category: Standards Track P. Leach
- Microsoft
- October 1997
-
-
- Simple Hit-Metering and Usage-Limiting for HTTP
-
-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.
-
-ABSTRACT
-
- This document proposes a simple extension to HTTP, using a new
- "Meter" header, which permits a limited form of demographic
- information (colloquially called "hit-counts") to be reported by
- caches to origin servers, in a more efficient manner than the
- "cache-busting" techniques currently used. It also permits an origin
- server to control the number of times a cache uses a cached response,
- and outlines a technique that origin servers can use to capture
- referral information without "cache-busting."
-
-TABLE OF CONTENTS
-
- 1 Introduction 2
- 1.1 Goals, non-goals, and limitations 3
- 1.2 Brief summary of the design 4
- 1.3 Terminology 5
- 2 Overview 5
- 2.1 Discussion 7
- 3 Design concepts 8
- 3.1 Implementation of the "metering subtree" 8
- 3.2 Format of the Meter header 10
- 3.3 Negotiation of hit-metering and usage-limiting 10
- 3.4 Transmission of usage reports 14
- 3.5 When to send usage reports 15
- 3.6 Subdivision of usage-limits 16
-
-
-
-
-Mogul & Leach Standards Track [Page 1]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- 4 Analysis 17
- 4.1 Approximation accuracy for counting users 18
- 4.2 What about "Network Computers"? 19
- 4.3 Critical-path delay analysis 19
- 5 Specification 20
- 5.1 Specification of Meter header and directives 20
- 5.2 Abbreviations for Meter directives 23
- 5.3 Counting rules 24
- 5.3.1 Counting rules for hit-metering 24
- 5.3.2 Counting rules for usage-limiting 25
- 5.3.3 Equivalent algorithms are allowed 26
- 5.4 Counting rules: interaction with Range requests 27
- 5.5 Implementation by non-caching proxies 27
- 5.6 Implementation by cooperating caches 28
- 6 Examples 28
- 6.1 Example of a complete set of exchanges 28
- 6.2 Protecting against HTTP/1.0 proxies 30
- 6.3 More elaborate examples 30
- 7 Interactions with content negotiation 31
- 7.1 Treatment of responses carrying a Vary header 31
- 7.2 Interaction with Transparent Content Negotiation 32
- 8 A Note on Capturing Referrals 32
- 9 Alternative proposals 33
- 10 Security Considerations 34
- 11 Acknowledgments 35
- 12 References 35
- 13 Authors' Addresses 36
- 14 Full Copyright Statement 37
-
-1 Introduction
-
- For a variety of reasons, content providers want to be able to
- collect information on the frequency with which their content is
- accessed. This desire leads to some of the "cache-busting" done by
- existing servers. ("Cache-busting" is the use by servers of
- techniques intended to prevent caching of responses; it is unknown
- exactly how common this is.) This kind of cache-busting is done not
- for the purpose of maintaining transparency or security properties,
- but simply to collect demographic information. Some cache-busting is
- also done to provide different advertising images to appear on the
- same page (i.e., each retrieval of the page sees a different ad).
-
- This proposal supports a model similar to that of publishers of
- hard-copy publications: such publishers (try to) report to their
- advertisers how many people read an issue of a publication at least
- once; they don't (try to) report how many times a reader re-reads an
- issue. They do this by counting copies published, and then try to
- estimate, for their publication, on average how many people read a
-
-
-
-Mogul & Leach Standards Track [Page 2]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- single copy at least once. The key point is that the results aren't
- exact, but are still useful. Another model is that of coding
- inquiries in such a way that the advertiser can tell which
- publication produced the inquiry.
-
-1.1 Goals, non-goals, and limitations
-
- HTTP/1.1 already allows origin servers to prevent caching of
- responses, and evidence exists [9] that at least some of the time,
- this is being done for the sole purpose of collecting counts of the
- number of accesses of specific pages. Some of this evidence is
- inferred from the study of proxy traces; some is based on explicit
- statements of the intention of the operators of Web servers.
- Information collected this way might or might not be of actual use to
- the people who collect it; the fact is that they want to collect it,
- or already do so.
-
- The goal of this proposal is to provide an optional performance
- optimization for this use of HTTP/1.1.
-
- This specification is:
-
- - Optional: no server or proxy is required to implement it.
-
- - Proxy-centered: there is no involvement on the part of
- end-client implementations.
-
- - Solely a performance optimization: it provides no
- information or functionality that is not already available
- in HTTP/1.1. The intent is to improve performance overall,
- and reduce latency for almost all interactions; latency
- might be increased for a small fraction of HTTP
- interactions.
-
- - Best-efforts: it does not guarantee the accuracy of the
- reported information, although it does provide accurate
- results in the absence of persistent network failures or
- host crashes.
-
- - Neutral with respect to privacy: it reveals to servers no
- information about clients that is not already available
- through the existing features of HTTP/1.1.
-
- The goals of this specification do not include:
-
- - Solving the entire problem of efficiently obtaining
- extensive information about requests made via proxies.
-
-
-
-
-Mogul & Leach Standards Track [Page 3]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- - Improving the protection of user privacy (although our
- proposal may reduce the transfer of user-specific
- information to servers, it does not prevent it).
-
- - Preventing or encouraging the use of log-exchange
- mechanisms.
-
- - Avoiding all forms of "cache-busting", or even all
- cache-busting done for gathering counts.
-
- This design has certain potential limitations:
-
- - If it is not deployed widely in both proxies and servers,
- it will provide little benefit.
-
- - It may, by partially solving the hit-counting problem,
- reduce the pressure to adopt more complete solutions, if
- any become available.
-
- - Even if widely deployed, it might not be widely used, and
- so might not significantly improve performance.
-
- These potential limitations might not be problems in actual practice.
-
-1.2 Brief summary of the design
-
- This section is included for people not wishing to read the entire
- document; it is not a specification for the proposed design, and
- over-simplifies many aspects of the design.
-
- The goal of this design is to eliminate the need for origin servers
- to use "cache-busting" techniques, when this is done just for the
- purpose of counting the number of users of a resource. (Cache-
- busting includes techniques such as setting immediate Expiration
- dates, or sending "Cache-control: private" in each response.)
-
- The design adds a new "Meter" header to HTTP; the header is always
- protected by the "Connection" header, and so is always hop-by-hop.
- This mechanism allows the construction of a "metering subtree", which
- is a connected subtree of proxies, rooted at an origin server. Only
- those proxies that explicitly volunteer to join in the metering
- subtree for a resource participate in hit-metering, but those proxies
- that do volunteer are required to make their best effort to provide
- accurate counts. When a hit-metered response is forwarded outside of
- the metering subtree, the forwarding proxy adds "Cache-control: s-
- maxage=0", so that other proxies (outside the metering subtree) are
- forced to forward all requests to a server in the metering subtree.
-
-
-
-
-Mogul & Leach Standards Track [Page 4]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- NOTE: the HTTP/1.1 specification does not currently define a "s-
- maxage" Cache-control directive. The HTTP working group has
- decided to add such a directive to the next revision of the
- HTTP/1.1 specification [7].
-
- The Meter header carries zero or more directives, similar to the way
- that the Cache-control header carries directives. Proxies may use
- certain Meter directives to volunteer to do hit-metering for a
- resource. If a proxy does volunteer, the server may use certain
- directives to require that a response be hit-metered. Finally,
- proxies use a "count" Meter directive to report the accumulated hit
- counts.
-
- The Meter mechanism can also be used by a server to limit the number
- of uses that a cache may make of a cached response, before
- revalidating it.
-
- The full specification includes complete rules for counting "uses" of
- a response (e.g., non-conditional GETs) and "reuses" (conditional
- GETs). These rules ensure that the results are entirely consistent
- in all cases, except when systems or networks fail.
-
-1.3 Terminology
-
- This document uses terms defined and explained in the HTTP/1.1
- specification [4], including "origin server," "resource," "hop-by-
- hop," "unconditional GET," and "conditional GET." The reader is
- expected to be familiar with the HTTP/1.1 specification and its
- 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 [1].
-
-2 Overview
-
- The design described in this document introduces several new features
- to HTTP:
-
- - Hit-metering: allows an origin server to obtain reasonably
- accurate counts of the number of clients using a resource
- instance via a proxy cache, or a hierarchy of proxy caches.
-
- - Usage-limiting: allows an origin server to control the
- number of times a cached response may be used by a proxy
- cache, or a hierarchy of proxy caches, before revalidation
- with the origin server.
-
-
-
-
-Mogul & Leach Standards Track [Page 5]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- These new non-mandatory features require minimal new protocol
- support, no change in protocol version, relatively little overhead in
- message headers. The design adds no additional network round-trips
- in any critical path that directly affects user-perceived latency
- (see section 4.3 for an analysis).
-
- The primary goal of hit-metering and usage-limiting is to obviate the
- need for an origin server to send "Cache-control: s-maxage=0" with
- responses for resources whose value is not likely to change
- immediately. In other words, in cases where the only reason for
- contacting the origin server on every request that might otherwise be
- satisfied by a proxy cache entry is to allow the server to collect
- demographic information or to control the number of times a cache
- entry is used, the extension proposed here will avoid a significant
- amount of unnecessary network traffic and latency.
-
- This design introduces one new "Meter" header, which is used both in
- HTTP request messages and HTTP response messages. The Meter header
- is used to transmit a number of directives and reports. In
- particular, all negotiation of the use of hit-metering and usage
- limits is done using this header. No other changes to the existing
- HTTP/1.1 specification [4] are proposed in this document.
-
- This design also introduces several new concepts:
-
- 1. The concepts of a "use" of a cache entry, which is when a
- proxy returns its entity-body in response to a conditional
- or non-conditional request, and the "reuse" of a cache
- entry, which is when a proxy returns a 304 (Not Modified)
- response to a conditional request which is satisfied by
- that cache entry.
-
- 2. The concept of a hit-metered resource, for which proxy
- caches make a best-effort attempt to report accurate
- counts of uses and/or reuses to the origin server.
-
- 3. The concept of a usage-limited resource, for which the
- origin server expects proxy caches to limit the number of
- uses and/or reuses.
-
- The new Meter directives and reports interact to allow proxy caches
- and servers to cooperate in the collection of demographic data. The
- goal is a best-efforts approximation of the true number of uses
- and/or reuses, not a guaranteed exact count.
-
-
-
-
-
-
-
-Mogul & Leach Standards Track [Page 6]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- The new Meter directives also allow a server to bound the inaccuracy
- of a particular hit-count, by bounding the number of uses between
- reports. It can also, for example, bound the number of times the
- same ad is shown because of caching.
-
- Section 7.1 describes a way to use server-driven content negotiation
- (the Vary header) that allows an HTTP origin server to flexibly
- separate requests into categories and count requests by category.
- Implementation of such a categorized hit counting is likely to be a
- very small modification to most implementations of Vary; some
- implementations may not require any modification at all.
-
-2.1 Discussion
-
- Mapping this onto the publishing model, a proxy cache would increment
- the use-count for a cache entry once for each unconditional GET done
- for the entry, and once for each conditional GET that results in
- sending a copy of the entry to update a client's invalid cached copy.
- Conditional GETs that result in 304 (Not Modified) are not included
- in the use-count, because they do not result in a new user seeing the
- page, but instead signify a repeat view by a user that had seen it
- before. However, 304 responses are counted in the reuse-count.
- HEADs are not counted at all, because their responses do not contain
- an entity-body.
-
- The Meter directives apply only to shared proxy caches, not to end-
- client (or other single-user) caches. Single user caches should not
- use Meter, because their hits will be automatically counted as a
- result of the unconditional GET with which they first fetch the page,
- from either the origin-server or from a proxy cache. Their
- subsequent conditional GETs do not result in a new user seeing the
- page.
-
- The mechanism specified here counts GETs; other methods either do not
- result in a page for the user to read, aren't cached, or are
- "written-through" and so can be directly counted by the origin
- server. (If, in the future, a "cachable POST" came into existence,
- whereby the entity-body in the POST request was used to select a
- cached response, then such POSTs would have to be treated just like
- GETs.) The applicability of hit-metering to any new HTTP methods
- that might be defined in the future is currently unspecifiable.
-
- In the case of multiple caches along a path, a proxy cache does the
- obvious summation when it receives a use-count or reuse-count in a
- request from another cache.
-
-
-
-
-
-
-Mogul & Leach Standards Track [Page 7]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
-3 Design concepts
-
- In order to allow the introduction of hit-metering and usage-limiting
- without requiring a protocol revision, and to ensure a reasonably
- close approximation of accurate counts, the negotiation of metering
- and usage-limiting is done hop-by-hop, not end-to-end. If one
- considers the "tree" of proxies that receive, store, and forward a
- specific response, the intent of this design is that within some
- (possibly null) "metering subtree", rooted at the origin server, all
- proxies are using the hit-metering and/or usage-limiting requested by
- the origin server.
-
- Proxies at the leaves of this subtree will insert a "Cache-control:
- s-maxage=0" directive, which forces all other proxies (below this
- subtree) to check with a leaf of the metering subtree on every
- request. However, it does not prevent them from storing and using
- the response, if the revalidation succeeds.
-
- No proxy is required to implement hit-metering or usage-limiting.
- However, any proxy that transmits the Meter header in a request MUST
- implement every unconditional requirement of this specification,
- without exception or amendment.
-
- This is a conservative design, which may sometimes fail to take
- advantage of hit-metering support in proxies outside the metering
- subtree. However, it is likely that without the reliability offered
- by a conservative design, managers of origin servers with
- requirements for accurate approximations will not take advantage of
- any hit-metering proposal.
-
- The hit-metering/usage-limiting mechanism is designed to avoid any
- extra network round-trips in the critical path of any client request,
- and (as much as possible) to avoid excessively lengthening HTTP
- messages.
-
- The Meter header is used to transmit both negotiation information and
- numeric information.
-
- A formal specification for the Meter header appears in section 5; the
- following discussion uses an informal approach to improve clarity.
-
-3.1 Implementation of the "metering subtree"
-
- The "metering subtree" approach is implemented in a simple,
- straightforward way by defining the new "Meter" header as one that
- MUST always be protected by a Connection header in every request or
- response. I.e., if the Meter header is present in an HTTP message,
- that message:
-
-
-
-Mogul & Leach Standards Track [Page 8]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- 1. MUST contain "Connection: meter", and MUST be handled
- according to the HTTP/1.1 specification of the Connection
- header.
-
- 2. MUST NOT be sent in response to a request from a client
- whose version number is less than HTTP/1.1.
-
- 3. MUST NOT be accepted from a client whose version number is
- less than HTTP/1.1.
-
- The reason for the latter two restrictions is to protect against
- proxies that might not properly implement the Connection header.
- Otherwise, a subtree that includes an HTTP/1.0 proxy might
- erroneously appear to be a metering subtree.
-
- Note: It appears that for the Connection header mechanism to
- function correctly, a system receiving an HTTP/1.0 (or lower-
- version) message that includes a Connection header must act as if
- this header, and all of the headers it protects, ought to have
- been removed from the message by an intermediate proxy.
-
- Although RFC2068 does not specifically require this behavior, it
- appears to be implied. Otherwise, one could not depend on the
- stated property (section 14.10) that the protected options "MUST
- NOT be communicated by proxies over further connections." This
- should probably be clarified in a subsequent draft of the HTTP/1.1
- specification.
-
- This specification does not, in any way, propose a modification of
- the specification of the Connection header.
-
- From the point of view of an origin server, the proxies in a metering
- subtree work together to obey usage limits and to maintain accurate
- usage counts. When an origin server specifies a usage limit, a proxy
- in the metering subtree may subdivide this limit among its children
- in the subtree as it sees fit. Similarly, when a proxy in the
- subtree receives a usage report, it ensures that the hits represented
- by this report are summed properly and reported to the origin server.
-
- When a proxy forwards a hit-metered or usage-limited response to a
- client (proxy or end-client) not in the metering subtree, it MUST
- omit the Meter header, and it MUST add "Cache-control: s-maxage=0" to
- the response.
-
-
-
-
-
-
-
-
-Mogul & Leach Standards Track [Page 9]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
-3.2 Format of the Meter header
-
- The Meter header is used to carry zero or more directives. Multiple
- Meter headers may occur in an HTTP message, but according to the
- rules in section 4.2 of the HTTP/1.1 specification [4], they may be
- combined into a single header (and should be so combined, to reduce
- overhead).
-
- For example, the following sequence of Meter headers
-
- Meter: max-uses=3
- Meter: max-reuses=10
- Meter: do-report
-
- may be expressed as
-
- Meter: max-uses=3, max-reuses=10, do-report
-
-3.3 Negotiation of hit-metering and usage-limiting
-
- An origin server that wants to collect hit counts for a resource, by
- simply forcing all requests to bypass any proxy caches, would respond
- to requests on the resource with "Cache-control: s-maxage=0". (An
- origin server wishing to prevent HTTP/1.0 proxies from improperly
- caching the response could also send both "Expires: <now>", to
- prevent such caching, and "Cache-control: max-age=NNNN", to allow
- newer proxies to cache the response).
-
- The purpose of the Meter header is to obviate the need for "Cache-
- control: s-maxage=0" within a metering subtree. Thus, any proxy may
- negotiate the use of hit-metering and/or usage-limiting with the
- next-hop server. If this server is the origin server, or is already
- part of a metering subtree (rooted at the origin server), then it may
- complete the negotiation, thereby extending the metering subtree to
- include the new proxy.
-
- To start the negotiation, a proxy sends its request with one of the
- following Meter directives:
-
- will-report-and-limit
- indicates that the proxy is willing and able to
- return usage reports and will obey any usage-limits.
-
- wont-report indicates that the proxy will obey usage-limits but
- will not send usage reports.
-
- wont-limit indicates that the proxy will not obey usage-limits
- but will send usage reports.
-
-
-
-Mogul & Leach Standards Track [Page 10]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- A proxy willing to neither obey usage-limits nor send usage reports
- MUST NOT transmit a Meter header in the request.
-
- By definition, an empty Meter header:
-
- Meter:
-
- is equivalent to "Meter: will-report-and-limit", and so, by the
- definition of the Connection header (see section 14.10 of the
- HTTP/1.1 specification [4]), a request that contains
-
- Connection: Meter
-
- and no explicit Meter header is equivalent to a request that contains
-
- Connection: Meter
- Meter: will-report-and-limit
-
- This makes the default case more efficient.
-
- An origin server that is not interested in metering or usage-limiting
- the requested resource simply ignores the Meter header.
-
- If the server wants the proxy to do hit-metering and/or usage-
- limiting, its response should include one or more of the following
- Meter directives:
-
- For hit-metering:
-
- do-report specifies that the proxy MUST send usage reports to
- the server.
-
- dont-report specifies that the proxy SHOULD NOT send usage
- reports to the server.
-
- timeout=NNN sets a metering timeout of NNN minutes, from the time
- that this response was originated, for the reporting
- of a hit-count. If the proxy has a non-zero hit
- count for this response when the timeout expires, it
- MUST send a report to the server at or before that
- time. Implies "do-report".
-
- By definition, an empty Meter header in a response, or any Meter
- header that does not contain "dont-report", means "Meter: do-report";
- this makes a common case more efficient.
-
-
-
-
-
-
-Mogul & Leach Standards Track [Page 11]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- Note: an origin server using the metering timeout mechanism to
- bound the collection period over which hit-counts are obtained
- should adjust the timeout values in the responses it sends so that
- all responses generated within that period reach their metering
- timeouts at or before the end of that period.
-
- If the origin server simply sends a constant metering timeout T
- with each response for a resource, the reports that it receives
- will reflect activity over a period whose duration is between T
- and N*T (in the worst case), where N is the maximum depth of the
- metering subtree.
-
- For usage-limiting
-
- max-uses=NNN sets an upper limit of NNN "uses" of the response,
- not counting its immediate forwarding to the
- requesting end-client, for all proxies in the
- following subtree taken together.
-
- max-reuses=NNN sets an upper limit of NNN "reuses" of the response
- for all proxies in the following subtree taken
- together.
-
- When a proxy has exhausted its allocation of "uses" or "reuses" for a
- cache entry, it MUST revalidate the cache entry (using a conditional
- request) before returning it in a response. (The proxy SHOULD use
- this revalidation message to send a usage report, if one was
- requested and it is time to send it. See sections 3.4 and 3.5.)
-
- These Meter response-directives apply only to the specific response
- that they are attached to.
-
- Note that the limit on "uses" set by the max-uses directive does
- not include the use of the response to satisfy the end-client
- request that caused the proxy's request to the server. This
- counting rule supports the notion of a cache-initiated prefetch: a
- cache may issue a prefetch request, receive a max-uses=0 response,
- store that response, and then return that response (without
- revalidation) when a client makes an actual request for the
- resource. However, each such response may be used at most once in
- this way, so the origin server maintains precise control over the
- number of actual uses.
-
- A server MUST NOT send a Meter header that would require a proxy to
- do something that it has not yet offered to do. A proxy receiving a
- Meter response-directive asking the proxy to do something it did not
- volunteer to do SHOULD ignore that directive.
-
-
-
-
-Mogul & Leach Standards Track [Page 12]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- A proxy receiving a Meter header in a response MUST either obey it,
- or it MUST revalidate the corresponding cache entry on every access.
- (I.e., if it chooses not to obey the Meter header in a response, it
- MUST act as if the response included "Cache-control: s-maxage=0".)
-
- Note: a proxy that has not sent the Meter header in a request for
- the given resource, and which has therefore not volunteered to
- honor Meter directives in a response, is not required to honor
- them. If, in this situation, the server does send a Meter header
- in a response, this is a protocol error. However, based on the
- robustness principle, the proxy may choose to interpret the Meter
- header as an implicit request to include "Cache-control: s-
- maxage=0" when it forwards the response, since this preserves the
- apparent intention of the server.
-
- A proxy that receives the Meter header in a request may ignore it
- only to the extent that this is consistent with its own duty to the
- next-hop server. If the received Meter request header is
- inconsistent with that duty, or if no Meter request header is
- received and the response from the next-hop server requests any form
- of metering or limiting, then the proxy MUST add "Cache-control: s-
- maxage=0" to any response it forwards for that request. (A proxy
- SHOULD NOT add or change the Expires header or max-age Cache-control
- directive.)
-
- For example, if proxy A receives a GET request from proxy B for
- URL X with "Connection: Meter", but proxy A's cached response for
- URL does not include any Meter directives, then proxy A may ignore
- the metering offer from proxy B.
-
- However, if proxy A has previously told the origin server "Meter:
- wont-limit" (implying will-report), and the cached response
- contains "Meter: do-report", and proxy B's request includes
- "Meter: wont-report", then proxy B's offer is inconsistent with
- proxy A's duty to the origin server. Therefore, in this case
- proxy A must add "Cache-control: s-maxage=0" when it returns the
- cached response to proxy B, and must not include a Meter header in
- this response.
-
- If a server does not want to use the Meter mechanism, and will not
- want to use it any time soon, it may send this directive:
-
- wont-ask recommends that the proxy SHOULD NOT send any Meter
- directives to this server.
-
-
-
-
-
-
-
-Mogul & Leach Standards Track [Page 13]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- The proxy SHOULD remember this fact for up to 24 hours. This avoids
- virtually all unnecessary overheads for servers that do not wish to
- use or support the Meter header. (This directive also implies
- "dont-report".)
-
-3.4 Transmission of usage reports
-
- To transmit a usage report, a proxy sends the following Meter header
- in a request on the appropriate resource:
-
- Meter: count=NNN/MMM
-
- The first integer indicates the count of uses of the cache entry
- since the last report; the second integer indicates the count of
- reuses of the entry (see section 5.3 for rules on counting uses and
- reuses). The transmission of a "count" directive in a request with
- no other Meter directive is also defined as an implicit transmission
- of a "will-report-and-limit" directive, to optimize the common case.
- (A proxy not willing to honor usage-limits would send "Meter:
- count=NNN/MMM, wont-limit" for its reports.)
-
- Note that when a proxy forwards a client's request and receives a
- response, the response that the proxy sends immediately to the
- requesting client is not counted as a "use". I.e., the reported
- count is the number of times the cache entry was used, and not the
- number of times that the response was used.
-
- A proxy SHOULD NOT transmit "Meter: count=0/0", since this conveys no
- useful information.
-
- Usage reports MUST always be transmitted as part of a conditional
- request (such as a GET or HEAD), since the information in the
- conditional header (e.g., If-Modified-Since or If-None-Match) is
- required for the origin server to know which instance of a resource
- is being counted. Proxys forwarding usage reports up the metering
- subtree MUST NOT change the contents of the conditional header, since
- otherwise this would result in incorrect counting.
-
- A usage report MUST NOT be transmitted as part of a forwarded request
- that includes multiple entity tags in an If-None-Match or If-Match
- header.
-
- Note: a proxy that offers its willingness to do hit-metering
- (report usage) must count both uses and reuses. It is not
- possible to negotiate the reporting of one but not the other.
-
-
-
-
-
-
-Mogul & Leach Standards Track [Page 14]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
-3.5 When to send usage reports
-
- A proxy that has offered to send usage reports to its parent in the
- metering subtree MUST send a usage report in each of these
- situations:
-
- 1. When it forwards a conditional GET on the resource
- instance on behalf of one of its clients (if the GET is
- conditional on at most one entity-tag).
-
- 2. When it forwards a conditional HEAD on the resource
- instance on behalf of one of its clients.
-
- 3. When it must generate a conditional GET to satisfy a
- client request because the max-uses limit has been
- exceeded.
-
- 4. Upon expiration of a metering timeout associated with a
- cache entry that has a non-zero hit-count.
-
- 5. When it removes the corresponding non-zero hit-count entry
- from its storage for any reason including:
-
- - the proxy needs the storage space for another
- hit-count entry.
-
- - the proxy is not able to store more than one response
- per resource, and a request forwarded on behalf of a
- client has resulted in the receipt of a new response
- (one with a different entity-tag or last-modified
- time).
-
- Note that a cache might continue to store hit-count information
- even after having deleted the body of the response, so it is
- not necessary to report the hit-count when deleting the body;
- it is only necessary to report it if the proxy is about to
- "forget" a non-zero value.
-
- (Section 5.3 explains how hit-counts become zero or non-zero.)
-
- If the usage report is being sent because the proxy is about to
- remove the hit-count entry from its storage, or because of an expired
- metering timeout:
-
- - The proxy MUST send the report as part of a conditional
- HEAD request on the resource instance.
-
-
-
-
-
-Mogul & Leach Standards Track [Page 15]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- - The proxy is not required to retry the HEAD request if it
- fails (this is a best-efforts design). To improve
- accuracy, however, the proxy SHOULD retry failed HEAD
- requests, subject to resource constraints.
-
- - The proxy is not required to serialize any other operation
- on the completion of this request.
-
- Note: proxy implementors are strongly encouraged to batch several
- HEAD-based reports to the same server, when possible, over a
- single persistent connection, to reduce network overhead as much
- as possible. This may involve a non-naive algorithm for
- scheduling the deletion of hit-count entries.
-
- If the usage count is sent because of an arriving request that also
- carries a "count" directive, the proxy MUST combine its own (possibly
- zero) use and reuse counts with the arriving counts, and then attempt
- to forward the request.
-
- However, the proxy is not required to forward an arriving request
- with a "count" directive, provided that:
-
- - it can reply to the request using a cached response, in
- compliance with other requirements of the HTTP
- specification.
-
- - such a response does not exceed a max-uses limit.
-
- - it is not required to forward the request because of an
- expired metering timeout.
-
- If an arriving request carries a "count" directive, and the proxy no
- longer has a cache entry for the resource, the proxy MUST forward the
- "count" directive. (This is, in any case, what a proxy without a
- suitable cache entry would normally do for any valid request it
- receives.)
-
-3.6 Subdivision of usage-limits
-
- When an origin server specifies a usage limit, a proxy in the
- metering subtree may subdivide this limit among its children in the
- subtree as it sees fit.
-
- For example, consider the situation with two proxies P1 and P2, each
- of which uses proxy P3 as a way to reach origin server S. Imagine
- that S sends P3 a response with
-
-
-
-
-
-Mogul & Leach Standards Track [Page 16]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- Meter: max-uses=10
-
- The proxies use that response to satisfy the current requesting end-
- client. The max-uses directive in this example allows the
- combination of P1, P2, and P3 together to satisfy 10 additional end-
- client uses (unconditional GETs) for the resource.
-
- This specification does not constrain how P3 divides up that
- allocation among itself and the other proxies. For example, P3 could
- retain all of max-use allocation for itself. In that case, it would
- forward the response to P1 and/or P2 with
-
- Meter: max-uses=0
-
- P3 might also divide the allocation equally among P1 and P2,
- retaining none for itself (which may be the right choice if P3 has
- few or no other clients). In this case, it could send
-
- Meter: max-uses=5
-
- to the proxy (P1 or P2) that made the initial request, and then
- record in some internal data structure that it "owes" the other proxy
- the rest of the allocation.
-
- Note that this freedom to choose the max-uses value applies to the
- origin server, as well. There is no requirement that an origin
- server send the same max-uses value to all caches. For example, it
- might make sense to send "max-uses=2" the first time one hears from a
- cache, and then double the value (up to some maximum limit) each time
- one gets a "use-count" from that cache. The idea is that the faster
- a cache is using up its max-use quota, the more likely it will be to
- report a use-count value before removing the cache entry. Also, high
- and frequent use-counts imply a corresponding high efficiency benefit
- from allowing caching.
-
- Again, the details of such heuristics would be outside the scope of
- this specification.
-
-4 Analysis
-
- This section includes informal analyses of several aspects of hit-
- metering:
-
- 1. the accuracy of results when applied to counting users
- (section 4.1).
-
- 2. the problem of counting users whose browsers do not
- include caches, such as Network Computers (section 4.2).
-
-
-
-Mogul & Leach Standards Track [Page 17]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- 3. delays imposed on "critical paths" for HTTP operations
- (section 4.3).
-
-4.1 Approximation accuracy for counting users
-
- For many (but not all) service operators, the single most important
- aspect of the request stream is the number of distinct users who have
- retrieved a particular entity within a given period (e.g., during a
- given day). The hit-metering mechanism is designed to provide an
- origin server with an approximation of the number of users that
- reference a given resource. The intent of the design is that the
- precision of this approximation is consistent with the goals of
- simplicity and optional implementation.
-
- Almost all Web users use client software that maintains local caches,
- and the state of the art of local-caching technology is quite
- effective. (Section 4.2 discusses the case where end-client caches
- are small or non-existent.) Therefore, assuming an effective and
- persistent end-client cache, each individual user who retrieves an
- entity does exactly one GET request that results in a 200 or 203
- response, or a 206 response that includes the first byte of the
- entity. If a proxy cache maintains and reports an accurate use-count
- of such retrievals, then its reported use-count will closely
- approximate the number of distinct users who have retrieved the
- entity.
-
- There are some circumstances under which this approximation can break
- down. For example, if an entity stays in a proxy cache for much
- longer than it persists in the typical client cache, and users often
- re-reference the entity, then this scheme will tend to over-count the
- number of users. Or, if the cache-management policy implemented in
- typical client caches is biased against retaining certain kinds of
- frequently re-referenced entities (such as very large images), the
- use-counts reported will tend to overestimate the user-counts for
- such entities.
-
- Browser log analysis has shown that when a user revisits a resource,
- this is almost always done very soon after the previous visit, almost
- always with fewer than eight intervening references [11]. Although
- this result might not apply universally, it implies that almost all
- reuses will hit in the end-client cache, and will not be seen as
- unconditional GETs by a proxy cache.
-
- The existing (HTTP/1.0) "cache-busting" mechanisms for counting
- distinct users will certainly overestimate the number of users behind
- a proxy, since it provides no reliable way to distinguish between a
- user's initial request and subsequent repeat requests that might have
- been conditional GETs, had not cache-busting been employed. The
-
-
-
-Mogul & Leach Standards Track [Page 18]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- "Cache-control: s-maxage=0" feature of HTTP/1.1 does allow the
- separation of use-counts and reuse-counts, provided that no HTTP/1.0
- proxy caches intervene.
-
- Note that if there is doubt about the validity of the results of
- hit-metering a given set of resources, the server can employ cache-
- busting techniques for short periods, to establish a baseline for
- validating the hit-metering results. Various approaches to this
- problem are discussed in a paper by James Pitkow [9].
-
-4.2 What about "Network Computers"?
-
- The analysis in section 4.1 assumed that "almost all Web users" have
- client caches. If the Network Computers (NC) model becomes popular,
- however, then this assumption may be faulty: most proposed NCs have
- no disk storage, and relatively little RAM. Many Personal Digital
- Assistants (PDAs), which sometimes have network access, have similar
- constraints. Such client systems may do little or no caching of HTTP
- responses. This means that a single user might well generate many
- unconditional GETs that yield the same response from a proxy cache.
-
- First note that the hit-metering design in this document, even with
- such clients, provides an approximation no worse than available with
- unmodified HTTP/1.1: the counts that a proxy would return to an
- origin server would represent exactly the number of requests that the
- proxy would forward to the server, if the server simply specifies
- "Cache-control: s-maxage=0".
-
- However, it may be possible to improve the accuracy of these hit-
- counts by use of some heuristics at the proxy. For example, the
- proxy might note the IP address of the client, and count only one GET
- per client address per response. This is not perfect: for example,
- it fails to distinguish between NCs and certain other kinds of hosts.
- The proxy might also use the heuristic that only those clients that
- never send a conditional GET should be treated this way, although we
- are not at all certain that NCs will never send conditional GETs.
-
- Since the solution to this problem appears to require heuristics
- based on the actual behavior of NCs (or perhaps a new HTTP protocol
- feature that allows unambiguous detection of cacheless clients), it
- appears to be premature to specify a solution.
-
-4.3 Critical-path delay analysis
-
- In systems (such as the Web) where latency is at issue, there is
- usually a tree of steps which depend on one another, in such a way
- that the final result cannot be accomplished until all of its
- predecessors have been. Since the tree structure admits some
-
-
-
-Mogul & Leach Standards Track [Page 19]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- parallelism, it is not necessary to add up the timings for each step
- to discover the latency for the entire process. But any single path
- through this dependency tree cannot be parallelized, and the longest
- such path is the one whose length (in units of seconds) determines
- the overall latency. This is the "critical path", because no matter
- how much shorter one makes any other path, that cannot change the
- overall latency for the final result.
-
- If one views the final result, for a Web request, as rendering a page
- at a browser, or otherwise acting on the result of a request, clearly
- some network round trips (e.g., exchanging TCP SYN packets if the
- connection doesn't already exist) are on the critical path. This
- hit-metering design does add some round-trips for reporting non-zero
- counts when a cache entry is removed, but, by design, these are off
- any critical path: they may be done in parallel with any other
- operation, and require only "best efforts", so a proxy does not have
- to serialize other operations with their success or failure.
-
- Clearly, anything that changes network utilization (either increasing
- or decreasing it) can indirectly affect user-perceived latency. Our
- expectation is that hit-metering, on average, will reduce loading and
- so even its indirect effects should not add network round-trips in
- any critical path. But there might be a few specific instances where
- the added non-critical-path operations (specifically, usage reports
- upon cache-entry removal) delay an operation on a critical path.
- This is an unavoidable problem in datagram networks.
-
-5 Specification
-
-5.1 Specification of Meter header and directives
-
- The Meter general-header field is used to:
-
- - Negotiate the use of hit-metering and usage-limiting among
- origin servers and proxy caches.
-
- - Report use counts and reuse counts.
-
- Implementation of the Meter header is optional for both proxies and
- origin servers. However, any proxy that transmits the Meter header
- in a request MUST implement every requirement of this specification,
- without exception or amendment.
-
- The Meter header MUST always be protected by a Connection header. A
- proxy that does not implement the Meter header MUST NOT pass it
- through to another system (see section 5.5 for how a non-caching
- proxy may comply with this specification). If a Meter header is
-
-
-
-
-Mogul & Leach Standards Track [Page 20]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- received in a message whose version is less than HTTP/1.1, it MUST be
- ignored (because it has clearly flowed through a proxy that does not
- implement Meter).
-
- A proxy that has received a response with a version less than
- HTTP/1.1, and therefore from a server (or another proxy) that does
- not implement the Meter header, SHOULD NOT send Meter request
- directives to that server, because these would simply waste
- bandwidth. This recommendation does not apply if the proxy is
- currently hit-metering or usage-limiting any responses from that
- server. If the proxy receives a HTTP/1.1 or higher response from
- such a server, it should cease its suppression of the Meter
- directives.
-
- All proxies sending the Meter header MUST adhere to the "metering
- subtree" design described in section 3.
-
- Meter = "Meter" ":" 0#meter-directive
-
- meter-directive = meter-request-directive
- | meter-response-directive
- | meter-report-directive
-
- meter-request-directive =
- "will-report-and-limit"
- | "wont-report"
- | "wont-limit"
-
- meter-report-directive =
- | "count" "=" 1*DIGIT "/" 1*DIGIT
-
- meter-response-directive =
- "max-uses" "=" 1*DIGIT
- | "max-reuses" "=" 1*DIGIT
- | "do-report"
- | "dont-report"
- | "timeout" "=" 1*DIGIT
- | "wont-ask"
-
- A meter-request-directive or meter-report-directive may only appear
- in an HTTP request message. A meter-response-directive may only
- appear in an HTTP response directive.
-
- An empty Meter header in a request means "Meter: will-report-and-
- limit". An empty Meter header in a response, or any other response
- including one or more Meter headers without the "dont-report" or
- "wont-ask" directive, implies "Meter: do-report".
-
-
-
-
-Mogul & Leach Standards Track [Page 21]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- The meaning of the meter-request-directives are as follows:
-
- will-report-and-limit
- indicates that the proxy is willing and able to
- return usage reports and will obey any usage-limits.
-
- wont-report indicates that the proxy will obey usage-limits but
- will not send usage reports.
-
- wont-limit indicates that the proxy will not obey usage-limits
- but will send usage reports.
-
- A proxy willing neither to obey usage-limits nor to send usage
- reports MUST NOT transmit a Meter header in the request.
-
- The meaning of the meter-report-directives are as follows:
-
- count "=" 1*DIGIT "/" 1*DIGIT
- Both digit strings encode decimal integers. The
- first integer indicates the count of uses of the
- cache entry since the last report; the second integer
- indicates the count of reuses of the entry.
-
- Section 5.3 specifies the counting rules.
-
- The meaning of the meter-response-directives are as follows:
-
- max-uses "=" 1*DIGIT
- sets an upper limit on the number of "uses" of the
- response, not counting its immediate forwarding to
- the requesting end-client, for all proxies in the
- following subtree taken together.
-
- max-reuses "=" 1*DIGIT
- sets an upper limit on the number of "reuses" of the
- response for all proxies in the following subtree
- taken together.
-
- do-report specifies that the proxy MUST send usage reports to
- the server.
-
- dont-report specifies that the proxy SHOULD NOT send usage
- reports to the server.
-
- timeout "=" 1*DIGIT
- sets a metering timeout of the specified number of
- minutes (not seconds) after the origination of this
- response (as indicated by its "Date" header). If the
-
-
-
-Mogul & Leach Standards Track [Page 22]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- proxy has a non-zero hit count for this response when
- the timeout expires, it MUST send a report to the
- server at or before that time. Timeouts should be
- implemented with an accuracy of plus or minus one
- minute. Implies "do-report".
-
- wont-ask specifies that the proxy SHOULD NOT send any Meter
- headers to the server. The proxy should forget this
- advice after a period of no more than 24 hours.
-
- Section 5.3 specifies the counting rules, and in particular specifies
- a somewhat non-obvious interpretation of the max-uses value.
-
-5.2 Abbreviations for Meter directives
-
- To allow for the most efficient possible encoding of Meter headers,
- we define abbreviated forms of all Meter directives. These are
- exactly semantically equivalent to their non-abbreviated
- counterparts. All systems implementing the Meter header MUST
- implement both the abbreviated and non-abbreviated forms.
- Implementations SHOULD use the abbreviated forms in normal use.
-
- The abbreviated forms of Meter directive are shown below, with the
- corresponding non-abbreviated literals in the comments:
-
- Abb-Meter = "Meter" ":" 0#abb-meter-directive
-
- abb-meter-directive = abb-meter-request-directive
- | abb-meter-response-directive
- | abb-meter-report-directive
-
- abb-meter-request-directive =
- "w" ; "will-report-and-limit"
- | "x" ; "wont-report"
- | "y" ; "wont-limit"
-
- abb-meter-report-directive =
- | "c" "=" 1*DIGIT "/" 1*DIGIT ; "count"
-
- abb-meter-response-directive =
- "u" "=" 1*DIGIT ; "max-uses"
- | "r" "=" 1*DIGIT ; "max-reuses"
- | "d" ; "do-report"
- | "e" ; "dont-report"
- | "t" "=" 1*DIGIT ; "timeout"
- | "n" ; "wont-ask"
-
-
-
-
-
-Mogul & Leach Standards Track [Page 23]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- Note: although the Abb-Meter BNF rule is defined separately from
- the Meter rule, one may freely mix abbreviated and non-abbreviated
- Meter directives in the same header.
-
-5.3 Counting rules
-
- Note: please remember that hit-counts and usage-counts are
- associated with individual responses, not with resources. A cache
- entry that, over its lifetime, holds more than one response is
- also not a "response", in this particular sense.
-
- Let R be a cached response, and V be the value of the Request-URI and
- selecting request-headers (if any, see section 14.43 of the HTTP/1.1
- specification [4]) that would select R if contained in a request. We
- define a "use" of R as occurring when the proxy returns its stored
- copy of R in a response with any of the following status codes: a 200
- (OK) status; a 203 (Non-Authoritative Information) status; or a 206
- (Partial Content) status when the response contains byte #0 of the
- entity (see section 5.4 for a discussion of Range requests).
-
- Note: when a proxy forwards a client's request and receives a
- response, the response that the proxy sends immediately to the
- requesting client is not counted as a "use". I.e., the reported
- count is the number of times the cache entry was used, and not the
- number of times that the response was used.
-
- We define a "reuse" of R as as occurring when the proxy responds to a
- request selecting R with a 304 (Not Modified) status, unless that
- request is a Range request that does not specify byte #0 of the
- entity.
-
-5.3.1 Counting rules for hit-metering
-
- A proxy participating in hit-metering for a cache response R
- maintains two counters, CU and CR, associated with R. When a proxy
- first stores R in its cache, it sets both CU and CR to 0 (zero).
- When a subsequent client request results in a "use" of R, the proxy
- increments CU. When a subsequent client request results in a "reuse"
- of R, the proxy increments CR. When a subsequent client request
- selecting R (i.e., including V) includes a "count" Meter directive,
- the proxy increments CU and CR using the corresponding values in the
- directive.
-
- When the proxy sends a request selecting R (i.e., including V) to the
- inbound server, it includes a "count" Meter directive with the
- current CU and CR as the parameter values. If this request was
- caused by the proxy's receipt of a request from a client, upon
- receipt of the server's response, the proxy sets CU and CR to the
-
-
-
-Mogul & Leach Standards Track [Page 24]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- number of uses and reuses, respectively, that may have occurred while
- the request was in progress. (These numbers are likely, but not
- certain, to be zero.) If the proxy's request was a final HEAD-based
- report, it need no longer maintain the CU and CR values, but it may
- also set them to the number of intervening uses and reuses and retain
- them.
-
-5.3.2 Counting rules for usage-limiting
-
- A proxy participating in usage-limiting for a response R maintains
- either or both of two counters TU and TR, as appropriate, for that
- resource. TU and TR are incremented in just the same way as CU and
- CR, respectively. However, TU is zeroed only upon receipt of a
- "max-uses" Meter directive for that response (including the initial
- receipt). Similarly, TR is zeroed only upon receipt of a "max-
- reuses" Meter directive for that response.
-
- A proxy participating in usage-limiting for a response R also stores
- values MU and/or MR associated with R. When it receives a response
- including only a max-uses value, it sets MU to that value and MR to
- infinity. When it receives a response including only a max-reuses
- value, it sets MR to that value and MU to infinity. When it receives
- a response including both max-reuses and max-reuses values, it sets
- MU and MR to those values, respectively. When it receives a
- subsequent response including neither max-reuses nor max-reuses
- values, it sets both MU and MR to infinity.
-
- If a proxy participating in usage-limiting for a response R receives
- a request that would cause a "use" of R, and TU >= MU, it MUST
- forward the request to the server. If it receives a request that
- would cause a "reuse" of R, and TR >= MR, it MUST forward the request
- to the server. If (in either case) the proxy has already forwarded a
- previous request to the server and is waiting for the response, it
- should delay further handling of the new request until the response
- arrives (or times out); it SHOULD NOT have two revalidation requests
- pending at once that select the same response, unless these are Range
- requests selecting different subranges.
-
- There is a special case of this rule for the "max-uses" directive: if
- the proxy receives a response with "max-uses=0" and does not forward
- it to a requesting client, the proxy should set a flag PF associated
- with R. If R is true, then when a request arrives while if TU >= MU,
- if the PF flag is set, then the request need not be forwarded to the
- server (provided that this is not required by other caching rules).
- However, the PF flag MUST be cleared on any use of the response.
-
-
-
-
-
-
-Mogul & Leach Standards Track [Page 25]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- Note: the "PF" flag is so named because this feature is useful
- only for caches that could issue a "prefetch" request before an
- actual client request for the response. A proxy not implementing
- prefetching need not implement the PF flag.
-
-5.3.3 Equivalent algorithms are allowed
-
- Any other algorithm that exhibits the same external behavior (i.e.,
- generates exactly the same requests from the proxy to the server) as
- the one in this section is explicitly allowed.
-
- Note: in most cases, TU will be equal to CU, and TR will be
- equal to CR. The only two cases where they could differ are:
-
- 1. The proxy issues a non-conditional request for the
- resource using V, while TU and/or TR are non-zero, and
- the server's response includes a new "max-uses" and/or
- "max-reuses" directive (thus zeroing TU and/or TR, but
- not CU and CR).
-
- 2. The proxy issues a conditional request reporting the
- hit-counts (and thus zeroing CU and CR, but not TU or
- TR), but the server's response does not include a new
- "max-uses" and/or "max-reuses" directive.
-
- To solve the first case, the proxy has several implementation
- options
-
- - Always store TU and TR separately from CU and CR.
-
- - Create "shadow" copies of TU and TR when this situation
- arises (analogous to "copy on write").
-
- - Generate a HEAD-based usage report when the
- non-conditional request is sent (or when the
- "max-uses=0" is received), causing CU and CR to be
- zeroed (analogous in some ways to a "memory barrier"
- instruction).
-
- In the second case, the server implicitly has removed the
- usage-limit(s) on the response (by setting MU and/or MR to
- infinity), and so the fact that, say, TU is different from CU
- is not significant.
-
- Note: It may also be possible to eliminate the PF flag by
- sending extra HEAD-based usage-report requests, but we
- recommend against this; it is better to allocate an extra bit
- per entry than to transmit extra requests.
-
-
-
-Mogul & Leach Standards Track [Page 26]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
-5.4 Counting rules: interaction with Range requests
-
-
- HTTP/1.1 allows a client to request sub-ranges of a resource. A
- client might end up issuing several requests with the net effect of
- receiving one copy of the resource. For uniformity of the results
- seen by origin servers, proxies need to observe a rule for counting
- these references, although it is not clear that one rule generates
- accurate results in every case.
-
- The rule established in this specification is that proxies count as a
- "use" or "reuse" only those Range requests that result in the return
- of byte #0 of the resource. The rationale for this rule is that in
- almost every case, an end-client will retrieve the beginning of any
- resource that it references at all, and that it will seldom retrieve
- any portion more than once. Therefore, this rule appears to meet the
- goal of a "best-efforts" approximation.
-
-5.5 Implementation by non-caching proxies
-
- A non-caching proxy may participate in the metering subtree; this is
- strongly recommended.
-
- A non-caching proxy (HTTP/1.1 or higher) that participates in the
- metering subtree SHOULD forward Meter headers on both requests and
- responses, with the appropriate Connection headers.
-
- If a non-caching proxy forwards Meter headers, it MUST comply with
- these restrictions:
-
- 1. If the proxy forwards Meter headers in responses, such a
- response MUST NOT be returned to any request except the
- one that elicited it.
-
- 2. Once a non-caching proxy starts forwarding Meter headers,
- it should not arbitrarily stop forwarding them (or else
- reports may be lost).
-
- A proxy that caches some responses and not others, for whatever
- reason, may choose to implement the Meter header as a caching proxy
- for the responses that it caches, and as a non-caching proxy for the
- responses that it does not cache, as long as its external behavior
- with respect to any particularly response is fully consistent with
- this specification.
-
-
-
-
-
-
-
-Mogul & Leach Standards Track [Page 27]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
-5.6 Implementation by cooperating caches
-
- Several HTTP cache implementations, most notably the Harvest/Squid
- cache [2], create cooperative arrangements between several caches.
- If such caches use a protocol other than HTTP to communicate between
- themselves, such as the Internet Cache Protocol (ICP) [12], and if
- they implement the Meter header, then they MUST act to ensure that
- their cooperation does not violate the intention of this
- specification.
-
- In particular, if one member of a group of cooperating caches agrees
- with a server to hit-meter a particular response, and then passes
- this response via a non-HTTP protocol to a second cache in the group,
- the caches MUST ensure that the server which requested the metering
- receives reports that appropriately account for any uses or resues
- made by the second cache. Similarly, if the first cache agreed to
- usage-limit the response, the total number of uses by the group of
- caches MUST be limited to the agreed-upon number.
-
-6 Examples
-
-6.1 Example of a complete set of exchanges
-
- This example shows how the protocol is intended to be used most of
- the time: for hit-metering without usage-limiting. Entity bodies are
- omitted.
-
- A client sends request to a proxy:
-
- GET http://foo.com/bar.html HTTP/1.1
-
- The proxy forwards request to the origin server:
-
- GET /bar.html HTTP/1.1
- Host: foo.com
- Connection: Meter
-
- thus offering (implicitly) "will-report-and-limit".
-
- The server responds to the proxy:
-
- HTTP/1.1 200 OK
- Date: Fri, 06 Dec 1996 18:44:29 GMT
- Cache-control: max-age=3600
- Connection: meter
- Etag: "abcde"
-
-
-
-
-
-Mogul & Leach Standards Track [Page 28]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- thus (implicitly) requiring "do-report" (but not requiring
- usage-limiting).
-
- The proxy responds to the client:
-
- HTTP/1.1 200 OK
- Date: Fri, 06 Dec 1996 18:44:29 GMT
- Etag: "abcde"
- Cache-control: max-age=3600, proxy-mustcheck
- Age: 1
-
- Since the proxy does not know if its client is an end-system, or a
- proxy that doesn't do metering, it adds the "proxy-mustcheck"
- directive.
-
- Another client soon asks for the resource:
-
- GET http://foo.com/bar.html HTTP/1.1
-
- and the proxy sends the same response as it sent to the other client,
- except (perhaps) for the Age value.
-
- After an hour has passed, a third client asks for the response:
-
- GET http://foo.com/bar.html HTTP/1.1
-
- But now the response's max-age has been exceeded, so the proxy
- revalidates the response with the origin server:
-
- GET /bar.html HTTP/1.1
- If-None-Match: "abcde"
- Host: foo.com
- Connection: Meter
- Meter: count=1/0
-
- thus simultaneously fulfilling its duties to validate the response
- and to report the one "use" that wasn't forwarded.
-
- The origin server responds:
-
- HTTP/1.1 304 Not Modified
- Date: Fri, 06 Dec 1996 19:44:29 GMT
- Cache-control: max-age=3600
- Etag: "abcde"
-
- so the proxy can use the original response to reply to the new
- client; the proxy also zeros the use-count it associates with that
- response.
-
-
-
-Mogul & Leach Standards Track [Page 29]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- Another client soon asks for the resource:
-
- GET http://foo.com/bar.html HTTP/1.1
-
- and the proxy sends the appropriate response.
-
- After another few hours, the proxy decides to remove the cache entry.
- When it does so, it sends to the origin server:
-
- HEAD /bar.html HTTP/1.1
- If-None-Match: "abcde"
- Host: foo.com
- Connection: Meter
- Meter: count=1/0
-
- reporting that one more use of the response was satisfied from the
- cache.
-
-6.2 Protecting against HTTP/1.0 proxies
-
- An origin server that does not want HTTP/1.0 caches to store the
- response at all, and is willing to have HTTP/1.0 end-system clients
- generate excess GETs (which will be forwarded by HTTP/1.0 proxies)
- could send this for its reply:
-
- HTTP/1.1 200 OK
- Cache-control: max-age=3600
- Connection: meter
- Etag: "abcde"
- Expires: Sun, 06 Nov 1994 08:49:37 GMT
-
- HTTP/1.0 caches will see the ancient Expires header, but HTTP/1.1
- caches will see the max-age directive and will ignore Expires.
-
- Note: although most major HTTP/1.0 proxy implementations observe
- the Expires header, it is possible that some are in use that do
- not. Use of the Expires header to prevent caching by HTTP/1.0
- proxies might not be entirely reliable.
-
-6.3 More elaborate examples
-
- Here is a request from a proxy that is willing to hit-meter but is
- not willing to usage-limit:
-
- GET /bar.html HTTP/1.1
- Host: foo.com
- Connection: Meter
- Meter: wont-limit
-
-
-
-Mogul & Leach Standards Track [Page 30]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- Here is a response from an origin server that does not want hit
- counting, but does want "uses" limited to 3, and "reuses" limited to
- 6:
-
- HTTP/1.1 200 OK
- Cache-control: max-age=3600
- Connection: meter
- Etag: "abcde"
- Expires: Sun, 06 Nov 1994 08:49:37 GMT
- Meter: max-uses=3, max-reuses=6, dont-report
-
- Here is the same example with abbreviated Meter directive names:
-
- HTTP/1.1 200 OK
- Cache-control: max-age=3600
- Connection: meter
- Etag: "abcde"
- Expires: Sun, 06 Nov 1994 08:49:37 GMT
- Meter:u=3,r=6,e
-
-7 Interactions with content negotiation
-
- This section describes two aspects of the interaction between hit-
- metering and "content-negotiated" resources:
-
- 1. treatment of responses carrying a Vary header (section
- 7.1).
-
- 2. treatment of responses that use the proposed Transparent
- Content Negotiation mechanism (section 7.2).
-
-7.1 Treatment of responses carrying a Vary header
-
- Separate counts should be kept for each combination of the headers
- named in the Vary header for the Request-URI (what [4] calls "the
- selecting request-headers"), even if they map to the same entity-tag.
- This rule has the effect of counting hits on each variant, if there
- are multiple variants of a page available.
-
- Note: This interaction between Vary and the hit-counting
- directives allows the origin server a lot of flexibility in
- specifying how hits should be counted. In essence, the origin
- server uses the Vary mechanism to divide the requests for a
- resource into arbitrary categories, based on the request- headers.
- (We will call these categories "request-patterns".) Since a proxy
- keeps its hit-counts for each request-pattern, rather than for
- each resource, the origin server can obtain separate statistics
- for many aspects of an HTTP request.
-
-
-
-Mogul & Leach Standards Track [Page 31]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- For example, if a page varied based on the value of the User-Agent
- header in the requests, then hit counts would be kept for each
- different flavor of browser. But it is in fact more general than
- that; because multiple header combinations can map to the same
- variant, it also enables the origin server to count the number of
- times (e.g.) the Swahili version of a page was requested, even though
- it is only available in English.
-
- If a proxy does not support the Vary mechanism, then [4] says that it
- MUST NOT cache any response that carries a Vary header, and hence
- need not implement any aspect of this hit-counting or usage-limiting
- design for varying resources.
-
- Note: this also implies that if a proxy supports the Vary
- mechanism but is not willing to maintain independent hit-counts
- for each variant response in its cache, then it must follow at
- least one of these rules:
-
- 1. It must not use the Meter header in a request to offer
- to hit-meter or usage-limit responses.
-
- 2. If it does offer to hit-meter or usage-limit responses,
- and then receives a response that includes both a Vary
- header and a Meter header with a directive that it
- cannot satisfy, then the proxy must not cache the
- response.
-
- In other words, a proxy is allowed to partially implement the
- Vary mechanism with respect to hit-metering, as long as this has
- no externally visible effect on its ability to comply with the
- Meter specification.
-
- This approach works for counting almost any aspect of the request
- stream, without embedding any specific list of countable aspects in
- the specification or proxy implementation.
-
-7.2 Interaction with Transparent Content Negotiation
-
- [A description of the interaction between this design and the
- proposed Transparent Content Negotiation (TCN) design [6] will be
- made available in a later document.]
-
-8 A Note on Capturing Referrals
-
- It is alleged that some advertisers want to pay content providers,
- not by the "hit", but by the "nibble" -- the number of people who
- actually click on the ad to get more information.
-
-
-
-
-Mogul & Leach Standards Track [Page 32]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- Now, HTTP already has a mechanism for doing this: the "Referer"
- header. However, perhaps it ought to be disabled for privacy reasons
- -- according the HTTP/1.1 spec:
-
- "Because the source of the link may be private information or may
- 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."
-
- However, in the case of ads, the source of the link actually wants to
- let the referred-to page know where the reference came from.
-
- This does not require the addition of any extra mechanism, but rather
- can use schemes that embed the referrer in the URI in a manner
- similar to this:
-
- http://www.blah.com/ad-reference?from=site1
-
- Such a URI should point to a resource (perhaps a CGI script) which
- returns a 302 redirect to the real page
-
- http://www.blah.com/ad-reference.html
-
- Proxies which do not cache 302s will cause one hit on the redirection
- page per use, but the real page will get cached. Proxies which do
- cache 302s and report hits on the cached 302s will behave optimally.
-
- This approach has the advantage that it works whether or not the
- end-client has disabled the use of Referer. Combined with the rest
- of the hit-metering proposal in this design, this approach allows,
- for example, an advertiser to know how often a reference to an
- advertisement was made from a particular page.
-
-9 Alternative proposals
-
- There might be a number of other ways of gathering demographic and
- usage information; other mechanisms might respond to a different set
- of needs than this proposal does. This proposal certainly does not
- preclude the proposal or deployment of other such mechanisms, and
- many of them may be complementary to and compatible with the
- mechanism proposed here.
-
- There has been some speculation that statistical sampling methods
- might be used to gather reasonably accurate data. One such proposal
- is to manipulate cache expiration times so that selected resources
- are uncachable for carefully chosen periods, allowing servers to
- accurately count accesses during those periods. The hit-metering
- mechanism proposed here is entirely complementary to that approach,
-
-
-
-Mogul & Leach Standards Track [Page 33]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- since it could be used to reduce the cost of gathering those counts.
- James Pitkow has written a paper comparing an earlier draft of this
- hit-metering proposal with sampling approaches [9].
-
- Phillip Hallam-Baker has proposed using a log-exchange protocol [5],
- by which a server could request a proxy's logs by making an HTTP
- request to the proxy. This proposal asserts that it is "believed to
- operate correctly in configurations involving multiple proxies", but
- it is not clear that this is true if an outer proxy is used as a
- (one-way) firewall. The proposal also leaves a number of open
- issues, such as how an origin server can be sure that all of the
- proxies in the request subtree actually support log-exchange. It is
- also not clear how this proposal couples a proxy's support of log-
- exchange to a server's permission to cache a response.
-
- For general background on the topic of Web measurement standards, see
- the discussion by Thomas P. Novak and Donna L. Hoffman [8]. Also see
- the "Privacy and Demographics Overview" page maintained by by the
- World Wide Web Consortium [10], which includes a pointer to some
- tentative proposals for gathering consumer demographics (not just
- counting references) [3].
-
-10 Security Considerations
-
- Which outbound clients should a server (proxy or origin) trust to
- report hit counts? A malicious proxy could easily report a large
- number of hits on some page, and thus perhaps cause a large payment
- to a content provider from an advertiser. To help avoid this
- possibility, a proxy may choose to only relay usage counts received
- from its outbound proxies to its inbound servers when the proxies
- have authenticated themselves using Proxy-Authorization and/or they
- are on a list of approved proxies.
-
- It is not possible to enforce usage limits if a proxy is willing to
- cheat (i.e., it offers to limit usage but then ignores a server's
- Meter directive).
-
- Regarding privacy: it appears that the design in this document does
- not reveal any more information about individual users than would
- already be revealed by implementation of the existing HTTP/1.1
- support for "Cache-control: max-age=0, proxy-revalidate" or "Cache-
- control: s-maxage=0". It may, in fact, help to conceal certain
- aspects of the organizational structure on the outbound side of a
- proxy. In any case, the conflict between user requirements for
- anonymity and origin server requirements for demographic information
- cannot be resolved by purely technical means.
-
-
-
-
-
-Mogul & Leach Standards Track [Page 34]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
-11 Acknowledgments
-
- We gratefully acknowledge the constructive comments received from
- Anselm Baird-Smith, Ted Hardie, Koen Holtman (who suggested the
- technique described in section 8), Dave Kristol, Ari Luotonen,
- Patrick R. McManus, Ingrid Melve, and James Pitkow.
-
-12 References
-
- 1. Bradner, S., "Key words for use in RFCs to Indicate Requirement
- Levels", BCP 14, RFC 2119, March 1997.
-
- 2. Anwat Chankhunthod, Peter B. Danzig, Chuck Neerdaels, Michael
- F. Schwartz, and Kurt J. Worrell. A Hierarchical Internet Object
- Cache. Proc. 1996 USENIX Technical Conf., San Diego, January,
- 1996, pp. 153-163.
-
- 3. Daniel W. Connolly. Proposals for Gathering Consumer
- Demographics.
- http://www.w3.org/pub/WWW/Demographics/Proposals.html.
-
- 4. Fielding, R., Gettys, J., Mogul, J., Nielsen, H. and T.
- Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1," RFC 2068,
- January, 1997.
-
- 5. Phillip M. Hallam-Baker. Notification for Proxy Caches. W3C
- Working Draft WD-proxy-960221, World Wide Web Consortium,
- February, 1996. http://www.w3.org/pub/WWW/TR/WD-proxy.html.
-
- 6. Holtman, K., and A. Mutz, "Transparent Content Negotiation in
- HTTP", Work in Progress.
-
- 7. Mogul, J., "Forcing HTTP/1.1 proxies to revalidate responses",
- Work in Progress.
-
- 8. Thomas P. Novak and Donna L. Hoffman. New Metrics for New Media:
- Toward the Development of Web Measurement Standards. This is a
- draft paper, currently available at http://
- www2000.ogsm.vanderbilt.edu/novak/web.standards/webstand.html.
- Cited by permission of the author; do not quote or cite without
- permission.
-
- 9. James Pitkow. In search of reliable usage data on the WWW.
- Proc. Sixth International World Wide Web Conference, Santa Clara,
- CA, April, 1997.
-
-
-
-
-
-
-Mogul & Leach Standards Track [Page 35]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
- 10. Joseph Reagle, Rohit Khare, Dan Connolly, and Tim Berners-Lee.
- Privacy and Demographics Overview.
- http://www.w3.org/pub/WWW/Demographics/.
-
- 11. Linda Tauscher and Saul Greenberg. Revisitation Patterns in
- World Wide Web Navigation. Research Report 96/587/07, Department
- of Computer Science, University of Calgary, March, 1996.
- http://www.cpsc.ucalgary.ca/projects/grouplab/
- papers/96WebReuse/TechReport96.html.
-
- 12. Wessels, D., and K. Claffy "Internet Cache Protocol (ICP),
- version 2", RFC 2186, September 1997.
-
-13 Authors' Addresses
-
- Jeffrey C. Mogul
- Western Research Laboratory
- Digital Equipment Corporation
- 250 University Avenue
- Palo Alto, California, 94305, U.S.A.
-
- EMail: mogul@wrl.dec.com
- Phone: 1 415 617 3304 (email preferred)
-
-
- Paul J. Leach
- Microsoft
- 1 Microsoft Way
- Redmond, Washington, 98052, U.S.A.
-
- EMail: paulle@microsoft.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Mogul & Leach Standards Track [Page 36]
-\f
-RFC 2227 Hit-Metering and Usage-Limiting October 1997
-
-
-14 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Mogul & Leach Standards Track [Page 37]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group M. Allman
-Request for Comments: 2428 NASA Lewis/Sterling Software
-Category: Standards Track S. Ostermann
- Ohio University
- C. Metz
- The Inner Net
- September 1998
-
-
- FTP Extensions for IPv6 and NATs
-
-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 (1998). All Rights Reserved.
-
-Abstract
-
- The specification for the File Transfer Protocol assumes that the
- underlying network protocol uses a 32-bit network address
- (specifically IP version 4). With the deployment of version 6 of the
- Internet Protocol, network addresses will no longer be 32-bits. This
- paper specifies extensions to FTP that will allow the protocol to
- work over IPv4 and IPv6. In addition, the framework defined can
- support additional network protocols in the future.
-
-1. Introduction
-
- The keywords, such as MUST and SHOULD, found in this document are
- used as defined in RFC 2119 [Bra97].
-
- The File Transfer Protocol [PR85] only provides the ability to
- communicate information about IPv4 data connections. FTP assumes
- network addresses will be 32 bits in length. However, with the
- deployment of version 6 of the Internet Protocol [DH96] addresses
- will no longer be 32 bits long. RFC 1639 [Pis94] specifies
- extensions to FTP to enable its use over various network protocols.
- Unfortunately, the mechanism can fail in a multi-protocol
- environment. During the transition between IPv4 and IPv6, FTP needs
- the ability to negotiate the network protocol that will be used for
- data transfer.
-
-
-
-Allman, et. al. Standards Track [Page 1]
-\f
-RFC 2428 FTP Extensions for IPv6 and NATs September 1998
-
-
- This document provides a specification for a way that FTP can
- communicate data connection endpoint information for network
- protocols other than IPv4. In this specification, the FTP commands
- PORT and PASV are replaced with EPRT and EPSV, respectively. This
- document is organized as follows. Section 2 outlines the EPRT
- command and Section 3 outlines the EPSV command. Section 4 defines
- the utilization of these two new FTP commands. Section 5 briefly
- presents security considerations. Finally, Section 6 provides
- conclusions.
-
-2. The EPRT Command
-
- The EPRT command allows for the specification of an extended address
- for the data connection. The extended address MUST consist of the
- network protocol as well as the network and transport addresses. The
- format of EPRT is:
-
- EPRT<space><d><net-prt><d><net-addr><d><tcp-port><d>
-
- The EPRT command keyword MUST be followed by a single space (ASCII
- 32). Following the space, a delimiter character (<d>) MUST be
- specified. The delimiter character MUST be one of the ASCII
- characters in range 33-126 inclusive. The character "|" (ASCII 124)
- is recommended unless it coincides with a character needed to encode
- the network address.
-
- The <net-prt> argument MUST be an address family number defined by
- IANA in the latest Assigned Numbers RFC (RFC 1700 [RP94] as of the
- writing of this document). This number indicates the protocol to be
- used (and, implicitly, the address length). This document will use
- two of address family numbers from [RP94] as examples, according to
- the following table:
-
- AF Number Protocol
- --------- --------
- 1 Internet Protocol, Version 4 [Pos81a]
- 2 Internet Protocol, Version 6 [DH96]
-
- The <net-addr> is a protocol specific string representation of the
- network address. For the two address families specified above (AF
- Number 1 and 2), addresses MUST be in the following format:
-
- AF Number Address Format Example
- --------- -------------- -------
- 1 dotted decimal 132.235.1.2
- 2 IPv6 string 1080::8:800:200C:417A
- representations
- defined in [HD96]
-
-
-
-Allman, et. al. Standards Track [Page 2]
-\f
-RFC 2428 FTP Extensions for IPv6 and NATs September 1998
-
-
- The <tcp-port> argument must be the string representation of the
- number of the TCP port on which the host is listening for the data
- connection.
-
- The following are sample EPRT commands:
-
- EPRT |1|132.235.1.2|6275|
-
- EPRT |2|1080::8:800:200C:417A|5282|
-
- The first command specifies that the server should use IPv4 to open a
- data connection to the host "132.235.1.2" on TCP port 6275. The
- second command specifies that the server should use the IPv6 network
- protocol and the network address "1080::8:800:200C:417A" to open a
- TCP data connection on port 5282.
-
- Upon receipt of a valid EPRT command, the server MUST return a code
- of 200 (Command OK). The standard negative error code 500 and 501
- [PR85] are sufficient to handle most errors (e.g., syntax errors)
- involving the EPRT command. However, an additional error code is
- needed. The response code 522 indicates that the server does not
- support the requested network protocol. The interpretation of this
- new error code is:
-
- 5yz Negative Completion
- x2z Connections
- xy2 Extended Port Failure - unknown network protocol
-
- The text portion of the response MUST indicate which network
- protocols the server does support. If the network protocol is
- unsupported, the format of the response string MUST be:
-
- <text stating that the network protocol is unsupported> \
- (prot1,prot2,...,protn)
-
- Both the numeric code specified above and the protocol information
- between the characters '(' and ')' are intended for the software
- automata receiving the response; the textual message between the
- numeric code and the '(' is intended for the human user and can be
- any arbitrary text, but MUST NOT include the characters '(' and ')'.
- In the above case, the text SHOULD indicate that the network protocol
- in the EPRT command is not supported by the server. The list of
- protocols inside the parenthesis MUST be a comma separated list of
- address family numbers. Two example response strings follow:
-
- Network protocol not supported, use (1)
-
- Network protocol not supported, use (1,2)
-
-
-
-Allman, et. al. Standards Track [Page 3]
-\f
-RFC 2428 FTP Extensions for IPv6 and NATs September 1998
-
-
-3. The EPSV Command
-
- The EPSV command requests that a server listen on a data port and
- wait for a connection. The EPSV command takes an optional argument.
- The response to this command includes only the TCP port number of the
- listening connection. The format of the response, however, is
- similar to the argument of the EPRT command. This allows the same
- parsing routines to be used for both commands. In addition, the
- format leaves a place holder for the network protocol and/or network
- address, which may be needed in the EPSV response in the future. The
- response code for entering passive mode using an extended address
- MUST be 229. The interpretation of this code, according to [PR85]
- is:
-
- 2yz Positive Completion
- x2z Connections
- xy9 Extended Passive Mode Entered
-
- The text returned in response to the EPSV command MUST be:
-
- <text indicating server is entering extended passive mode> \
- (<d><d><d><tcp-port><d>)
-
- The portion of the string enclosed in parentheses MUST be the exact
- string needed by the EPRT command to open the data connection, as
- specified above.
-
- The first two fields contained in the parenthesis MUST be blank. The
- third field MUST be the string representation of the TCP port number
- on which the server is listening for a data connection. The network
- protocol used by the data connection will be the same network
- protocol used by the control connection. In addition, the network
- address used to establish the data connection will be the same
- network address used for the control connection. An example response
- string follows:
-
- Entering Extended Passive Mode (|||6446|)
-
- The standard negative error codes 500 and 501 are sufficient to
- handle all errors involving the EPSV command (e.g., syntax errors).
-
- When the EPSV command is issued with no argument, the server will
- choose the network protocol for the data connection based on the
- protocol used for the control connection. However, in the case of
- proxy FTP, this protocol might not be appropriate for communication
- between the two servers. Therefore, the client needs to be able to
- request a specific protocol. If the server returns a protocol that
- is not supported by the host that will be connecting to the port, the
-
-
-
-Allman, et. al. Standards Track [Page 4]
-\f
-RFC 2428 FTP Extensions for IPv6 and NATs September 1998
-
-
- client MUST issue an ABOR (abort) command to allow the server to
- close down the listening connection. The client can then send an
- EPSV command requesting the use of a specific network protocol, as
- follows:
-
- EPSV<space><net-prt>
-
- If the requested protocol is supported by the server, it SHOULD use
- the protocol. If not, the server MUST return the 522 error messages
- as outlined in section 2.
-
- Finally, the EPSV command can be used with the argument "ALL" to
- inform Network Address Translators that the EPRT command (as well as
- other data commands) will no longer be used. An example of this
- command follows:
-
- EPSV<space>ALL
-
- Upon receipt of an EPSV ALL command, the server MUST reject all data
- connection setup commands other than EPSV (i.e., EPRT, PORT, PASV, et
- al.). This use of the EPSV command is further explained in section
- 4.
-
-4. Command Usage
-
- For all FTP transfers where the control and data connection(s) are
- being established between the same two machines, the EPSV command
- MUST be used. Using the EPSV command benefits performance of
- transfers that traverse firewalls or Network Address Translators
- (NATs). RFC 1579 [Bel94] recommends using the passive command when
- behind firewalls since firewalls do not generally allow incoming
- connections (which are required when using the PORT (EPRT) command).
- In addition, using EPSV as defined in this document does not require
- NATs to change the network address in the traffic as it is forwarded.
- The NAT would have to change the address if the EPRT command was
- used. Finally, if the client issues an "EPSV ALL" command, NATs may
- be able to put the connection on a "fast path" through the
- translator, as the EPRT command will never be used and therefore,
- translation of the data portion of the segments will never be needed.
- When a client only expects to do two-way FTP transfers, it SHOULD
- issue this command as soon as possible. If a client later finds that
- it must do a three-way FTP transfer after issuing an EPSV ALL
- command, a new FTP session MUST be started.
-
-
-
-
-
-
-
-
-Allman, et. al. Standards Track [Page 5]
-\f
-RFC 2428 FTP Extensions for IPv6 and NATs September 1998
-
-
-5. Security Issues
-
- The authors do not believe that these changes to FTP introduce new
- security problems. A companion Work in Progress [AO98] is a more
- general discussion of FTP security issues and techniques to reduce
- these security problems.
-
-6. Conclusions
-
- The extensions specified in this paper will enable FTP to operate
- over a variety of network protocols.
-
-References
-
- [AO98] Allman, M., and S. Ostermann, "FTP Security
- Considerations", Work in Progress.
-
- [Bel94] Bellovin, S., "Firewall-Friendly FTP", RFC 1579, February
- 1994.
-
- [Bra97] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [DH96] Deering, S., and R. Hinden, "Internet Protocol, Version 6
- (IPv6) Specification", RFC 1883, December 1995.
-
- [HD96] Hinden, R., and S. Deering, "IP Version 6 Addressing
- Architecture", RFC 2373, July 1998.
-
- [Pis94] Piscitello, D., "FTP Operation Over Big Address Records
- (FOOBAR)", RFC 1639, June 1994.
-
- [Pos81a] Postel, J., "Internet Protocol", STD 5, RFC 791, September
- 1981.
-
- [Pos81b] Postel, J., "Transmission Control Protocol", STD 7, RFC 793,
- September 1981.
-
- [PR85] Postel, J., and J. Reynolds, "File Transfer Protocol (FTP)",
- STD 9, RFC 959, October 1985.
-
- [RP94] Reynolds, J., and J. Postel, "Assigned Numbers", STD 2, RFC
- 1700, October 1994. See also:
- http://www.iana.org/numbers.html
-
-
-
-
-
-
-
-Allman, et. al. Standards Track [Page 6]
-\f
-RFC 2428 FTP Extensions for IPv6 and NATs September 1998
-
-
-Authors' Addresses
-
- Mark Allman
- NASA Lewis Research Center/Sterling Software
- 21000 Brookpark Rd. MS 54-2
- Cleveland, OH 44135
-
- Phone: (216) 433-6586
- EMail: mallman@lerc.nasa.gov
- http://gigahertz.lerc.nasa.gov/~mallman/
-
-
- Shawn Ostermann
- School of Electrical Engineering and Computer Science
- Ohio University
- 416 Morton Hall
- Athens, OH 45701
-
- Phone: (740) 593-1234
- EMail: ostermann@cs.ohiou.edu
-
-
- Craig Metz
- The Inner Net
- Box 10314-1954
- Blacksburg, VA 24062-0314
-
- Phone: (DSN) 754-8590
- EMail: cmetz@inner.net
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Allman, et. al. Standards Track [Page 7]
-\f
-RFC 2428 FTP Extensions for IPv6 and NATs September 1998
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (1998). 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Allman, et. al. Standards Track [Page 8]
-\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 P. Vixie
-Request for Comments: 2756 ISC
-Category: Experimental D. Wessels
- NLANR
- January 2000
-
-
- Hyper Text Caching Protocol (HTCP/0.0)
-
-
-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 (2000). All Rights Reserved.
-
-Abstract
-
- This document describes HTCP, a protocol for discovering HTTP caches
- and cached data, managing sets of HTTP caches, and monitoring cache
- activity. This is an experimental protocol, one among several
- proposals to perform these functions.
-
-1. Definitions, Rationale and Scope
-
- 1.1. HTTP/1.1 (see [RFC2616]) permits the transfer of web objects
- from "origin servers," possibly via "proxies" (which are allowed
- under some circumstances to "cache" such objects for subsequent
- reuse) to "clients" which consume the object in some way, usually by
- displaying it as part of a "web page." HTTP/1.0 and later permit
- "headers" to be included in a request and/or a response, thus
- expanding upon the HTTP/0.9 (and earlier) behaviour of specifying
- only a URI in the request and offering only a body in the response.
-
- 1.2. ICP (see [RFC2186]) permits caches to be queried as to their
- content, usually by other caches who are hoping to avoid an expensive
- fetch from a distant origin server. ICP was designed with HTTP/0.9
- in mind, such that only the URI (without any headers) is used when
- describing cached content, and the possibility of multiple compatible
- bodies for the same URI had not yet been imagined.
-
-
-
-
-
-
-Vixie & Wessels Experimental [Page 1]
-\f
-RFC 2756 Hyper Text Caching Protocol (HTCP/0.0) January 2000
-
-
- 1.3. This document specifies a Hyper Text Caching Protocol (HTCP)
- which permits full request and response headers to be used in cache
- management, and expands the domain of cache management to include
- monitoring a remote cache's additions and deletions, requesting
- immediate deletions, and sending hints about web objects such as the
- third party locations of cacheable objects or the measured
- uncacheability or unavailability of web objects.
-
-2. HTCP Protocol
-
- 2.1. All multi-octet HTCP protocol elements are transmitted in
- network byte order. All RESERVED fields should be set to binary zero
- by senders and left unexamined by receivers. Headers must be
- presented with the CRLF line termination, as in HTTP.
-
- 2.2. Any hostnames specified should be compatible between sender and
- receiver, such that if a private naming scheme (such as HOSTS.TXT or
- NIS) is in use, names depending on such schemes will only be sent to
- HTCP neighbors who are known to participate in said schemes. Raw
- addresses (dotted quad IPv4, or colon-format IPv6) are universal, as
- are public DNS names. Use of private names or addresses will require
- special operational care.
-
- 2.3. HTCP messages may be sent as UDP datagrams, or over TCP
- connections. UDP must be supported. HTCP agents must not be
- isolated from NETWORK failures and delays. An HTCP agent should be
- prepared to act in useful ways when no response is forthcoming, or
- when responses are delayed or reordered or damaged. TCP is optional
- and is expected to be used only for protocol debugging. The IANA has
- assigned port 4827 as the standard TCP and UDP port number for HTCP.
-
- 2.4. A set of configuration variables concerning transport
- characteristics should be maintained for each agent which is capable
- of initiating HTCP transactions, perhaps with a set of per-agent
- global defaults. These variables are:
-
- Maximum number of unacknowledged transactions before a "failure" is
- imputed.
-
- Maximum interval without a response to some transaction before a
- "failure" is imputed.
-
- Minimum interval before trying a new transaction after a failure.
-
-
-
-
-
-
-
-
-Vixie & Wessels Experimental [Page 2]
-\f
-RFC 2756 Hyper Text Caching Protocol (HTCP/0.0) January 2000
-
-
- 2.5. An HTCP Message has the following general format:
-
- +---------------------+
- | HEADER | tells message length and protocol versions
- +---------------------+
- | DATA | HTCP message (varies per major version number)
- +---------------------+
- | AUTH | optional authentication for transaction
- +---------------------+
-
- 2.6. An HTCP/*.* HEADER has the following format:
-
- +0 (MSB) +1 (LSB)
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 0: | LENGTH |
- + + + + + + + + + + + + + + + + +
- 2: | LENGTH |
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 2: | MAJOR | MINOR |
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
-
- LENGTH is the message length, inclusive of all header and data
- octets, including the LENGTH field itself. This field will
- be equal to the datagram payload size ("record length") if a
- datagram protocol is in use, and can include padding, i.e.,
- not all octets of the message need be used in the DATA and
- AUTH sections.
-
- MAJOR is the major version number (0 for this specification). The
- DATA section of an HTCP message need not be upward or
- downward compatible between different major version numbers.
-
- MINOR is the minor version number (0 for this specification).
- Feature levels and interpretation rules can vary depending on
- this field, in particular RESERVED fields can take on new
- (though optional) meaning in successive minor version numbers
- within the same major version number.
-
- 2.6.1. It is expected that an HTCP initiator will know the version
- number of a prospective HTCP responder, or that the initiator will
- probe using declining values for MINOR and MAJOR (beginning with the
- highest locally supported value) and locally cache the probed version
- number of the responder.
-
- 2.6.2. Higher MAJOR numbers are to be preferred, as are higher MINOR
- numbers within a particular MAJOR number.
-
-
-
-
-
-Vixie & Wessels Experimental [Page 3]
-\f
-RFC 2756 Hyper Text Caching Protocol (HTCP/0.0) January 2000
-
-
- 2.7. An HTCP/0.* DATA has the following structure:
-
- +0 (MSB) +1 (LSB)
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 0: | LENGTH |
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 2: | OPCODE | RESPONSE | RESERVED |F1 |RR |
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 4: | TRANS-ID |
- + + + + + + + + + + + + + + + + +
- 6: | TRANS-ID |
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 8: | |
- / OP-DATA /
- / /
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
-
- LENGTH is the number of octets of the message which are reserved
- for the DATA section, including the LENGTH field itself.
- This number can include padding, i.e., not all octets
- reserved by LENGTH need be used in OP-DATA.
-
- OPCODE is the operation code of an HTCP transaction. An HTCP
- transaction can consist of multiple HTCP messages, e.g., a
- request (sent by the initiator), or a response (sent by the
- responder).
-
- RESPONSE is a numeric code indicating the success or failure of a
- transaction. It should be set to zero (0) by requestors
- and ignored by responders. Each operation has its own set
- of response codes, which are described later. The overall
- message has a set of response codes which are as follows:
-
- 0 authentication wasn't used but is required
- 1 authentication was used but unsatisfactorily
- 2 opcode not implemented
- 3 major version not supported
- 4 minor version not supported (major version is ok)
- 5 inappropriate, disallowed, or undesirable opcode
-
- The above response codes all indicate errors and all depend
- for their visibility on MO=1 (as specified below).
-
- RR is a flag indicating whether this message is a request (0)
- or response (1).
-
-
-
-
-
-
-Vixie & Wessels Experimental [Page 4]
-\f
-RFC 2756 Hyper Text Caching Protocol (HTCP/0.0) January 2000
-
-
- F1 is overloaded such that it is used differently by
- requestors than by responders. If RR=0, then F1 is defined
- as RD. If RR=1, then F1 is defined as MO.
-
- RD is a flag which if set to 1 means that a response is
- desired. Some OPCODEs require RD to be set to 1 to be
- meaningful.
-
- MO (em-oh) is a flag which indicates whether the RESPONSE code
- is to be interpreted as a response to the overall message
- (fixed fields in DATA or any field of AUTH) [MO=1] or as a
- response to fields in the OP-DATA [MO=0].
-
- TRANS-ID is a 32-bit value which when combined with the initiator's
- network address, uniquely identifies this HTCP transaction.
- Care should be taken not to reuse TRANS-ID's within the
- life-time of a UDP datagram.
-
- OP-DATA is opcode-dependent and is defined below, per opcode.
-
- 2.8. An HTCP/0.0 AUTH has the following structure:
-
- +0 (MSB) +1 (LSB)
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 0: | LENGTH |
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 2: | SIG-TIME |
- + + + + + + + + + + + + + + + + +
- 4: | SIG-TIME |
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 6: | SIG-EXPIRE |
- + + + + + + + + + + + + + + + + +
- 8: | SIG-EXPIRE |
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 10: | |
- / KEY-NAME /
- / /
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- n: | |
- / SIGNATURE /
- / /
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
-
-
-
-
-
-
-
-
-
-Vixie & Wessels Experimental [Page 5]
-\f
-RFC 2756 Hyper Text Caching Protocol (HTCP/0.0) January 2000
-
-
- LENGTH is the number of octets used by the AUTH, including the
- LENGTH field itself. If the optional AUTH is not being
- transmitted, this field should be set to 2 (two). LENGTH
- can include padding, which means that not all octets
- reserved by LENGTH will necessarily be consumed by
- SIGNATURE.
-
- SIG-TIME is an unsigned binary count of the number of seconds
- since 00:00:00 1-Jan-70 UTC at the time the SIGNATURE is
- generated.
-
- SIG-EXPIRE is an unsigned binary count of the number of seconds
- since 00:00:00 1-Jan-70 UTC at the time the SIGNATURE is
- considered to have expired.
-
- KEY-NAME is a COUNTSTR [3.1] which specifies the name of a shared
- secret. (Each HTCP implementation is expected to allow
- configuration of several shared secrets, each of which
- will have a name.)
-
- SIGNATURE is a COUNTSTR [3.1] which holds the HMAC-MD5 digest (see
- [RFC 2104]), with a B value of 64, of the following
- elements, each of which is digested in its "on the wire"
- format, including transmitted padding if any is covered
- by a field's associated LENGTH:
-
- IP SRC ADDR [4 octets]
- IP SRC PORT [2 octets]
- IP DST ADDR [4 octets]
- IP DST PORT [2 octets]
- HTCP MAJOR version number [1 octet]
- HTCP MINOR version number [1 octet]
- SIG-TIME [4 octets]
- SIG-EXPIRE [4 octets]
- HTCP DATA [variable]
- KEY-NAME (the whole COUNTSTR [3.1]) [variable]
-
- 2.8.1. Shared secrets should be cryptorandomly generated and should
- be at least a few hundred octets in size.
-
-3. Data Types
-
- HTCP/0.* data types are defined as follows:
-
-
-
-
-
-
-
-
-Vixie & Wessels Experimental [Page 6]
-\f
-RFC 2756 Hyper Text Caching Protocol (HTCP/0.0) January 2000
-
-
- 3.1. COUNTSTR is a counted string whose format is:
-
- +0 (MSB) +1 (LSB)
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 0: | LENGTH |
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 2: | |
- / TEXT /
- / /
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
-
- LENGTH is the number of octets which will follow in TEXT. This
- field is *not* self-inclusive as is the case with other HTCP
- LENGTH fields.
-
- TEXT is a stream of uninterpreted octets, usually ISO8859-1
- "characters".
-
- 3.2. SPECIFIER is used with the TST and CLR request messages,
- defined below. Its format is:
-
- +---------------------+
- | METHOD | : COUNTSTR
- +---------------------+
- | URI | : COUNTSTR
- +---------------------+
- | VERSION | : COUNTSTR
- +---------------------+
- | REQ-HDRS | : COUNTSTR
- +---------------------+
-
- METHOD (Since HTCP only returns headers, methods GET and HEAD are
- equivalent.)
-
- URI (If the URI is a URL, it should always include a ":"<port>
- specifier, but in its absense, port 80 should be imputed by
- a receiver.)
-
- VERSION is an entire HTTP version string such as" HTTP/1.1".
- VERSION strings with prefixes other than "HTTP/" or with
- version numbers less than "1.1" are outside the domain of
- this specification.
-
- REQ-HDRS are those presented by an HTTP initiator. These headers
- should include end-to-end but NOT hop-by-hop headers, and
- they can be canonicalized (aggregation of "Accept:" is
- permitted, for example.)
-
-
-
-
-Vixie & Wessels Experimental [Page 7]
-\f
-RFC 2756 Hyper Text Caching Protocol (HTCP/0.0) January 2000
-
-
- 3.3. DETAIL is used with the TST response message, defined below.
- Its format is:
-
- +---------------------+
- | RESP-HDRS | : COUNTSTR
- +---------------------+
- | ENTITY-HDRS | : COUNTSTR
- +---------------------+
- | CACHE-HDRS | : COUNTSTR
- +---------------------+
-
- 3.4. IDENTITY is used with the MON request and SET response message,
- defined below. Its format is:
-
- +---------------------+
- | SPECIFIER |
- +---------------------+
- | DETAIL |
- +---------------------+
-
-4. Cache Headers
-
- HTCP/0.0 CACHE-HDRS consist of zero or more of the following headers:
-
- Cache-Vary: <header-name> ...
- The sender of this header has learned that content varies on a set
- of headers different from the set given in the object's Vary:
- header. Cache-Vary:, if present, overrides the object's Vary:
- header.
-
- Cache-Location: <cache-hostname>:<port> ...
- The sender of this header has learned of one or more proxy caches
- who are holding a copy of this object. Probing these caches with
- HTCP may result in discovery of new, close-by (preferrable to
- current) HTCP neighbors.
-
- Cache-Policy: [no-cache] [no-share] [no-cache-cookie]
- The sender of this header has learned that the object's caching
- policy has more detail than is given in its response headers.
-
- no-cache means that it is uncacheable (no reason given),
- but may be shareable between simultaneous
- requestors.
-
- no-share means that it is unshareable (no reason given),
- and per-requestor tunnelling is always
- required).
-
-
-
-
-Vixie & Wessels Experimental [Page 8]
-\f
-RFC 2756 Hyper Text Caching Protocol (HTCP/0.0) January 2000
-
-
- no-cache-cookie means that the content could change as a result
- of different, missing, or even random cookies
- being included in the request headers, and that
- caching is inadvisable.
-
- Cache-Flags: [incomplete]
- The sender of this header has modified the object's caching policy
- locally, such that requesters may need to treat this response
- specially, i.e., not necessarily in accordance with the object's
- actual policy.
-
- incomplete means that the response headers and/or entity headers
- given in this response are not known to be complete,
- and may not be suitable for use as a cache key.
-
- Cache-Expiry: <date>
- The sender of this header has learned that this object should be
- considered to have expired at a time different than that indicated
- by its response headers. The format is the same as HTTP/1.1
- Expires:.
-
- Cache-MD5: <discovered content MD5>
- The sender of this header has computed an MD5 checksum for this
- object which is either different from that given in the object's
- Content-MD5: header, or is being supplied since the object has no
- Content-MD5 header. The format is the same as HTTP/1.1 Content-
- MD5:.
-
- Cache-to-Origin: <origin> <rtt> <samples> <hops>
- The sender of this header has measured the round trip time to an
- origin server (given as a hostname or literal address). The <rtt>
- is the average number of seconds, expressed as decimal ASCII with
- arbitrary precision and no exponent. <Samples> is the number of
- RTT samples which have had input to this average. <Hops> is the
- number of routers between the cache and the origin, expressed as
- decimal ASCII with arbitrary precision and no exponent, or 0 if
- the cache doesn't know.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Vixie & Wessels Experimental [Page 9]
-\f
-RFC 2756 Hyper Text Caching Protocol (HTCP/0.0) January 2000
-
-
-6. HTCP Operations
-
- HTCP/0.* opcodes and their respective OP-DATA are defined below:
-
- 6.1. NOP (OPCODE 0):
-
- This is an HTCP-level "ping." Responders are encouraged to process
- NOP's with minimum delay since the requestor may be using the NOP RTT
- (round trip time) for configuration or mapping purposes. The
- RESPONSE code for a NOP is always zero (0). There is no OP-DATA for
- a NOP. NOP requests with RD=0 cause no processing to occur at all.
-
- 6.2. TST (OPCODE 1):
-
- Test for the presence of a specified content entity in a proxy cache.
- TST requests with RD=0 cause no processing to occur at all.
-
- TST requests have the following OP-DATA:
-
- +0 (MSB) +1 (LSB)
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 0: | |
- / SPECIFIER /
- / /
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
-
- RESPONSE codes for TST are as follows:
-
- 0 entity is present in responder's cache
- 1 entity is not present in responder's cache
-
- TST responses have the following OP-DATA, if RESPONSE is zero (0):
-
- +0 (MSB) +1 (LSB)
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 0: | |
- / DETAIL /
- / /
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
-
- Note: The response headers returned by a positive TST can be of a
- stale object. Requestors should be prepared to cope with this
- condition, either by using the responder as a source for this
- object (which could cause the responder to simply refresh it)
- or by choosing a different responder.
-
-
-
-
-
-
-Vixie & Wessels Experimental [Page 10]
-\f
-RFC 2756 Hyper Text Caching Protocol (HTCP/0.0) January 2000
-
-
- TST responses have the following OP-DATA, if RESPONSE is one (1):
-
- +0 (MSB) +1 (LSB)
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 0: | |
- / CACHE-HDRS /
- / /
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
-
- 6.3. MON (OPCODE 2):
-
- Monitor activity in a proxy cache's local object store (adds, deletes,
- replacements, etc). Since interleaving of HTCP transactions over a
- single pair of UDP endpoints is not supported, it is recommended that a
- unique UDP endpoint be allocated by the requestor for each concurrent
- MON request. MON requests with RD=0 are equivalent to those with RD=1
- and TIME=0; that is, they will cancel any outstanding MON transaction.
-
- MON requests have the following OP-DATA structure:
-
- +0 (MSB)
- +---+---+---+---+---+---+---+---+
- 0: | TIME |
- +---+---+---+---+---+---+---+---+
-
- TIME is the number of seconds of monitoring output desired by the
- initiator. Subsequent MON requests from the same initiator
- with the same TRANS-ID should update the time on a ongoing MON
- transaction. This is called "overlapping renew."
-
- RESPONSE codes for MON are as follows:
-
- 0 accepted, OP-DATA is present and valid
- 1 refused (quota error -- too many MON's are active)
-
- MON responses have the following OP-DATA structure, if RESPONSE is
- zero (0):
-
- +0 (MSB) +1 (LSB)
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 0: | TIME | ACTION | REASON |
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 2: | |
- / IDENTITY /
- / /
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
-
-
-
-
-
-Vixie & Wessels Experimental [Page 11]
-\f
-RFC 2756 Hyper Text Caching Protocol (HTCP/0.0) January 2000
-
-
- TIME is the number of seconds remaining for this MON
- transaction.
-
- ACTION is a numeric code indicating a cache population action.
- Codes are:
-
- 0 an entity has been added to the cache
- 1 an entity in the cache has been refreshed
- 2 an entity in the cache has been replaced
- 3 an entity in the cache has been deleted
-
- REASON is a numeric code indicating the reason for an ACTION.
- Codes are:
-
- 0 some reason not covered by the other REASON codes
- 1 a proxy client fetched this entity
- 2 a proxy client fetched with caching disallowed
- 3 the proxy server prefetched this entity
- 4 the entity expired, per its headers
- 5 the entity was purged due to caching storage limits
-
- 6.4. SET (OPCODE 3):
-
- Inform a cache of the identity of an object. This is a "push"
- transaction, whereby cooperating caches can share information such as
- updated Age/Date/Expires headers (which might result from an origin
- "304 Not modified" HTTP response) or updated cache headers (which
- might result from the discovery of non-authoritative "vary"
- conditions or from learning of second or third party cache locations
- for this entity. RD is honoured.
-
- SET requests have the following OP-DATA structure:
-
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 0: | |
- / IDENTITY /
- / /
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
-
- RESPONSE codes are as follows:
-
- 0 identity accepted, thank you
- 1 identity ignored, no reason given, thank you
-
- SET responses have no OP-DATA.
-
-
-
-
-
-
-Vixie & Wessels Experimental [Page 12]
-\f
-RFC 2756 Hyper Text Caching Protocol (HTCP/0.0) January 2000
-
-
- 6.5. CLR (OPCODE 4):
-
- Tell a cache to completely forget about an entity. RD is honoured.
-
- CLR requests have the following OP-DATA structure:
-
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 0: | RESERVED | REASON |
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 2: | |
- / SPECIFIER /
- / /
- +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
-
- REASON is a numeric code indicating the reason why the requestor
- is asking that this entity be removed. The codes are as
- follows:
-
- 0 some reason not better specified by another code
- 1 the origin server told me that this entity does not
- exist
-
- RESPONSE codes are as follows:
-
- 0 i had it, it's gone now
- 1 i had it, i'm keeping it, no reason given.
- 2 i didn't have it
-
- CLR responses have no OP-DATA.
-
- Clearing a URI without specifying response, entity, or cache headers
- means to clear all entities using that URI.
-
-7. Security Considerations
-
- If the optional AUTH element is not used, it is possible for
- unauthorized third parties to both view and modify a cache using the
- HTCP protocol.
-
-8. Acknowledgements
-
- Mattias Wingstedt of Idonex brought key insights to the development
- of this protocol. David Hankins helped clarify this document.
-
-
-
-
-
-
-
-
-Vixie & Wessels Experimental [Page 13]
-\f
-RFC 2756 Hyper Text Caching Protocol (HTCP/0.0) January 2000
-
-
-9. References
-
- [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.
-
- [RFC2104] Krawczyk, H., Bellare, M. and R. Canetti, "HMAC: Keyed-
- Hashing for Message Authentication", RFC 2104, February,
- 1997.
-
- [RFC2186] Wessels, D. and K. Claffy, "Internet Cache Protocol (ICP),
- version 2", RFC 2186, September 1997.
-
-10. Authors' Addresses
-
- Paul Vixie
- Internet Software Consortium
- 950 Charter Street
- Redwood City, CA 94063
-
- Phone: +1 650 779 7001
- EMail: vixie@isc.org
-
-
- Duane Wessels
- National Lab for Applied Network Research
- USCD, 9500 Gilman Drive
- La Jolla, CA 92093
-
- Phone: +1 303 497 1822
- EMail: wessels@nlanr.net
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Vixie & Wessels Experimental [Page 14]
-\f
-RFC 2756 Hyper Text Caching Protocol (HTCP/0.0) January 2000
-
-
-11. 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Vixie & Wessels Experimental [Page 15]
-\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 M. Crawford
-Request for Comments: 2874 Fermilab
-Category: Standards Track C. Huitema
- Microsoft Corporation
- July 2000
-
-
- DNS Extensions to Support IPv6 Address Aggregation and Renumbering
-
-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 defines changes to the Domain Name System to support
- renumberable and aggregatable IPv6 addressing. The changes include a
- new resource record type to store an IPv6 address in a manner which
- expedites network renumbering and updated definitions of existing
- query types that return Internet addresses as part of additional
- section processing.
-
- For lookups keyed on IPv6 addresses (often called reverse lookups),
- this document defines a new zone structure which allows a zone to be
- used without modification for parallel copies of an address space (as
- for a multihomed provider or site) and across network renumbering
- events.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Crawford, et al. Standards Track [Page 1]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
-Table of Contents
-
- 1. Introduction ............................................... 2
- 2. Overview ................................................... 3
- 2.1. Name-to-Address Lookup ............................... 4
- 2.2. Underlying Mechanisms for Reverse Lookups ............ 4
- 2.2.1. Delegation on Arbitrary Boundaries ............. 4
- 2.2.2. Reusable Zones ................................. 5
- 3. Specifications ............................................. 5
- 3.1. The A6 Record Type ................................... 5
- 3.1.1. Format ......................................... 6
- 3.1.2. Processing ..................................... 6
- 3.1.3. Textual Representation ......................... 7
- 3.1.4. Name Resolution Procedure ...................... 7
- 3.2. Zone Structure for Reverse Lookups ................... 7
- 4. Modifications to Existing Query Types ...................... 8
- 5. Usage Illustrations ........................................ 8
- 5.1. A6 Record Chains ..................................... 9
- 5.1.1. Authoritative Data ............................. 9
- 5.1.2. Glue ........................................... 10
- 5.1.3. Variations ..................................... 12
- 5.2. Reverse Mapping Zones ................................ 13
- 5.2.1. The TLA level .................................. 13
- 5.2.2. The ISP level .................................. 13
- 5.2.3. The Site Level ................................. 13
- 5.3. Lookups .............................................. 14
- 5.4. Operational Note ..................................... 15
- 6. Transition from RFC 1886 and Deployment Notes .............. 15
- 6.1. Transition from AAAA and Coexistence with A Records .. 16
- 6.2. Transition from Nibble Labels to Binary Labels ....... 17
- 7. Security Considerations .................................... 17
- 8. IANA Considerations ........................................ 17
- 9. Acknowledgments ............................................ 18
- 10. References ................................................ 18
- 11. Authors' Addresses ........................................ 19
- 12. Full Copyright Statement .................................. 20
-
-1. Introduction
-
- Maintenance of address information in the DNS is one of several
- obstacles which have prevented site and provider renumbering from
- being feasible in IP version 4. Arguments about the importance of
- network renumbering for the preservation of a stable routing system
- and for other purposes may be read in [RENUM1, RENUM2, RENUM3]. To
- support the storage of IPv6 addresses without impeding renumbering we
- define the following extensions.
-
-
-
-
-
-Crawford, et al. Standards Track [Page 2]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
- o A new resource record type, "A6", is defined to map a domain name
- to an IPv6 address, with a provision for indirection for leading
- "prefix" bits.
-
- o Existing queries that perform additional section processing to
- locate IPv4 addresses are redefined to do that processing for both
- IPv4 and IPv6 addresses.
-
- o A new domain, IP6.ARPA, is defined to support lookups based on
- IPv6 address.
-
- o A new prefix-delegation method is defined, relying on new DNS
- features [BITLBL, DNAME].
-
- The changes are designed to be compatible with existing application
- programming interfaces. The existing support for IPv4 addresses is
- retained. Transition issues related to the coexistence of both IPv4
- and IPv6 addresses in DNS are discussed in [TRANS].
-
- This memo proposes a replacement for the specification in RFC 1886
- [AAAA] and a departure from current implementation practices. The
- changes are designed to facilitate network renumbering and
- multihoming. Domains employing the A6 record for IPv6 addresses can
- insert automatically-generated AAAA records in zone files to ease
- transition. It is expected that after a reasonable period, RFC 1886
- will become Historic.
-
- The next three major sections of this document are an overview of the
- facilities defined or employed by this specification, the
- specification itself, and examples of use.
-
- 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 [KWORD]. The key word
- "SUGGESTED" signifies a strength between MAY and SHOULD: it is
- believed that compliance with the suggestion has tangible benefits in
- most instances.
-
-2. Overview
-
- This section provides an overview of the DNS facilities for storage
- of IPv6 addresses and for lookups based on IPv6 address, including
- those defined here and elsewhere.
-
-
-
-
-
-
-
-
-Crawford, et al. Standards Track [Page 3]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
-2.1. Name-to-Address Lookup
-
- IPv6 addresses are stored in one or more A6 resource records. A
- single A6 record may include a complete IPv6 address, or a contiguous
- portion of an address and information leading to one or more
- prefixes. Prefix information comprises a prefix length and a DNS
- name which is in turn the owner of one or more A6 records defining
- the prefix or prefixes which are needed to form one or more complete
- IPv6 addresses. When the prefix length is zero, no DNS name is
- present and all the leading bits of the address are significant.
- There may be multiple levels of indirection and the existence of
- multiple A6 records at any level multiplies the number of IPv6
- addresses which are formed.
-
- An application looking up an IPv6 address will generally cause the
- DNS resolver to access several A6 records, and multiple IPv6
- addresses may be returned even if the queried name was the owner of
- only one A6 record. The authenticity of the returned address(es)
- cannot be directly verified by DNS Security [DNSSEC]. The A6 records
- which contributed to the address(es) may of course be verified if
- signed.
-
- Implementers are reminded of the necessity to limit the amount of
- work a resolver will perform in response to a client request. This
- principle MUST be extended to also limit the generation of DNS
- requests in response to one name-to-address (or address-to-name)
- lookup request.
-
-2.2. Underlying Mechanisms for Reverse Lookups
-
- This section describes the new DNS features which this document
- exploits. This section is an overview, not a specification of those
- features. The reader is directed to the referenced documents for
- more details on each.
-
-2.2.1. Delegation on Arbitrary Boundaries
-
- This new scheme for reverse lookups relies on a new type of DNS label
- called the "bit-string label" [BITLBL]. This label compactly
- represents an arbitrary string of bits which is treated as a
- hierarchical sequence of one-bit domain labels. Resource records can
- thereby be stored at arbitrary bit-boundaries.
-
- Examples in section 5 will employ the following textual
- representation for bit-string labels, which is a subset of the syntax
- defined in [BITLBL]. A base indicator "x" for hexadecimal and a
- sequence of hexadecimal digits is enclosed between "\[" and "]". The
- bits denoted by the digits represent a sequence of one-bit domain
-
-
-
-Crawford, et al. Standards Track [Page 4]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
- labels ordered from most to least significant. (This is the opposite
- of the order they would appear if listed one bit at a time, but it
- appears to be a convenient notation.) The digit string may be
- followed by a slash ("/") and a decimal count. If omitted, the
- implicit count is equal to four times the number of hexadecimal
- digits.
-
- Consecutive bit-string labels are equivalent (up to the limit imposed
- by the size of the bit count field) to a single bit-string label
- containing all the bits of the consecutive labels in the proper
- order. As an example, either of the following domain names could be
- used in a QCLASS=IN, QTYPE=PTR query to find the name of the node
- with IPv6 address 3ffe:7c0:40:9:a00:20ff:fe81:2b32.
-
- \[x3FFE07C0004000090A0020FFFE812B32/128].IP6.ARPA.
-
- \[x0A0020FFFE812B32/64].\[x0009/16].\[x3FFE07C00040/48].IP6.ARPA.
-
-2.2.2. Reusable Zones
-
- DNS address space delegation is implemented not by zone cuts and NS
- records, but by a new analogue to the CNAME record, called the DNAME
- resource record [DNAME]. The DNAME record provides alternate naming
- to an entire subtree of the domain name space, rather than to a
- single node. It causes some suffix of a queried name to be
- substituted with a name from the DNAME record's RDATA.
-
- For example, a resolver or server providing recursion, while looking
- up a QNAME a.b.c.d.e.f may encounter a DNAME record
-
- d.e.f. DNAME w.xy.
-
- which will cause it to look for a.b.c.w.xy.
-
-3. Specifications
-
-3.1. The A6 Record Type
-
- The A6 record type is specific to the IN (Internet) class and has
- type number 38 (decimal).
-
-
-
-
-
-
-
-
-
-
-
-Crawford, et al. Standards Track [Page 5]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
-3.1.1. Format
-
- The RDATA portion of the A6 record contains two or three fields.
-
- +-----------+------------------+-------------------+
- |Prefix len.| Address suffix | Prefix name |
- | (1 octet) | (0..16 octets) | (0..255 octets) |
- +-----------+------------------+-------------------+
-
- o A prefix length, encoded as an eight-bit unsigned integer with
- value between 0 and 128 inclusive.
-
- o An IPv6 address suffix, encoded in network order (high-order octet
- first). There MUST be exactly enough octets in this field to
- contain a number of bits equal to 128 minus prefix length, with 0
- to 7 leading pad bits to make this field an integral number of
- octets. Pad bits, if present, MUST be set to zero when loading a
- zone file and ignored (other than for SIG [DNSSEC] verification)
- on reception.
-
- o The name of the prefix, encoded as a domain name. By the rules of
- [DNSIS], this name MUST NOT be compressed.
-
- The domain name component SHALL NOT be present if the prefix length
- is zero. The address suffix component SHALL NOT be present if the
- prefix length is 128.
-
- It is SUGGESTED that an A6 record intended for use as a prefix for
- other A6 records have all the insignificant trailing bits in its
- address suffix field set to zero.
-
-3.1.2. Processing
-
- A query with QTYPE=A6 causes type A6 and type NS additional section
- processing for the prefix names, if any, in the RDATA field of the A6
- records in the answer section. This processing SHOULD be recursively
- applied to the prefix names of A6 records included as additional
- data. When space in the reply packet is a limit, inclusion of
- additional A6 records takes priority over NS records.
-
- It is an error for an A6 record with prefix length L1 > 0 to refer to
- a domain name which owns an A6 record with a prefix length L2 > L1.
- If such a situation is encountered by a resolver, the A6 record with
- the offending (larger) prefix length MUST be ignored. Robustness
- precludes signaling an error if addresses can still be formed from
- valid A6 records, but it is SUGGESTED that zone maintainers from time
- to time check all the A6 records their zones reference.
-
-
-
-
-Crawford, et al. Standards Track [Page 6]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
-3.1.3. Textual Representation
-
- The textual representation of the RDATA portion of the A6 resource
- record in a zone file comprises two or three fields separated by
- whitespace.
-
- o A prefix length, represented as a decimal number between 0 and 128
- inclusive,
-
- o the textual representation of an IPv6 address as defined in
- [AARCH] (although some leading and/or trailing bits may not be
- significant),
-
- o a domain name, if the prefix length is not zero.
-
- The domain name MUST be absent if the prefix length is zero. The
- IPv6 address MAY be be absent if the prefix length is 128. A number
- of leading address bits equal to the prefix length SHOULD be zero,
- either implicitly (through the :: notation) or explicitly, as
- specified in section 3.1.1.
-
-3.1.4. Name Resolution Procedure
-
- To obtain the IPv6 address or addresses which belong to a given name,
- a DNS client MUST obtain one or more complete chains of A6 records,
- each chain beginning with a record owned by the given name and
- including a record owned by the prefix name in that record, and so on
- recursively, ending with an A6 record with a prefix length of zero.
- One IPv6 address is formed from one such chain by taking the value of
- each bit position from the earliest A6 record in the chain which
- validly covers that position, as indicated by the prefix length. The
- set of all IPv6 addresses for the given name comprises the addresses
- formed from all complete chains of A6 records beginning at that name,
- discarding records which have invalid prefix lengths as defined in
- section 3.1.2.
-
- If some A6 queries fail and others succeed, a client might obtain a
- non-empty but incomplete set of IPv6 addresses for a host. In many
- situations this may be acceptable. The completeness of a set of A6
- records may always be determined by inspection.
-
-3.2. Zone Structure for Reverse Lookups
-
- Very little of the new scheme's data actually appears under IP6.ARPA;
- only the first level of delegation needs to be under that domain.
- More levels of delegation could be placed under IP6.ARPA if some
- top-level delegations were done via NS records instead of DNAME
- records, but this would incur some cost in renumbering ease at the
-
-
-
-Crawford, et al. Standards Track [Page 7]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
- level of TLAs [AGGR]. Therefore, it is declared here that all
- address space delegations SHOULD be done by the DNAME mechanism
- rather than NS.
-
- In addition, since uniformity in deployment will simplify maintenance
- of address delegations, it is SUGGESTED that address and prefix
- information be stored immediately below a DNS label "IP6". Stated
- another way, conformance with this suggestion would mean that "IP6"
- is the first label in the RDATA field of DNAME records which support
- IPv6 reverse lookups.
-
- When any "reserved" or "must be zero" bits are adjacent to a
- delegation boundary, the higher-level entity MUST retain those bits
- in its own control and delegate only the bits over which the lower-
- level entity has authority.
-
- To find the name of a node given its IPv6 address, a DNS client MUST
- perform a query with QCLASS=IN, QTYPE=PTR on the name formed from the
- 128 bit address as one or more bit-string labels [BITLBL], followed
- by the two standard labels "IP6.ARPA". If recursive service was not
- obtained from a server and the desired PTR record was not returned,
- the resolver MUST handle returned DNAME records as specified in
- [DNAME], and NS records as specified in [DNSCF], and iterate.
-
-4. Modifications to Existing Query Types
-
- All existing query types that perform type A additional section
- processing, i.e. the name server (NS), mail exchange (MX), and
- mailbox (MB) query types, and the experimental AFS data base (AFSDB)
- and route through (RT) types, must be redefined to perform type A, A6
- and AAAA additional section processing, with type A having the
- highest priority for inclusion and type AAAA the lowest. This
- redefinition means that a name server may add any relevant IPv4 and
- IPv6 address information available locally to the additional section
- of a response when processing any one of the above queries. The
- recursive inclusion of A6 records referenced by A6 records already
- included in the additional section is OPTIONAL.
-
-5. Usage Illustrations
-
- This section provides examples of use of the mechanisms defined in
- the previous section. All addresses and domains mentioned here are
- intended to be fictitious and for illustrative purposes only.
- Example delegations will be on 4-bit boundaries solely for
- readability; this specification is indifferent to bit alignment.
-
- Use of the IPv6 aggregatable address format [AGGR] is assumed in the
- examples.
-
-
-
-Crawford, et al. Standards Track [Page 8]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
-5.1. A6 Record Chains
-
- Let's take the example of a site X that is multi-homed to two
- "intermediate" providers A and B. The provider A is itself multi-
- homed to two "transit" providers, C and D. The provider B gets its
- transit service from a single provider, E. For simplicity suppose
- that C, D and E all belong to the same top-level aggregate (TLA) with
- identifier (including format prefix) '2345', and the TLA authority at
- ALPHA-TLA.ORG assigns to C, D and E respectively the next level
- aggregate (NLA) prefixes 2345:00C0::/28, 2345:00D0::/28 and
- 2345:000E::/32.
-
- C assigns the NLA prefix 2345:00C1:CA00::/40 to A, D assigns the
- prefix 2345:00D2:DA00::/40 to A and E assigns 2345:000E:EB00::/40 to
- B.
-
- A assigns to X the subscriber identification '11' and B assigns the
- subscriber identification '22'. As a result, the site X inherits
- three address prefixes:
-
- o 2345:00C1:CA11::/48 from A, for routes through C.
- o 2345:00D2:DA11::/48 from A, for routes through D.
- o 2345:000E:EB22::/48 from B, for routes through E.
-
- Let us suppose that N is a node in the site X, that it is assigned to
- subnet number 1 in this site, and that it uses the interface
- identifier '1234:5678:9ABC:DEF0'. In our configuration, this node
- will have three addresses:
-
- o 2345:00C1:CA11:0001:1234:5678:9ABC:DEF0
- o 2345:00D2:DA11:0001:1234:5678:9ABC:DEF0
- o 2345:000E:EB22:0001:1234:5678:9ABC:DEF0
-
-5.1.1. Authoritative Data
-
- We will assume that the site X is represented in the DNS by the
- domain name X.EXAMPLE, while A, B, C, D and E are represented by
- A.NET, B.NET, C.NET, D.NET and E.NET. In each of these domains, we
- assume a subdomain "IP6" that will hold the corresponding prefixes.
- The node N is identified by the domain name N.X.EXAMPLE. The
- following records would then appear in X's DNS.
-
- $ORIGIN X.EXAMPLE.
- N A6 64 ::1234:5678:9ABC:DEF0 SUBNET-1.IP6
- SUBNET-1.IP6 A6 48 0:0:0:1:: IP6
- IP6 A6 48 0::0 SUBSCRIBER-X.IP6.A.NET.
- IP6 A6 48 0::0 SUBSCRIBER-X.IP6.B.NET.
-
-
-
-
-Crawford, et al. Standards Track [Page 9]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
- And elsewhere there would appear
-
- SUBSCRIBER-X.IP6.A.NET. A6 40 0:0:0011:: A.NET.IP6.C.NET.
- SUBSCRIBER-X.IP6.A.NET. A6 40 0:0:0011:: A.NET.IP6.D.NET.
-
- SUBSCRIBER-X.IP6.B.NET. A6 40 0:0:0022:: B-NET.IP6.E.NET.
-
- A.NET.IP6.C.NET. A6 28 0:0001:CA00:: C.NET.ALPHA-TLA.ORG.
-
- A.NET.IP6.D.NET. A6 28 0:0002:DA00:: D.NET.ALPHA-TLA.ORG.
-
- B-NET.IP6.E.NET. A6 32 0:0:EB00:: E.NET.ALPHA-TLA.ORG.
-
- C.NET.ALPHA-TLA.ORG. A6 0 2345:00C0::
- D.NET.ALPHA-TLA.ORG. A6 0 2345:00D0::
- E.NET.ALPHA-TLA.ORG. A6 0 2345:000E::
-
-5.1.2. Glue
-
- When, as is common, some or all DNS servers for X.EXAMPLE are within
- the X.EXAMPLE zone itself, the top-level zone EXAMPLE must carry
- enough "glue" information to enable DNS clients to reach those
- nameservers. This is true in IPv6 just as in IPv4. However, the A6
- record affords the DNS administrator some choices. The glue could be
- any of
-
- o a minimal set of A6 records duplicated from the X.EXAMPLE zone,
-
- o a (possibly smaller) set of records which collapse the structure
- of that minimal set,
-
- o or a set of A6 records with prefix length zero, giving the entire
- global addresses of the servers.
-
- The trade-off is ease of maintenance against robustness. The best
- and worst of both may be had together by implementing either the
- first or second option together with the third. To illustrate the
- glue options, suppose that X.EXAMPLE is served by two nameservers
- NS1.X.EXAMPLE and NS2.X.EXAMPLE, having interface identifiers
- ::1:11:111:1111 and ::2:22:222:2222 on subnets 1 and 2 respectively.
- Then the top-level zone EXAMPLE would include one (or more) of the
- following sets of A6 records as glue.
-
-
-
-
-
-
-
-
-
-Crawford, et al. Standards Track [Page 10]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
- $ORIGIN EXAMPLE. ; first option
- X NS NS1.X
- NS NS2.X
- NS1.X A6 64 ::1:11:111:1111 SUBNET-1.IP6.X
- NS2.X A6 64 ::2:22:222:2222 SUBNET-2.IP6.X
- SUBNET-1.IP6.X A6 48 0:0:0:1:: IP6.X
- SUBNET-2.IP6.X A6 48 0:0:0:2:: IP6.X
- IP6.X A6 48 0::0 SUBSCRIBER-X.IP6.A.NET.
- IP6.X A6 48 0::0 SUBSCRIBER-X.IP6.B.NET.
-
-
- $ORIGIN EXAMPLE. ; second option
- X NS NS1.X
- NS NS2.X
- NS1.X A6 48 ::1:1:11:111:1111 SUBSCRIBER-X.IP6.A.NET.
- A6 48 ::1:1:11:111:1111 SUBSCRIBER-X.IP6.B.NET.
- NS2.X A6 48 ::2:2:22:222:2222 SUBSCRIBER-X.IP6.A.NET.
- A6 48 ::2:2:22:222:2222 SUBSCRIBER-X.IP6.B.NET.
-
-
- $ORIGIN EXAMPLE. ; third option
- X NS NS1.X
- NS NS2.X
- NS1.X A6 0 2345:00C1:CA11:1:1:11:111:1111
- A6 0 2345:00D2:DA11:1:1:11:111:1111
- A6 0 2345:000E:EB22:1:1:11:111:1111
- NS2.X A6 0 2345:00C1:CA11:2:2:22:222:2222
- A6 0 2345:00D2:DA11:2:2:22:222:2222
- A6 0 2345:000E:EB22:2:2:22:222:2222
-
- The first and second glue options are robust against renumbering of
- X.EXAMPLE's prefixes by providers A.NET and B.NET, but will fail if
- those providers' own DNS is unreachable. The glue records of the
- third option are robust against DNS failures elsewhere than the zones
- EXAMPLE and X.EXAMPLE themselves, but must be updated when X's
- address space is renumbered.
-
- If the EXAMPLE zone includes redundant glue, for instance the union
- of the A6 records of the first and third options, then under normal
- circumstances duplicate IPv6 addresses will be derived by DNS
- clients. But if provider DNS fails, addresses will still be obtained
- from the zero-prefix-length records, while if the EXAMPLE zone lags
- behind a renumbering of X.EXAMPLE, half of the addresses obtained by
- DNS clients will still be up-to-date.
-
- The zero-prefix-length glue records can of course be automatically
- generated and/or checked in practice.
-
-
-
-
-Crawford, et al. Standards Track [Page 11]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
-5.1.3. Variations
-
- Several more-or-less arbitrary assumptions are reflected in the above
- structure. All of the following choices could have been made
- differently, according to someone's notion of convenience or an
- agreement between two parties.
-
- First, that site X has chosen to put subnet information in a
- separate A6 record rather than incorporate it into each node's A6
- records.
-
- Second, that site X is referred to as "SUBSCRIBER-X" by both of
- its providers A and B.
-
- Third, that site X chose to indirect its provider information
- through A6 records at IP6.X.EXAMPLE containing no significant
- bits. An alternative would have been to replicate each subnet
- record for each provider.
-
- Fourth, B and E used a slightly different prefix naming convention
- between themselves than did A, C and D. Each hierarchical pair of
- network entities must arrange this naming between themselves.
-
- Fifth, that the upward prefix referral chain topped out at ALPHA-
- TLA.ORG. There could have been another level which assigned the
- TLA values and holds A6 records containing those bits.
-
- Finally, the above structure reflects an assumption that address
- fields assigned by a given entity are recorded only in A6 records
- held by that entity. Those bits could be entered into A6 records in
- the lower-level entity's zone instead, thus:
-
- IP6.X.EXAMPLE. A6 40 0:0:11:: IP6.A.NET.
- IP6.X.EXAMPLE. A6 40 0:0:22:: IP6.B.NET.
-
- IP6.A.NET. A6 28 0:1:CA00:: IP6.C.NET.
- and so on.
-
- Or the higher-level entities could hold both sorts of A6 records
- (with different DNS owner names) and allow the lower-level entities
- to choose either mode of A6 chaining. But the general principle of
- avoiding data duplication suggests that the proper place to store
- assigned values is with the entity that assigned them.
-
- It is possible, but not necessarily recommended, for a zone
- maintainer to forego the renumbering support afforded by the chaining
- of A6 records and to record entire IPv6 addresses within one zone
- file.
-
-
-
-Crawford, et al. Standards Track [Page 12]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
-5.2. Reverse Mapping Zones
-
- Supposing that address space assignments in the TLAs with Format
- Prefix (001) binary and IDs 0345, 0678 and 09AB were maintained in
- zones called ALPHA-TLA.ORG, BRAVO-TLA.ORG and CHARLIE-TLA.XY, then
- the IP6.ARPA zone would include
-
- $ORIGIN IP6.ARPA.
- \[x234500/24] DNAME IP6.ALPHA-TLA.ORG.
- \[x267800/24] DNAME IP6.BRAVO-TLA.ORG.
- \[x29AB00/24] DNAME IP6.CHARLIE-TLA.XY.
-
- Eight trailing zero bits have been included in each TLA ID to reflect
- the eight reserved bits in the current aggregatable global unicast
- addresses format [AGGR].
-
-5.2.1. The TLA level
-
- ALPHA-TLA's assignments to network providers C, D and E are reflected
- in the reverse data as follows.
-
- \[xC/4].IP6.ALPHA-TLA.ORG. DNAME IP6.C.NET.
- \[xD/4].IP6.ALPHA-TLA.ORG. DNAME IP6.D.NET.
- \[x0E/8].IP6.ALPHA-TLA.ORG. DNAME IP6.E.NET.
-
-5.2.2. The ISP level
-
- The providers A through E carry the following delegation information
- in their zone files.
-
- \[x1CA/12].IP6.C.NET. DNAME IP6.A.NET.
- \[x2DA/12].IP6.D.NET. DNAME IP6.A.NET.
- \[xEB/8].IP6.E.NET. DNAME IP6.B.NET.
- \[x11/8].IP6.A.NET. DNAME IP6.X.EXAMPLE.
- \[x22/8].IP6.B.NET. DNAME IP6.X.EXAMPLE.
-
- Note that some domain names appear in the RDATA of more than one
- DNAME record. In those cases, one zone is being used to map multiple
- prefixes.
-
-5.2.3. The Site Level
-
- Consider the customer X.EXAMPLE using IP6.X.EXAMPLE for address-to-
- name translations. This domain is now referenced by two different
- DNAME records held by two different providers.
-
-
-
-
-
-
-Crawford, et al. Standards Track [Page 13]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
- $ORIGIN IP6.X.EXAMPLE.
- \[x0001/16] DNAME SUBNET-1
- \[x123456789ABCDEF0].SUBNET-1 PTR N.X.EXAMPLE.
- and so on.
-
- SUBNET-1 need not have been named in a DNAME record; the subnet bits
- could have been joined with the interface identifier. But if subnets
- are treated alike in both the A6 records and in the reverse zone, it
- will always be possible to keep the forward and reverse definition
- data for each prefix in one zone.
-
-5.3. Lookups
-
- A DNS resolver looking for a hostname for the address
- 2345:00C1:CA11:0001:1234:5678:9ABC:DEF0 would acquire certain of the
- DNAME records shown above and would form new queries. Assuming that
- it began the process knowing servers for IP6.ARPA, but that no server
- it consulted provided recursion and none had other useful additional
- information cached, the sequence of queried names and responses would
- be (all with QCLASS=IN, QTYPE=PTR):
-
- To a server for IP6.ARPA:
- QNAME=\[x234500C1CA110001123456789ABCDEF0/128].IP6.ARPA.
-
- Answer:
- \[x234500/24].IP6.ARPA. DNAME IP6.ALPHA-TLA.ORG.
-
- To a server for IP6.ALPHA-TLA.ORG:
- QNAME=\[xC1CA110001123456789ABCDEF0/104].IP6.ALPHA-TLA.ORG.
-
- Answer:
- \[xC/4].IP6.ALPHA-TLA.ORG. DNAME IP6.C.NET.
-
- To a server for IP6.C.NET.:
- QNAME=\[x1CA110001123456789ABCDEF0/100].IP6.C.NET.
-
- Answer:
- \[x1CA/12].IP6.C.NET. DNAME IP6.A.NET.
-
- To a server for IP6.A.NET.:
- QNAME=\[x110001123456789ABCDEF0/88].IP6.A.NET.
-
- Answer:
- \[x11/8].IP6.A.NET. DNAME IP6.X.EXAMPLE.
-
- To a server for IP6.X.EXAMPLE.:
- QNAME=\[x0001123456789ABCDEF0/80].IP6.X.EXAMPLE.
-
-
-
-
-Crawford, et al. Standards Track [Page 14]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
- Answer:
- \[x0001/16].IP6.X.EXAMPLE. DNAME SUBNET-1.IP6.X.EXAMPLE.
- \[x123456789ABCDEF0/64].SUBNET-1.X.EXAMPLE. PTR N.X.EXAMPLE.
-
- All the DNAME (and NS) records acquired along the way can be cached
- to expedite resolution of addresses topologically near to this
- address. And if another global address of N.X.EXAMPLE were resolved
- within the TTL of the final PTR record, that record would not have to
- be fetched again.
-
-5.4. Operational Note
-
- In the illustrations in section 5.1, hierarchically adjacent
- entities, such as a network provider and a customer, must agree on a
- DNS name which will own the definition of the delegated prefix(es).
- One simple convention would be to use a bit-string label representing
- exactly the bits which are assigned to the lower-level entity by the
- higher. For example, "SUBSCRIBER-X" could be replaced by "\[x11/8]".
- This would place the A6 record(s) defining the delegated prefix at
- exactly the same point in the DNS tree as the DNAME record associated
- with that delegation. The cost of this simplification is that the
- lower-level zone must update its upward-pointing A6 records when it
- is renumbered. This cost may be found quite acceptable in practice.
-
-6. Transition from RFC 1886 and Deployment Notes
-
- When prefixes have been "delegated upward" with A6 records, the
- number of DNS resource records required to establish a single IPv6
- address increases by some non-trivial factor. Those records will
- typically, but not necessarily, come from different DNS zones (which
- can independently suffer failures for all the usual reasons). When
- obtaining multiple IPv6 addresses together, this increase in RR count
- will be proportionally less -- and the total size of a DNS reply
- might even decrease -- if the addresses are topologically clustered.
- But the records could still easily exceed the space available in a
- UDP response which returns a large RRset [DNSCLAR] to an MX, NS, or
- SRV query, for example. The possibilities for overall degradation of
- performance and reliability of DNS lookups are numerous, and increase
- with the number of prefix delegations involved, especially when those
- delegations point to records in other zones.
-
- DNS Security [DNSSEC] addresses the trustworthiness of cached data,
- which is a problem intrinsic to DNS, but the cost of applying this to
- an IPv6 address is multiplied by a factor which may be greater than
- the number of prefix delegations involved if different signature
- chains must be verified for different A6 records. If a trusted
- centralized caching server (as in [TSIG], for example) is used, this
- cost might be amortized to acceptable levels. One new phenomenon is
-
-
-
-Crawford, et al. Standards Track [Page 15]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
- the possibility that IPv6 addresses may be formed from a A6 records
- from a combination of secure and unsecured zones.
-
- Until more deployment experience is gained with the A6 record, it is
- recommended that prefix delegations be limited to one or two levels.
- A reasonable phasing-in mechanism would be to start with no prefix
- delegations (all A6 records having prefix length 0) and then to move
- to the use of a single level of delegation within a single zone. (If
- the TTL of the "prefix" A6 records is kept to an appropriate duration
- the capability for rapid renumbering is not lost.) More aggressively
- flexible delegation could be introduced for a subset of hosts for
- experimentation.
-
-6.1. Transition from AAAA and Coexistence with A Records
-
- Administrators of zones which contain A6 records can easily
- accommodate deployed resolvers which understand AAAA records but not
- A6 records. Such administrators can do automatic generation of AAAA
- records for all of a zone's names which own A6 records by a process
- which mimics the resolution of a hostname to an IPv6 address (see
- section 3.1.4). Attention must be paid to the TTL assigned to a
- generated AAAA record, which MUST be no more than the minimum of the
- TTLs of the A6 records that were used to form the IPv6 address in
- that record. For full robustness, those A6 records which were in
- different zones should be monitored for changes (in TTL or RDATA)
- even when there are no changes to zone for which AAAA records are
- being generated. If the zone is secure [DNSSEC], the generated AAAA
- records MUST be signed along with the rest of the zone data.
-
- A zone-specific heuristic MAY be used to avoid generation of AAAA
- records for A6 records which record prefixes, although such
- superfluous records would be relatively few in number and harmless.
- Examples of such heuristics include omitting A6 records with a prefix
- length less than the largest value found in the zone file, or records
- with an address suffix field with a certain number of trailing zero
- bits.
-
- On the client side, when looking up and IPv6 address, the order of A6
- and AAAA queries MAY be configurable to be one of: A6, then AAAA;
- AAAA, then A6; A6 only; or both in parallel. The default order (or
- only order, if not configurable) MUST be to try A6 first, then AAAA.
- If and when the AAAA becomes deprecated a new document will change
- the default.
-
- The guidelines and options for precedence between IPv4 and IPv6
- addresses are specified in [TRANS]. All mentions of AAAA records in
- that document are henceforth to be interpreted as meaning A6 and/or
- AAAA records in the order specified in the previous paragraph.
-
-
-
-Crawford, et al. Standards Track [Page 16]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
-6.2. Transition from Nibble Labels to Binary Labels
-
- Implementations conforming to RFC 1886 [AAAA] perform reverse lookups
- as follows:
-
- An IPv6 address is represented as a name in the IP6.INT domain by
- a sequence of nibbles separated by dots with the suffix
- ".IP6.INT". The sequence of nibbles is encoded in reverse order,
- i.e. the low-order nibble is encoded first, followed by the next
- low-order nibble and so on. Each nibble is represented by a
- hexadecimal digit. For example, a name for the address
- 2345:00C1:CA11:0001:1234:5678:9ABC:DEF0 of the example in section
- 5.3 would be sought at the DNS name "0.f.e.d.c.b.a.9.-
- 8.7.6.5.4.3.2.1.1.0.0.0.1.1.a.c.1.c.0.0.5.4.3.2.ip6.int."
-
- Implementations conforming to this specification will perform a
- lookup of a binary label in IP6.ARPA as specified in Section 3.2. It
- is RECOMMENDED that for a transition period implementations first
- lookup the binary label in IP6.ARPA and if this fails try to lookup
- the 'nibble' label in IP6.INT.
-
-7. Security Considerations
-
- The signing authority [DNSSEC] for the A6 records which determine an
- IPv6 address is distributed among several entities, reflecting the
- delegation path of the address space which that address occupies.
- DNS Security is fully applicable to bit-string labels and DNAME
- records. And just as in IPv4, verification of name-to-address
- mappings is logically independent of verification of address-to-name
- mappings.
-
- With or without DNSSEC, the incomplete but non-empty address set
- scenario of section 3.1.4 could be caused by selective interference
- with DNS lookups. If in some situation this would be more harmful
- than complete DNS failure, it might be mitigated on the client side
- by refusing to act on an incomplete set, or on the server side by
- listing all addresses in A6 records with prefix length 0.
-
-8. IANA Considerations
-
- The A6 resource record has been assigned a Type value of 38.
-
-
-
-
-
-
-
-
-
-
-Crawford, et al. Standards Track [Page 17]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
-9. Acknowledgments
-
- The authors would like to thank the following persons for valuable
- discussions and reviews: Mark Andrews, Rob Austein, Jim Bound, Randy
- Bush, Brian Carpenter, David Conrad, Steve Deering, Francis Dupont,
- Robert Elz, Bob Fink, Olafur Gudmundsson, Bob Halley, Bob Hinden,
- Edward Lewis, Bill Manning, Keith Moore, Thomas Narten, Erik
- Nordmark, Mike O'Dell, Michael Patton and Ken Powell.
-
-10. References
-
- [AAAA] Thomson, S. and C. Huitema, "DNS Extensions to support IP
- version 6, RFC 1886, December 1995.
-
- [AARCH] Hinden, R. and S. Deering, "IP Version 6 Addressing
- Architecture", RFC 2373, July 1998.
-
- [AGGR] Hinden, R., O'Dell, M. and S. Deering, "An IPv6
- Aggregatable Global Unicast Address Format", RFC 2374, July
- 1998.
-
- [BITLBL] Crawford, M., "Binary Labels in the Domain Name System",
- RFC 2673, August 1999.
-
- [DNAME] Crawford, M., "Non-Terminal DNS Name Redirection", RFC
- 2672, August 1999.
-
- [DNSCLAR] Elz, R. and R. Bush, "Clarifications to the DNS
- Specification", RFC 2181, July 1997.
-
- [DNSIS] Mockapetris, P., "Domain names - implementation and
- specification", STD 13, RFC 1035, November 1987.
-
- [DNSSEC] Eastlake, D. 3rd and C. Kaufman, "Domain Name System
- Security Extensions", RFC 2535, March 1999.
-
- [KWORD] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RENUM1] Carpenter, B. and Y. Rekhter, "Renumbering Needs Work", RFC
- 1900, February 1996.
-
- [RENUM2] Ferguson, P. and H. Berkowitz, "Network Renumbering
- Overview: Why would I want it and what is it anyway?", RFC
- 2071, January 1997.
-
- [RENUM3] Carpenter, B., Crowcroft, J. and Y. Rekhter, "IPv4 Address
- Behaviour Today", RFC 2101, February 1997.
-
-
-
-Crawford, et al. Standards Track [Page 18]
-\f
-RFC 2874 IPv6 DNS July 2000
-
-
- [TRANS] Gilligan, R. and E. Nordmark, "Transition Mechanisms for
- IPv6 Hosts and Routers", RFC 1933, April 1996.
-
- [TSIG] Vixie, P., Gudmundsson, O., Eastlake, D. 3rd and B.
- Wellington, "Secret Key Transaction Authentication for DNS
- (TSIG)", RFC 2845, May 2000.
-
-11. Authors' Addresses
-
- Matt Crawford
- Fermilab
- MS 368
- PO Box 500
- Batavia, IL 60510
- USA
-
- Phone: +1 630 840-3461
- EMail: crawdad@fnal.gov
-
-
- Christian Huitema
- Microsoft Corporation
- One Microsoft Way
- Redmond, WA 98052-6399
-
- EMail: huitema@microsoft.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Crawford, et al. Standards Track [Page 19]
-\f
-RFC 2874 IPv6 DNS July 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Crawford, et al. Standards Track [Page 20]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group K. Moore
-Request for Comments: 2964 University of Tennessee
-BCP: 44 N. Freed
-Category: Best Current Practice Innosoft
- October 2000
-
-
- Use of HTTP State Management
-
-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 (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
-
- The mechanisms described in "HTTP State Management Mechanism" (RFC-
- 2965), and its predecessor (RFC-2109), can be used for many different
- purposes. However, some current and potential uses of the protocol
- are controversial because they have significant user privacy and
- security implications. This memo identifies specific uses of
- Hypertext Transfer Protocol (HTTP) State Management protocol which
- are either (a) not recommended by the IETF, or (b) believed to be
- harmful, and discouraged. This memo also details additional privacy
- considerations which are not covered by the HTTP State Management
- protocol specification.
-
-1. Introduction
-
- The HTTP State Management mechanism is both useful and controversial.
- It is useful because numerous applications of HTTP benefit from the
- ability to save state between HTTP transactions, without encoding
- such state in URLs. It is controversial because the mechanism has
- been used to accomplish things for which it was not designed and is
- not well-suited. Some of these uses have attracted a great deal of
- public criticism because they threaten to violate the privacy of web
-
-
-
-Moore & Freed Best Current Practice [Page 1]
-\f
-RFC 2964 Use of HTTP State Management October 2000
-
-
- users, specifically by leaking potentially sensitive information to
- third parties such as the Web sites a user has visited. There are
- also other uses of HTTP State Management which are inappropriate even
- though they do not threaten user privacy.
-
- This memo therefore identifies uses of the HTTP State Management
- protocol specified in RFC-2965 which are not recommended by the IETF,
- or which are believed to be harmful and are therefore discouraged.
-
- This document occasionally uses terms that appear in capital letters.
- When the terms "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
- appear capitalized, they are being used to indicate particular
- requirements of this specification. A discussion of the meanings of
- the terms "MUST", "SHOULD", and "MAY" appears in [RFC-1123]; the
- terms "MUST NOT" and "SHOULD NOT" are logical extensions of this
- usage.
-
-2. Uses of HTTP State Management
-
- The purpose of HTTP State Management is to allow an HTTP-based
- service to create stateful "sessions" which persist across multiple
- HTTP transactions. A single session may involve transactions with
- multiple server hosts. Multiple client hosts may also be involved in
- a single session when the session data for a particular user is
- shared between client hosts (e.g., via a networked file system). In
- other words, the "session" retains state between a "user" and a
- "service", not between particular hosts.
-
- It's important to realize that similar capabilities may also be
- achieved using the "bare" HTTP protocol, and/or dynamically-generated
- HTML, without the State Management extensions. For example, state
- information can be transmitted from the service to the user by
- embedding a session identifier in one or more URLs which appear in
- HTTP redirects, or dynamically generated HTML; and the state
- information may be returned from the user to the service when such
- URLs appear in a GET or POST request. HTML forms can also be used to
- pass state information from the service to the user and back, without
- the user being aware of this happening.
-
- However, the HTTP State Management facility does provide an increase
- in functionality over ordinary HTTP and HTML. In practice, this
- additional functionality includes:
-
- (1) The ability to exchange URLs between users, of resources
- accessed during stateful sessions, without leaking the state
- information associated with those sessions. (e.g. "Here's the
- URL for the FooCorp web catalog entry for those sandals that
- you wanted.")
-
-
-
-Moore & Freed Best Current Practice [Page 2]
-\f
-RFC 2964 Use of HTTP State Management October 2000
-
-
- (2) The ability to maintain session state without "cache-busting".
- That is, separating the session state from the URL allows a web
- cache to maintain only a single copy of the named resource. If
- the state is maintained in session-specific URLs, the cache
- would likely have to maintain several identical copies of the
- resource.
-
- (3) The ability to implement sessions with minimal server
- configuration and minimal protocol overhead, as compared to
- other techniques of maintaining session state.
-
- (4) The ability to associate the user with session state whenever a
- user accesses the service, regardless of whether the user
- enters through a particular "home page" or "portal".
-
- (5) The ability to save session information in stable storage, so
- that a "session" can be maintained across client invocations,
- system reboots, and client or system crashes.
-
-2.1. Recommended Uses
-
- Use of HTTP State Management is appropriate whenever it is desirable
- to maintain state between a user and a service across multiple HTTP
- transactions, provided that:
-
- (1) the user is aware that session state is being maintained and
- consents to it,
-
- (2) the user has the ability to delete the state associated with
- such a session at any time,
-
- (3) the information obtained through the ability to track the
- user's usage of the service is not disclosed to other parties
- without the user's explicit consent, and
-
- (4) session information itself cannot contain sensitive information
- and cannot be used to obtain sensitive information that is not
- otherwise available to an eavesdropper.
-
- This last point is important because cookies are usually sent in the
- clear and hence are readily available to eavesdroppers.
-
- An example of such a recommended use would be a "shopping cart",
- where the existence of the shopping cart is explicitly made known to
- the user, the user can explicitly "empty" his or her shopping cart
- (either by requesting that it be emptied or by purchasing those
-
-
-
-
-
-Moore & Freed Best Current Practice [Page 3]
-\f
-RFC 2964 Use of HTTP State Management October 2000
-
-
- items) and thus cause the shared state to be discarded, and the
- service asserts that it will not disclose the user's shopping or
- browsing habits to third parties without the user's consent.
-
- Note that the HTTP State Management protocol effectively allows a
- service provider to refuse to provide a service, or provide a reduced
- level of service, if the user or a user's client fails to honor a
- request to maintain session state. Absent legal prohibition to the
- contrary, the server MAY refuse to provide the service, or provide a
- reduced level of service, under these conditions. As a purely
- practical consideration, services designed to utilize HTTP State
- Management may be unable to function properly if the client does not
- provide it. Such servers SHOULD gracefully handle such conditions
- and explain to the user why the full level of service is not
- available.
-
-2.2. Problematic Uses
-
- The following uses of HTTP State Management are deemed inappropriate
- and contrary to this specification:
-
-2.2.1. Leakage of Information to Third Parties
-
- HTTP State Management MUST NOT be used to leak information about the
- user or the user's browsing habits to other parties besides the user
- or service, without the user's explicit consent. Such usage is
- prohibited even if the user's name or other externally-assigned
- identifier are not exposed to other parties, because the state
- management mechanism itself provides an identifier which can be used
- to compile information about the user.
-
- Because such practices encourage users to defeat HTTP State
- Management mechanisms, they tend to reduce the effectiveness of HTTP
- State Management, and are therefore considered detrimental to the
- operation of the web.
-
-2.2.2. Use as an Authentication Mechanism
-
- It is generally inappropriate to use the HTTP State Management
- protocol as an authentication mechanism. HTTP State Management is
- not designed with such use in mind, and safeguards for protection of
- authentication credentials are lacking in both the protocol
- specification and in widely deployed HTTP clients and servers. Most
- HTTP sessions are not encrypted and "cookies" may therefore be
- exposed to passive eavesdroppers. Furthermore, HTTP clients and
- servers typically store "cookies" in cleartext with little or no
- protection against exposure. HTTP State Management therefore SHOULD
-
-
-
-
-Moore & Freed Best Current Practice [Page 4]
-\f
-RFC 2964 Use of HTTP State Management October 2000
-
-
- NOT be used as an authentication mechanism to protect information
- from being exposed to unauthorized parties, even if the HTTP sessions
- are encrypted.
-
- The prohibition against using HTTP State Management for
- authentication includes both its use to protect information which is
- provided by the service, and its use to protect potentially sensitive
- information about the user which is entrusted to the service's care.
- For example, it would be inappropriate to expose a user's name,
- address, telephone number, or billing information to a client that
- merely presented a cookie which had been previously associated with
- the user.
-
- Similarly, HTTP State Management SHOULD NOT be used to authenticate
- user requests if unauthorized requests might have undesirable side-
- effects for the user, unless the user is aware of the potential for
- such side-effects and explicitly consents to such use. For example,
- a service which allowed a user to order merchandise with a single
- "click", based entirely on the user's stored "cookies", could
- inconvenience the user by requiring her to dispute charges to her
- credit card, and/or return the unwanted merchandise, in the event
- that the cookies were exposed to third parties.
-
- Some uses of HTTP State Management to identify users may be
- relatively harmless, for example, if the only information which can
- be thus exposed belongs to the service, and the service will suffer
- little harm from the exposure of such information.
-
-3. User Interface Considerations for HTTP State Management
-
- HTTP State Management has been very controversial because of its
- potential to expose information about a user's browsing habits to
- third parties, without the knowledge or consent of the user. While
- such exposure is possible, this is less a flaw in the protocol itself
- than a failure of HTTP client implementations (and of some providers
- of HTTP-based services) to protect users' interests.
-
- As implied above, there are other ways to maintain session state than
- using HTTP State Management, and therefore other ways in which users'
- browsing habits can be tracked. Indeed, it is difficult to imagine
- how the HTTP protocol or an HTTP client could actually prevent a
- service from disclosing a user's "click trail" to other parties if
- the service chose to do so. Protection of such information from
- inappropriate exposure must therefore be the responsibility of the
- service. HTTP client implementations inherently cannot provide such
- protection, though they can implement countermeasures which make it
- more difficult for HTTP State Management to be used as the mechanism
- by which such information is exposed.
-
-
-
-Moore & Freed Best Current Practice [Page 5]
-\f
-RFC 2964 Use of HTTP State Management October 2000
-
-
- It is arguable that HTTP clients should provide more protection in
- general against inappropriate exposure of tracking information,
- regardless of whether the exposure were facilitated by use of HTTP
- State Management or by some other means. However, issues related to
- other mechanisms are beyond the scope of this memo.
-
-3.1. Capabilities Required of an HTTP Client
-
- A user's willingness to consent to use of HTTP State Management is
- likely to vary from one service to another, according to whether the
- user trusts the service to use the information appropriately and to
- limit its exposure to other parties. The user therefore SHOULD be
- able to control whether his client supports a service's request to
- use HTTP State Management, on a per-service basis. In particular:
-
- (1) Clients MUST NOT respond to HTTP State Management requests
- unless explicitly enabled by the user.
-
- (2) Clients SHOULD provide an effective interface which allows
- users to review, and approve or refuse, any particular requests
- from a server to maintain state information, before the client
- provides any state information to the server.
-
- (3) Clients SHOULD provide an effective interface which allows
- users to instruct their clients to ignore all requests from a
- particular service to maintain state information, on a per-
- service basis, immediately in response to any particular
- request from a server, before the client provides any state
- information to the server.
-
- (4) Clients SHOULD provide an effective interface which allows a
- user to disable future transmission of any state information to
- a service, and/or discard any saved state information for that
- service, even though the user has previously approved a
- service's request to maintain state information.
-
- (5) Clients SHOULD provide an effective interface which allows a
- user to terminate a previous request not to retain state
- management information for a given service.
-
-3.2. Limitations of the domain-match algorithm
-
- The domain-match algorithm in RFC-2965 section 2 is intended as a
- heuristic to allow a client to "guess" whether or not two domains are
- part of the same service. There are few rules about how domain names
- can be used, and the structure of domain names and how they are
- delegated varies from one top-level domain to another (i.e. the
- client cannot tell which part of the domain was assigned to the
-
-
-
-Moore & Freed Best Current Practice [Page 6]
-\f
-RFC 2964 Use of HTTP State Management October 2000
-
-
- service). Therefore NO string comparison algorithm (including the
- domain-match algorithm) can be relied on to distinguish a domain that
- belongs to a particular service, from a domain that belongs to
- another party.
-
- As stated above, each service is ultimately responsible for ensuring
- that user information is not inappropriately leaked to third parties.
- Leaking information to third parties via State Management by careful
- selection of domain names, or by assigning domain names to hosts
- maintained by third parties, is at least as inappropriate as leaking
- the same information by other means.
-
-4. Security Considerations
-
- This entire memo is about security considerations.
-
-5. Authors' Addresses
-
- Keith Moore
- University of Tennessee Computer Science Department
- 1122 Volunteer Blvd, Suite 203
- Knoxville TN, 37996-3450
-
- EMail: moore@cs.utk.edu
-
-
- Ned Freed
- Innosoft International, Inc.
- 1050 Lakes Drive
- West Covina, CA 81790
-
- EMail: ned.freed@innosoft.com
-
-6. References
-
- [RFC 1123] Braden, R., "Requirements for Internet Hosts --
- Application and Support", STD 3, RFC 1123, October 1989.
-
- [RFC 2965] Kristol, D. and L. Montulli, "HTTP State Management
- Mechanism", RFC 2965, October 2000.
-
- [RFC 2109] Kristol, D. and L. Montulli, "HTTP State Management
- Mechanism", RFC 2109, February 1997.
-
-
-
-
-
-
-
-
-Moore & Freed Best Current Practice [Page 7]
-\f
-RFC 2964 Use of HTTP State Management October 2000
-
-
-7. 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Moore & Freed Best Current Practice [Page 8]
-\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 B. Aboba
-Request for Comments: 3162 Microsoft
-Category: Standards Track G. Zorn
- Cisco Systems
- D. Mitton
- Circular Logic UnLtd.
- August 2001
-
-
- RADIUS and IPv6
-
-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 specifies the operation of RADIUS (Remote
- Authentication Dial In User Service) when run over IPv6 as well as
- the RADIUS attributes used to support IPv6 network access.
-
-1. Introduction
-
- This document specifies the operation of RADIUS [4]-[8] over IPv6
- [13] as well as the RADIUS attributes used to support IPv6 network
- access.
-
- Note that a NAS sending a RADIUS Access-Request may not know a-priori
- whether the host will be using IPv4, IPv6, or both. For example,
- within PPP, IPv6CP [11] occurs after LCP, so that address assignment
- will not occur until after RADIUS authentication and authorization
- has completed.
-
- Therefore it is presumed that the IPv6 attributes described in this
- document MAY be sent along with IPv4-related attributes within the
- same RADIUS message and that the NAS will decide which attributes to
- use. The NAS SHOULD only allocate addresses and prefixes that the
- client can actually use, however. For example, there is no need for
-
-
-
-
-
-Aboba, et al. Standards Track [Page 1]
-\f
-RFC 3162 RADIUS and IPv6 August 2001
-
-
- the NAS to reserve use of an IPv4 address for a host that only
- supports IPv6; similarly, a host only using IPv4 or 6to4 [12] does
- not require allocation of an IPv6 prefix.
-
- The NAS can provide IPv6 access natively, or alternatively, via other
- methods such as IPv6 within IPv4 tunnels [15] or 6over4 [14]. The
- choice of method for providing IPv6 access has no effect on RADIUS
- usage per se, although if it is desired that an IPv6 within IPv4
- tunnel be opened to a particular location, then tunnel attributes
- should be utilized, as described in [6], [7].
-
-1.1. Requirements language
-
- In this document, the key words "MAY", "MUST, "MUST NOT", "optional",
- "recommended", "SHOULD", and "SHOULD NOT", are to be interpreted as
- described in [1].
-
-2. Attributes
-
-2.1. NAS-IPv6-Address
-
- Description
-
- This Attribute indicates the identifying IPv6 Address of the NAS
- which is requesting authentication of the user, and SHOULD be
- unique to the NAS within the scope of the RADIUS server. NAS-
- IPv6-Address is only used in Access-Request packets. NAS-IPv6-
- Address and/or NAS-IP-Address MAY be present in an Access-Request
- packet; however, if neither attribute is present then NAS-
- Identifier MUST be present.
-
- A summary of the NAS-IPv6-Address Attribute format is shown below.
- The fields are transmitted from left to right.
-
- 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
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Type | Length | Address
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Address
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Address
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Address
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Address |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
-
-
-
-Aboba, et al. Standards Track [Page 2]
-\f
-RFC 3162 RADIUS and IPv6 August 2001
-
-
- Type
-
- 95 for NAS-IPv6-Address
-
- Length
-
- 18
-
- Address
-
- The Address field is 16 octets.
-
-3.2. Framed-Interface-Id
-
- Description
-
- This Attribute indicates the IPv6 interface identifier to be
- configured for the user. It MAY be used in Access-Accept packets.
- If the Interface-Identifier IPv6CP option [11] has been
- successfully negotiated, this Attribute MUST be included in an
- Access-Request packet as a hint by the NAS to the server that it
- would prefer that value. It is recommended, but not required,
- that the server honor the hint.
-
- A summary of the Framed-Interface-Id Attribute format is shown below.
- The fields are transmitted from left to right.
-
- 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
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Type | Length | Interface-Id
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Interface-Id
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Interface-Id |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- Type
-
- 96 for Framed-Interface-Id
-
- Length
-
- 10
-
- Interface-Id
-
- The Interface-Id field is 8 octets.
-
-
-
-Aboba, et al. Standards Track [Page 3]
-\f
-RFC 3162 RADIUS and IPv6 August 2001
-
-
-2.3. Framed-IPv6-Prefix
-
- Description
-
- This Attribute indicates an IPv6 prefix (and corresponding route)
- to be configured for the user. It MAY be used in Access-Accept
- packets, and can appear multiple times. It MAY be used in an
- Access-Request packet as a hint by the NAS to the server that it
- would prefer these prefix(es), but the server is not required to
- honor the hint. Since it is assumed that the NAS will plumb a
- route corresponding to the prefix, it is not necessary for the
- server to also send a Framed-IPv6-Route attribute for the same
- prefix.
-
- A summary of the Framed-IPv6-Prefix Attribute format is shown below.
- The fields are transmitted from left to right.
-
- 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
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Type | Length | Reserved | Prefix-Length |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Prefix
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Prefix
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Prefix
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Prefix |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- Type
-
- 97 for Framed-IPv6-Prefix
-
- Length
-
- At least 4 and no larger than 20.
-
- Reserved
-
- This field, which is reserved and MUST be present, is always set
- to zero.
-
- Prefix-Length
-
- The length of the prefix, in bits. At least 0 and no larger than
- 128.
-
-
-
-Aboba, et al. Standards Track [Page 4]
-\f
-RFC 3162 RADIUS and IPv6 August 2001
-
-
- Prefix
-
- The Prefix field is up to 16 octets in length. Bits outside of
- the Prefix-Length, if included, must be zero.
-
-2.4. Login-IPv6-Host
-
- Description
-
- This Attribute indicates the system with which to connect the
- user, when the Login-Service Attribute is included. It MAY be
- used in Access-Accept packets. It MAY be used in an Access-
- Request packet as a hint to the server that the NAS would prefer
- to use that host, but the server is not required to honor the
- hint.
-
- A summary of the Login-IPv6-Host Attribute format is shown below.
- The fields are transmitted from left to right.
-
- 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
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Type | Length | Address
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Address
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Address
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Address
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Address |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- Type
-
- 98 for Login-IPv6-Host
-
- Length
-
- 18
-
-
-
-
-
-
-
-
-
-
-
-Aboba, et al. Standards Track [Page 5]
-\f
-RFC 3162 RADIUS and IPv6 August 2001
-
-
- Address
-
- The Address field is 16 octets in length. The value
- 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF indicates that the NAS SHOULD
- allow the user to select an address or name to be connected to.
- The value 0 indicates that the NAS SHOULD select a host to connect
- the user to. Other values indicate the address the NAS SHOULD
- connect the user to.
-
-2.5. Framed-IPv6-Route
-
- Description
-
- This Attribute provides routing information to be configured for
- the user on the NAS. It is used in the Access-Accept packet and
- can appear multiple times.
-
- A summary of the Framed-IPv6-Route Attribute format is shown below.
- The fields are transmitted from left to right.
-
- 0 1 2
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
- | Type | Length | Text ...
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
-
- Type
-
- 99 for Framed-IPv6-Route
-
- Length
-
- >=3
-
- Text
-
- The Text field is one or more octets, and its contents are
- implementation dependent. The field is not NUL (hex 00)
- terminated. It is intended to be human readable and MUST NOT
- affect operation of the protocol.
-
- For IPv6 routes, it SHOULD contain a destination prefix optionally
- followed by a slash and a decimal length specifier stating how
- many high order bits of the prefix to use. That is followed by a
- space, a gateway address, a space, and one or more metrics
- (encoded in decimal) separated by spaces. Prefixes and addresses
- are formatted as described in [16]. For example,
- "2000:0:0:106::/64 2000::106:a00:20ff:fe99:a998 1".
-
-
-
-Aboba, et al. Standards Track [Page 6]
-\f
-RFC 3162 RADIUS and IPv6 August 2001
-
-
- Whenever the gateway address is the IPv6 unspecified address the
- IP address of the user SHOULD be used as the gateway address. The
- unspecified address can be expressed in any of the acceptable
- formats described in [16]. For example, "2000:0:0:106::/64 :: 1".
-
-2.6. Framed-IPv6-Pool
-
- Description
-
- This Attribute contains the name of an assigned pool that SHOULD
- be used to assign an IPv6 prefix for the user. If a NAS does not
- support multiple prefix pools, the NAS MUST ignore this Attribute.
-
- A summary of the Framed-IPv6-Pool Attribute format is shown below.
- The fields are transmitted from left to right.
-
- 0 1 2
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Type | Length | String...
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-
- Type
-
- 100 for Framed-IPv6-Pool
-
- Length
-
- >= 3
-
- String
-
- The string field contains the name of an assigned IPv6 prefix pool
- configured on the NAS. The field is not NUL (hex 00) terminated.
-
-3. Table of Attributes
-
- The following table provides a guide to which attributes may be found
- in which kinds of packets, and in what quantity.
-
- Request Accept Reject Challenge Accounting # Attribute
- Request
- 0-1 0 0 0 0-1 95 NAS-IPv6-Address
- 0-1 0-1 0 0 0-1 96 Framed-Interface-Id
- 0+ 0+ 0 0 0+ 97 Framed-IPv6-Prefix
- 0+ 0+ 0 0 0+ 98 Login-IPv6-Host
- 0 0+ 0 0 0+ 99 Framed-IPv6-Route
- 0 0-1 0 0 0-1 100 Framed-IPv6-Pool
-
-
-
-Aboba, et al. Standards Track [Page 7]
-\f
-RFC 3162 RADIUS and IPv6 August 2001
-
-
-4. References
-
- [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
- Levels", BCP 14, RFC 2119, March, 1997.
-
- [2] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO
- 10646", RFC 2044, October 1996.
-
- [3] Aboba, B. and J. Vollbrecht, "Proxy Chaining and Policy
- Implementation in Roaming", RFC 2607, June 1999.
-
- [4] Rigney, C., Rubens, A., Simpson, W. and S. Willens, "Remote
- Authentication Dial In User Service (RADIUS)", RFC 2865, June
- 2000.
-
- [5] Rigney, C., "RADIUS Accounting", RFC 2866, June 2000.
-
- [6] Zorn, G., Mitton, D. and B. Aboba, "RADIUS Accounting
- Modifications for Tunnel Protocol Support", RFC 2867, June
- 2000.
-
- [7] Zorn, G., Leifer, D., Rubens, A., Shriver, J., Holdrege, M.
- and I. Goyret, "RADIUS Attributes for Tunnel Protocol Support",
- RFC 2868, June 2000.
-
- [8] Rigney, C., Willats, W. and P. Calhoun, "RADIUS Extensions",
- RFC 2869, June 2000.
-
- [9] Kent S. and R. Atkinson, "Security Architecture for the
- Internet Protocol", RFC 2401, November 1998.
-
- [10] Alvestrand, H. and T. Narten, "Guidelines for Writing an IANA
- Considerations Section in RFCs", BCP 26, RFC 2434, October
- 1998.
-
- [11] Haskin, D. and E. Allen, "IP Version 6 over PPP", RFC 2472,
- December 1998.
-
- [12] Carpenter, B. and K. Moore, "Connection of IPv6 Domains via
- IPv4 Clouds", RFC 3056, February 2001.
-
- [13] Deering, S. and R. Hinden, "Internet Protocol, Version 6 (IPv6)
- Specification", RFC 2460, December 1998.
-
- [14] Carpenter, B. and C. Jung, "Transmission of IPv6 over IPv4
- Domains without Explicit Tunnels", RFC 2529, March 1999.
-
-
-
-
-
-Aboba, et al. Standards Track [Page 8]
-\f
-RFC 3162 RADIUS and IPv6 August 2001
-
-
- [15] Gilligan, R. and E. Nordmark, "Transition Mechanisms for IPv6
- Hosts and Routers", RFC 2893, August 2000.
-
- [16] Hinden, R. and S. Deering, "IP Version 6 Addressing
- Architecture", RFC 2373, July 1998.
-
-5. Security Considerations
-
- This document describes the use of RADIUS for the purposes of
- authentication, authorization and accounting in IPv6-enabled
- networks. In such networks, the RADIUS protocol may run either over
- IPv4 or over IPv6. Known security vulnerabilities of the RADIUS
- protocol are described in [3], [4] and [8].
-
- Since IPSEC [9] is mandatory to implement for IPv6, it is expected
- that running RADIUS implementations supporting IPv6 will typically
- run over IPSEC. Where RADIUS is run over IPSEC and where
- certificates are used for authentication, it may be desirable to
- avoid management of RADIUS shared secrets, so as to leverage the
- improved scalability of public key infrastructure.
-
- Within RADIUS, a shared secret is used for hiding of attributes such
- as User-Password [4] and Tunnel-Password [7]. In addition, the
- shared secret is used in computation of the Response Authenticator
- [4], as well as the Message-Authenticator attribute [8]. Therefore,
- in RADIUS a shared secret is used to provide confidentiality as well
- as integrity protection and authentication. As a result, only use of
- IPSEC ESP with a non-null transform can provide security services
- sufficient to substitute for RADIUS application-layer security.
- Therefore, where IPSEC AH or ESP null is used, it will typically
- still be necessary to configure a RADIUS shared secret.
-
- However, where RADIUS is run over IPSEC ESP with a non-null
- transform, the secret shared between the NAS and the RADIUS server
- MAY NOT be configured. In this case, a shared secret of zero length
- MUST be assumed.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Aboba, et al. Standards Track [Page 9]
-\f
-RFC 3162 RADIUS and IPv6 August 2001
-
-
-6. IANA Considerations
-
- This document requires the assignment of six new RADIUS attribute
- numbers for the following attributes:
-
- NAS-IPv6-Address
- Framed-Interface-Id
- Framed-IPv6-Prefix
- Login-IPv6-Host
- Framed-IPv6-Route
- Framed-IPv6-Pool
-
- See section 3 for the registered list of numbers.
-
-7. Acknowledgments
-
- The authors would like to acknowledge Jun-ichiro itojun Hagino of IIJ
- Research Laboratory, Darran Potter of Cisco and Carl Rigney of Lucent
- for contributions to this document.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Aboba, et al. Standards Track [Page 10]
-\f
-RFC 3162 RADIUS and IPv6 August 2001
-
-
-8. Authors' Addresses
-
- Bernard Aboba
- Microsoft Corporation
- One Microsoft Way
- Redmond, WA 98052
-
- Phone: +1 425 936 6605
- Fax: +1 425 936 7329
- EMail: bernarda@microsoft.com
-
-
- Glen Zorn
- Cisco Systems, Inc.
- 500 108th Avenue N.E., Suite 500
- Bellevue, WA 98004
-
- Phone: +1 425 471 4861
- EMail: gwz@cisco.com
-
-
- Dave Mitton
- Circular Logic UnLtd.
- 733 Turnpike Street #154
- North Andover, MA 01845
-
- Phone: 978 683-1814
- Email: david@mitton.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Aboba, et al. Standards Track [Page 11]
-\f
-RFC 3162 RADIUS and IPv6 August 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Aboba, et al. Standards Track [Page 12]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group O. Gudmundsson
-Request for Comments: 3226 December 2001
-Updates: 2874, 2535
-Category: Standards Track
-
-
- DNSSEC and IPv6 A6 aware server/resolver message size requirements
-
-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 mandates support for EDNS0 (Extension Mechanisms for
- DNS) in DNS entities claiming to support either DNS Security
- Extensions or A6 records. This requirement is necessary because
- these new features increase the size of DNS messages. If EDNS0 is
- not supported fall back to TCP will happen, having a detrimental
- impact on query latency and DNS server load. This document updates
- RFC 2535 and RFC 2874, by adding new requirements.
-
-1. Introduction
-
- Familiarity with the DNS [RFC1034, RFC1035], DNS Security Extensions
- [RFC2535], EDNS0 [RFC2671] and A6 [RFC2874] is helpful.
-
- STD 13, RFC 1035 Section 2.3.4 requires that DNS messages over UDP
- have a data payload of 512 octets or less. Most DNS software today
- will not accept larger UDP datagrams. Any answer that requires more
- than 512 octets, results in a partial and sometimes useless reply
- with the Truncation Bit set; in most cases the requester will then
- retry using TCP. Furthermore, server delivery of truncated responses
- varies widely and resolver handling of these responses also varies,
- leading to additional inefficiencies in handling truncation.
-
- Compared to UDP, TCP is an expensive protocol to use for a simple
- transaction like DNS: a TCP connection requires 5 packets for setup
- and tear down, excluding data packets, thus requiring at least 3
- round trips on top of the one for the original UDP query. The DNS
-
-
-
-Gudmundsson Standards Track [Page 1]
-\f
-RFC 3226 DNSSEC and IPv6 A6 requirements December 2001
-
-
- server also needs to keep a state of the connection during this
- transaction. Many DNS servers answer thousands of queries per
- second, requiring them to use TCP will cause significant overhead and
- delays.
-
-1.1. Requirements
-
- The key words "MUST", "REQUIRED", "SHOULD", "RECOMMENDED", and "MAY"
- in this document are to be interpreted as described in RFC 2119.
-
-2. Motivating factors
-
-2.1. DNSSEC motivations
-
- DNSSEC [RFC2535] secures DNS by adding a Public Key signature on each
- RR set. These signatures range in size from about 80 octets to 800
- octets, most are going to be in the range of 80 to 200 octets. The
- addition of signatures on each or most RR sets in an answer
- significantly increases the size of DNS answers from secure zones.
-
- For performance reasons and to reduce load on DNS servers, it is
- important that security aware servers and resolvers get all the data
- in Answer and Authority section in one query without truncation.
- Sending Additional Data in the same query is helpful when the server
- is authoritative for the data, and this reduces round trips.
-
- DNSSEC OK[OK] specifies how a client can, using EDNS0, indicate that
- it is interested in receiving DNSSEC records. The OK bit does not
- eliminate the need for large answers for DNSSEC capable clients.
-
-2.1.1. Message authentication or TSIG motivation
-
- TSIG [RFC2845] allows for the light weight authentication of DNS
- messages, but increases the size of the messages by at least 70
- octets. DNSSEC specifies for computationally expensive message
- authentication SIG(0) using a standard public key signature. As only
- one TSIG or SIG(0) can be attached to each DNS answer the size
- increase of message authentication is not significant, but may still
- lead to a truncation.
-
-2.2. IPv6 Motivations
-
- IPv6 addresses [RFC2874] are 128 bits and can be represented in the
- DNS by multiple A6 records, each consisting of a domain name and a
- bit field. The domain name refers to an address prefix that may
- require additional A6 RRs to be included in the answer. Answers
- where the queried name has multiple A6 addresses may overflow a 512-
- octet UDP packet size.
-
-
-
-Gudmundsson Standards Track [Page 2]
-\f
-RFC 3226 DNSSEC and IPv6 A6 requirements December 2001
-
-
-2.3. Root server and TLD server motivations
-
- The current number of root servers is limited to 13 as that is the
- maximum number of name servers and their address records that fit in
- one 512-octet answer for a SOA record. If root servers start
- advertising A6 or KEY records then the answer for the root NS records
- will not fit in a single 512-octet DNS message, resulting in a large
- number of TCP query connections to the root servers. Even if all
- client resolver query their local name server for information, there
- are millions of these servers. Each name server must periodically
- update its information about the high level servers.
-
- For redundancy, latency and load balancing reasons, large numbers of
- DNS servers are required for some zones. Since the root zone is used
- by the entire net, it is important to have as many servers as
- possible. Large TLDs (and many high-visibility SLDs) often have
- enough servers that either A6 or KEY records would cause the NS
- response to overflow the 512 byte limit. Note that these zones with
- large numbers of servers are often exactly those zones that are
- critical to network operation and that already sustain fairly high
- loads.
-
-2.4. UDP vs TCP for DNS messages
-
- Given all these factors, it is essential that any implementation that
- supports DNSSEC and or A6 be able to use larger DNS messages than 512
- octets.
-
- The original 512 restriction was put in place to reduce the
- probability of fragmentation of DNS responses. A fragmented UDP
- message that suffers a loss of one of the fragments renders the
- answer useless and the query must be retried. A TCP connection
- requires a larger number of round trips for establishment, data
- transfer and tear down, but only the lost data segments are
- retransmitted.
-
- In the early days a number of IP implementations did not handle
- fragmentation well, but all modern operating systems have overcome
- that issue thus sending fragmented messages is fine from that
- standpoint. The open issue is the effect of losses on fragmented
- messages. If connection has high loss ratio only TCP will allow
- reliable transfer of DNS data, most links have low loss ratios thus
- sending fragmented UDP packet in one round trip is better than
- establishing a TCP connection to transfer a few thousand octets.
-
-
-
-
-
-
-
-Gudmundsson Standards Track [Page 3]
-\f
-RFC 3226 DNSSEC and IPv6 A6 requirements December 2001
-
-
-2.5. EDNS0 and large UDP messages
-
- EDNS0 [RFC2671] allows clients to declare the maximum size of UDP
- message they are willing to handle. Thus, if the expected answer is
- between 512 octets and the maximum size that the client can accept,
- the additional overhead of a TCP connection can be avoided.
-
-3. Protocol changes:
-
- This document updates RFC 2535 and RFC 2874, by adding new
- requirements.
-
- All RFC 2535 compliant servers and resolvers MUST support EDNS0 and
- advertise message size of at least 1220 octets, but SHOULD advertise
- message size of 4000. This value might be too low to get full
- answers for high level servers and successor of this document may
- require a larger value.
-
- All RFC 2874 compliant servers and resolver MUST support EDNS0 and
- advertise message size of at least 1024 octets, but SHOULD advertise
- message size of 2048. The IPv6 datagrams should be 1024 octets,
- unless the MTU of the path is known. (Note that this is smaller than
- the minimum IPv6 MTU to allow for some extension headers and/or
- encapsulation without exceeding the minimum MTU.)
-
- All RFC 2535 and RFC 2874 compliant entities MUST be able to handle
- fragmented IPv4 and IPv6 UDP packets.
-
- All hosts supporting both RFC 2535 and RFC 2874 MUST use the larger
- required value in EDNS0 advertisements.
-
-4. Acknowledgments
-
- Harald Alvestrand, Rob Austein, Randy Bush, David Conrad, Andreas
- Gustafsson, Jun-ichiro itojun Hagino, Bob Halley, Edward Lewis
- Michael Patton and Kazu Yamamoto were instrumental in motivating and
- shaping this document.
-
-5. Security Considerations:
-
- There are no additional security considerations other than those in
- RFC 2671.
-
-6. IANA Considerations:
-
- None
-
-
-
-
-
-Gudmundsson Standards Track [Page 4]
-\f
-RFC 3226 DNSSEC and IPv6 A6 requirements December 2001
-
-
-7. References
-
- [RFC1034] Mockapetris, P., "Domain Names - Concepts and Facilities",
- STD 13, RFC 1034, November 1987.
-
- [RFC1035] Mockapetris, P., "Domain Names - Implementation and
- Specification", STD 13, RFC 1035, November 1987.
-
- [RFC2535] Eastlake, D. "Domain Name System Security Extensions", RFC
- 2535, March 1999.
-
- [RFC2671] Vixie, P., "Extension Mechanisms for DNS (EDNS0)", RFC
- 2671, August 1999.
-
- [RFC2845] Vixie, P., Gudmundsson, O., Eastlake, D. and B.
- Wellington, "Secret Key Transaction Authentication for DNS
- (TSIG)", RFC 2845, May 2000.
-
- [RFC2874] Crawford, M. and C. Huitema, "DNS Extensions to Support
- IPv6 Address Aggregation and Renumbering", RFC 2874, July
- 2000.
-
- [RFC3225] Conrad, D., "Indicating Resolver Support of DNSSEC", RFC
- 3225, December 2001.
-
-8. Author Address
-
- Olafur Gudmundsson
- 3826 Legation Street, NW
- Washington, DC 20015
- USA
-
- EMail: ogud@ogud.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Gudmundsson Standards Track [Page 5]
-\f
-RFC 3226 DNSSEC and IPv6 A6 requirements December 2001
-
-
-9. 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Gudmundsson Standards Track [Page 6]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group A. Niemi
-Request for Comments: 3310 Nokia
-Category: Informational J. Arkko
- V. Torvinen
- Ericsson
- September 2002
-
-
- Hypertext Transfer Protocol (HTTP) Digest Authentication
- Using Authentication and Key Agreement (AKA)
-
-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 memo specifies an Authentication and Key Agreement (AKA) based
- one-time password generation mechanism for Hypertext Transfer
- Protocol (HTTP) Digest access authentication. The HTTP
- Authentication Framework includes two authentication schemes: Basic
- and Digest. Both schemes employ a shared secret based mechanism for
- access authentication. The AKA mechanism performs user
- authentication and session key distribution in Universal Mobile
- Telecommunications System (UMTS) networks. AKA is a challenge-
- response based mechanism that uses symmetric cryptography.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Niemi, et. al. Informational [Page 1]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA September 2002
-
-
-Table of Contents
-
- 1. Introduction and Motivation . . . . . . . . . . . . . . . . . 2
- 1.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 1.2 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4
- 2. AKA Mechanism Overview . . . . . . . . . . . . . . . . . . . . 4
- 3. Specification of Digest AKA . . . . . . . . . . . . . . . . . 5
- 3.1 Algorithm Directive . . . . . . . . . . . . . . . . . . . . . 5
- 3.2 Creating a Challenge . . . . . . . . . . . . . . . . . . . . . 6
- 3.3 Client Authentication . . . . . . . . . . . . . . . . . . . . 7
- 3.4 Synchronization Failure . . . . . . . . . . . . . . . . . . . 7
- 3.5 Server Authentication . . . . . . . . . . . . . . . . . . . . 8
- 4. Example Digest AKA Operation . . . . . . . . . . . . . . . . . 8
- 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12
- 5.1 Authentication of Clients using Digest AKA . . . . . . . . . . 13
- 5.2 Limited Use of Nonce Values . . . . . . . . . . . . . . . . . 13
- 5.3 Multiple Authentication Schemes and Algorithms . . . . . . . . 14
- 5.4 Online Dictionary Attacks . . . . . . . . . . . . . . . . . . 14
- 5.5 Session Protection . . . . . . . . . . . . . . . . . . . . . . 14
- 5.6 Replay Protection . . . . . . . . . . . . . . . . . . . . . . 15
- 5.7 Improvements to AKA Security . . . . . . . . . . . . . . . . . 15
- 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
- 6.1 Registration Template . . . . . . . . . . . . . . . . . . . . 16
- Normative References . . . . . . . . . . . . . . . . . . . . . 16
- Informative References . . . . . . . . . . . . . . . . . . . . 16
- A. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17
- Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 17
- Full Copyright Statement . . . . . . . . . . . . . . . . . . . 18
-
-1. Introduction and Motivation
-
- The Hypertext Transfer Protocol (HTTP) Authentication Framework,
- described in RFC 2617 [2], includes two authentication schemes: Basic
- and Digest. Both schemes employ a shared secret based mechanism for
- access authentication. The Basic scheme is inherently insecure in
- that it transmits user credentials in plain text. The Digest scheme
- improves security by hiding user credentials with cryptographic
- hashes, and additionally by providing limited message integrity.
-
- The Authentication and Key Agreement (AKA) [6] mechanism performs
- authentication and session key distribution in Universal Mobile
- Telecommunications System (UMTS) networks. AKA is a challenge-
- response based mechanism that uses symmetric cryptography. AKA is
- typically run in a UMTS IM Services Identity Module (ISIM), which
- resides on a smart card like device that also provides tamper
- resistant storage of shared secrets.
-
-
-
-
-
-Niemi, et. al. Informational [Page 2]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA September 2002
-
-
- This document specifies a mapping of AKA parameters onto HTTP Digest
- authentication. In essence, this mapping enables the usage of AKA as
- a one-time password generation mechanism for Digest authentication.
-
- As the Session Initiation Protocol (SIP) [3] Authentication Framework
- closely follows the HTTP Authentication Framework, Digest AKA is
- directly applicable to SIP as well as any other embodiment of HTTP
- Digest.
-
-1.1 Terminology
-
- This chapter explains the terminology used in this document.
-
- AKA
- Authentication and Key Agreement.
-
- AuC
- Authentication Center. The network element in mobile networks
- that can authorize users either in GSM or in UMTS networks.
-
- AUTN
- Authentication Token. A 128 bit value generated by the AuC, which
- together with the RAND parameter authenticates the server to the
- client.
-
- AUTS
- Authentication Token. A 112 bit value generated by the client
- upon experiencing an SQN synchronization failure.
-
- CK
- Cipher Key. An AKA session key for encryption.
-
- IK
- Integrity Key. An AKA session key for integrity check.
-
- ISIM
- IP Multimedia Services Identity Module.
-
- PIN
- Personal Identification Number. Commonly assigned passcodes for
- use with automatic cash machines, smart cards, etc.
-
- RAND
- Random Challenge. Generated by the AuC using the SQN.
-
- RES
- Authentication Response. Generated by the ISIM.
-
-
-
-
-Niemi, et. al. Informational [Page 3]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA September 2002
-
-
- SIM
- Subscriber Identity Module. GSM counter part for ISIM.
-
- SQN
- Sequence Number. Both AuC and ISIM maintain the value of the SQN.
-
- UMTS
- Universal Mobile Telecommunications System.
-
- XRES
- Expected Authentication Response. In a successful authentication
- this is equal to RES.
-
-1.2 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, RFC 2119 [1].
-
-2. AKA Mechanism Overview
-
- This chapter describes the AKA operation in detail:
-
- 1. A shared secret K is established beforehand between the ISIM and
- the Authentication Center (AuC). The secret is stored in the
- ISIM, which resides on a smart card like, tamper resistant device.
-
- 2. The AuC of the home network produces an authentication vector AV,
- based on the shared secret K and a sequence number SQN. The
- authentication vector contains a random challenge RAND, network
- authentication token AUTN, expected authentication result XRES, a
- session key for integrity check IK, and a session key for
- encryption CK.
-
- 3. The authentication vector is downloaded to a server. Optionally,
- the server can also download a batch of AVs, containing more than
- one authentication vector.
-
- 4. The server creates an authentication request, which contains the
- random challenge RAND, and the network authenticator token AUTN.
-
- 5. The authentication request is delivered to the client.
-
- 6. Using the shared secret K and the sequence number SQN, the client
- verifies the AUTN with the ISIM. If the verification is
- successful, the network has been authenticated. The client then
- produces an authentication response RES, using the shared secret K
- and the random challenge RAND.
-
-
-
-Niemi, et. al. Informational [Page 4]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA September 2002
-
-
- 7. The authentication response, RES, is delivered to the server.
-
- 8. The server compares the authentication response RES with the
- expected response, XRES. If the two match, the user has been
- successfully authenticated, and the session keys, IK and CK, can
- be used for protecting further communications between the client
- and the server.
-
- When verifying the AUTN, the client may detect that the sequence
- numbers between the client and the server have fallen out of sync.
- In this case, the client produces a synchronization parameter AUTS,
- using the shared secret K and the client sequence number SQN. The
- AUTS parameter is delivered to the network in the authentication
- response, and the authentication can be tried again based on
- authentication vectors generated with the synchronized sequence
- number.
-
- For a specification of the AKA mechanism and the generation of the
- cryptographic parameters AUTN, RES, IK, CK, and AUTS, see reference
- 3GPP TS 33.102 [6].
-
-3. Specification of Digest AKA
-
- In general, the Digest AKA operation is identical to the Digest
- operation in RFC 2617 [2]. This chapter specifies the parts in which
- Digest AKA extends the Digest operation. The notation used in the
- Augmented BNF definitions for the new and modified syntax elements in
- this section is as used in SIP [3], and any elements not defined in
- this section are as defined in SIP and the documents to which it
- refers.
-
-3.1 Algorithm Directive
-
- In order to direct the client into using AKA for authentication
- instead of the standard password system, the RFC 2617 defined
- algorithm directive is overloaded in Digest AKA:
-
- algorithm = "algorithm" EQUAL ( aka-namespace
- / algorithm-value )
- aka-namespace = aka-version "-" algorithm-value
- aka-version = "AKAv" 1*DIGIT
- algorithm-value = ( "MD5" / "MD5-sess" / token )
-
- algorithm
- A string indicating the algorithm used in producing the digest and
- the checksum. If the directive is not understood, the nonce
- SHOULD be ignored, and another challenge (if one is present)
- should be used instead. The default aka-version is "AKAv1".
-
-
-
-Niemi, et. al. Informational [Page 5]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA September 2002
-
-
- Further AKA versions can be specified, with version numbers
- assigned by IANA [7]. When the algorithm directive is not
- present, it is assumed to be "MD5". This indicates, that AKA is
- not used to produce the Digest password.
-
- Example:
-
- algorithm=AKAv1-MD5
-
- If the entropy of the used RES value is limited (e.g., only 32
- bits), reuse of the same RES value in authenticating subsequent
- requests and responses is NOT RECOMMENDED. Such a RES value
- SHOULD only be used as a one-time password, and algorithms such as
- "MD5-sess", which limit the amount of material hashed with a
- single key, by producing a session key for authentication, SHOULD
- NOT be used.
-
-3.2 Creating a Challenge
-
- In order to deliver the AKA authentication challenge to the client in
- Digest AKA, the nonce directive defined in RFC 2617 is extended:
-
- nonce = "nonce" EQUAL ( aka-nonce
- / nonce-value )
- aka-nonce = LDQUOT aka-nonce-value RDQUOT
- aka-nonce-value = <base64 encoding of RAND, AUTN, and
- server specific data>
-
- nonce
- A parameter, which is populated with the Base64 [4] encoding of
- the concatenation of the AKA authentication challenge RAND, the
- AKA AUTN token, and optionally some server specific data, as in
- Figure 1.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Niemi, et. al. Informational [Page 6]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA September 2002
-
-
- Example:
-
- nonce="MzQ0a2xrbGtmbGtsZm9wb2tsc2tqaHJzZXNy9uQyMzMzMzQK="
-
- 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
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | |
- | RAND |
- | |
- | |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | |
- | AUTN |
- | |
- | |
- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- | Server Data...
- +-+-+-+-+-+-+-+-+-+-+-+
-
- Figure 1: Generating the nonce value.
-
- If the server receives a client authentication containing the "auts"
- parameter defined in Section 3.4, that includes a valid AKA AUTS
- parameter, the server MUST use it to generate a new challenge to the
- client. Note that when the AUTS is present, the included "response"
- parameter is calculated using an empty password (password of ""),
- instead of a RES.
-
-3.3 Client Authentication
-
- When a client receives a Digest AKA authentication challenge, it
- extracts the RAND and AUTN from the "nonce" parameter, and assesses
- the AUTN token provided by the server. If the client successfully
- authenticates the server with the AUTN, and determines that the SQN
- used in generating the challenge is within expected range, the AKA
- algorithms are run with the RAND challenge and shared secret K.
-
- The resulting AKA RES parameter is treated as a "password" when
- calculating the response directive of RFC 2617.
-
-3.4 Synchronization Failure
-
- For indicating an AKA sequence number synchronization failure, and to
- re-synchronize the SQN in the AuC using the AUTS token, a new
- directive is defined for the "digest-response" of the "Authorization"
- request header defined in RFC 2617:
-
-
-
-
-Niemi, et. al. Informational [Page 7]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA September 2002
-
-
- auts = "auts" EQUAL auts-param
- auts-param = LDQUOT auts-value RDQUOT
- auts-value = <base64 encoding of AUTS>
-
-
- auts
- A string carrying a base64 encoded AKA AUTS parameter. This
- directive is used to re-synchronize the server side SQN. If the
- directive is present, the client doesn't use any password when
- calculating its credentials. Instead, the client MUST calculate
- its credentials using an empty password (password of "").
-
- Example:
-
- auts="CjkyMzRfOiwg5CfkJ2UK="
-
- Upon receiving the "auts" parameter, the server will check the
- validity of the parameter value using the shared secret K. A valid
- AUTS parameter is used to re-synchronize the SQN in the AuC. The
- synchronized SQN is then used to generate a fresh authentication
- vector AV, with which the client is then re-challenged.
-
-3.5 Server Authentication
-
- Even though AKA provides inherent mutual authentication with the AKA
- AUTN token, mutual authentication mechanisms provided by Digest may
- still be useful in order to provide message integrity.
-
- In Digest AKA, the server uses the AKA XRES parameter as "password"
- when calculating the "response-auth" of the "Authentication-Info"
- header defined in RFC 2617.
-
-4. Example Digest AKA Operation
-
- Figure 2 below describes a message flow describing a Digest AKA
- process of authenticating a SIP request, namely the SIP REGISTER
- request.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Niemi, et. al. Informational [Page 8]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA September 2002
-
-
- Client Server
-
- | 1) REGISTER |
- |------------------------------------------------------>|
- | |
- | +-----------------------------+
- | | Server runs AKA algorithms, |
- | | generates RAND and AUTN. |
- | +-----------------------------+
- | |
- | 2) 401 Unauthorized |
- | WWW-Authenticate: Digest |
- | (RAND, AUTN delivered) |
- |<------------------------------------------------------|
- | |
- +------------------------------------+ |
- | Client runs AKA algorithms on ISIM,| |
- | verifies AUTN, derives RES | |
- | and session keys. | |
- +------------------------------------+ |
- | |
- | 3) REGISTER |
- | Authorization: Digest (RES is used) |
- |------------------------------------------------------>|
- | |
- | +------------------------------+
- | | Server checks the given RES, |
- | | and finds it correct. |
- | +------------------------------+
- | |
- | 4) 200 OK |
- | Authentication-Info: (XRES is used) |
- |<------------------------------------------------------|
- | |
-
- Figure 2: Message flow representing a successful authentication.
-
- 1) Initial request
-
- REGISTER sip:home.mobile.biz SIP/2.0
-
-
-
-
-
-
-
-
-
-
-
-Niemi, et. al. Informational [Page 9]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA September 2002
-
-
- 2) Response containing a challenge
-
- SIP/2.0 401 Unauthorized
- WWW-Authenticate: Digest
- realm="RoamingUsers@mobile.biz",
- nonce="CjPk9mRqNuT25eRkajM09uTl9nM09uTl9nMz5OX25PZz==",
- qop="auth,auth-int",
- opaque="5ccc069c403ebaf9f0171e9517f40e41",
- algorithm=AKAv1-MD5
-
- 3) Request containing credentials
-
- REGISTER sip:home.mobile.biz SIP/2.0
- Authorization: Digest
- username="jon.dough@mobile.biz",
- realm="RoamingUsers@mobile.biz",
- nonce="CjPk9mRqNuT25eRkajM09uTl9nM09uTl9nMz5OX25PZz==",
- uri="sip:home.mobile.biz",
- qop=auth-int,
- nc=00000001,
- cnonce="0a4f113b",
- response="6629fae49393a05397450978507c4ef1",
- opaque="5ccc069c403ebaf9f0171e9517f40e41"
-
- 4) Successful response
-
- SIP/2.0 200 OK
- Authentication-Info:
- qop=auth-int,
- rspauth="6629fae49393a05397450978507c4ef1",
- cnonce="0a4f113b",
- nc=00000001
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Niemi, et. al. Informational [Page 10]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA September 2002
-
-
- Figure 3 below describes a message flow describing a Digest AKA
- authentication process, in which there is a synchronization failure.
-
- Client Server
-
- | 1) REGISTER |
- |------------------------------------------------------>|
- | |
- | +-----------------------------+
- | | Server runs AKA algorithms, |
- | | generates RAND and AUTN. |
- | +-----------------------------+
- | |
- | 2) 401 Unauthorized |
- | WWW-Authenticate: Digest |
- | (RAND, AUTN delivered) |
- |<------------------------------------------------------|
- | |
- +------------------------------------+ |
- | Client runs AKA algorithms on ISIM,| |
- | verifies the AUTN, but discovers | |
- | that it contains an invalid | |
- | sequence number. The client then | |
- | generates an AUTS token. | |
- +------------------------------------+ |
- | |
- | 3) REGISTER |
- | Authorization: Digest (AUTS is delivered) |
- |------------------------------------------------------>|
- | |
- | +-----------------------+
- | | Server performs |
- | | re-synchronization |
- | | using AUTS and RAND. |
- | +-----------------------+
- | |
- | 4) 401 Unauthorized |
- | WWW-Authenticate: Digest |
- | (re-synchronized RAND, |
- | AUTN delivered) |
- |<------------------------------------------------------|
- | |
-
- Figure 3: Message flow representing an authentication synchronization
- failure.
-
-
-
-
-
-
-Niemi, et. al. Informational [Page 11]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA September 2002
-
-
- 1) Initial request
-
- REGISTER sip:home.mobile.biz SIP/2.0
-
- 2) Response containing a challenge
-
- SIP/2.0 401 Unauthorized
- WWW-Authenticate: Digest
- realm="RoamingUsers@mobile.biz",
- qop="auth",
- nonce="CjPk9mRqNuT25eRkajM09uTl9nM09uTl9nMz5OX25PZz==",
- opaque="5ccc069c403ebaf9f0171e9517f40e41",
- algorithm=AKAv1-MD5
-
- 3) Request containing credentials
-
- REGISTER sip:home.mobile.biz SIP/2.0
- Authorization: Digest
- username="jon.dough@mobile.biz",
- realm="RoamingUsers@mobile.biz",
- nonce="CjPk9mRqNuT25eRkajM09uTl9nM09uTl9nMz5OX25PZz==",
- uri="sip:home.mobile.biz",
- qop=auth,
- nc=00000001,
- cnonce="0a4f113b",
- response="4429ffe49393c02397450934607c4ef1",
- opaque="5ccc069c403ebaf9f0171e9517f40e41",
- auts="5PYxMuX2NOT2NeQ="
-
- 4) Response containing a new challenge
-
- SIP/2.0 401 Unauthorized
- WWW-Authenticate: Digest
- realm="RoamingUsers@mobile.biz",
- qop="auth,auth-int",
- nonce="9uQzNPbk9jM05Pbl5Pbl5DIz9uTl9uTl9jM0NTHk9uXk==",
- opaque="dcd98b7102dd2f0e8b11d0f600bfb0c093",
- algorithm=AKAv1-MD5
-
-5. Security Considerations
-
- In general, Digest AKA is vulnerable to the same security threats as
- HTTP authentication [2]. This chapter discusses the relevant
- exceptions.
-
-
-
-
-
-
-
-Niemi, et. al. Informational [Page 12]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA September 2002
-
-
-5.1 Authentication of Clients using Digest AKA
-
- AKA is typically -- though this isn't a theoretical limitation -- run
- on an ISIM application that usually resides in a tamper resistant
- smart card. Interfaces to the ISIM exist, which enable the host
- device to request authentication to be performed on the card.
- However, these interfaces do not allow access to the long-term secret
- outside the ISIM, and the authentication can only be performed if the
- device accessing the ISIM has knowledge of a PIN code, shared between
- the user and the ISIM. Such PIN codes are typically obtained from
- user input, and are usually required when the device is powered on.
-
- The use of tamper resistant cards with secure interfaces implies that
- Digest AKA is typically more secure than regular Digest
- implementations, as neither possession of the host device nor Trojan
- Horses in the software give access to the long term secret. Where a
- PIN scheme is used, the user is also authenticated when the device is
- powered on. However, there may be a difference in the resulting
- security of Digest AKA, compared to traditional Digest
- implementations, depending of course on whether those implementations
- cache/store passwords that are received from the user.
-
-5.2 Limited Use of Nonce Values
-
- The Digest scheme uses server-specified nonce values to seed the
- generation of the request-digest value. The server is free to
- construct the nonce in such a way, 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.
-
- Digest AKA limits the applicability of a nonce value to a particular
- ISIM. Typically, the ISIM is accessible only to one client device at
- a time. However, the nonce values are strong and secure even though
- limited to a particular ISIM. Additionally, this requires that the
- server is provided with the client identity before an authentication
- challenge can be generated. If a client identity is not available,
- an additional round trip is needed to acquire it. Such a case is
- analogous to an AKA synchronization failure.
-
- A server may allow each nonce value to be used only once by sending a
- next-nonce directive in the Authentication-Info header field of every
- response. However, this may cause a synchronization failure, and
- consequently some additional round trips in AKA, if the same SQN
- space is also used for other access schemes at the same time.
-
-
-
-
-
-Niemi, et. al. Informational [Page 13]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA September 2002
-
-
-5.3 Multiple Authentication Schemes and Algorithms
-
- In HTTP authentication, a user agent MUST choose the strongest
- authentication scheme it understands and request credentials from the
- user, based upon that challenge.
-
- In general, using passwords generated by Digest AKA with other HTTP
- authentication schemes is not recommended even though the realm
- values or protection domains would coincide. In these cases, a
- password should be requested from the end-user instead. Digest AKA
- passwords MUST NOT be re-used with such HTTP authentication schemes,
- which send the password in clear. In particular, AKA passwords MUST
- NOT be re-used with HTTP Basic.
-
- The same principle must be applied within a scheme if several
- algorithms are supported. A client receiving an HTTP Digest
- challenge with several available algorithms MUST choose the strongest
- algorithm it understands. For example, Digest with "AKAv1-MD5" would
- be stronger than Digest with "MD5".
-
-5.4 Online Dictionary Attacks
-
- Since user-selected passwords are typically quite simple, it has been
- proposed that servers should not accept passwords for HTTP Digest,
- which are in the dictionary [2]. This potential threat does not
- exist in HTTP Digest AKA because the algorithm will use ISIM
- originated passwords. However, the end-user must still be careful
- with PIN codes. Even though HTTP Digest AKA password requests are
- never displayed to the end-user, she will be authenticated to the
- ISIM via a PIN code. Commonly known initial PIN codes are typically
- installed to the ISIM during manufacturing and if the end-users do
- not change them, there is a danger that an unauthorized user may be
- able to use the device. Naturally this requires that the
- unauthorized user has access to the physical device, and that the
- end-user has not changed the initial PIN code. For this reason,
- end-users are strongly encouraged to change their PIN codes when they
- receive an ISIM.
-
-5.5 Session Protection
-
- Digest AKA is able to generate additional session keys for integrity
- (IK) and confidentiality (CK) protection. Even though this document
- does not specify the use of these additional keys, they may be used
- for creating additional security within HTTP authentication or some
- other security mechanism.
-
-
-
-
-
-
-Niemi, et. al. Informational [Page 14]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA September 2002
-
-
-5.6 Replay Protection
-
- AKA allows sequence numbers to be tracked for each authentication,
- with the SQN parameter. This allows authentications to be replay
- protected even if the RAND parameter happened to be the same for two
- authentication requests. More importantly, this offers additional
- protection for the case where an attacker replays an old
- authentication request sent by the network. The client will be able
- to detect that the request is old, and refuse authentication. This
- proves liveliness of the authentication request even in the case
- where a MitM attacker tries to trick the client into providing an
- authentication response, and then replaces parts of the message with
- something else. In other words, a client challenged by Digest AKA is
- not vulnerable for chosen plain text attacks. Finally, frequent
- sequence number errors would reveal an attack where the tamper
- resistant card has been cloned and is being used in multiple devices.
-
- The downside of sequence number tracking is that servers must hold
- more information for each user than just their long-term secret,
- namely the current SQN value. However, this information is typically
- not stored in the SIP nodes, but in dedicated authentication servers
- instead.
-
-5.7 Improvements to AKA Security
-
- Even though AKA is perceived as a secure mechanism, Digest AKA is
- able to improve it. More specifically, the AKA parameters carried
- between the client and the server during authentication may be
- protected along with other parts of the message by using Digest AKA.
- This is not possible with plain AKA.
-
-6. IANA Considerations
-
- This document specifies an aka-version namespace in Section 3.1 which
- requires a central coordinating body. The body responsible for this
- coordination is the Internet Assigned Numbers Authority (IANA).
-
- The default aka-version defined in this document is "AKAv1".
- Following the policies outlined in [5], versions above 1 are
- allocated as Expert Review.
-
- Registrations with the IANA MUST include the version number being
- registered, including the "AKAv" prefix. For example, a registration
- for "AKAv2" would potentially be a valid one, whereas a registration
- for "FOOv2" or "2" would not be valid. Further, the registration
- MUST include contact information for the party responsible for the
- registration.
-
-
-
-
-Niemi, et. al. Informational [Page 15]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA September 2002
-
-
- As this document defines the default aka-version, the initial IANA
- registration for aka-version values will contain an entry for
- "AKAv1".
-
-6.1 Registration Template
-
- To: ietf-digest-aka@iana.org
- Subject: Registration of a new AKA version
-
- Version identifier:
-
- (Must contain a valid aka-version value,
- as described in section 3.1.)
-
- Person & email address to contact for further information:
-
- (Must contain contact information for the
- person(s) responsible for the registration.)
-
-Normative References
-
- [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
- Levels", BCP 14, RFC 2119, March 1997.
-
- [2] 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.
-
- [3] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A.,
- Peterson, J., Sparks, R., Handley, M. and E. Schooler, "SIP:
- Session Initiation Protocol", RFC 3261, June 2002.
-
- [4] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part One: Format of Internet Message Bodies",
- RFC 2045, November 1996.
-
-Informative References
-
- [5] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA
- Considerations Section in RFCs", BCP 26, RFC 2434, October 1998.
-
- [6] 3rd Generation Partnership Project, "Security Architecture
- (Release 4)", TS 33.102, December 2001.
-
- [7] http://www.iana.org, "Assigned Numbers".
-
-
-
-
-
-
-Niemi, et. al. Informational [Page 16]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA September 2002
-
-
-Appendix A. Acknowledgements
-
- The authors would like to thank Sanjoy Sen, Jonathan Rosenberg, Pete
- McCann, Tao Haukka, Ilkka Uusitalo, Henry Haverinen, John Loughney,
- Allison Mankin and Greg Rose.
-
-Authors' Addresses
-
- Aki Niemi
- Nokia
- P.O. Box 301
- NOKIA GROUP, FIN 00045
- Finland
-
- Phone: +358 50 389 1644
- EMail: aki.niemi@nokia.com
-
-
- Jari Arkko
- Ericsson
- Hirsalantie 1
- Jorvas, FIN 02420
- Finland
-
- Phone: +358 40 5079256
- EMail: jari.arkko@ericsson.com
-
-
- Vesa Torvinen
- Ericsson
- Joukahaisenkatu 1
- Turku, FIN 20520
- Finland
-
- Phone: +358 40 7230822
- EMail: vesa.torvinen@ericsson.fi
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Niemi, et. al. Informational [Page 17]
-\f
-RFC 3310 HTTP Digest Authentication Using AKA 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Niemi, et. al. Informational [Page 18]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group R. Gilligan
-Request for Comments: 3493 Intransa, Inc.
-Obsoletes: 2553 S. Thomson
-Category: Informational Cisco
- J. Bound
- J. McCann
- Hewlett-Packard
- W. Stevens
- February 2003
-
-
- Basic Socket Interface Extensions for IPv6
-
-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 (2003). All Rights Reserved.
-
-Abstract
-
- The de facto standard Application Program Interface (API) for TCP/IP
- applications is the "sockets" interface. Although this API was
- developed for Unix in the early 1980s it has also been implemented on
- a wide variety of non-Unix systems. TCP/IP applications written
- using the sockets API have in the past enjoyed a high degree of
- portability and we would like the same portability with IPv6
- applications. But changes are required to the sockets API to support
- IPv6 and this memo describes these changes. These include a new
- socket address structure to carry IPv6 addresses, new address
- conversion functions, and some new socket options. These extensions
- are designed to provide access to the basic IPv6 features required by
- TCP and UDP applications, including multicasting, while introducing a
- minimum of change into the system and providing complete
- compatibility for existing IPv4 applications. Additional extensions
- for advanced IPv6 features (raw sockets and access to the IPv6
- extension headers) are defined in another document.
-
-
-
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 1]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-Table of Contents
-
- 1. Introduction................................................3
- 2. Design Considerations.......................................4
- 2.1 What Needs to be Changed...............................4
- 2.2 Data Types.............................................6
- 2.3 Headers................................................6
- 2.4 Structures.............................................6
- 3. Socket Interface............................................6
- 3.1 IPv6 Address Family and Protocol Family................6
- 3.2 IPv6 Address Structure.................................7
- 3.3 Socket Address Structure for 4.3BSD-Based Systems......7
- 3.4 Socket Address Structure for 4.4BSD-Based Systems......9
- 3.5 The Socket Functions...................................9
- 3.6 Compatibility with IPv4 Applications..................10
- 3.7 Compatibility with IPv4 Nodes.........................11
- 3.8 IPv6 Wildcard Address.................................11
- 3.9 IPv6 Loopback Address.................................13
- 3.10 Portability Additions.................................14
- 4. Interface Identification...................................16
- 4.1 Name-to-Index.........................................17
- 4.2 Index-to-Name.........................................17
- 4.3 Return All Interface Names and Indexes................18
- 4.4 Free Memory...........................................18
- 5. Socket Options.............................................18
- 5.1 Unicast Hop Limit.....................................19
- 5.2 Sending and Receiving Multicast Packets...............19
- 5.3 IPV6_V6ONLY option for AF_INET6 Sockets...............22
- 6. Library Functions..........................................22
- 6.1 Protocol-Independent Nodename and
- Service Name Translation..............................23
- 6.2 Socket Address Structure to Node Name
- and Service Name......................................28
- 6.3 Address Conversion Functions..........................31
- 6.4 Address Testing Macros................................33
- 7. Summary of New Definitions.................................33
- 8. Security Considerations....................................35
- 9. Changes from RFC 2553......................................35
- 10. Acknowledgments............................................36
- 11. References.................................................37
- 12. Authors' Addresses.........................................38
- 13. Full Copyright Statement...................................39
-
-
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 2]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-1. Introduction
-
- While IPv4 addresses are 32 bits long, IPv6 addresses are 128 bits
- long. The socket interface makes the size of an IP address quite
- visible to an application; virtually all TCP/IP applications for
- BSD-based systems have knowledge of the size of an IP address. Those
- parts of the API that expose the addresses must be changed to
- accommodate the larger IPv6 address size. IPv6 also introduces new
- features, some of which must be made visible to applications via the
- API. This memo defines a set of extensions to the socket interface
- to support the larger address size and new features of IPv6. It
- defines "basic" extensions that are of use to a broad range of
- applications. A companion document, the "advanced" API [4], covers
- extensions that are of use to more specialized applications, examples
- of which include routing daemons, and the "ping" and "traceroute"
- utilities.
-
- The development of this API was started in 1994 in the IETF IPng
- working group. The API has evolved over the years, published first
- in RFC 2133, then again in RFC 2553, and reaching its final form in
- this document.
-
- As the API matured and stabilized, it was incorporated into the Open
- Group's Networking Services (XNS) specification, issue 5.2, which was
- subsequently incorporated into a joint Open Group/IEEE/ISO standard
- [3].
-
- Effort has been made to ensure that this document and [3] contain the
- same information with regard to the API definitions. However, the
- reader should note that this document is for informational purposes
- only, and that the official standard specification of the sockets API
- is [3].
-
- It is expected that any future standardization work on this API would
- be done by the Open Group Base Working Group [6].
-
- It should also be noted that this document describes only those
- portions of the API needed for IPv4 and IPv6 communications. Other
- potential uses of the API, for example the use of getaddrinfo() and
- getnameinfo() with the AF_UNIX address family, are beyond the scope
- of this document.
-
-
-
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 3]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-2. Design Considerations
-
- There are a number of important considerations in designing changes
- to this well-worn API:
-
- - The API changes should provide both source and binary
- compatibility for programs written to the original API. That is,
- existing program binaries should continue to operate when run on a
- system supporting the new API. In addition, existing applications
- that are re-compiled and run on a system supporting the new API
- should continue to operate. Simply put, the API changes for IPv6
- should not break existing programs. An additional mechanism for
- implementations to verify this is to verify the new symbols are
- protected by Feature Test Macros as described in [3]. (Such
- Feature Test Macros are not defined by this RFC.)
-
- - The changes to the API should be as small as possible in order to
- simplify the task of converting existing IPv4 applications to
- IPv6.
-
- - Where possible, applications should be able to use this API to
- interoperate with both IPv6 and IPv4 hosts. Applications should
- not need to know which type of host they are communicating with.
-
- - IPv6 addresses carried in data structures should be 64-bit
- aligned. This is necessary in order to obtain optimum performance
- on 64-bit machine architectures.
-
- Because of the importance of providing IPv4 compatibility in the API,
- these extensions are explicitly designed to operate on machines that
- provide complete support for both IPv4 and IPv6. A subset of this
- API could probably be designed for operation on systems that support
- only IPv6. However, this is not addressed in this memo.
-
-2.1 What Needs to be Changed
-
- The socket interface API consists of a few distinct components:
-
- - Core socket functions.
-
- - Address data structures.
-
- - Name-to-address translation functions.
-
- - Address conversion functions.
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 4]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- The core socket functions -- those functions that deal with such
- things as setting up and tearing down TCP connections, and sending
- and receiving UDP packets -- were designed to be transport
- independent. Where protocol addresses are passed as function
- arguments, they are carried via opaque pointers. A protocol-specific
- address data structure is defined for each protocol that the socket
- functions support. Applications must cast pointers to these
- protocol-specific address structures into pointers to the generic
- "sockaddr" address structure when using the socket functions. These
- functions need not change for IPv6, but a new IPv6-specific address
- data structure is needed.
-
- The "sockaddr_in" structure is the protocol-specific data structure
- for IPv4. This data structure actually includes 8-octets of unused
- space, and it is tempting to try to use this space to adapt the
- sockaddr_in structure to IPv6. Unfortunately, the sockaddr_in
- structure is not large enough to hold the 16-octet IPv6 address as
- well as the other information (address family and port number) that
- is needed. So a new address data structure must be defined for IPv6.
-
- IPv6 addresses are scoped [2] so they could be link-local, site,
- organization, global, or other scopes at this time undefined. To
- support applications that want to be able to identify a set of
- interfaces for a specific scope, the IPv6 sockaddr_in structure must
- support a field that can be used by an implementation to identify a
- set of interfaces identifying the scope for an IPv6 address.
-
- The IPv4 name-to-address translation functions in the socket
- interface are gethostbyname() and gethostbyaddr(). These are left as
- is, and new functions are defined which support both IPv4 and IPv6.
-
- The IPv4 address conversion functions -- inet_ntoa() and inet_addr()
- -- convert IPv4 addresses between binary and printable form. These
- functions are quite specific to 32-bit IPv4 addresses. We have
- designed two analogous functions that convert both IPv4 and IPv6
- addresses, and carry an address type parameter so that they can be
- extended to other protocol families as well.
-
- Finally, a few miscellaneous features are needed to support IPv6. A
- new interface is needed to support the IPv6 hop limit header field.
- New socket options are needed to control the sending and receiving of
- IPv6 multicast packets.
-
- The socket interface will be enhanced in the future to provide access
- to other IPv6 features. Some of these extensions are described in
- [4].
-
-
-
-
-
-Gilligan, et al. Informational [Page 5]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-2.2 Data Types
-
- The data types of the structure elements given in this memo are
- intended to track the relevant standards. uintN_t means an unsigned
- integer of exactly N bits (e.g., uint16_t). The sa_family_t and
- in_port_t types are defined in [3].
-
-2.3 Headers
-
- When function prototypes and structures are shown we show the headers
- that must be #included to cause that item to be defined.
-
-2.4 Structures
-
- When structures are described the members shown are the ones that
- must appear in an implementation. Additional, nonstandard members
- may also be defined by an implementation. As an additional
- precaution nonstandard members could be verified by Feature Test
- Macros as described in [3]. (Such Feature Test Macros are not
- defined by this RFC.)
-
- The ordering shown for the members of a structure is the recommended
- ordering, given alignment considerations of multibyte members, but an
- implementation may order the members differently.
-
-3. Socket Interface
-
- This section specifies the socket interface changes for IPv6.
-
-3.1 IPv6 Address Family and Protocol Family
-
- A new address family name, AF_INET6, is defined in <sys/socket.h>.
- The AF_INET6 definition distinguishes between the original
- sockaddr_in address data structure, and the new sockaddr_in6 data
- structure.
-
- A new protocol family name, PF_INET6, is defined in <sys/socket.h>.
- Like most of the other protocol family names, this will usually be
- defined to have the same value as the corresponding address family
- name:
-
- #define PF_INET6 AF_INET6
-
- The AF_INET6 is used in the first argument to the socket() function
- to indicate that an IPv6 socket is being created.
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 6]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-3.2 IPv6 Address Structure
-
- A new in6_addr structure holds a single IPv6 address and is defined
- as a result of including <netinet/in.h>:
-
- struct in6_addr {
- uint8_t s6_addr[16]; /* IPv6 address */
- };
-
- This data structure contains an array of sixteen 8-bit elements,
- which make up one 128-bit IPv6 address. The IPv6 address is stored
- in network byte order.
-
- The structure in6_addr above is usually implemented with an embedded
- union with extra fields that force the desired alignment level in a
- manner similar to BSD implementations of "struct in_addr". Those
- additional implementation details are omitted here for simplicity.
-
- An example is as follows:
-
- struct in6_addr {
- union {
- uint8_t _S6_u8[16];
- uint32_t _S6_u32[4];
- uint64_t _S6_u64[2];
- } _S6_un;
- };
- #define s6_addr _S6_un._S6_u8
-
-3.3 Socket Address Structure for 4.3BSD-Based Systems
-
- In the socket interface, a different protocol-specific data structure
- is defined to carry the addresses for each protocol suite. Each
- protocol-specific data structure is designed so it can be cast into a
- protocol-independent data structure -- the "sockaddr" structure.
- Each has a "family" field that overlays the "sa_family" of the
- sockaddr data structure. This field identifies the type of the data
- structure.
-
- The sockaddr_in structure is the protocol-specific address data
- structure for IPv4. It is used to pass addresses between
- applications and the system in the socket functions. The following
- sockaddr_in6 structure holds IPv6 addresses and is defined as a
- result of including the <netinet/in.h> header:
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 7]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-struct sockaddr_in6 {
- sa_family_t sin6_family; /* AF_INET6 */
- in_port_t sin6_port; /* transport layer port # */
- uint32_t sin6_flowinfo; /* IPv6 flow information */
- struct in6_addr sin6_addr; /* IPv6 address */
- uint32_t sin6_scope_id; /* set of interfaces for a scope */
-};
-
- This structure is designed to be compatible with the sockaddr data
- structure used in the 4.3BSD release.
-
- The sin6_family field identifies this as a sockaddr_in6 structure.
- This field overlays the sa_family field when the buffer is cast to a
- sockaddr data structure. The value of this field must be AF_INET6.
-
- The sin6_port field contains the 16-bit UDP or TCP port number. This
- field is used in the same way as the sin_port field of the
- sockaddr_in structure. The port number is stored in network byte
- order.
-
- The sin6_flowinfo field is a 32-bit field intended to contain flow-
- related information. The exact way this field is mapped to or from a
- packet is not currently specified. Until such time as its use is
- specified, applications should set this field to zero when
- constructing a sockaddr_in6, and ignore this field in a sockaddr_in6
- structure constructed by the system.
-
- The sin6_addr field is a single in6_addr structure (defined in the
- previous section). This field holds one 128-bit IPv6 address. The
- address is stored in network byte order.
-
- The ordering of elements in this structure is specifically designed
- so that when sin6_addr field is aligned on a 64-bit boundary, the
- start of the structure will also be aligned on a 64-bit boundary.
- This is done for optimum performance on 64-bit architectures.
-
- The sin6_scope_id field is a 32-bit integer that identifies a set of
- interfaces as appropriate for the scope [2] of the address carried in
- the sin6_addr field. The mapping of sin6_scope_id to an interface or
- set of interfaces is left to implementation and future specifications
- on the subject of scoped addresses.
-
- Notice that the sockaddr_in6 structure will normally be larger than
- the generic sockaddr structure. On many existing implementations the
- sizeof(struct sockaddr_in) equals sizeof(struct sockaddr), with both
- being 16 bytes. Any existing code that makes this assumption needs
- to be examined carefully when converting to IPv6.
-
-
-
-
-Gilligan, et al. Informational [Page 8]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-3.4 Socket Address Structure for 4.4BSD-Based Systems
-
- The 4.4BSD release includes a small, but incompatible change to the
- socket interface. The "sa_family" field of the sockaddr data
- structure was changed from a 16-bit value to an 8-bit value, and the
- space saved used to hold a length field, named "sa_len". The
- sockaddr_in6 data structure given in the previous section cannot be
- correctly cast into the newer sockaddr data structure. For this
- reason, the following alternative IPv6 address data structure is
- provided to be used on systems based on 4.4BSD. It is defined as a
- result of including the <netinet/in.h> header.
-
-struct sockaddr_in6 {
- uint8_t sin6_len; /* length of this struct */
- sa_family_t sin6_family; /* AF_INET6 */
- in_port_t sin6_port; /* transport layer port # */
- uint32_t sin6_flowinfo; /* IPv6 flow information */
- struct in6_addr sin6_addr; /* IPv6 address */
- uint32_t sin6_scope_id; /* set of interfaces for a scope */
-};
-
- The only differences between this data structure and the 4.3BSD
- variant are the inclusion of the length field, and the change of the
- family field to a 8-bit data type. The definitions of all the other
- fields are identical to the structure defined in the previous
- section.
-
- Systems that provide this version of the sockaddr_in6 data structure
- must also declare SIN6_LEN as a result of including the
- <netinet/in.h> header. This macro allows applications to determine
- whether they are being built on a system that supports the 4.3BSD or
- 4.4BSD variants of the data structure.
-
-3.5 The Socket Functions
-
- Applications call the socket() function to create a socket descriptor
- that represents a communication endpoint. The arguments to the
- socket() function tell the system which protocol to use, and what
- format address structure will be used in subsequent functions. For
- example, to create an IPv4/TCP socket, applications make the call:
-
- s = socket(AF_INET, SOCK_STREAM, 0);
-
- To create an IPv4/UDP socket, applications make the call:
-
- s = socket(AF_INET, SOCK_DGRAM, 0);
-
-
-
-
-
-Gilligan, et al. Informational [Page 9]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- Applications may create IPv6/TCP and IPv6/UDP sockets (which may also
- handle IPv4 communication as described in section 3.7) by simply
- using the constant AF_INET6 instead of AF_INET in the first argument.
- For example, to create an IPv6/TCP socket, applications make the
- call:
-
- s = socket(AF_INET6, SOCK_STREAM, 0);
-
- To create an IPv6/UDP socket, applications make the call:
-
- s = socket(AF_INET6, SOCK_DGRAM, 0);
-
- Once the application has created a AF_INET6 socket, it must use the
- sockaddr_in6 address structure when passing addresses in to the
- system. The functions that the application uses to pass addresses
- into the system are:
-
- bind()
- connect()
- sendmsg()
- sendto()
-
- The system will use the sockaddr_in6 address structure to return
- addresses to applications that are using AF_INET6 sockets. The
- functions that return an address from the system to an application
- are:
-
- accept()
- recvfrom()
- recvmsg()
- getpeername()
- getsockname()
-
- No changes to the syntax of the socket functions are needed to
- support IPv6, since all of the "address carrying" functions use an
- opaque address pointer, and carry an address length as a function
- argument.
-
-3.6 Compatibility with IPv4 Applications
-
- In order to support the large base of applications using the original
- API, system implementations must provide complete source and binary
- compatibility with the original API. This means that systems must
- continue to support AF_INET sockets and the sockaddr_in address
- structure. Applications must be able to create IPv4/TCP and IPv4/UDP
- sockets using the AF_INET constant in the socket() function, as
-
-
-
-
-
-Gilligan, et al. Informational [Page 10]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- described in the previous section. Applications should be able to
- hold a combination of IPv4/TCP, IPv4/UDP, IPv6/TCP and IPv6/UDP
- sockets simultaneously within the same process.
-
- Applications using the original API should continue to operate as
- they did on systems supporting only IPv4. That is, they should
- continue to interoperate with IPv4 nodes.
-
-3.7 Compatibility with IPv4 Nodes
-
- The API also provides a different type of compatibility: the ability
- for IPv6 applications to interoperate with IPv4 applications. This
- feature uses the IPv4-mapped IPv6 address format defined in the IPv6
- addressing architecture specification [2]. This address format
- allows the IPv4 address of an IPv4 node to be represented as an IPv6
- address. The IPv4 address is encoded into the low-order 32 bits of
- the IPv6 address, and the high-order 96 bits hold the fixed prefix
- 0:0:0:0:0:FFFF. IPv4-mapped addresses are written as follows:
-
- ::FFFF:<IPv4-address>
-
- These addresses can be generated automatically by the getaddrinfo()
- function, as described in Section 6.1.
-
- Applications may use AF_INET6 sockets to open TCP connections to IPv4
- nodes, or send UDP packets to IPv4 nodes, by simply encoding the
- destination's IPv4 address as an IPv4-mapped IPv6 address, and
- passing that address, within a sockaddr_in6 structure, in the
- connect() or sendto() call. When applications use AF_INET6 sockets
- to accept TCP connections from IPv4 nodes, or receive UDP packets
- from IPv4 nodes, the system returns the peer's address to the
- application in the accept(), recvfrom(), or getpeername() call using
- a sockaddr_in6 structure encoded this way.
-
- Few applications will likely need to know which type of node they are
- interoperating with. However, for those applications that do need to
- know, the IN6_IS_ADDR_V4MAPPED() macro, defined in Section 6.4, is
- provided.
-
-3.8 IPv6 Wildcard Address
-
- While the bind() function allows applications to select the source IP
- address of UDP packets and TCP connections, applications often want
- the system to select the source address for them. With IPv4, one
- specifies the address as the symbolic constant INADDR_ANY (called the
- "wildcard" address) in the bind() call, or simply omits the bind()
- entirely.
-
-
-
-
-Gilligan, et al. Informational [Page 11]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- Since the IPv6 address type is a structure (struct in6_addr), a
- symbolic constant can be used to initialize an IPv6 address variable,
- but cannot be used in an assignment. Therefore systems provide the
- IPv6 wildcard address in two forms.
-
- The first version is a global variable named "in6addr_any" that is an
- in6_addr structure. The extern declaration for this variable is
- defined in <netinet/in.h>:
-
- extern const struct in6_addr in6addr_any;
-
- Applications use in6addr_any similarly to the way they use INADDR_ANY
- in IPv4. For example, to bind a socket to port number 23, but let
- the system select the source address, an application could use the
- following code:
-
- struct sockaddr_in6 sin6;
- . . .
- sin6.sin6_family = AF_INET6;
- sin6.sin6_flowinfo = 0;
- sin6.sin6_port = htons(23);
- sin6.sin6_addr = in6addr_any; /* structure assignment */
- . . .
- if (bind(s, (struct sockaddr *) &sin6, sizeof(sin6)) == -1)
- . . .
-
- The other version is a symbolic constant named IN6ADDR_ANY_INIT and
- is defined in <netinet/in.h>. This constant can be used to
- initialize an in6_addr structure:
-
- struct in6_addr anyaddr = IN6ADDR_ANY_INIT;
-
- Note that this constant can be used ONLY at declaration time. It can
- not be used to assign a previously declared in6_addr structure. For
- example, the following code will not work:
-
- /* This is the WRONG way to assign an unspecified address */
- struct sockaddr_in6 sin6;
- . . .
- sin6.sin6_addr = IN6ADDR_ANY_INIT; /* will NOT compile */
-
- Be aware that the IPv4 INADDR_xxx constants are all defined in host
- byte order but the IPv6 IN6ADDR_xxx constants and the IPv6
- in6addr_xxx externals are defined in network byte order.
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 12]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-3.9 IPv6 Loopback Address
-
- Applications may need to send UDP packets to, or originate TCP
- connections to, services residing on the local node. In IPv4, they
- can do this by using the constant IPv4 address INADDR_LOOPBACK in
- their connect(), sendto(), or sendmsg() call.
-
- IPv6 also provides a loopback address to contact local TCP and UDP
- services. Like the unspecified address, the IPv6 loopback address is
- provided in two forms -- a global variable and a symbolic constant.
-
- The global variable is an in6_addr structure named
- "in6addr_loopback." The extern declaration for this variable is
- defined in <netinet/in.h>:
-
- extern const struct in6_addr in6addr_loopback;
-
- Applications use in6addr_loopback as they would use INADDR_LOOPBACK
- in IPv4 applications (but beware of the byte ordering difference
- mentioned at the end of the previous section). For example, to open
- a TCP connection to the local telnet server, an application could use
- the following code:
-
- struct sockaddr_in6 sin6;
- . . .
- sin6.sin6_family = AF_INET6;
- sin6.sin6_flowinfo = 0;
- sin6.sin6_port = htons(23);
- sin6.sin6_addr = in6addr_loopback; /* structure assignment */
- . . .
- if (connect(s, (struct sockaddr *) &sin6, sizeof(sin6)) == -1)
- . . .
-
- The symbolic constant is named IN6ADDR_LOOPBACK_INIT and is defined
- in <netinet/in.h>. It can be used at declaration time ONLY; for
- example:
-
- struct in6_addr loopbackaddr = IN6ADDR_LOOPBACK_INIT;
-
- Like IN6ADDR_ANY_INIT, this constant cannot be used in an assignment
- to a previously declared IPv6 address variable.
-
-
-
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 13]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-3.10 Portability Additions
-
- One simple addition to the sockets API that can help application
- writers is the "struct sockaddr_storage". This data structure can
- simplify writing code that is portable across multiple address
- families and platforms. This data structure is designed with the
- following goals.
-
- - Large enough to accommodate all supported protocol-specific address
- structures.
-
- - Aligned at an appropriate boundary so that pointers to it can be
- cast as pointers to protocol specific address structures and used
- to access the fields of those structures without alignment
- problems.
-
- The sockaddr_storage structure contains field ss_family which is of
- type sa_family_t. When a sockaddr_storage structure is cast to a
- sockaddr structure, the ss_family field of the sockaddr_storage
- structure maps onto the sa_family field of the sockaddr structure.
- When a sockaddr_storage structure is cast as a protocol specific
- address structure, the ss_family field maps onto a field of that
- structure that is of type sa_family_t and that identifies the
- protocol's address family.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 14]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- An example implementation design of such a data structure would be as
- follows.
-
-/*
- * Desired design of maximum size and alignment
- */
-#define _SS_MAXSIZE 128 /* Implementation specific max size */
-#define _SS_ALIGNSIZE (sizeof (int64_t))
- /* Implementation specific desired alignment */
-/*
- * Definitions used for sockaddr_storage structure paddings design.
- */
-#define _SS_PAD1SIZE (_SS_ALIGNSIZE - sizeof (sa_family_t))
-#define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof (sa_family_t) +
- _SS_PAD1SIZE + _SS_ALIGNSIZE))
-struct sockaddr_storage {
- sa_family_t ss_family; /* address family */
- /* Following fields are implementation specific */
- char __ss_pad1[_SS_PAD1SIZE];
- /* 6 byte pad, this is to make implementation
- /* specific pad up to alignment field that */
- /* follows explicit in the data structure */
- int64_t __ss_align; /* field to force desired structure */
- /* storage alignment */
- char __ss_pad2[_SS_PAD2SIZE];
- /* 112 byte pad to achieve desired size, */
- /* _SS_MAXSIZE value minus size of ss_family */
- /* __ss_pad1, __ss_align fields is 112 */
-};
-
- The above example implementation illustrates a data structure which
- will align on a 64-bit boundary. An implementation-specific field
- "__ss_align" along with "__ss_pad1" is used to force a 64-bit
- alignment which covers proper alignment good enough for the needs of
- sockaddr_in6 (IPv6), sockaddr_in (IPv4) address data structures. The
- size of padding field __ss_pad1 depends on the chosen alignment
- boundary. The size of padding field __ss_pad2 depends on the value
- of overall size chosen for the total size of the structure. This
- size and alignment are represented in the above example by
- implementation specific (not required) constants _SS_MAXSIZE (chosen
- value 128) and _SS_ALIGNSIZE (with chosen value 8). Constants
- _SS_PAD1SIZE (derived value 6) and _SS_PAD2SIZE (derived value 112)
- are also for illustration and not required. The derived values
- assume sa_family_t is 2 bytes. The implementation specific
- definitions and structure field names above start with an underscore
- to denote implementation private namespace. Portable code is not
- expected to access or reference those fields or constants.
-
-
-
-
-Gilligan, et al. Informational [Page 15]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- On implementations where the sockaddr data structure includes a
- "sa_len" field this data structure would look like this:
-
-/*
- * Definitions used for sockaddr_storage structure paddings design.
- */
-#define _SS_PAD1SIZE (_SS_ALIGNSIZE -
- (sizeof (uint8_t) + sizeof (sa_family_t))
-#define _SS_PAD2SIZE (_SS_MAXSIZE -
- (sizeof (uint8_t) + sizeof (sa_family_t) +
- _SS_PAD1SIZE + _SS_ALIGNSIZE))
-struct sockaddr_storage {
- uint8_t ss_len; /* address length */
- sa_family_t ss_family; /* address family */
- /* Following fields are implementation specific */
- char __ss_pad1[_SS_PAD1SIZE];
- /* 6 byte pad, this is to make implementation
- /* specific pad up to alignment field that */
- /* follows explicit in the data structure */
- int64_t __ss_align; /* field to force desired structure */
- /* storage alignment */
- char __ss_pad2[_SS_PAD2SIZE];
- /* 112 byte pad to achieve desired size, */
- /* _SS_MAXSIZE value minus size of ss_len, */
- /* __ss_family, __ss_pad1, __ss_align fields is 112 */
-};
-
-4. Interface Identification
-
- This API uses an interface index (a small positive integer) to
- identify the local interface on which a multicast group is joined
- (Section 5.2). Additionally, the advanced API [4] uses these same
- interface indexes to identify the interface on which a datagram is
- received, or to specify the interface on which a datagram is to be
- sent.
-
- Interfaces are normally known by names such as "le0", "sl1", "ppp2",
- and the like. On Berkeley-derived implementations, when an interface
- is made known to the system, the kernel assigns a unique positive
- integer value (called the interface index) to that interface. These
- are small positive integers that start at 1. (Note that 0 is never
- used for an interface index.) There may be gaps so that there is no
- current interface for a particular positive interface index.
-
- This API defines two functions that map between an interface name and
- index, a third function that returns all the interface names and
- indexes, and a fourth function to return the dynamic memory allocated
- by the previous function. How these functions are implemented is
-
-
-
-Gilligan, et al. Informational [Page 16]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- left up to the implementation. 4.4BSD implementations can implement
- these functions using the existing sysctl() function with the
- NET_RT_IFLIST command. Other implementations may wish to use ioctl()
- for this purpose.
-
-4.1 Name-to-Index
-
- The first function maps an interface name into its corresponding
- index.
-
- #include <net/if.h>
-
- unsigned int if_nametoindex(const char *ifname);
-
- If ifname is the name of an interface, the if_nametoindex() function
- shall return the interface index corresponding to name ifname;
- otherwise, it shall return zero. No errors are defined.
-
-4.2 Index-to-Name
-
- The second function maps an interface index into its corresponding
- name.
-
- #include <net/if.h>
-
- char *if_indextoname(unsigned int ifindex, char *ifname);
-
- When this function is called, the ifname argument shall point to a
- buffer of at least IF_NAMESIZE bytes. The function shall place in
- this buffer the name of the interface with index ifindex.
- (IF_NAMESIZE is also defined in <net/if.h> and its value includes a
- terminating null byte at the end of the interface name.) If ifindex
- is an interface index, then the function shall return the value
- supplied in ifname, which points to a buffer now containing the
- interface name. Otherwise, the function shall return a NULL pointer
- and set errno to indicate the error. If there is no interface
- corresponding to the specified index, errno is set to ENXIO. If
- there was a system error (such as running out of memory), errno would
- be set to the proper value (e.g., ENOMEM).
-
-
-
-
-
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 17]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-4.3 Return All Interface Names and Indexes
-
- The if_nameindex structure holds the information about a single
- interface and is defined as a result of including the <net/if.h>
- header.
-
- struct if_nameindex {
- unsigned int if_index; /* 1, 2, ... */
- char *if_name; /* null terminated name: "le0", ... */
- };
-
- The final function returns an array of if_nameindex structures, one
- structure per interface.
-
- #include <net/if.h>
-
- struct if_nameindex *if_nameindex(void);
-
- The end of the array of structures is indicated by a structure with
- an if_index of 0 and an if_name of NULL. The function returns a NULL
- pointer upon an error, and would set errno to the appropriate value.
-
- The memory used for this array of structures along with the interface
- names pointed to by the if_name members is obtained dynamically.
- This memory is freed by the next function.
-
-4.4 Free Memory
-
- The following function frees the dynamic memory that was allocated by
- if_nameindex().
-
- #include <net/if.h>
-
- void if_freenameindex(struct if_nameindex *ptr);
-
- The ptr argument shall be a pointer that was returned by
- if_nameindex(). After if_freenameindex() has been called, the
- application shall not use the array of which ptr is the address.
-
-5. Socket Options
-
- A number of new socket options are defined for IPv6. All of these
- new options are at the IPPROTO_IPV6 level. That is, the "level"
- parameter in the getsockopt() and setsockopt() calls is IPPROTO_IPV6
- when using these options. The constant name prefix IPV6_ is used in
- all of the new socket options. This serves to clearly identify these
- options as applying to IPv6.
-
-
-
-
-Gilligan, et al. Informational [Page 18]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- The declaration for IPPROTO_IPV6, the new IPv6 socket options, and
- related constants defined in this section are obtained by including
- the header <netinet/in.h>.
-
-5.1 Unicast Hop Limit
-
- A new setsockopt() option controls the hop limit used in outgoing
- unicast IPv6 packets. The name of this option is IPV6_UNICAST_HOPS,
- and it is used at the IPPROTO_IPV6 layer. The following example
- illustrates how it is used:
-
- int hoplimit = 10;
-
- if (setsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS,
- (char *) &hoplimit, sizeof(hoplimit)) == -1)
- perror("setsockopt IPV6_UNICAST_HOPS");
-
- When the IPV6_UNICAST_HOPS option is set with setsockopt(), the
- option value given is used as the hop limit for all subsequent
- unicast packets sent via that socket. If the option is not set, the
- system selects a default value. The integer hop limit value (called
- x) is interpreted as follows:
-
- x < -1: return an error of EINVAL
- x == -1: use kernel default
- 0 <= x <= 255: use x
- x >= 256: return an error of EINVAL
-
- The IPV6_UNICAST_HOPS option may be used with getsockopt() to
- determine the hop limit value that the system will use for subsequent
- unicast packets sent via that socket. For example:
-
- int hoplimit;
- socklen_t len = sizeof(hoplimit);
-
- if (getsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS,
- (char *) &hoplimit, &len) == -1)
- perror("getsockopt IPV6_UNICAST_HOPS");
- else
- printf("Using %d for hop limit.\n", hoplimit);
-
-5.2 Sending and Receiving Multicast Packets
-
- IPv6 applications may send multicast packets by simply specifying an
- IPv6 multicast address as the destination address, for example in the
- destination address argument of the sendto() function.
-
-
-
-
-
-Gilligan, et al. Informational [Page 19]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- Three socket options at the IPPROTO_IPV6 layer control some of the
- parameters for sending multicast packets. Setting these options is
- not required: applications may send multicast packets without using
- these options. The setsockopt() options for controlling the sending
- of multicast packets are summarized below. These three options can
- also be used with getsockopt().
-
- IPV6_MULTICAST_IF
-
- Set the interface to use for outgoing multicast packets. The
- argument is the index of the interface to use. If the
- interface index is specified as zero, the system selects the
- interface (for example, by looking up the address in a routing
- table and using the resulting interface).
-
- Argument type: unsigned int
-
- IPV6_MULTICAST_HOPS
-
- Set the hop limit to use for outgoing multicast packets. (Note
- a separate option - IPV6_UNICAST_HOPS - is provided to set the
- hop limit to use for outgoing unicast packets.)
-
- The interpretation of the argument is the same as for the
- IPV6_UNICAST_HOPS option:
-
- x < -1: return an error of EINVAL
- x == -1: use kernel default
- 0 <= x <= 255: use x
- x >= 256: return an error of EINVAL
-
- If IPV6_MULTICAST_HOPS is not set, the default is 1
- (same as IPv4 today)
-
- Argument type: int
-
- IPV6_MULTICAST_LOOP
-
- If a multicast datagram is sent to a group to which the sending
- host itself belongs (on the outgoing interface), a copy of the
- datagram is looped back by the IP layer for local delivery if
- this option is set to 1. If this option is set to 0 a copy is
- not looped back. Other option values return an error of
- EINVAL.
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 20]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- If IPV6_MULTICAST_LOOP is not set, the default is 1 (loopback;
- same as IPv4 today).
-
- Argument type: unsigned int
-
- The reception of multicast packets is controlled by the two
- setsockopt() options summarized below. An error of EOPNOTSUPP is
- returned if these two options are used with getsockopt().
-
- IPV6_JOIN_GROUP
-
- Join a multicast group on a specified local interface.
- If the interface index is specified as 0,
- the kernel chooses the local interface.
- For example, some kernels look up the multicast group
- in the normal IPv6 routing table and use the resulting
- interface.
-
- Argument type: struct ipv6_mreq
-
- IPV6_LEAVE_GROUP
-
- Leave a multicast group on a specified interface.
- If the interface index is specified as 0, the system
- may choose a multicast group membership to drop by
- matching the multicast address only.
-
- Argument type: struct ipv6_mreq
-
- The argument type of both of these options is the ipv6_mreq
- structure, defined as a result of including the <netinet/in.h>
- header;
-
- struct ipv6_mreq {
- struct in6_addr ipv6mr_multiaddr; /* IPv6 multicast addr */
- unsigned int ipv6mr_interface; /* interface index */
- };
-
- Note that to receive multicast datagrams a process must join the
- multicast group to which datagrams will be sent. UDP applications
- must also bind the UDP port to which datagrams will be sent. Some
- processes also bind the multicast group address to the socket, in
- addition to the port, to prevent other datagrams destined to that
- same port from being delivered to the socket.
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 21]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-5.3 IPV6_V6ONLY option for AF_INET6 Sockets
-
- This socket option restricts AF_INET6 sockets to IPv6 communications
- only. As stated in section <3.7 Compatibility with IPv4 Nodes>,
- AF_INET6 sockets may be used for both IPv4 and IPv6 communications.
- Some applications may want to restrict their use of an AF_INET6
- socket to IPv6 communications only. For these applications the
- IPV6_V6ONLY socket option is defined. When this option is turned on,
- the socket can be used to send and receive IPv6 packets only. This
- is an IPPROTO_IPV6 level option. This option takes an int value.
- This is a boolean option. By default this option is turned off.
-
- Here is an example of setting this option:
-
- int on = 1;
-
- if (setsockopt(s, IPPROTO_IPV6, IPV6_V6ONLY,
- (char *)&on, sizeof(on)) == -1)
- perror("setsockopt IPV6_V6ONLY");
- else
- printf("IPV6_V6ONLY set\n");
-
- Note - This option has no effect on the use of IPv4 Mapped addresses
- which enter a node as a valid IPv6 addresses for IPv6 communications
- as defined by Stateless IP/ICMP Translation Algorithm (SIIT) [5].
-
- An example use of this option is to allow two versions of the same
- server process to run on the same port, one providing service over
- IPv6, the other providing the same service over IPv4.
-
-6. Library Functions
-
- New library functions are needed to perform a variety of operations
- with IPv6 addresses. Functions are needed to lookup IPv6 addresses
- in the Domain Name System (DNS). Both forward lookup (nodename-to-
- address translation) and reverse lookup (address-to-nodename
- translation) need to be supported. Functions are also needed to
- convert IPv6 addresses between their binary and textual form.
-
- We note that the two existing functions, gethostbyname() and
- gethostbyaddr(), are left as-is. New functions are defined to handle
- both IPv4 and IPv6 addresses.
-
- The commonly used function gethostbyname() is inadequate for many
- applications, first because it provides no way for the caller to
- specify anything about the types of addresses desired (IPv4 only,
- IPv6 only, IPv4-mapped IPv6 are OK, etc.), and second because many
- implementations of this function are not thread safe. RFC 2133
-
-
-
-Gilligan, et al. Informational [Page 22]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- defined a function named gethostbyname2() but this function was also
- inadequate, first because its use required setting a global option
- (RES_USE_INET6) when IPv6 addresses were required, and second because
- a flag argument is needed to provide the caller with additional
- control over the types of addresses required. The gethostbyname2()
- function was deprecated in RFC 2553 and is no longer part of the
- basic API.
-
-6.1 Protocol-Independent Nodename and Service Name Translation
-
- Nodename-to-address translation is done in a protocol-independent
- fashion using the getaddrinfo() function.
-
-#include <sys/socket.h>
-#include <netdb.h>
-
-
-int getaddrinfo(const char *nodename, const char *servname,
- const struct addrinfo *hints, struct addrinfo **res);
-
-void freeaddrinfo(struct addrinfo *ai);
-
-struct addrinfo {
- int ai_flags; /* AI_PASSIVE, AI_CANONNAME,
- AI_NUMERICHOST, .. */
- int ai_family; /* AF_xxx */
- int ai_socktype; /* SOCK_xxx */
- int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
- socklen_t ai_addrlen; /* length of ai_addr */
- char *ai_canonname; /* canonical name for nodename */
- struct sockaddr *ai_addr; /* binary address */
- struct addrinfo *ai_next; /* next structure in linked list */
-};
-
- The getaddrinfo() function translates the name of a service location
- (for example, a host name) and/or a service name and returns a set of
- socket addresses and associated information to be used in creating a
- socket with which to address the specified service.
-
- The nodename and servname arguments are either null pointers or
- pointers to null-terminated strings. One or both of these two
- arguments must be a non-null pointer.
-
- The format of a valid name depends on the address family or families.
- If a specific family is not given and the name could be interpreted
- as valid within multiple supported families, the implementation will
- attempt to resolve the name in all supported families and, in absence
- of errors, one or more results shall be returned.
-
-
-
-Gilligan, et al. Informational [Page 23]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- If the nodename argument is not null, it can be a descriptive name or
- can be an address string. If the specified address family is
- AF_INET, AF_INET6, or AF_UNSPEC, valid descriptive names include host
- names. If the specified address family is AF_INET or AF_UNSPEC,
- address strings using Internet standard dot notation as specified in
- inet_addr() are valid. If the specified address family is AF_INET6
- or AF_UNSPEC, standard IPv6 text forms described in inet_pton() are
- valid.
-
- If nodename is not null, the requested service location is named by
- nodename; otherwise, the requested service location is local to the
- caller.
-
- If servname is null, the call shall return network-level addresses
- for the specified nodename. If servname is not null, it is a null-
- terminated character string identifying the requested service. This
- can be either a descriptive name or a numeric representation suitable
- for use with the address family or families. If the specified
- address family is AF_INET, AF_INET6 or AF_UNSPEC, the service can be
- specified as a string specifying a decimal port number.
-
- If the argument hints is not null, it refers to a structure
- containing input values that may direct the operation by providing
- options and by limiting the returned information to a specific socket
- type, address family and/or protocol. In this hints structure every
- member other than ai_flags, ai_family, ai_socktype and ai_protocol
- shall be set to zero or a null pointer. A value of AF_UNSPEC for
- ai_family means that the caller shall accept any address family. A
- value of zero for ai_socktype means that the caller shall accept any
- socket type. A value of zero for ai_protocol means that the caller
- shall accept any protocol. If hints is a null pointer, the behavior
- shall be as if it referred to a structure containing the value zero
- for the ai_flags, ai_socktype and ai_protocol fields, and AF_UNSPEC
- for the ai_family field.
-
- Note:
-
- 1. If the caller handles only TCP and not UDP, for example, then the
- ai_protocol member of the hints structure should be set to
- IPPROTO_TCP when getaddrinfo() is called.
-
- 2. If the caller handles only IPv4 and not IPv6, then the ai_family
- member of the hints structure should be set to AF_INET when
- getaddrinfo() is called.
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 24]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- The ai_flags field to which hints parameter points shall be set to
- zero or be the bitwise-inclusive OR of one or more of the values
- AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV,
- AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG.
-
- If the AI_PASSIVE flag is specified, the returned address information
- shall be suitable for use in binding a socket for accepting incoming
- connections for the specified service (i.e., a call to bind()). In
- this case, if the nodename argument is null, then the IP address
- portion of the socket address structure shall be set to INADDR_ANY
- for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 address. If the
- AI_PASSIVE flag is not specified, the returned address information
- shall be suitable for a call to connect() (for a connection-mode
- protocol) or for a call to connect(), sendto() or sendmsg() (for a
- connectionless protocol). In this case, if the nodename argument is
- null, then the IP address portion of the socket address structure
- shall be set to the loopback address. This flag is ignored if the
- nodename argument is not null.
-
- If the AI_CANONNAME flag is specified and the nodename argument is
- not null, the function shall attempt to determine the canonical name
- corresponding to nodename (for example, if nodename is an alias or
- shorthand notation for a complete name).
-
- If the AI_NUMERICHOST flag is specified, then a non-null nodename
- string supplied shall be a numeric host address string. Otherwise,
- an [EAI_NONAME] error is returned. This flag shall prevent any type
- of name resolution service (for example, the DNS) from being invoked.
-
- If the AI_NUMERICSERV flag is specified, then a non-null servname
- string supplied shall be a numeric port string. Otherwise, an
- [EAI_NONAME] error shall be returned. This flag shall prevent any
- type of name resolution service (for example, NIS+) from being
- invoked.
-
- If the AI_V4MAPPED flag is specified along with an ai_family of
- AF_INET6, then getaddrinfo() shall return IPv4-mapped IPv6 addresses
- on finding no matching IPv6 addresses (ai_addrlen shall be 16).
-
- For example, when using the DNS, if no AAAA records are found then
- a query is made for A records and any found are returned as IPv4-
- mapped IPv6 addresses.
-
- The AI_V4MAPPED flag shall be ignored unless ai_family equals
- AF_INET6.
-
- If the AI_ALL flag is used with the AI_V4MAPPED flag, then
- getaddrinfo() shall return all matching IPv6 and IPv4 addresses.
-
-
-
-Gilligan, et al. Informational [Page 25]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- For example, when using the DNS, queries are made for both AAAA
- records and A records, and getaddrinfo() returns the combined
- results of both queries. Any IPv4 addresses found are returned as
- IPv4-mapped IPv6 addresses.
-
- The AI_ALL flag without the AI_V4MAPPED flag is ignored.
-
- Note:
-
- When ai_family is not specified (AF_UNSPEC), AI_V4MAPPED and
- AI_ALL flags will only be used if AF_INET6 is supported.
-
- If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be
- returned only if an IPv4 address is configured on the local system,
- and IPv6 addresses shall be returned only if an IPv6 address is
- configured on the local system. The loopback address is not
- considered for this case as valid as a configured address.
-
- For example, when using the DNS, a query for AAAA records should
- occur only if the node has at least one IPv6 address configured
- (other than IPv6 loopback) and a query for A records should occur
- only if the node has at least one IPv4 address configured (other
- than the IPv4 loopback).
-
- The ai_socktype field to which argument hints points specifies the
- socket type for the service, as defined for socket(). If a specific
- socket type is not given (for example, a value of zero) and the
- service name could be interpreted as valid with multiple supported
- socket types, the implementation shall attempt to resolve the service
- name for all supported socket types and, in the absence of errors,
- all possible results shall be returned. A non-zero socket type value
- shall limit the returned information to values with the specified
- socket type.
-
- If the ai_family field to which hints points has the value AF_UNSPEC,
- addresses shall be returned for use with any address family that can
- be used with the specified nodename and/or servname. Otherwise,
- addresses shall be returned for use only with the specified address
- family. If ai_family is not AF_UNSPEC and ai_protocol is not zero,
- then addresses are returned for use only with the specified address
- family and protocol; the value of ai_protocol shall be interpreted as
- in a call to the socket() function with the corresponding values of
- ai_family and ai_protocol.
-
- The freeaddrinfo() function frees one or more addrinfo structures
- returned by getaddrinfo(), along with any additional storage
- associated with those structures (for example, storage pointed to by
- the ai_canonname and ai_addr fields; an application must not
-
-
-
-Gilligan, et al. Informational [Page 26]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- reference this storage after the associated addrinfo structure has
- been freed). If the ai_next field of the structure is not null, the
- entire list of structures is freed. The freeaddrinfo() function must
- support the freeing of arbitrary sublists of an addrinfo list
- originally returned by getaddrinfo().
-
- Functions getaddrinfo() and freeaddrinfo() must be thread-safe.
-
- A zero return value for getaddrinfo() indicates successful
- completion; a non-zero return value indicates failure. The possible
- values for the failures are listed below under Error Return Values.
-
- Upon successful return of getaddrinfo(), the location to which res
- points shall refer to a linked list of addrinfo structures, each of
- which shall specify a socket address and information for use in
- creating a socket with which to use that socket address. The list
- shall include at least one addrinfo structure. The ai_next field of
- each structure contains a pointer to the next structure on the list,
- or a null pointer if it is the last structure on the list. Each
- structure on the list shall include values for use with a call to the
- socket() function, and a socket address for use with the connect()
- function or, if the AI_PASSIVE flag was specified, for use with the
- bind() function. The fields ai_family, ai_socktype, and ai_protocol
- shall be usable as the arguments to the socket() function to create a
- socket suitable for use with the returned address. The fields
- ai_addr and ai_addrlen are usable as the arguments to the connect()
- or bind() functions with such a socket, according to the AI_PASSIVE
- flag.
-
- If nodename is not null, and if requested by the AI_CANONNAME flag,
- the ai_canonname field of the first returned addrinfo structure shall
- point to a null-terminated string containing the canonical name
- corresponding to the input nodename; if the canonical name is not
- available, then ai_canonname shall refer to the nodename argument or
- a string with the same contents. The contents of the ai_flags field
- of the returned structures are undefined.
-
- All fields in socket address structures returned by getaddrinfo()
- that are not filled in through an explicit argument (for example,
- sin6_flowinfo) shall be set to zero.
-
- Note: This makes it easier to compare socket address structures.
-
-
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 27]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- Error Return Values:
-
- The getaddrinfo() function shall fail and return the corresponding
- value if:
-
- [EAI_AGAIN] The name could not be resolved at this time. Future
- attempts may succeed.
-
- [EAI_BADFLAGS] The flags parameter had an invalid value.
-
- [EAI_FAIL] A non-recoverable error occurred when attempting to
- resolve the name.
-
- [EAI_FAMILY] The address family was not recognized.
-
- [EAI_MEMORY] There was a memory allocation failure when trying to
- allocate storage for the return value.
-
- [EAI_NONAME] The name does not resolve for the supplied
- parameters. Neither nodename nor servname were
- supplied. At least one of these must be supplied.
-
- [EAI_SERVICE] The service passed was not recognized for the
- specified socket type.
-
- [EAI_SOCKTYPE] The intended socket type was not recognized.
-
- [EAI_SYSTEM] A system error occurred; the error code can be found
- in errno.
-
- The gai_strerror() function provides a descriptive text string
- corresponding to an EAI_xxx error value.
-
- #include <netdb.h>
-
- const char *gai_strerror(int ecode);
-
- The argument is one of the EAI_xxx values defined for the
- getaddrinfo() and getnameinfo() functions. The return value points
- to a string describing the error. If the argument is not one of the
- EAI_xxx values, the function still returns a pointer to a string
- whose contents indicate an unknown error.
-
-6.2 Socket Address Structure to Node Name and Service Name
-
- The getnameinfo() function is used to translate the contents of a
- socket address structure to a node name and/or service name.
-
-
-
-
-Gilligan, et al. Informational [Page 28]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- #include <sys/socket.h>
- #include <netdb.h>
-
- int getnameinfo(const struct sockaddr *sa, socklen_t salen,
- char *node, socklen_t nodelen,
- char *service, socklen_t servicelen,
- int flags);
-
- The getnameinfo() function shall translate a socket address to a node
- name and service location, all of which are defined as in
- getaddrinfo().
-
- The sa argument points to a socket address structure to be
- translated.
-
- The salen argument holds the size of the socket address structure
- pointed to by sa.
-
- If the socket address structure contains an IPv4-mapped IPv6 address
- or an IPv4-compatible IPv6 address, the implementation shall extract
- the embedded IPv4 address and lookup the node name for that IPv4
- address.
-
- Note: The IPv6 unspecified address ("::") and the IPv6 loopback
- address ("::1") are not IPv4-compatible addresses. If the address
- is the IPv6 unspecified address ("::"), a lookup is not performed,
- and the [EAI_NONAME] error is returned.
-
- If the node argument is non-NULL and the nodelen argument is nonzero,
- then the node argument points to a buffer able to contain up to
- nodelen characters that receives the node name as a null-terminated
- string. If the node argument is NULL or the nodelen argument is
- zero, the node name shall not be returned. If the node's name cannot
- be located, the numeric form of the node's address is returned
- instead of its name.
-
- If the service argument is non-NULL and the servicelen argument is
- non-zero, then the service argument points to a buffer able to
- contain up to servicelen bytes that receives the service name as a
- null-terminated string. If the service argument is NULL or the
- servicelen argument is zero, the service name shall not be returned.
- If the service's name cannot be located, the numeric form of the
- service address (for example, its port number) shall be returned
- instead of its name.
-
- The arguments node and service cannot both be NULL.
-
-
-
-
-
-Gilligan, et al. Informational [Page 29]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- The flags argument is a flag that changes the default actions of the
- function. By default the fully-qualified domain name (FQDN) for the
- host shall be returned, but:
-
- - If the flag bit NI_NOFQDN is set, only the node name portion of
- the FQDN shall be returned for local hosts.
-
- - If the flag bit NI_NUMERICHOST is set, the numeric form of the
- host's address shall be returned instead of its name, under all
- circumstances.
-
- - If the flag bit NI_NAMEREQD is set, an error shall be returned if
- the host's name cannot be located.
-
- - If the flag bit NI_NUMERICSERV is set, the numeric form of the
- service address shall be returned (for example, its port number)
- instead of its name, under all circumstances.
-
- - If the flag bit NI_DGRAM is set, this indicates that the service
- is a datagram service (SOCK_DGRAM). The default behavior shall
- assume that the service is a stream service (SOCK_STREAM).
-
- Note:
-
- 1. The NI_NUMERICxxx flags are required to support the "-n" flags
- that many commands provide.
-
- 2. The NI_DGRAM flag is required for the few AF_INET and AF_INET6
- port numbers (for example, [512,514]) that represent different
- services for UDP and TCP.
-
- The getnameinfo() function shall be thread safe.
-
- A zero return value for getnameinfo() indicates successful
- completion; a non-zero return value indicates failure.
-
- Upon successful completion, getnameinfo() shall return the node and
- service names, if requested, in the buffers provided. The returned
- names are always null-terminated strings.
-
-
-
-
-
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 30]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- Error Return Values:
-
- The getnameinfo() function shall fail and return the corresponding
- value if:
-
- [EAI_AGAIN] The name could not be resolved at this time.
- Future attempts may succeed.
-
- [EAI_BADFLAGS] The flags had an invalid value.
-
- [EAI_FAIL] A non-recoverable error occurred.
-
- [EAI_FAMILY] The address family was not recognized or the address
- length was invalid for the specified family.
-
- [EAI_MEMORY] There was a memory allocation failure.
-
- [EAI_NONAME] The name does not resolve for the supplied parameters.
- NI_NAMEREQD is set and the host's name cannot be
- located, or both nodename and servname were null.
-
- [EAI_OVERFLOW] An argument buffer overflowed.
-
- [EAI_SYSTEM] A system error occurred. The error code can be found
- in errno.
-
-6.3 Address Conversion Functions
-
- The two IPv4 functions inet_addr() and inet_ntoa() convert an IPv4
- address between binary and text form. IPv6 applications need similar
- functions. The following two functions convert both IPv6 and IPv4
- addresses:
-
- #include <arpa/inet.h>
-
- int inet_pton(int af, const char *src, void *dst);
-
- const char *inet_ntop(int af, const void *src,
- char *dst, socklen_t size);
-
- The inet_pton() function shall convert an address in its standard
- text presentation form into its numeric binary form. The af argument
- shall specify the family of the address. The AF_INET and AF_INET6
- address families shall be supported. The src argument points to the
- string being passed in. The dst argument points to a buffer into
- which the function stores the numeric address; this shall be large
- enough to hold the numeric address (32 bits for AF_INET, 128 bits for
- AF_INET6). The inet_pton() function shall return 1 if the conversion
-
-
-
-Gilligan, et al. Informational [Page 31]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- succeeds, with the address pointed to by dst in network byte order.
- It shall return 0 if the input is not a valid IPv4 dotted-decimal
- string or a valid IPv6 address string, or -1 with errno set to
- EAFNOSUPPORT if the af argument is unknown.
-
- If the af argument of inet_pton() is AF_INET, the src string shall be
- in the standard IPv4 dotted-decimal form:
-
- ddd.ddd.ddd.ddd
-
- where "ddd" is a one to three digit decimal number between 0 and 255.
- The inet_pton() function does not accept other formats (such as the
- octal numbers, hexadecimal numbers, and fewer than four numbers that
- inet_addr() accepts).
-
- If the af argument of inet_pton() is AF_INET6, the src string shall
- be in one of the standard IPv6 text forms defined in Section 2.2 of
- the addressing architecture specification [2].
-
- The inet_ntop() function shall convert a numeric address into a text
- string suitable for presentation. The af argument shall specify the
- family of the address. This can be AF_INET or AF_INET6. The src
- argument points to a buffer holding an IPv4 address if the af
- argument is AF_INET, or an IPv6 address if the af argument is
- AF_INET6; the address must be in network byte order. The dst
- argument points to a buffer where the function stores the resulting
- text string; it shall not be NULL. The size argument specifies the
- size of this buffer, which shall be large enough to hold the text
- string (INET_ADDRSTRLEN characters for IPv4, INET6_ADDRSTRLEN
- characters for IPv6).
-
- In order to allow applications to easily declare buffers of the
- proper size to store IPv4 and IPv6 addresses in string form, the
- following two constants are defined in <netinet/in.h>:
-
- #define INET_ADDRSTRLEN 16
- #define INET6_ADDRSTRLEN 46
-
- The inet_ntop() function shall return a pointer to the buffer
- containing the text string if the conversion succeeds, and NULL
- otherwise. Upon failure, errno is set to EAFNOSUPPORT if the af
- argument is invalid or ENOSPC if the size of the result buffer is
- inadequate.
-
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 32]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-6.4 Address Testing Macros
-
- The following macros can be used to test for special IPv6 addresses.
-
- #include <netinet/in.h>
-
- int IN6_IS_ADDR_UNSPECIFIED (const struct in6_addr *);
- int IN6_IS_ADDR_LOOPBACK (const struct in6_addr *);
- int IN6_IS_ADDR_MULTICAST (const struct in6_addr *);
- int IN6_IS_ADDR_LINKLOCAL (const struct in6_addr *);
- int IN6_IS_ADDR_SITELOCAL (const struct in6_addr *);
- int IN6_IS_ADDR_V4MAPPED (const struct in6_addr *);
- int IN6_IS_ADDR_V4COMPAT (const struct in6_addr *);
-
- int IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *);
- int IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *);
- int IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *);
- int IN6_IS_ADDR_MC_ORGLOCAL (const struct in6_addr *);
- int IN6_IS_ADDR_MC_GLOBAL (const struct in6_addr *);
-
- The first seven macros return true if the address is of the specified
- type, or false otherwise. The last five test the scope of a
- multicast address and return true if the address is a multicast
- address of the specified scope or false if the address is either not
- a multicast address or not of the specified scope.
-
- Note that IN6_IS_ADDR_LINKLOCAL and IN6_IS_ADDR_SITELOCAL return true
- only for the two types of local-use IPv6 unicast addresses (Link-
- Local and Site-Local) defined in [2], and that by this definition,
- the IN6_IS_ADDR_LINKLOCAL macro returns false for the IPv6 loopback
- address (::1). These two macros do not return true for IPv6
- multicast addresses of either link-local scope or site-local scope.
-
-7. Summary of New Definitions
-
- The following list summarizes the constants, structure, and extern
- definitions discussed in this memo, sorted by header.
-
-<net/if.h> IF_NAMESIZE
-<net/if.h> struct if_nameindex{};
-
-<netdb.h> AI_ADDRCONFIG
-<netdb.h> AI_ALL
-<netdb.h> AI_CANONNAME
-<netdb.h> AI_NUMERICHOST
-<netdb.h> AI_NUMERICSERV
-<netdb.h> AI_PASSIVE
-<netdb.h> AI_V4MAPPED
-
-
-
-Gilligan, et al. Informational [Page 33]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-<netdb.h> EAI_AGAIN
-<netdb.h> EAI_BADFLAGS
-<netdb.h> EAI_FAIL
-<netdb.h> EAI_FAMILY
-<netdb.h> EAI_MEMORY
-<netdb.h> EAI_NONAME
-<netdb.h> EAI_OVERFLOW
-<netdb.h> EAI_SERVICE
-<netdb.h> EAI_SOCKTYPE
-<netdb.h> EAI_SYSTEM
-<netdb.h> NI_DGRAM
-<netdb.h> NI_NAMEREQD
-<netdb.h> NI_NOFQDN
-<netdb.h> NI_NUMERICHOST
-<netdb.h> NI_NUMERICSERV
-<netdb.h> struct addrinfo{};
-
-<netinet/in.h> IN6ADDR_ANY_INIT
-<netinet/in.h> IN6ADDR_LOOPBACK_INIT
-<netinet/in.h> INET6_ADDRSTRLEN
-<netinet/in.h> INET_ADDRSTRLEN
-<netinet/in.h> IPPROTO_IPV6
-<netinet/in.h> IPV6_JOIN_GROUP
-<netinet/in.h> IPV6_LEAVE_GROUP
-<netinet/in.h> IPV6_MULTICAST_HOPS
-<netinet/in.h> IPV6_MULTICAST_IF
-<netinet/in.h> IPV6_MULTICAST_LOOP
-<netinet/in.h> IPV6_UNICAST_HOPS
-<netinet/in.h> IPV6_V6ONLY
-<netinet/in.h> SIN6_LEN
-<netinet/in.h> extern const struct in6_addr in6addr_any;
-<netinet/in.h> extern const struct in6_addr in6addr_loopback;
-<netinet/in.h> struct in6_addr{};
-<netinet/in.h> struct ipv6_mreq{};
-<netinet/in.h> struct sockaddr_in6{};
-
-<sys/socket.h> AF_INET6
-<sys/socket.h> PF_INET6
-<sys/socket.h> struct sockaddr_storage;
-
- The following list summarizes the function and macro prototypes
- discussed in this memo, sorted by header.
-
-<arpa/inet.h> int inet_pton(int, const char *, void *);
-<arpa/inet.h> const char *inet_ntop(int, const void *,
- char *, socklen_t);
-
-
-
-
-
-Gilligan, et al. Informational [Page 34]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-<net/if.h> char *if_indextoname(unsigned int, char *);
-<net/if.h> unsigned int if_nametoindex(const char *);
-<net/if.h> void if_freenameindex(struct if_nameindex *);
-<net/if.h> struct if_nameindex *if_nameindex(void);
-
-<netdb.h> int getaddrinfo(const char *, const char *,
- const struct addrinfo *,
- struct addrinfo **);
-<netdb.h> int getnameinfo(const struct sockaddr *, socklen_t,
- char *, socklen_t, char *, socklen_t, int);
-<netdb.h> void freeaddrinfo(struct addrinfo *);
-<netdb.h> const char *gai_strerror(int);
-
-<netinet/in.h> int IN6_IS_ADDR_LINKLOCAL(const struct in6_addr *);
-<netinet/in.h> int IN6_IS_ADDR_LOOPBACK(const struct in6_addr *);
-<netinet/in.h> int IN6_IS_ADDR_MC_GLOBAL(const struct in6_addr *);
-<netinet/in.h> int IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *);
-<netinet/in.h> int IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *);
-<netinet/in.h> int IN6_IS_ADDR_MC_ORGLOCAL(const struct in6_addr *);
-<netinet/in.h> int IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *);
-<netinet/in.h> int IN6_IS_ADDR_MULTICAST(const struct in6_addr *);
-<netinet/in.h> int IN6_IS_ADDR_SITELOCAL(const struct in6_addr *);
-<netinet/in.h> int IN6_IS_ADDR_UNSPECIFIED(const struct in6_addr *);
-<netinet/in.h> int IN6_IS_ADDR_V4COMPAT(const struct in6_addr *);
-<netinet/in.h> int IN6_IS_ADDR_V4MAPPED(const struct in6_addr *);
-
-8. Security Considerations
-
- IPv6 provides a number of new security mechanisms, many of which need
- to be accessible to applications. Companion memos detailing the
- extensions to the socket interfaces to support IPv6 security are
- being written.
-
-9. Changes from RFC 2553
-
- 1. Add brief description of the history of this API and its relation
- to the Open Group/IEEE/ISO standards.
-
- 2. Alignments with [3].
-
- 3. Removed all references to getipnodebyname() and getipnodebyaddr(),
- which are deprecated in favor of getaddrinfo() and getnameinfo().
-
- 4. Added IPV6_V6ONLY IP level socket option to permit nodes to not
- process IPv4 packets as IPv4 Mapped addresses in implementations.
-
- 5. Added SIIT to references and added new contributors.
-
-
-
-
-Gilligan, et al. Informational [Page 35]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
- 6. In previous versions of this specification, the sin6_flowinfo
- field was associated with the IPv6 traffic class and flow label,
- but its usage was not completely specified. The complete
- definition of the sin6_flowinfo field, including its association
- with the traffic class or flow label, is now deferred to a future
- specification.
-
-10. Acknowledgments
-
- This specification's evolution and completeness were significantly
- influenced by the efforts of Richard Stevens, who has passed on.
- Richard's wisdom and talent made the specification what it is today.
- The co-authors will long think of Richard with great respect.
-
- Thanks to the many people who made suggestions and provided feedback
- to this document, including:
-
- Werner Almesberger, Ran Atkinson, Fred Baker, Dave Borman, Andrew
- Cherenson, Alex Conta, Alan Cox, Steve Deering, Richard Draves,
- Francis Dupont, Robert Elz, Brian Haberman, Jun-ichiro itojun Hagino,
- Marc Hasson, Tom Herbert, Bob Hinden, Wan-Yen Hsu, Christian Huitema,
- Koji Imada, Markus Jork, Ron Lee, Alan Lloyd, Charles Lynn, Dan
- McDonald, Dave Mitton, Finnbarr Murphy, Thomas Narten, Josh Osborne,
- Craig Partridge, Jean-Luc Richier, Bill Sommerfield, Erik Scoredos,
- Keith Sklower, JINMEI Tatuya, Dave Thaler, Matt Thomas, Harvey
- Thompson, Dean D. Throop, Karen Tracey, Glenn Trewitt, Paul Vixie,
- David Waitzman, Carl Williams, Kazu Yamamoto, Vlad Yasevich, Stig
- Venaas, and Brian Zill.
-
- The getaddrinfo() and getnameinfo() functions are taken from an
- earlier document by Keith Sklower. As noted in that document,
- William Durst, Steven Wise, Michael Karels, and Eric Allman provided
- many useful discussions on the subject of protocol-independent name-
- to-address translation, and reviewed early versions of Keith
- Sklower's original proposal. Eric Allman implemented the first
- prototype of getaddrinfo(). The observation that specifying the pair
- of name and service would suffice for connecting to a service
- independent of protocol details was made by Marshall Rose in a
- proposal to X/Open for a "Uniform Network Interface".
-
- Craig Metz, Jack McCann, Erik Nordmark, Tim Hartrick, and Mukesh
- Kacker made many contributions to this document. Ramesh Govindan
- made a number of contributions and co-authored an earlier version of
- this memo.
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 36]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-11. References
-
- [1] Deering, S. and R. Hinden, "Internet Protocol, Version 6 (IPv6)
- Specification", RFC 2460, December 1998.
-
- [2] Hinden, R. and S. Deering, "IP Version 6 Addressing
- Architecture", RFC 2373, July 1998.
-
- [3] IEEE Std. 1003.1-2001 Standard for Information Technology --
- Portable Operating System Interface (POSIX). Open Group
- Technical Standard: Base Specifications, Issue 6, December 2001.
- ISO/IEC 9945:2002. http://www.opengroup.org/austin
-
- [4] Stevens, W. and M. Thomas, "Advanced Sockets API for IPv6", RFC
- 2292, February 1998.
-
- [5] Nordmark, E., "Stateless IP/ICMP Translation Algorithm (SIIT)",
- RFC 2765, February 2000.
-
- [6] The Open Group Base Working Group
- http://www.opengroup.org/platform/base.html
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 37]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-12. Authors' Addresses
-
- Bob Gilligan
- Intransa, Inc.
- 2870 Zanker Rd.
- San Jose, CA 95134
-
- Phone: 408-678-8647
- EMail: gilligan@intransa.com
-
-
- Susan Thomson
- Cisco Systems
- 499 Thornall Street, 8th floor
- Edison, NJ 08837
-
- Phone: 732-635-3086
- EMail: sethomso@cisco.com
-
-
- Jim Bound
- Hewlett-Packard Company
- 110 Spitbrook Road ZKO3-3/W20
- Nashua, NH 03062
-
- Phone: 603-884-0062
- EMail: Jim.Bound@hp.com
-
-
- Jack McCann
- Hewlett-Packard Company
- 110 Spitbrook Road ZKO3-3/W20
- Nashua, NH 03062
-
- Phone: 603-884-2608
- EMail: Jack.McCann@hp.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 38]
-\f
-RFC 3493 Basic Socket Interface Extensions for IPv6 February 2003
-
-
-13. 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Gilligan, et al. Informational [Page 39]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group J. Elson
-Request for Comments: 3507 A. Cerpa
-Category: Informational UCLA
- April 2003
-
-
- Internet Content Adaptation Protocol (ICAP)
-
-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 (2003). All Rights Reserved.
-
-IESG Note
-
- The Open Pluggable Services (OPES) working group has been chartered
- to produce a standards track protocol specification for a protocol
- intended to perform the same of functions as ICAP. However, since
- ICAP is already in widespread use the IESG believes it is appropriate
- to document existing usage by publishing the ICAP specification as an
- informational document. The IESG also notes that ICAP was developed
- before the publication of RFC 3238 and therefore does not address the
- architectural and policy issues described in that document.
-
-Abstract
-
- ICAP, the Internet Content Adaption Protocol, is a protocol aimed at
- providing simple object-based content vectoring for HTTP services.
- ICAP is, in essence, a lightweight protocol for executing a "remote
- procedure call" on HTTP messages. It allows ICAP clients to pass
- HTTP messages to ICAP servers for some sort of transformation or
- other processing ("adaptation"). The server executes its
- transformation service on messages and sends back responses to the
- client, usually with modified messages. Typically, the adapted
- messages are either HTTP requests or HTTP responses.
-
-
-
-
-
-
-
-
-
-
-
-Elson & Cerpa Informational [Page 1]
-\f
-RFC 3507 ICAP April 2003
-
-
-Table of Contents
-
- 1. Introduction............................................3
- 2. Terminology.............................................5
- 3. ICAP Overall Operation..................................8
- 3.1 Request Modification..............................8
- 3.2 Response Modification............................10
- 4. Protocol Semantics.....................................11
- 4.1 General Operation................................11
- 4.2 ICAP URIs........................................11
- 4.3 ICAP Headers.....................................12
- 4.3.1 Headers Common to Requests and
- Responses................................12
- 4.3.2 Request Headers..........................13
- 4.3.3 Response Headers.........................14
- 4.3.4 ICAP-Related Headers in HTTP
- Messages.................................15
- 4.4 ICAP Bodies: Encapsulation of HTTP
- Messages.........................................16
- 4.4.1 Expected Encapsulated Sections...........16
- 4.4.2 Encapsulated HTTP Headers................18
- 4.5 Message Preview..................................18
- 4.6 "204 No Content" Responses outside of
- Previews.........................................22
- 4.7 ISTag Response Header............................22
- 4.8 Request Modification Mode........................23
- 4.8.1 Request..................................23
- 4.8.2 Response.................................24
- 4.8.3 Examples.................................24
- 4.9 Response Modification Mode.......................27
- 4.9.1 Request..................................27
- 4.9.2 Response.................................27
- 4.9.3 Examples.................................28
- 4.10 OPTIONS Method...................................29
- 4.10.1 OPTIONS request..........................29
- 4.10.2 OPTIONS response.........................30
- 4.10.3 OPTIONS examples.........................33
- 5. Caching................................................33
- 6. Implementation Notes...................................34
- 6.1 Vectoring Points.................................34
- 6.2 Application Level Errors.........................35
- 6.3 Use of Chunked Transfer-Encoding.................37
- 6.4 Distinct URIs for Distinct Services..............37
- 7. Security Considerations................................37
- 7.1 Authentication...................................37
- 7.2 Encryption.......................................38
- 7.3 Service Validation...............................38
- 8. Motivations and Design Alternatives....................39
-
-
-
-Elson & Cerpa Informational [Page 2]
-\f
-RFC 3507 ICAP April 2003
-
-
- 8.1 To Be HTTP, or Not to Be.........................39
- 8.2 Mandatory Use of Chunking........................39
- 8.3 Use of the null-body directive in the
- Encapsulated header..............................40
- 9. References.............................................40
- 10. Contributors...........................................41
- Appendix A BNF Grammar for ICAP Messages..................45
- Authors' Addresses..........................................48
- Full Copyright Statement....................................49
-
-1. Introduction
-
- As the Internet grows, so does the need for scalable Internet
- services. Popular web servers are asked to deliver content to
- hundreds of millions of users connected at ever-increasing
- bandwidths. The model of centralized, monolithic servers that are
- responsible for all aspects of every client's request seems to be
- reaching the end of its useful life.
-
- To keep up with the growth in the number of clients, there has been a
- move towards architectures that scale better through the use of
- replication, distribution, and caching. On the content provider
- side, replication and load-balancing techniques allow the burden of
- client requests to be spread out over a myriad of servers. Content
- providers have also begun to deploy geographically diverse content
- distribution networks that bring origin-servers closer to the "edge"
- of the network where clients are attached. These networks of
- distributed origin-servers or "surrogates" allow the content provider
- to distribute their content whilst retaining control over the
- integrity of that content. The distributed nature of this type of
- deployment and the proximity of a given surrogate to the end-user
- enables the content provider to offer additional services to a user
- which might be based, for example, on geography where this would have
- been difficult with a single, centralized service.
-
- ICAP, the Internet Content Adaption Protocol, is a protocol aimed at
- providing simple object-based content vectoring for HTTP services.
- ICAP is, in essence, a lightweight protocol for executing a "remote
- procedure call" on HTTP messages. It allows ICAP clients to pass
- HTTP messages to ICAP servers for some sort of transformation or
- other processing ("adaptation"). The server executes its
- transformation service on messages and sends back responses to the
- client, usually with modified messages. The adapted messages may be
- either HTTP requests or HTTP responses. Though transformations may
- be possible on other non-HTTP content, they are beyond the scope of
- this document.
-
-
-
-
-
-Elson & Cerpa Informational [Page 3]
-\f
-RFC 3507 ICAP April 2003
-
-
- This type of Remote Procedure Call (RPC) is useful in a number of
- ways. For example:
-
- o Simple transformations of content can be performed near the edge
- of the network instead of requiring an updated copy of an object
- from an origin server. For example, a content provider might want
- to provide a popular web page with a different advertisement every
- time the page is viewed. Currently, content providers implement
- this policy by marking such pages as non-cachable and tracking
- user cookies. This imposes additional load on the origin server
- and the network. In our architecture, the page could be cached
- once near the edges of the network. These edge caches can then
- use an ICAP call to a nearby ad-insertion server every time the
- page is served to a client.
-
- Other such transformations by edge servers are possible, either
- with cooperation from the content provider (as in a content
- distribution network), or as a value-added service provided by a
- client's network provider (as in a surrogate). Examples of these
- kinds of transformations are translation of web pages to different
- human languages or to different formats that are appropriate for
- special physical devices (e.g., PDA-based or cell-phone-based
- browsers).
-
- o Surrogates or origin servers can avoid performing expensive
- operations by shipping the work off to other servers instead.
- This helps distribute load across multiple machines. For example,
- consider a user attempting to download an executable program via a
- surrogate (e.g., a caching proxy). The surrogate, acting as an
- ICAP client, can ask an external server to check the executable
- for viruses before accepting it into its cache.
-
- o Firewalls or surrogates can act as ICAP clients and send outgoing
- requests to a service that checks to make sure the URI in the
- request is allowed (for example, in a system that allows parental
- control of web content viewed by children). In this case, it is a
- *request* that is being adapted, not an object returned by a
- response.
-
- In all of these examples, ICAP is helping to reduce or distribute the
- load on origin servers, surrogates, or the network itself. In some
- cases, ICAP facilitates transformations near the edge of the network,
- allowing greater cachability of the underlying content. In other
- examples, devices such as origin servers or surrogates are able to
- reduce their load by distributing expensive operations onto other
- machines. In all cases, ICAP has also created a standard interface
- for content adaptation to allow greater flexibility in content
- distribution or the addition of value added services in surrogates.
-
-
-
-Elson & Cerpa Informational [Page 4]
-\f
-RFC 3507 ICAP April 2003
-
-
- There are two major components in our architecture:
-
- 1. Transaction semantics -- "How do I ask for adaptation?"
-
- 2. Control of policy -- "When am I supposed to ask for adaptation,
- what kind of adaptation do I ask for, and from where?"
-
- Currently, ICAP defines only the transaction semantics. For example,
- this document specifies how to send an HTTP message from an ICAP
- client to an ICAP server, specify the URI of the ICAP resource
- requested along with other resource-specific parameters, and receive
- the adapted message.
-
- Although a necessary building-block, this wire-protocol defined by
- ICAP is of limited use without the second part: an accompanying
- application framework in which it operates. The more difficult
- policy issue is beyond the scope of the current ICAP protocol, but is
- planned in future work.
-
- In initial implementations, we expect that implementation-specific
- manual configuration will be used to define policy. This includes
- the rules for recognizing messages that require adaptation, the URIs
- of available adaptation resources, and so on. For ICAP clients and
- servers to interoperate, the exact method used to define policy need
- not be consistent across implementations, as long as the policy
- itself is consistent.
-
- IMPORTANT:
- Note that at this time, in the absence of a policy-framework, it
- is strongly RECOMMENDED that transformations SHOULD only be
- performed on messages with the explicit consent of either the
- content-provider or the user (or both). Deployment of
- transformation services without the consent of either leads to, at
- best, unpredictable results. For more discussion of these issues,
- see Section 7.
-
- Once the full extent of the typical policy decisions are more fully
- understood through experience with these initial implementations,
- later follow-ons to this architecture may define an additional policy
- control protocol. This future protocol may allow a standard policy
- definition interface complementary to the ICAP transaction interface
- defined here.
-
-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 BCP 14, RFC 2119 [2].
-
-
-
-Elson & Cerpa Informational [Page 5]
-\f
-RFC 3507 ICAP April 2003
-
-
- The special terminology used in this document is defined below. The
- majority of these terms are taken as-is from HTTP/1.1 [4] and are
- reproduced here for reference. A thorough understanding of HTTP/1.1
- is assumed on the part of the reader.
-
- 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 of
- HTTP/1.1 [4] and transmitted via the connection.
-
- request:
- An HTTP request message, as defined in Section 5 of HTTP/1.1 [4].
-
- response:
- An HTTP response message, as defined in Section 6 of HTTP/1.1 [4].
-
- resource:
- A network data object or service that can be identified by a URI,
- as defined in Section 3.2 of HTTP/1.1 [4]. Resources may be
- available in multiple representations (e.g., multiple languages,
- data formats, size, resolutions) or vary in other ways.
-
- client:
- A program that establishes connections for the purpose of sending
- requests.
-
- 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,
- surrogate, gateway, or tunnel, switching behavior based on the
- nature of each request.
-
- origin server:
- The server on which a given resource resides or is to be created.
-
-
-
-
-
-
-
-
-
-Elson & Cerpa Informational [Page 6]
-\f
-RFC 3507 ICAP April 2003
-
-
- 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.
-
- cache:
- A program's local store of response messages and the subsystem
- that controls its message storage, retrieval, and deletion. A
- cache stores cachable 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.
-
- cachable:
- A response is cachable if a cache is allowed to store a copy of
- the response message for use in answering subsequent requests.
- The rules for determining the cachability of HTTP responses are
- defined in Section 13 of [4]. Even if a resource is cachable,
- there may be additional constraints on whether a cache can use the
- cached copy for a particular request.
-
- surrogate:
- A gateway co-located with an origin server, or at a different
- point in the network, delegated the authority to operate on behalf
- of, and typically working in close co-operation with, one or more
- origin servers. Responses are typically delivered from an
- internal cache. Surrogates may derive cache entries from the
- origin server or from another of the origin server's delegates.
- In some cases a surrogate may tunnel such requests.
-
- Where close co-operation between origin servers and surrogates
- exists, this enables modifications of some protocol requirements,
- including the Cache-Control directives in [4]. Such modifications
- have yet to be fully specified.
-
- Devices commonly known as "reverse proxies" and "(origin) server
- accelerators" are both more properly defined as surrogates.
-
- New definitions:
-
- ICAP resource:
- Similar to an HTTP resource as described above, but the URI refers
- to an ICAP service that performs adaptations of HTTP messages.
-
-
-
-
-
-
-Elson & Cerpa Informational [Page 7]
-\f
-RFC 3507 ICAP April 2003
-
-
- ICAP server:
- Similar to an HTTP server as described above, except that the
- application services ICAP requests.
-
- ICAP client:
- A program that establishes connections to ICAP servers for the
- purpose of sending requests. An ICAP client is often, but not
- always, a surrogate acting on behalf of a user.
-
-3. ICAP Overall Operation
-
- Before describing ICAP's semantics in detail, we will first give a
- general overview of the protocol's major functions and expected uses.
- As described earlier, ICAP focuses on modification of HTTP requests
- (Section 3.1), and modification of HTTP responses (Section 3.2).
-
-3.1 Request Modification
-
- In "request modification" (reqmod) mode, an ICAP client sends an HTTP
- request to an ICAP server. The ICAP server may then:
-
- 1) Send back a modified version of the request. The ICAP client may
- then perform the modified request by contacting an origin server;
- or, pipeline the modified request to another ICAP server for
- further modification.
-
- 2) Send back an HTTP response to the request. This is used to
- provide information useful to the user in case of an error (e.g.,
- "you sent a request to view a page you are not allowed to see").
-
- 3) Return an error.
-
- ICAP clients MUST be able to handle all three types of responses.
- However, in line with the guidance provided for HTTP surrogates in
- Section 13.8 of [4], ICAP client implementors do have flexibility in
- handling errors. If the ICAP server returns an error, the ICAP
- client may (for example) return the error to the user, execute the
- unadapted request as it arrived from the client, or re-try the
- adaptation again.
-
- We will illustrate this method with an example application: content
- filtering. Consider a surrogate that receives a request from a
- client for a web page on an origin server. The surrogate, acting as
- an ICAP client, sends the client's request to an ICAP server that
- performs URI-based content filtering. If access to the requested URI
- is allowed, the request is returned to the ICAP client unmodified.
- However, if the ICAP server chooses to disallow access to the
- requested resources, it may either:
-
-
-
-Elson & Cerpa Informational [Page 8]
-\f
-RFC 3507 ICAP April 2003
-
-
- 1) Modify the request so that it points to a page containing an error
- message instead of the original URI.
-
- 2) Return an encapsulated HTTP response that indicates an HTTP error.
-
- This method can be used for a variety of other applications; for
- example, anonymization, modification of the Accept: headers to handle
- special device requirements, and so forth.
-
- Typical data flow:
-
- origin-server
- | /|\
- | |
- 5 | | 4
- | |
- \|/ | 2
- ICAP-client --------------> ICAP-resource
- (surrogate) <-------------- on ICAP-server
- | /|\ 3
- | |
- 6 | | 1
- | |
- \|/ |
- client
-
- 1. A client makes a request to a ICAP-capable surrogate (ICAP client)
- for an object on an origin server.
-
- 2. The surrogate sends the request to the ICAP server.
-
- 3. The ICAP server executes the ICAP resource's service on the
- request and sends the possibly modified request, or a response to
- the request back to the ICAP client.
-
- If Step 3 returned a request:
-
- 4. The surrogate sends the request, possibly different from original
- client request, to the origin server.
-
- 5. The origin server responds to request.
-
- 6. The surrogate sends the reply (from either the ICAP server or the
- origin server) to the client.
-
-
-
-
-
-
-
-Elson & Cerpa Informational [Page 9]
-\f
-RFC 3507 ICAP April 2003
-
-
-3.2 Response Modification
-
- In the "response modification" (respmod) mode, an ICAP client sends
- an HTTP response to an ICAP server. (The response sent by the ICAP
- client typically has been generated by an origin server.) The ICAP
- server may then:
-
- 1) Send back a modified version of the response.
-
- 2) Return an error.
-
- The response modification method is intended for post-processing
- performed on an HTTP response before it is delivered to a client.
- Examples include formatting HTML for display on special devices,
- human language translation, virus checking, and so forth.
-
- Typical data flow:
-
- origin-server
- | /|\
- | |
- 3 | | 2
- | |
- \|/ | 4
- ICAP-client --------------> ICAP-resource
- (surrogate) <-------------- on ICAP-server
- | /|\ 5
- | |
- 6 | | 1
- | |
- \|/ |
- client
-
- 1. A client makes a request to a ICAP-capable surrogate (ICAP client)
- for an object on an origin server.
-
- 2. The surrogate sends the request to the origin server.
-
- 3. The origin server responds to request.
-
- 4. The ICAP-capable surrogate sends the origin server's reply to the
- ICAP server.
-
- 5. The ICAP server executes the ICAP resource's service on the origin
- server's reply and sends the possibly modified reply back to the
- ICAP client.
-
-
-
-
-
-Elson & Cerpa Informational [Page 10]
-\f
-RFC 3507 ICAP April 2003
-
-
- 6. The surrogate sends the reply, possibly modified from the original
- origin server's reply, to the client.
-
-4. Protocol Semantics
-
-4.1 General Operation
-
- ICAP is a request/response protocol similar in semantics and usage to
- HTTP/1.1 [4]. Despite the similarity, ICAP is not HTTP, nor is it an
- application protocol that runs over HTTP. This means, for example,
- that ICAP messages can not be forwarded by HTTP surrogates. Our
- reasons for not building directly on top of HTTP are discussed in
- Section 8.1.
-
- ICAP uses TCP/IP as a transport protocol. The default port is 1344,
- but other ports may be used. The TCP flow is initiated by the ICAP
- client to a passively listening ICAP server.
-
- ICAP messages consist of requests from client to server and responses
- from server to client. Requests and responses use the generic
- message format of RFC 2822 [3] -- that is, a start-line (either a
- request line or a status line), a number of 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 a message-body.
-
- The header lines of an ICAP message specify the ICAP resource being
- requested as well as other meta-data such as cache control
- information. The message body of an ICAP request contains the
- (encapsulated) HTTP messages that are being modified.
-
- As in HTTP/1.1, a single transport connection MAY (perhaps even
- SHOULD) be re-used for multiple request/response pairs. The rules
- for doing so in ICAP are the same as described in Section 8.1.2.2 of
- [4]. Specifically, requests are matched up with responses by
- allowing only one outstanding request on a transport connection at a
- time. Multiple parallel connections MAY be used as in HTTP.
-
-4.2 ICAP URIs
-
- All ICAP requests specify the ICAP resource being requested from the
- server using an ICAP URI. This MUST be an absolute URI that
- specifies both the complete hostname and the path of the resource
- being requested. For definitive information on URL syntax and
- semantics, see "Uniform Resource Identifiers (URI): Generic Syntax
- and Semantics," RFC 2396 [1], Section 3. The URI structure defined
- by ICAP is roughly:
-
-
-
-
-
-Elson & Cerpa Informational [Page 11]
-\f
-RFC 3507 ICAP April 2003
-
-
- ICAP_URI = Scheme ":" Net_Path [ "?" Query ]
-
- Scheme = "icap"
-
- Net_Path = "//" Authority [ Abs_Path ]
-
- Authority = [ userinfo "@" ] host [ ":" port ]
-
- ICAP adds the new scheme "icap" to the ones defined in RFC 2396. If
- the port is empty or not given, port 1344 is assumed. An example
- ICAP URI line might look like this:
-
- icap://icap.example.net:2000/services/icap-service-1
-
- An ICAP server MUST be able to recognize all of its hosts names,
- including any aliases, local variations, and numeric IP addresses of
- its interfaces.
-
- Any arguments that an ICAP client wishes to pass to an ICAP service
- to modify the nature of the service MAY be passed as part of the
- ICAP-URI, using the standard "?"-encoding of attribute-value pairs
- used in HTTP. For example:
-
- icap://icap.net/service?mode=translate&lang=french
-
-4.3 ICAP Headers
-
- The following sections define the valid headers for ICAP messages.
- Section 4.3.1 describes headers common to both requests and
- responses. Request-specific and response-specific headers are
- described in Sections 4.3.2 and 4.3.3, respectively.
-
- User-defined header extensions are allowed. In compliance with the
- precedent established by the Internet mail format [3] and later
- adopted by HTTP [4], all user-defined headers MUST follow the "X-"
- naming convention ("X-Extension-Header: Foo"). ICAP implementations
- MAY ignore any "X-" headers without loss of compliance with the
- protocol as defined in this document.
-
- Each header field consists of a name followed by a colon (":") and
- the field value. Field names are case-insensitive. ICAP follows the
- rules describe in section 4.2 of [4].
-
-4.3.1 Headers Common to Requests and Responses
-
- The headers of all ICAP messages MAY include the following
- directives, defined in ICAP the same as they are in HTTP:
-
-
-
-
-Elson & Cerpa Informational [Page 12]
-\f
-RFC 3507 ICAP April 2003
-
-
- Cache-Control
- Connection
- Date
- Expires
- Pragma
- Trailer
- Upgrade
-
- Note in particular that the "Transfer-Encoding" option is not
- allowed. The special transfer-encoding requirements of ICAP bodies
- are described in Section 4.4.
-
- The Upgrade header MAY be used to negotiate Transport-Layer Security
- on an ICAP connection, exactly as described for HTTP/1.1 in [4].
-
- The ICAP-specific headers defined are:
-
- Encapsulated (See Section 4.4)
-
-4.3.2 Request Headers
-
- Similar to HTTP, ICAP requests MUST start with a request line that
- contains a method, the complete URI of the ICAP resource being
- requested, and an ICAP version string. The current version number of
- ICAP is "1.0".
-
- This version of ICAP defines three methods:
-
- REQMOD - for Request Modification (Section 4.8)
- RESPMOD - for Response Modification (Section 4.9)
- OPTIONS - to learn about configuration (Section 4.10)
-
- The OPTIONS method MUST be implemented by all ICAP servers. All
- other methods are optional and MAY be implemented.
-
- User-defined extension methods are allowed. Before attempting to use
- an extension method, an ICAP client SHOULD use the OPTIONS method to
- query the ICAP server's list of supported methods; see Section 4.10.
- (If an ICAP server receives a request for an unknown method, it MUST
- give a 501 error response as described in the next section.)
-
- Given the URI rules described in Section 4.2, a well-formed ICAP
- request line looks like the following example:
-
- RESPMOD icap://icap.example.net/translate?mode=french ICAP/1.0
-
-
-
-
-
-
-Elson & Cerpa Informational [Page 13]
-\f
-RFC 3507 ICAP April 2003
-
-
- A number of request-specific headers are allowed in ICAP requests,
- following the same semantics as the corresponding HTTP request
- headers (Section 5.3 of [4]). These are:
-
- Authorization
- Allow (see Section 4.6)
- From (see Section 14.22 of [4])
- Host (REQUIRED in ICAP as it is in HTTP/1.1)
- Referer (see Section 14.36 of [4])
- User-Agent
-
- In addition to HTTP-like headers, there are also request headers
- unique to ICAP defined:
-
- Preview (see Section 4.5)
-
-4.3.3 Response Headers
-
- ICAP responses MUST start with an ICAP status line, similar in form
- to that used by HTTP, including the ICAP version and a status code.
- For example:
-
- ICAP/1.0 200 OK
-
- Semantics of ICAP status codes in ICAP match the status codes defined
- by HTTP (Section 6.1.1 and 10 of [4]), except where otherwise
- indicated in this document; n.b. 100 (Section 4.5) and 204 (Section
- 4.6).
-
- ICAP error codes that differ from their HTTP counterparts are:
-
- 100 - Continue after ICAP Preview (Section 4.5).
-
- 204 - No modifications needed (Section 4.6).
-
- 400 - Bad request.
-
- 404 - ICAP Service not found.
-
- 405 - Method not allowed for service (e.g., RESPMOD requested for
- service that supports only REQMOD).
-
- 408 - Request timeout. ICAP server gave up waiting for a request
- from an ICAP client.
-
- 500 - Server error. Error on the ICAP server, such as "out of disk
- space".
-
-
-
-
-Elson & Cerpa Informational [Page 14]
-\f
-RFC 3507 ICAP April 2003
-
-
- 501 - Method not implemented. This response is illegal for an
- OPTIONS request since implementation of OPTIONS is mandatory.
-
- 502 - Bad Gateway. This is an ICAP proxy and proxying produced an
- error.
-
- 503 - Service overloaded. The ICAP server has exceeded a maximum
- connection limit associated with this service; the ICAP client
- should not exceed this limit in the future.
-
- 505 - ICAP version not supported by server.
-
- As in HTTP, the 4xx class of error codes indicate client errors, and
- the 5xx class indicate server errors.
-
- ICAP's response-header fields allow the server to pass additional
- information in the response that cannot be placed in the ICAP's
- status line.
-
- A response-specific header is allowed in ICAP requests, following the
- same semantics as the corresponding HTTP response headers (Section
- 6.2 of [4]). This is:
-
- Server (see Section 14.38 of [4])
-
- In addition to HTTP-like headers, there is also a response header
- unique to ICAP defined:
-
- ISTag (see Section 4.7)
-
-4.3.4 ICAP-Related Headers in HTTP Messages
-
- When an ICAP-enabled HTTP surrogate makes an HTTP request to an
- origin server, it is often useful to advise the origin server of the
- surrogate's ICAP capabilities. Origin servers can use this
- information to modify its response accordingly. For example, an
- origin server may choose not to insert an advertisement into a page
- if it knows that a downstream ICAP server can insert the ad instead.
-
- Although this ICAP specification can not mandate how HTTP is used in
- communication between HTTP clients and servers, we do suggest a
- convention: such headers (if used) SHOULD start with "X-ICAP". HTTP
- clients with ICAP services SHOULD minimally include an "X-ICAP-
- Version: 1.0" header along with their application-specific headers.
-
-
-
-
-
-
-
-Elson & Cerpa Informational [Page 15]
-\f
-RFC 3507 ICAP April 2003
-
-
-4.4 ICAP Bodies: Encapsulation of HTTP Messages
-
- The ICAP encapsulation model is a lightweight means of packaging any
- number of HTTP message sections into an encapsulating ICAP message-
- body, in order to allow the vectoring of requests, responses, and
- request/response pairs to an ICAP server.
-
- This is accomplished by concatenating interesting message parts
- (encapsulatED sections) into a single ICAP message-body (the
- encapsulatING message). The encapsulated sections may be the headers
- or bodies of HTTP messages.
-
- Encapsulated bodies MUST be transferred using the "chunked"
- transfer-coding described in Section 3.6.1 of [4]. However,
- encapsulated headers MUST NOT be chunked. In other words, an ICAP
- message-body switches from being non-chunked to chunked as the body
- passes from the encapsulated header to encapsulated body section.
- (See Examples in Sections 4.8.3 and 4.9.3.). The motivation behind
- this decision is described in Section 8.2.
-
-4.4.1 The "Encapsulated" Header
-
- The offset of each encapsulated section's start relative to the start
- of the encapsulating message's body is noted using the "Encapsulated"
- header. This header MUST be included in every ICAP message. For
- example, the header
-
- Encapsulated: req-hdr=0, res-hdr=45, res-body=100
-
- indicates a message that encapsulates a group of request headers, a
- group of response headers, and then a response body. Each of these
- is included at the byte-offsets listed. The byte-offsets are in
- decimal notation for consistency with HTTP's Content-Length header.
-
- The special entity "null-body" indicates there is no encapsulated
- body in the ICAP message.
-
- The syntax of an Encapsulated header is:
-
- encapsulated_header: "Encapsulated: " encapsulated_list
- encapsulated_list: encapsulated_entity |
- encapsulated_entity ", " encapsulated_list
- encapsulated_entity: reqhdr | reshdr | reqbody | resbody | optbody
- reqhdr = "req-hdr" "=" (decimal integer)
- reshdr = "res-hdr" "=" (decimal integer)
- reqbody = { "req-body" | "null-body" } "=" (decimal integer)
- resbody = { "res-body" | "null-body" } "=" (decimal integer)
- optbody = { "opt-body" | "null-body" } "=" (decimal integer)
-
-
-
-Elson & Cerpa Informational [Page 16]
-\f
-RFC 3507 ICAP April 2003
-
-
- There are semantic restrictions on Encapsulated headers beyond the
- syntactic restrictions. The order in which the encapsulated parts
- appear in the encapsulating message-body MUST be the same as the
- order in which the parts are named in the Encapsulated header. In
- other words, the offsets listed in the Encapsulated line MUST be
- monotonically increasing. In addition, the legal forms of the
- Encapsulated header depend on the method being used (REQMOD, RESPMOD,
- or OPTIONS). Specifically:
-
- REQMOD request encapsulated_list: [reqhdr] reqbody
- REQMOD response encapsulated_list: {[reqhdr] reqbody} |
- {[reshdr] resbody}
- RESPMOD request encapsulated_list: [reqhdr] [reshdr] resbody
- RESPMOD response encapsulated_list: [reshdr] resbody
- OPTIONS response encapsulated_list: optbody
-
- In the above grammar, note that encapsulated headers are always
- optional. At most one body per encapsulated message is allowed. If
- no encapsulated body is presented, the "null-body" header is used
- instead; this is useful because it indicates the length of the header
- section.
-
- Examples of legal Encapsulated headers:
-
- /* REQMOD request: This encapsulated HTTP request's headers start
- * at offset 0; the HTTP request body (e.g., in a POST) starts
- * at 412. */
- Encapsulated: req-hdr=0, req-body=412
-
- /* REQMOD request: Similar to the above, but no request body is
- * present (e.g., a GET). We use the null-body directive instead.
- * In both this case and the previous one, we can tell from the
- * Encapsulated header that the request headers were 412 bytes
- * long. */
- Encapsulated: req-hdr=0, null-body=412
-
- /* REQMOD response: ICAP server returned a modified request,
- * with body */
- Encapsulated: req-hdr=0, req-body=512
-
- /* RESPMOD request: Request headers at 0, response headers at 822,
- * response body at 1655. Note that no request body is allowed in
- * RESPMOD requests. */
- Encapsulated: req-hdr=0, res-hdr=822, res-body=1655
-
- /* RESPMOD or REQMOD response: header and body returned */
- Encapsulated: res-hdr=0, res-body=749
-
-
-
-
-Elson & Cerpa Informational [Page 17]
-\f
-RFC 3507 ICAP April 2003
-
-
- /* OPTIONS response when there IS an options body */
- Encapsulated: opt-body=0
-
- /* OPTIONS response when there IS NOT an options body */
- Encapsulated: null-body=0
-
-4.4.2 Encapsulated HTTP Headers
-
- By default, ICAP messages may encapsulate HTTP message headers and
- entity bodies. HTTP headers MUST start with the request-line or
- status-line for requests and responses, respectively, followed by
- interesting HTTP headers.
-
- The encapsulated headers MUST be terminated by a blank line, in order
- to make them human readable, and in order to terminate line-by-line
- HTTP parsers.
-
- HTTP/1.1 makes a distinction between end-to-end headers and hop-by-
- hop headers (see Section 13.5.1 of [4]). End-to-end headers are
- meaningful to the ultimate recipient of a message, whereas hop-by-hop
- headers are meaningful only for a single transport-layer connection.
- Hop-by-hop headers include Connection, Keep-Alive, and so forth. All
- end-to-end HTTP headers SHOULD be encapsulated, and all hop-by-hop
- headers MUST NOT be encapsulated.
-
- Despite the above restrictions on encapsulation, the hop-by-hop
- Proxy-Authenticate and Proxy-Authorization headers MUST be forwarded
- to the ICAP server in the ICAP header section (not the encapsulated
- message). This allows propagation of client credentials that might
- have been sent to the ICAP client in cases where the ICAP client is
- also an HTTP surrogate. Note that this does not contradict HTTP/1.1,
- which explicitly states "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." (Section
- 14.34).
-
- The Via header of an encapsulated message SHOULD be modified by an
- ICAP server as if the encapsulated message were traveling through an
- HTTP surrogate. The Via header added by an ICAP server MUST specify
- protocol as ICAP/1.0.
-
-4.5 Message Preview
-
- ICAP REQMOD or RESPMOD requests sent by the ICAP client to the ICAP
- server may include a "preview". This feature allows an ICAP server
- to see the beginning of a transaction, then decide if it wants to
-
-
-
-
-
-Elson & Cerpa Informational [Page 18]
-\f
-RFC 3507 ICAP April 2003
-
-
- opt-out of the transaction early instead of receiving the remainder
- of the request message. Previewing can yield significant performance
- improvements in a variety of situations, such as the following:
-
- - Virus-checkers can certify a large fraction of files as "clean"
- just by looking at the file type, file name extension, and the
- first few bytes of the file. Only the remaining files need to be
- transmitted to the virus-checking ICAP server in their entirety.
-
- - Content filters can use Preview to decide if an HTTP entity needs
- to be inspected (the HTTP file type alone is not enough in cases
- where "text" actually turns out to be graphics data). The magic
- numbers at the front of the file can identify a file as a JPEG or
- GIF.
-
- - If an ICAP server wants to transcode all GIF87 files into GIF89
- files, then the GIF87 files could quickly be detected by looking
- at the first few body bytes of the file.
-
- - If an ICAP server wants to force all cacheable files to expire in
- 24 hours or less, then this could be implemented by selecting HTTP
- messages with expiries more than 24 hours in the future.
-
- ICAP servers SHOULD use the OPTIONS method (see Section 4.10) to
- specify how many bytes of preview are needed for a particular ICAP
- application on a per-resource basis. Clients SHOULD be able to
- provide Previews of at least 4096 bytes. Clients furthermore SHOULD
- provide a Preview when using any ICAP resource that has indicated a
- Preview is useful. (This indication might be provided via the
- OPTIONS method, or some other "out-of-band" configuration.) Clients
- SHOULD NOT provide a larger Preview than a server has indicated it is
- willing to accept.
-
- To effect a Preview, an ICAP client MUST add a "Preview:" header to
- its request headers indicating the length of the preview. The ICAP
- client then sends:
-
- - all of the encapsulated header sections, and
-
- - the beginning of the encapsulated body section, if any, up to the
- number of bytes advertised in the Preview (possibly 0).
-
- After the Preview is sent, the client stops and waits for an
- intermediate response from the ICAP server before continuing. This
- mechanism is similar to the "100-Continue" feature found in HTTP,
- except that the stop-and-wait point can be within the message body.
- In contrast, HTTP requires that the point must be the boundary
- between the headers and body.
-
-
-
-Elson & Cerpa Informational [Page 19]
-\f
-RFC 3507 ICAP April 2003
-
-
- For example, to effect a Preview consisting of only encapsulated HTTP
- headers, the ICAP client would add the following header to the ICAP
- request:
-
- Preview: 0
-
- This indicates that the ICAP client will send only the encapsulated
- header sections to the ICAP server, then it will send a zero-length
- chunk and stop and wait for a "go ahead" to send more encapsulated
- body bytes to the ICAP server.
-
- Similarly, the ICAP header:
-
- Preview: 4096
-
- Indicates that the ICAP client will attempt to send 4096 bytes of
- origin server data in the encapsulated body of the ICAP request to
- the ICAP server. It is important to note that the actual transfer
- may be less, because the ICAP client is acting like a surrogate and
- is not looking ahead to find the total length of the origin server
- response. The entire ICAP encapsulated header section(s) will be
- sent, followed by up to 4096 bytes of encapsulated HTTP body. The
- chunk body terminator "0\r\n\r\n" is always included in these
- transactions.
-
- After sending the preview, the ICAP client will wait for a response
- from the ICAP server. The response MUST be one of the following:
-
- - 204 No Content. The ICAP server does not want to (or can not)
- modify the ICAP client's request. The ICAP client MUST treat this
- the same as if it had sent the entire message to the ICAP server
- and an identical message was returned.
-
- - ICAP reqmod or respmod response, depending what method was the
- original request. See Section 4.8.2 and 4.9.2 for the format of
- reqmod and respmod responses.
-
- - 100 Continue. If the entire encapsulated HTTP body did not fit
- in the preview, the ICAP client MUST send the remainder of its
- ICAP message, starting from the first chunk after the preview. If
- the entire message fit in the preview (detected by the "EOF"
- symbol explained below), then the ICAP server MUST NOT respond
- with 100 Continue.
-
- When an ICAP client is performing a preview, it may not yet know how
- many bytes will ultimately be available in the arriving HTTP message
- that it is relaying to the HTTP server. Therefore, ICAP defines a
- way for ICAP clients to indicate "EOF" to ICAP servers if one
-
-
-
-Elson & Cerpa Informational [Page 20]
-\f
-RFC 3507 ICAP April 2003
-
-
- unexpectedly arrives during the preview process. This is a
- particularly useful optimization if a header-only HTTP response
- arrives at the ICAP client (i.e., zero bytes of body); only a single
- round trip will be needed for the complete ICAP server response.
-
- We define an HTTP chunk-extension of "ieof" to indicate that an ICAP
- chunk is the last chunk (see [4]). The ICAP server MUST strip this
- chunk extension before passing the chunk data to an ICAP application
- process.
-
- For example, consider an ICAP client that has just received HTTP
- response headers from an origin server and initiates an ICAP RESPMOD
- transaction to an ICAP server. It does not know yet how many body
- bytes will be arriving from the origin server because the server is
- not using the Content-Length header. The ICAP client informs the
- ICAP server that it will be sending a 1024-byte preview using a
- "Preview: 1024" request header. If the HTTP origin server then
- closes its connection to the ICAP client before sending any data
- (i.e., it provides a zero-byte body), the corresponding zero-byte
- preview for that zero-byte origin response would appear as follows:
-
- \r\n
- 0; ieof\r\n\r\n
-
- If an ICAP server sees this preview, it knows from the presence of
- "ieof" that the client will not be sending any more chunk data. In
- this case, the server MUST respond with the modified response or a
- 204 No Content message right away. It MUST NOT send a 100-Continue
- response in this case. (In contrast, if the origin response had been
- 1 byte or larger, the "ieof" would not have appeared. In that case,
- an ICAP server MAY reply with 100-Continue, a modified response, or
- 204 No Content.)
-
- In another example, if the preview is 1024 bytes and the origin
- response is 1024 bytes in two chunks, then the encapsulation would
- appear as follows:
-
- 200\r\n
- <512 bytes of data>\r\n
- 200\r\n
- <512 bytes of data>\r\n
- 0; ieof\r\n\r\n
-
- <204 or modified response> (100 Continue disallowed due to ieof)
-
- If the preview is 1024 bytes and the origin response is 1025 bytes
- (and the ICAP server responds with 100-continue), then these chunks
- would appear on the wire:
-
-
-
-Elson & Cerpa Informational [Page 21]
-\f
-RFC 3507 ICAP April 2003
-
-
- 200\r\n
- <512 bytes of data>\r\n
- 200\r\n
- <512 bytes of data>\r\n
- 0\r\n
-
- <100 Continue Message>
-
- 1\r\n
- <1 byte of data>\r\n
- 0\r\n\r\n <no ieof because we are no longer in preview mode>
-
- Once the ICAP server receives the eof indicator, it finishes reading
- the current chunk stream.
-
- Note that when offering a Preview, the ICAP client is committing to
- temporarily buffer the previewed portion of the message so that it
- can honor a "204 No Content" response. The remainder of the message
- is not necessarily buffered; it might be pipelined directly from
- another source to the ICAP server after a 100-Continue.
-
-4.6 "204 No Content" Responses outside of Previews
-
- An ICAP client MAY choose to honor "204 No Content" responses for an
- entire message. This is the decision of the client because it
- imposes a burden on the client of buffering the entire message.
-
- An ICAP client MAY include "Allow: 204" in its request headers,
- indicating that the server MAY reply to the message with a "204 No
- Content" response if the object does not need modification.
-
- If an ICAP server receives a request that does not have "Allow: 204",
- it MUST NOT reply with a 204. In this case, an ICAP server MUST
- return the entire message back to the client, even though it is
- identical to the message it received.
-
- The ONLY EXCEPTION to this rule is in the case of a message preview,
- as described in the previous section. If this is the case, an ICAP
- server can respond with a 204 No Content message in response to a
- message preview EVEN if the original request did not have the "Allow:
- 204" header.
-
-4.7 ISTag Response Header
-
- The ISTag ("ICAP Service Tag") response-header field provides a way
- for ICAP servers to send a service-specific "cookie" to ICAP clients
- that represents a service's current state. It is a 32-byte-maximum
- alphanumeric string of data (not including the null character) that
-
-
-
-Elson & Cerpa Informational [Page 22]
-\f
-RFC 3507 ICAP April 2003
-
-
- may, for example, be a representation of the software version or
- configuration of a service. An ISTag validates that previous ICAP
- server responses can still be considered fresh by an ICAP client that
- may be caching them. If a change on the ICAP server invalidates
- previous responses, the ICAP server can invalidate portions of the
- ICAP client's cache by changing its ISTag. The ISTag MUST be
- included in every ICAP response from an ICAP server.
-
- For example, consider a virus-scanning ICAP service. The ISTag might
- be a combination of the virus scanner's software version and the
- release number of its virus signature database. When the database is
- updated, the ISTag can be changed to invalidate all previous
- responses that had been certified as "clean" and cached with the old
- ISTag.
-
- ISTag is similar, but not identical, to the HTTP ETag. While an ETag
- is a validator for a particular entity (object), an ISTag validates
- all entities generated by a particular service (URI). A change in
- the ISTag invalidates all the other entities provided a service with
- the old ISTag, not just the entity whose response contained the
- updated ISTag.
-
- The syntax of an ISTag is simply:
- ISTag = "ISTag: " quoted-string
-
- In this document we use the quoted-string definition defined in
- section 2.2 of [4].
-
- For example:
- ISTag: "874900-1994-1c02798"
-
-4.8 Request Modification Mode
-
- In this method, described in Section 3.1, an ICAP client sends an
- HTTP request to an ICAP server. The ICAP server returns a modified
- version of the request, an HTTP response, or (if the client indicates
- it supports 204 responses) an indication that no modification is
- required.
-
-4.8.1 Request
-
- In REQMOD mode, the ICAP request MUST contain an encapsulated HTTP
- request. The headers and body (if any) MUST both be encapsulated,
- except that hop-by-hop headers are not encapsulated.
-
-
-
-
-
-
-
-Elson & Cerpa Informational [Page 23]
-\f
-RFC 3507 ICAP April 2003
-
-
-4.8.2 Response
-
- The response from the ICAP server back to the ICAP client may take
- one of four forms:
-
- - An error indication,
-
- - A 204 indicating that the ICAP client's request requires no
- adaptation (see Section 4.6 for limitations of this response),
-
- - An encapsulated, adapted version of the ICAP client's request, or
-
- - An encapsulated HTTP error response. Note that Request
- Modification requests may only be satisfied with HTTP responses in
- cases when the HTTP response is an error (e.g., 403 Forbidden).
-
- The first line of the response message MUST be a status line as
- described in Section 4.3.3. If the return code is a 2XX, the ICAP
- client SHOULD continue its normal execution of the request. If the
- ICAP client is a surrogate, this may include serving an object from
- its cache or forwarding the modified request to an origin server.
- Note it is valid for a 2XX ICAP response to contain an encapsulated
- HTTP error response, which in turn should be returned to the
- downstream client by the ICAP client.
-
- For other return codes that indicate an error, the ICAP client MAY
- (for example) return the error to the downstream client or user,
- execute the unadapted request as it arrived from the client, or re-
- try the adaptation again.
-
- The modified request headers, if any, MUST be returned to the ICAP
- client using appropriate encapsulation as described in Section 4.4.
-
-4.8.3 Examples
-
- Consider the following example, in which a surrogate receives a
- simple GET request from a client. The surrogate, acting as an ICAP
- client, then forwards this request to an ICAP server for
- modification. The ICAP server modifies the request headers and sends
- them back to the ICAP client. Our hypothetical ICAP server will
- modify several headers and strip the cookie from the original
- request.
-
- In all of our examples, we include the extra meta-data added to the
- message due to chunking the encapsulated message body (if any). We
- assume that end-of-line terminations, and blank lines, are two-byte
- "CRLF" sequences.
-
-
-
-
-Elson & Cerpa Informational [Page 24]
-\f
-RFC 3507 ICAP April 2003
-
-
- ICAP Request Modification Example 1 - ICAP Request
- ----------------------------------------------------------------
- REQMOD icap://icap-server.net/server?arg=87 ICAP/1.0
- Host: icap-server.net
- Encapsulated: req-hdr=0, null-body=170
-
- GET / HTTP/1.1
- Host: www.origin-server.com
- Accept: text/html, text/plain
- Accept-Encoding: compress
- Cookie: ff39fk3jur@4ii0e02i
- If-None-Match: "xyzzy", "r2d2xxxx"
-
- ----------------------------------------------------------------
- ICAP Request Modification Example 1 - ICAP Response
- ----------------------------------------------------------------
- ICAP/1.0 200 OK
- Date: Mon, 10 Jan 2000 09:55:21 GMT
- Server: ICAP-Server-Software/1.0
- Connection: close
- ISTag: "W3E4R7U9-L2E4-2"
- Encapsulated: req-hdr=0, null-body=231
-
- GET /modified-path HTTP/1.1
- Host: www.origin-server.com
- Via: 1.0 icap-server.net (ICAP Example ReqMod Service 1.1)
- Accept: text/html, text/plain, image/gif
- Accept-Encoding: gzip, compress
- If-None-Match: "xyzzy", "r2d2xxxx"
-
- ----------------------------------------------------------------
-
- The second example is similar to the first, except that the request
- being modified in this case is a POST instead of a GET. Note that
- the encapsulated Content-Length argument has been modified to reflect
- the modified body of the POST message. The outer ICAP message does
- not need a Content-Length header because it uses chunking (not
- shown).
-
- In this second example, the Encapsulated header shows the division
- between the forwarded header and forwarded body, for both the request
- and the response.
-
- ICAP Request Modification Example 2 - ICAP Request
- ----------------------------------------------------------------
- REQMOD icap://icap-server.net/server?arg=87 ICAP/1.0
- Host: icap-server.net
- Encapsulated: req-hdr=0, req-body=147
-
-
-
-Elson & Cerpa Informational [Page 25]
-\f
-RFC 3507 ICAP April 2003
-
-
- POST /origin-resource/form.pl HTTP/1.1
- Host: www.origin-server.com
- Accept: text/html, text/plain
- Accept-Encoding: compress
- Pragma: no-cache
-
- 1e
- I am posting this information.
- 0
-
- ----------------------------------------------------------------
- ICAP Request Modification Example 2 - ICAP Response
- ----------------------------------------------------------------
- ICAP/1.0 200 OK
- Date: Mon, 10 Jan 2000 09:55:21 GMT
- Server: ICAP-Server-Software/1.0
- Connection: close
- ISTag: "W3E4R7U9-L2E4-2"
- Encapsulated: req-hdr=0, req-body=244
-
- POST /origin-resource/form.pl HTTP/1.1
- Host: www.origin-server.com
- Via: 1.0 icap-server.net (ICAP Example ReqMod Service 1.1)
- Accept: text/html, text/plain, image/gif
- Accept-Encoding: gzip, compress
- Pragma: no-cache
- Content-Length: 45
-
- 2d
- I am posting this information. ICAP powered!
- 0
-
- ----------------------------------------------------------------
- Finally, this third example shows an ICAP server returning an error
- response when it receives a Request Modification request.
-
- ICAP Request Modification Example 3 - ICAP Request
- ----------------------------------------------------------------
- REQMOD icap://icap-server.net/content-filter ICAP/1.0
- Host: icap-server.net
- Encapsulated: req-hdr=0, null-body=119
-
- GET /naughty-content HTTP/1.1
- Host: www.naughty-site.com
- Accept: text/html, text/plain
- Accept-Encoding: compress
-
- ----------------------------------------------------------------
-
-
-
-Elson & Cerpa Informational [Page 26]
-\f
-RFC 3507 ICAP April 2003
-
-
- ICAP Request Modification Example 3 - ICAP Response
- ----------------------------------------------------------------
- ICAP/1.0 200 OK
- Date: Mon, 10 Jan 2000 09:55:21 GMT
- Server: ICAP-Server-Software/1.0
- Connection: close
- ISTag: "W3E4R7U9-L2E4-2"
- Encapsulated: res-hdr=0, res-body=213
-
- HTTP/1.1 403 Forbidden
- Date: Wed, 08 Nov 2000 16:02:10 GMT
- Server: Apache/1.3.12 (Unix)
- Last-Modified: Thu, 02 Nov 2000 13:51:37 GMT
- ETag: "63600-1989-3a017169"
- Content-Length: 58
- Content-Type: text/html
-
- 3a
- Sorry, you are not allowed to access that naughty content.
- 0
-
- ----------------------------------------------------------------
-
-4.9 Response Modification Mode
-
- In this method, described in Section 3.2, an ICAP client sends an
- origin server's HTTP response to an ICAP server, and (if available)
- the original client request that caused that response. Similar to
- Request Modification method, the response from the ICAP server can be
- an adapted HTTP response, an error, or a 204 response code indicating
- that no adaptation is required.
-
-4.9.1 Request
-
- Using encapsulation described in Section 4.4, the header and body of
- the HTTP response to be modified MUST be included in the ICAP body.
- If available, the header of the original client request SHOULD also
- be included. As with the other method, the hop-by-hop headers of the
- encapsulated messages MUST NOT be forwarded. The Encapsulated header
- MUST indicate the byte-offsets of the beginning of each of these four
- parts.
-
-4.9.2 Response
-
- The response from the ICAP server looks just like a reply in the
- Request Modification method (Section 4.8); that is,
-
- - An error indication,
-
-
-
-Elson & Cerpa Informational [Page 27]
-\f
-RFC 3507 ICAP April 2003
-
-
- - An encapsulated and potentially modified HTTP response header and
- response body, or
-
- - An HTTP response 204 indicating that the ICAP client's request
- requires no adaptation.
-
- The first line of the response message MUST be a status line as
- described in Section 4.3.3. If the return code is a 2XX, the ICAP
- client SHOULD continue its normal execution of the response. The
- ICAP client MAY re-examine the headers in the response's message
- headers in order to make further decisions about the response (e.g.,
- its cachability).
-
- For other return codes that indicate an error, the ICAP client SHOULD
- NOT return these directly to downstream client, since these errors
- only make sense in the ICAP client/server transaction.
-
- The modified response headers, if any, MUST be returned to the ICAP
- client using appropriate encapsulation as described in Section 4.4.
-
-4.9.3 Examples
-
- In Example 4, an ICAP client is requesting modification of an entity
- that was returned as a result of a client GET. The original client
- GET was to an origin server at "www.origin-server.com"; the ICAP
- server is at "icap.example.org".
-
- ICAP Response Modification Example 4 - ICAP Request
- ----------------------------------------------------------------
- RESPMOD icap://icap.example.org/satisf ICAP/1.0
- Host: icap.example.org
- Encapsulated: req-hdr=0, res-hdr=137, res-body=296
-
- GET /origin-resource HTTP/1.1
- Host: www.origin-server.com
- Accept: text/html, text/plain, image/gif
- Accept-Encoding: gzip, compress
-
- HTTP/1.1 200 OK
- Date: Mon, 10 Jan 2000 09:52:22 GMT
- Server: Apache/1.3.6 (Unix)
- ETag: "63840-1ab7-378d415b"
- Content-Type: text/html
- Content-Length: 51
-
-
-
-
-
-
-
-Elson & Cerpa Informational [Page 28]
-\f
-RFC 3507 ICAP April 2003
-
-
- 33
- This is data that was returned by an origin server.
- 0
-
- ----------------------------------------------------------------
-
- ICAP Response Modification Example 4 - ICAP Response
- ----------------------------------------------------------------
- ICAP/1.0 200 OK
- Date: Mon, 10 Jan 2000 09:55:21 GMT
- Server: ICAP-Server-Software/1.0
- Connection: close
- ISTag: "W3E4R7U9-L2E4-2"
- Encapsulated: res-hdr=0, res-body=222
-
- HTTP/1.1 200 OK
- Date: Mon, 10 Jan 2000 09:55:21 GMT
- Via: 1.0 icap.example.org (ICAP Example RespMod Service 1.1)
- Server: Apache/1.3.6 (Unix)
- ETag: "63840-1ab7-378d415b"
- Content-Type: text/html
- Content-Length: 92
-
- 5c
- This is data that was returned by an origin server, but with
- value added by an ICAP server.
- 0
-
- ----------------------------------------------------------------
-
-4.10 OPTIONS Method
-
- The ICAP "OPTIONS" method is used by the ICAP client to retrieve
- configuration information from the ICAP server. In this method, the
- ICAP client sends a request addressed to a specific ICAP resource and
- receives back a response with options that are specific to the
- service named by the URI. All OPTIONS requests MAY also return
- options that are global to the server (i.e., apply to all services).
-
-4.10.1 OPTIONS Request
-
- The OPTIONS method consists of a request-line, as described in
- Section 4.3.2, such as the following example:
-
- OPTIONS icap://icap.server.net/sample-service ICAP/1.0 User-Agent:
- ICAP-client-XYZ/1.001
-
-
-
-
-
-Elson & Cerpa Informational [Page 29]
-\f
-RFC 3507 ICAP April 2003
-
-
- Other headers are also allowed as described in Section 4.3.1 and
- Section 4.3.2 (for example, Host).
-
-4.10.2 OPTIONS Response
-
- The OPTIONS response consists of a status line as described in
- section 4.3.3 followed by a series of header field names-value pairs
- optionally followed by an opt-body. Multiple values in the value
- field MUST be separated by commas. If an opt-body is present in the
- OPTIONS response, the Opt-body-type header describes the format of
- the opt-body.
-
- The OPTIONS headers supported in this version of the protocol are:
-
- -- Methods:
-
- The method that is supported by this service. This header MUST be
- included in the OPTIONS response. The OPTIONS method MUST NOT be
- in the Methods' list since it MUST be supported by all the ICAP
- server implementations. Each service should have a distinct URI
- and support only one method in addition to OPTIONS (see Section
- 6.4).
-
- For example:
- Methods: RESPMOD
-
- -- Service:
-
- A text description of the vendor and product name. This header
- MAY be included in the OPTIONS response.
-
- For example:
- Service: XYZ Technology Server 1.0
-
- -- ISTag:
-
- See section 4.7 for details. This header MUST be included in the
- OPTIONS response.
-
- For example:
- ISTag: "5BDEEEA9-12E4-2"
-
- -- Encapsulated:
-
- This header MUST be included in the OPTIONS response; see Section
- 4.4.
-
-
-
-
-
-Elson & Cerpa Informational [Page 30]
-\f
-RFC 3507 ICAP April 2003
-
-
- For example:
- Encapsulated: opt-body=0
-
- -- Opt-body-type:
-
- A token identifying the format of the opt-body. (Valid opt-body
- types are not defined by ICAP.) This header MUST be included in
- the OPTIONS response ONLY if an opt-body type is present.
-
- For example:
- Opt-body-type: XML-Policy-Table-1.0
-
- -- Max-Connections:
-
- The maximum number of ICAP connections the server is able to
- support. This header MAY be included in the OPTIONS response.
-
- For example:
- Max-Connections: 1500
-
- -- Options-TTL:
-
- The time (in seconds) for which this OPTIONS response is valid.
- If none is specified, the OPTIONS response does not expire. This
- header MAY be included in the OPTIONS response. The ICAP client
- MAY reissue an OPTIONS request once the Options-TTL expires.
-
- For example:
- Options-TTL: 3600
-
- -- Date:
-
- The server's clock, specified as an RFC 1123 compliant date/time
- string. This header MAY be included in the OPTIONS response.
-
- For example:
- Date: Fri, 15 Jun 2001 04:33:55 GMT
-
- -- Service-ID:
-
- A short label identifying the ICAP service. It MAY be used in
- attribute header names. This header MAY be included in the
- OPTIONS response.
-
- For example:
- Service-ID: xyztech
-
-
-
-
-
-Elson & Cerpa Informational [Page 31]
-\f
-RFC 3507 ICAP April 2003
-
-
- -- Allow:
-
- A directive declaring a list of optional ICAP features that this
- server has implemented. This header MAY be included in the
- OPTIONS response. In this document we define the value "204" to
- indicate that the ICAP server supports a 204 response.
-
- For example:
- Allow: 204
-
- -- Preview:
-
- The number of bytes to be sent by the ICAP client during a
- preview. This header MAY be included in the OPTIONS response.
-
- For example:
- Preview: 1024
-
- -- Transfer-Preview:
-
- A list of file extensions that should be previewed to the ICAP
- server before sending them in their entirety. This header MAY be
- included in the OPTIONS response. Multiple file extensions values
- should be separated by commas. The wildcard value "*" specifies
- the default behavior for all the file extensions not specified in
- any other Transfer-* header (see below).
-
- For example:
- Transfer-Preview: *
-
- -- Transfer-Ignore:
-
- A list of file extensions that should NOT be sent to the ICAP
- server. This header MAY be included in the OPTIONS response.
- Multiple file extensions should be separated by commas.
-
- For example:
- Transfer-Ignore: html
-
- -- Transfer-Complete:
-
- A list of file extensions that should be sent in their entirety
- (without preview) to the ICAP server. This header MAY be included
- in the OPTIONS response. Multiple file extensions values should
- be separated by commas.
-
- For example:
- Transfer-Complete: asp, bat, exe, com, ole
-
-
-
-Elson & Cerpa Informational [Page 32]
-\f
-RFC 3507 ICAP April 2003
-
-
- Note: If any of Transfer-* are sent, exactly one of them MUST contain
- the wildcard value "*" to specify the default. If no Transfer-* are
- sent, all responses will be sent in their entirety (without Preview).
-
-4.10.3 OPTIONS Examples
-
- In example 5, an ICAP Client sends an OPTIONS Request to an ICAP
- Service named icap.server.net/sample-service in order to get
- configuration information for the service provided.
-
- ICAP OPTIONS Example 5 - ICAP OPTIONS Request
- ----------------------------------------------------------------
- OPTIONS icap://icap.server.net/sample-service ICAP/1.0
- Host: icap.server.net
- User-Agent: BazookaDotCom-ICAP-Client-Library/2.3
-
- ----------------------------------------------------------------
-
- ICAP OPTIONS Example 5 - ICAP OPTIONS Response
- ----------------------------------------------------------------
- ICAP/1.0 200 OK
- Date: Mon, 10 Jan 2000 09:55:21 GMT
- Methods: RESPMOD
- Service: FOO Tech Server 1.0
- ISTag: "W3E4R7U9-L2E4-2"
- Encapsulated: null-body=0
- Max-Connections: 1000
- Options-TTL: 7200
- Allow: 204
- Preview: 2048
- Transfer-Complete: asp, bat, exe, com
- Transfer-Ignore: html
- Transfer-Preview: *
-
- ----------------------------------------------------------------
-
-5. Caching
-
- ICAP servers' responses MAY be cached by ICAP clients, just as any
- other surrogate might cache HTTP responses. Similar to HTTP, ICAP
- clients MAY always store a successful response (see sections 4.8.2
- and 4.9.2) as a cache entry, and MAY return it without validation if
- it is fresh. ICAP servers use the caching directives described in
- HTTP/1.1 [4].
-
- In Request Modification mode, the ICAP server MAY include caching
- directives in the ICAP header section of the ICAP response (NOT in
- the encapsulated HTTP request of the ICAP message body). In Response
-
-
-
-Elson & Cerpa Informational [Page 33]
-\f
-RFC 3507 ICAP April 2003
-
-
- Modification mode, the ICAP server MAY add or modify the HTTP caching
- directives located in the encapsulated HTTP response (NOT in the ICAP
- header section). Consequently, the ICAP client SHOULD look for
- caching directives in the ICAP headers in case of REQMOD, and in the
- encapsulated HTTP response in case of RESPMOD.
-
- In cases where an ICAP server returns a modified version of an object
- created by an origin server, such as in Response Modification mode,
- the expiration of the ICAP-modified object MUST NOT be longer than
- that of the origin object. In other words, ICAP servers MUST NOT
- extend the lifetime of origin server objects, but MAY shorten it.
-
- In cases where the ICAP server is the authoritative source of an ICAP
- response, such as in Request Modification mode, the ICAP server is
- not restricted in its expiration policy.
-
- Note that the ISTag response-header may also be used to providing
- caching hints to clients; see Section 4.7.
-
-6. Implementation Notes
-
-6.1 Vectoring Points
-
- The definition of the ICAP protocol itself only describes two
- different adaptation channels: modification (and satisfaction) of
- requests, and modifications of replies. However, an ICAP client
- implementation is likely to actually distinguish among four different
- classes of adaptation:
-
- 1. Adaptation of client requests. This is adaptation done every
- time a request arrives from a client. This is adaptation done
- when a request is "on its way into the cache". Factors such as
- the state of the objects currently cached will determine whether
- or not this request actually gets forwarded to an origin server
- (instead of, say, getting served off the cache's disk). An
- example of this type of adaptation would be special access
- control or authentication services that must be performed on a
- per-client basis.
-
- 2. Adaptation of requests on their way to an origin server.
- Although this type of adaptation is also an adaptation of
- requests similar to (1), it describes requests that are "on their
- way out of the cache"; i.e., if a request actually requires that
- an origin server be contacted. These adaptation requests are not
- necessarily specific to particular clients. An example would be
- addition of "Accept:" headers for special devices; these
- adaptations can potentially apply to many clients.
-
-
-
-
-Elson & Cerpa Informational [Page 34]
-\f
-RFC 3507 ICAP April 2003
-
-
- 3. Adaptations of responses coming from an origin server. This is
- the adaptation of an object "on its way into the cache". In
- other words, this is adaptation that a surrogate might want to
- perform on an object before caching it. The adapted object may
- subsequently served to many clients. An example of this type of
- adaptation is virus checking: a surrogate will want to check an
- incoming origin reply for viruses once, before allowing it into
- the cache -- not every time the cached object is served to a
- client.
-
- Adaptation of responses coming from the surrogate, heading back
- to the client. Although this type of adaptation, like (3), is
- the adaptation of a response, it is client-specific. Client
- reply adaptation is adaptation that is required every time an
- object is served to a client, even if all the replies come from
- the same cached object off of disk. Ad insertion is a common
- form of this kind of adaptation; e.g., if a popular (cached)
- object that rarely changes needs a different ad inserted into it
- every time it is served off disk to a client. Note that the
- relationship between adaptations of type (3) and (4) is analogous
- to the relationship between types (2) and (1).
-
- Although the distinction among these four adaptation points is
- critical for ICAP client implementations, the distinction is not
- significant for the ICAP protocol itself. From the point of view of
- an ICAP server, a request is a request -- the ICAP server doesn't
- care what policy led the ICAP client to generate the request. We
- therefore did not make these four channels explicit in ICAP for
- simplicity.
-
-6.2 Application Level Errors
-
- Section 4 described "on the wire" protocol errors that MUST be
- standardized across implementations to ensure interoperability. In
- this section, we describe errors that are communicated between ICAP
- software and the clients and servers on which they are implemented.
- Although such errors are implementation dependent and do not
- necessarily need to be standardized because they are "within the
- box", they are presented here as advice to future implementors based
- on past implementation experience.
-
-
-
-
-
-
-
-
-
-
-
-Elson & Cerpa Informational [Page 35]
-\f
-RFC 3507 ICAP April 2003
-
-
- Error name Value
- ====================================================
- ICAP_CANT_CONNECT 1000
- ICAP_SERVER_RESPONSE_CLOSE 1001
- ICAP_SERVER_RESPONSE_RESET 1002
- ICAP_SERVER_UNKNOWN_CODE 1003
- ICAP_SERVER_UNEXPECTED_CLOSE_204 1004
- ICAP_SERVER_UNEXPECTED_CLOSE 1005
-
- 1000 ICAP_CANT_CONNECT:
- "Cannot connect to ICAP server".
-
- The ICAP server is not connected on the socket. Maybe the ICAP
- server is dead or it is not connected on the socket.
-
- 1001 ICAP_SERVER_RESPONSE_CLOSE:
- "ICAP Server closed connection while reading response".
-
- The ICAP server TCP-shutdowns the connection before the ICAP
- client can send all the body data.
-
- 1002 ICAP_SERVER_RESPONSE_RESET:
- "ICAP Server reset connection while reading response".
-
- The ICAP server TCP-reset the connection before the ICAP client
- can send all the body data.
-
- 1003 ICAP_SERVER_UNKNOWN_CODE:
- "ICAP Server sent unknown response code".
-
- An unknown ICAP response code (see Section 4.x) was received by
- the ICAP client.
-
- 1004 ICAP_SERVER_UNEXPECTED_CLOSE_204:
- "ICAP Server closed connection on 204 without 'Connection: close'
- header".
-
- An ICAP server MUST send the "Connection: close" header if
- intends to close after the current transaction.
-
- 1005 ICAP_SERVER_UNEXPECTED_CLOSE:
- "ICAP Server closed connection as ICAP client wrote body
- preview".
-
-
-
-
-
-
-
-
-Elson & Cerpa Informational [Page 36]
-\f
-RFC 3507 ICAP April 2003
-
-
-6.3 Use of Chunked Transfer-Encoding
-
- For simplicity, ICAP messages MUST use the "chunked" transfer-
- encoding within the encapsulated body section as defined in HTTP/1.1
- [4]. This requires that ICAP client implementations convert incoming
- objects "on the fly" to chunked from whatever transfer-encoding on
- which they arrive. However, the transformation is simple:
-
- - For objects arriving using "Content-Length" headers, one big chunk
- can be created of the same size as indicated in the Content-Length
- header.
-
- - For objects arriving using a TCP close to signal the end of the
- object, each incoming group of bytes read from the OS can be
- converted into a chunk (by writing the length of the bytes read,
- followed by the bytes themselves)
-
- - For objects arriving using chunked encoding, they can be
- retransmitted as is (without re-chunking).
-
-6.4 Distinct URIs for Distinct Services
-
- ICAP servers SHOULD assign unique URIs to each service they provide,
- even if such services might theoretically be differentiated based on
- their method. In other words, a REQMOD and RESPMOD service should
- never have the same URI, even if they do something that is
- conceptually the same.
-
- This situation in ICAP is similar to that found in HTTP where it
- might, in theory, be possible to perform a GET or a POST to the same
- URI and expect two different results. This kind of overloading of
- URIs only causes confusion and should be avoided.
-
-7. Security Considerations
-
-7.1 Authentication
-
- Authentication in ICAP is very similar to proxy authentication in
- HTTP as specified in RFC 2617. Specifically, the following rules
- apply:
-
- - WWW-Authenticate challenges and responses are for end-to-end
- authentication between a client (user) and an origin server. As
- any proxy, ICAP clients and ICAP servers MUST forward these
- headers without modification.
-
-
-
-
-
-
-Elson & Cerpa Informational [Page 37]
-\f
-RFC 3507 ICAP April 2003
-
-
- - If authentication is required between an ICAP client and ICAP
- server, hop-by-hop Proxy Authentication as described in RFC 2617
- MUST be used.
-
- There are potential applications where a user (as opposed to ICAP
- client) might have rights to access an ICAP service. In this version
- of the protocol, we assume that ICAP clients and ICAP servers are
- under the same administrative domain, and contained in a single trust
- domain. Therefore, in these cases, we assume that it is sufficient
- for users to authenticate themselves to the ICAP client (which is a
- surrogate from the point of view from the user). This type of
- authentication will also be Proxy Authentication as described in RFC
- 2617.
-
- This standard explicitly excludes any method for a user to
- authenticate directly to an ICAP server; the ICAP client MUST be
- involved as described above.
-
-7.2 Encryption
-
- Users of ICAP should note well that ICAP messages are not encrypted
- for transit by default. In the absence of some other form of
- encryption at the link or network layers, eavesdroppers may be able
- to record the unencrypted transactions between ICAP clients and
- servers. As described in Section 4.3.1, the Upgrade header MAY be
- used to negotiate transport-layer security for an ICAP connection
- [5].
-
- Note also that end-to-end encryption between a client and origin
- server is likely to preclude the use of value-added services by
- intermediaries such as surrogates. An ICAP server that is unable to
- decrypt a client's messages will, of course, be unable to perform any
- transformations on it.
-
-7.3 Service Validation
-
- Normal HTTP surrogates, when operating correctly, should not affect
- the end-to-end semantics of messages that pass through them. This
- forms a well-defined criterion to validate that a surrogate is
- working correctly: a message should look the same before the
- surrogate as it does after the surrogate.
-
- In contrast, ICAP is meant to cause changes in the semantics of
- messages on their way from origin servers to users. The criteria for
- a correctly operating surrogate are no longer as easy to define.
- This will make validation of ICAP services significantly more
- difficult. Incorrect adaptations may lead to security
- vulnerabilities that were not present in the unadapted content.
-
-
-
-Elson & Cerpa Informational [Page 38]
-\f
-RFC 3507 ICAP April 2003
-
-
-8. Motivations and Design Alternatives
-
- This section describes some of our design decisions in more detail,
- and describes the ideas and motivations behind them. This section
- does not define protocol requirements, but hopefully sheds light on
- the requirements defined in previous sections. Nothing in this
- section carries the "force of law" or is part of the formal protocol
- specification.
-
- In general, our guiding principle was to make ICAP the simplest
- possible protocol that would do the job, and no simpler. Some
- features were rejected where alternative (non-protocol-based)
- solutions could be found. In addition, we have intentionally left a
- number of issues at the discretion of the implementor, where we
- believe that doing so does not compromise interoperability.
-
-8.1 To Be HTTP, or Not To Be
-
- ICAP was initially designed as an application-layer protocol built to
- run on top of HTTP. This was desirable for a number of reasons.
- HTTP is well-understood in the community and has enjoyed significant
- investments in software infrastructure (clients, servers, parsers,
- etc.). Our initial designs focused on leveraging that existing work;
- we hoped that it would be possible to implement ICAP services simply,
- using CGI scripts run by existing web servers.
-
- However, the devil (as always) proved to be in the details. Certain
- features that we considered important were impossible to implement
- with HTTP. For example, ICAP clients can stop and wait for a "100
- Continue" message in the midst of a message-body; HTTP clients may
- only wait between the header and body. In addition, certain
- transformations of HTTP messages by surrogates are legal (and
- harmless for HTTP), but caused problems with ICAP's "header-in-
- header" encapsulation and other features.
-
- Ultimately, we decided that the tangle of workarounds required to fit
- ICAP into HTTP was more complex and confusing than moving away from
- HTTP and defining a new (but similar) protocol.
-
-8.2 Mandatory Use of Chunking
-
- Chunking is mandatory in ICAP encapsulated bodies for three reasons.
- First, efficiency is important, and the chunked encoding allows both
- the client and server to keep the transport-layer connection open for
- later reuse. Second, ICAP servers (and their developers) should be
- encouraged to produce "incremental" responses where possible, to
- reduce the latency perceived by users. Chunked encoding is the only
- way to support this type of implementation. Finally, by
-
-
-
-Elson & Cerpa Informational [Page 39]
-\f
-RFC 3507 ICAP April 2003
-
-
- standardizing on a single encapsulation mechanism, we avoid the
- complexity that would be required in client and server software to
- support multiple mechanisms. This simplifies ICAP, particularly in
- the "body preview" feature described in Section 4.5.
-
- While chunking of encapsulated bodies is mandatory, encapsulated
- headers are not chunked. There are two reasons for this decision.
- First, in cases where a chunked HTTP message body is being
- encapsulated in an ICAP message, the ICAP client (HTTP server) can
- copy it directly from the HTTP client to the ICAP server without un-
- chunking and then re-chunking it. Second, many header-parser
- implementations have difficulty dealing with headers that come in
- multiple chunks. Earlier drafts of this document mandated that a
- chunk boundary not come within a header. For clarity, chunking of
- encapsulated headers has simply been disallowed.
-
-8.3 Use of the null-body directive in the Encapsulated header
-
- There is a disadvantage to not using the chunked transfer-encoding
- for encapsulated header part of an ICAP message. Specifically,
- parsers do not know in advance how much header data is coming (e.g.,
- for buffer allocation). ICAP does not allow chunking in the header
- part for reasons described in Section 8.2. To compensate, the
- "null-body" directive allows the final header's length to be
- determined, despite it not being chunked.
-
-9. References
-
- [1] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource
- Identifiers (URI): Generic Syntax and Semantics", RFC 2396,
- August 1998.
-
- [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement
- Levels", BCP 14, RFC 2119, March 1997.
-
- [3] Resnick, P., "Internet Message Format", RFC 2822, April 2001.
-
- [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] Khare, R. and S. Lawrence, "Upgrading to TLS Within HTTP/1.1",
- RFC 2817, May 2000.
-
-
-
-
-
-
-
-
-Elson & Cerpa Informational [Page 40]
-\f
-RFC 3507 ICAP April 2003
-
-
-10. Contributors
-
- ICAP is based on an original idea by John Martin and Peter Danzig.
- Many individuals and organizations have contributed to the
- development of ICAP, including the following contributors (past and
- present):
-
- Lee Duggs
- Network Appliance, Inc.
- 495 East Java Dr.
- Sunnyvale, CA 94089 USA
-
- Phone: (408) 822-6000
- EMail: lee.duggs@netapp.com
-
- Paul Eastham
- Network Appliance, Inc.
- 495 East Java Dr.
- Sunnyvale, CA 94089 USA
-
- Phone: (408) 822-6000
- EMail: eastham@netapp.com
-
- Debbie Futcher
- Network Appliance, Inc.
- 495 East Java Dr.
- Sunnyvale, CA 94089 USA
-
- Phone: (408) 822-6000
- EMail: deborah.futcher@netapp.com
-
- Don Gillies
- Network Appliance, Inc.
- 495 East Java Dr.
- Sunnyvale, CA 94089 USA
-
- Phone: (408) 822-6000
- EMail: gillies@netapp.com
-
- Steven La
- Network Appliance, Inc.
- 495 East Java Dr.
- Sunnyvale, CA 94089 USA
-
- Phone: (408) 822-6000
- EMail: steven.la@netapp.com
-
-
-
-
-
-Elson & Cerpa Informational [Page 41]
-\f
-RFC 3507 ICAP April 2003
-
-
- John Martin
- Network Appliance, Inc.
- 495 East Java Dr.
- Sunnyvale, CA 94089 USA
-
- Phone: (408) 822-6000
- EMail: jmartin@netapp.com
-
- Jeff Merrick
- Network Appliance, Inc.
- 495 East Java Dr.
- Sunnyvale, CA 94089 USA
-
- Phone: (408) 822-6000
- EMail: jeffrey.merrick@netapp.com
-
- John Schuster
- Network Appliance, Inc.
- 495 East Java Dr.
- Sunnyvale, CA 94089 USA
-
- Phone: (408) 822-6000
- EMail: john.schuster@netapp.com
-
- Edward Sharp
- Network Appliance, Inc.
- 495 East Java Dr.
- Sunnyvale, CA 94089 USA
-
- Phone: (408) 822-6000
- EMail: edward.sharp@netapp.com
-
- Peter Danzig
- Akamai Technologies
- 1400 Fashion Island Blvd
- San Mateo, CA 94404 USA
-
- Phone: (650) 372-5757
- EMail: danzig@akamai.com
-
- Mark Nottingham
- Akamai Technologies
- 1400 Fashion Island Blvd
- San Mateo, CA 94404 USA
-
- Phone: (650) 372-5757
- EMail: mnot@akamai.com
-
-
-
-
-Elson & Cerpa Informational [Page 42]
-\f
-RFC 3507 ICAP April 2003
-
-
- Nitin Sharma
- Akamai Technologies
- 1400 Fashion Island Blvd
- San Mateo, CA 94404 USA
-
- Phone: (650) 372-5757
- EMail: nitin@akamai.com
-
- Hilarie Orman
- Novell, Inc.
- 122 East 1700 South
- Provo, UT 84606 USA
-
- Phone: (801) 861-7021
- EMail: horman@novell.com
-
- Craig Blitz
- Novell, Inc.
- 122 East 1700 South
- Provo, UT 84606 USA
-
- Phone: (801) 861-7021
- EMail: cblitz@novell.com
-
- Gary Tomlinson
- Novell, Inc.
- 122 East 1700 South
- Provo, UT 84606 USA
-
- Phone: (801) 861-7021
- EMail: garyt@novell.com
-
- Andre Beck
- Bell Laboratories / Lucent Technologies
- 101 Crawfords Corner Road
- Holmdel, New Jersey 07733-3030
-
- Phone: (732) 332-5983
- EMail: abeck@bell-labs.com
-
- Markus Hofmann
- Bell Laboratories / Lucent Technologies
- 101 Crawfords Corner Road
- Holmdel, New Jersey 07733-3030
-
- Phone: (732) 332-5983
- EMail: hofmann@bell-labs.com
-
-
-
-
-Elson & Cerpa Informational [Page 43]
-\f
-RFC 3507 ICAP April 2003
-
-
- David Bryant
- CacheFlow, Inc.
- 650 Almanor Avenue
- Sunnyvale, California 94086
-
- Phone: (888) 462-3568
- EMail: david.bryant@cacheflow.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Elson & Cerpa Informational [Page 44]
-\f
-RFC 3507 ICAP April 2003
-
-
-Appendix A BNF Grammar for ICAP Messages
-
- This grammar is specified in terms of the augmented Backus-Naur Form
- (BNF) similar to that used by the HTTP/1.1 specification (See Section
- 2.1 of [4]). Implementors will need to be familiar with the notation
- in order to understand this specification.
-
- Many header values (where noted) have exactly the same grammar and
- semantics as in HTTP/1.1. We do not reproduce those grammars here.
-
- ICAP-Version = "ICAP/1.0"
-
- ICAP-Message = Request | Response
-
- Request = Request-Line
- *(Request-Header CRLF)
- CRLF
- [ Request-Body ]
-
- Request-Line = Method SP ICAP_URI SP ICAP-Version CRLF
-
- Method = "REQMOD" ; Section 4.8
- | "RESPMOD" ; Section 4.9
- | "OPTIONS" ; Section 4.10
- | Extension-Method ; Section 4.3.2
-
- Extension-Method = token
-
- ICAP_URI = Scheme ":" Net_Path [ "?" Query ] ; Section 4.2
-
- Scheme = "icap"
-
- Net_Path = "//" Authority [ Abs_Path ]
-
- Authority = [ userinfo "@" ] host [ ":" port ]
-
-
- Request-Header = Request-Fields ":" [ Generic-Field-Value ]
-
- Request-Fields = Request-Field-Name
- | Common-Field-Name
-
- ; Header fields specific to requests
- Request-Field-Name = "Authorization" ; Section 4.3.2
- | "Allow" ; Section 4.3.2
- | "From" ; Section 4.3.2
- | "Host" ; Section 4.3.2
- | "Referer" ; Section 4.3.2
-
-
-
-Elson & Cerpa Informational [Page 45]
-\f
-RFC 3507 ICAP April 2003
-
-
- | "User-Agent" ; Section 4.3.2
- | "Preview" ; Section 4.5
-
- ; Header fields common to both requests and responses
- Common-Field-Name = "Cache-Control" ; Section 4.3.1
- | "Connection" ; Section 4.3.1
- | "Date" ; Section 4.3.1
- | "Expires" ; Section 4.3.1
- | "Pragma" ; Section 4.3.1
- | "Trailer" ; Section 4.3.1
- | "Upgrade" ; Section 4.3.1
- | "Encapsulated" ; Section 4.4
- | Extension-Field-Name ; Section 4.3
-
- Extension-Field-Name = "X-" token
-
- Generic-Field-Value = *( Generic-Field-Content | LWS )
- Generic-Field-Content = <the OCTETs making up the field-value
- and consisting of either *TEXT or
- combinations of token, separators,
- and quoted-string>
-
- Request-Body = *OCTET ; See Sections 4.4 and 4.5 for semantics
-
- Response = Status-Line
- *(Response-Header CRLF)
- CRLF
- [ Response-Body ]
-
- Status-Line = ICAP-Version SP Status-Code SP Reason-Phrase CRLF
-
- Status-Code = "100" ; Section 4.5
- | "101" ; Section 10.1.2 of [4]
- | "200" ; Section 10.2.1 of [4]
- | "201" ; Section 10.2.2 of [4]
- | "202" ; Section 10.2.3 of [4]
- | "203" ; Section 10.2.4 of [4]
- | "204" ; Section 4.6
- | "205" ; Section 10.2.6 of [4]
- | "206" ; Section 10.2.7 of [4]
- | "300" ; Section 10.3.1 of [4]
- | "301" ; Section 10.3.2 of [4]
- | "302" ; Section 10.3.3 of [4]
- | "303" ; Section 10.3.4 of [4]
- | "304" ; Section 10.3.5 of [4]
- | "305" ; Section 10.3.6 of [4]
- | "306" ; Section 10.3.7 of [4]
- | "307" ; Section 10.3.8 of [4]
-
-
-
-Elson & Cerpa Informational [Page 46]
-\f
-RFC 3507 ICAP April 2003
-
-
- | "400" ; Section 4.3.3
- | "401" ; Section 10.4.2 of [4]
- | "402" ; Section 10.4.3 of [4]
- | "403" ; Section 10.4.4 of [4]
- | "404" ; Section 4.3.3
- | "405" ; Section 4.3.3
- | "406" ; Section 10.4.7 of [4]
- | "407" ; Section 10.4.8 of [4]
- | "408" ; Section 4.3.3
- | "409" ; Section 10.4.10 of [4]
- | "410" ; Section 10.4.11 of [4]
- | "411" ; Section 10.4.12 of [4]
- | "412" ; Section 10.4.13 of [4]
- | "413" ; Section 10.4.14 of [4]
- | "414" ; Section 10.4.15 of [4]
- | "415" ; Section 10.4.16 of [4]
- | "416" ; Section 10.4.17 of [4]
- | "417" ; Section 10.4.18 of [4]
- | "500" ; Section 4.3.3
- | "501" ; Section 4.3.3
- | "502" ; Section 4.3.3
- | "503" ; Section 4.3.3
- | "504" ; Section 10.5.5 of [4]
- | "505" ; Section 4.3.3
- | Extension-Code
-
- Extension-Code = 3DIGIT
-
- Reason-Phrase = *<TEXT, excluding CR, LF>
-
- Response-Header = Response-Fields ":" [ Generic-Field-Value ]
-
- Response-Fields = Response-Field-Name
- | Common-Field-Name
-
- Response-Field-Name = "Server" ; Section 4.3.3
- | "ISTag" ; Section 4.7
-
- Response-Body = *OCTET ; See Sections 4.4 and 4.5 for semantics
-
-
-
-
-
-
-
-
-
-
-
-
-Elson & Cerpa Informational [Page 47]
-\f
-RFC 3507 ICAP April 2003
-
-
-Authors' Addresses
-
- Jeremy Elson
- University of California Los Angeles
- Department of Computer Science
- 3440 Boelter Hall
- Los Angeles CA 90095
-
- Phone: (310) 206-3925
- EMail: jelson@cs.ucla.edu
-
-
- Alberto Cerpa
- University of California Los Angeles
- Department of Computer Science
- 3440 Boelter Hall
- Los Angeles CA 90095
-
- Phone: (310) 206-3925
- EMail: cerpa@cs.ucla.edu
-
-
- ICAP discussion currently takes place at
- icap-discussions@yahoogroups.com.
- For more information, see
- http://groups.yahoo.com/group/icap-discussions/.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Elson & Cerpa Informational [Page 48]
-\f
-RFC 3507 ICAP 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Elson & Cerpa Informational [Page 49]
-\f
+++ /dev/null
-
-
-
-
-
-Network Working Group R. Hinden
-Request for Comments: 3513 Nokia
-Obsoletes: 2373 S. Deering
-Category: Standards Track Cisco Systems
- April 2003
-
-
- Internet Protocol Version 6 (IPv6) Addressing Architecture
-
-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 specification defines the addressing architecture of the IP
- Version 6 (IPv6) protocol. The document includes the IPv6 addressing
- model, text representations of IPv6 addresses, definition of IPv6
- unicast addresses, anycast addresses, and multicast addresses, and an
- IPv6 node's required addresses.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hinden & Deering Standards Track [Page 1]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
-Table of Contents
-
- 1. Introduction.................................................3
- 2. IPv6 Addressing..............................................3
- 2.1 Addressing Model.........................................4
- 2.2 Text Representation of Addresses.........................4
- 2.3 Text Representation of Address Prefixes..................5
- 2.4 Address Type Identification..............................6
- 2.5 Unicast Addresses........................................7
- 2.5.1 Interface Identifiers..............................8
- 2.5.2 The Unspecified Address............................9
- 2.5.3 The Loopback Address...............................9
- 2.5.4 Global Unicast Addresses..........................10
- 2.5.5 IPv6 Addresses with Embedded IPv4 Addresses.......10
- 2.5.6 Local-use IPv6 Unicast Addresses..................11
- 2.6 Anycast Addresses.......................................12
- 2.6.1 Required Anycast Address..........................13
- 2.7 Multicast Addresses.....................................13
- 2.7.1 Pre-Defined Multicast Addresses...................15
- 2.8 A Node's Required Addresses.............................17
- 3. Security Considerations.....................................17
- 4. IANA Considerations.........................................18
- 5. References..................................................19
- 5.1 Normative References....................................19
- 5.2 Informative References..................................19
- APPENDIX A: Creating Modified EUI-64 format Interface IDs......21
- APPENDIX B: Changes from RFC-2373..............................24
- Authors' Addresses.............................................25
- Full Copyright Statement.......................................26
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hinden & Deering Standards Track [Page 2]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
-1. Introduction
-
- This specification defines the addressing architecture of the IP
- Version 6 (IPv6) protocol. It includes the basic formats for the
- various types of IPv6 addresses (unicast, anycast, and multicast).
-
- The authors would like to acknowledge the contributions of Paul
- Francis, Scott Bradner, Jim Bound, Brian Carpenter, Matt Crawford,
- Deborah Estrin, Roger Fajman, Bob Fink, Peter Ford, Bob Gilligan,
- Dimitry Haskin, Tom Harsch, Christian Huitema, Tony Li, Greg
- Minshall, Thomas Narten, Erik Nordmark, Yakov Rekhter, Bill Simpson,
- Sue Thomson, Markku Savela, and Larry Masinter.
-
-2. IPv6 Addressing
-
- IPv6 addresses are 128-bit identifiers for interfaces and sets of
- interfaces (where "interface" is as defined in section 2 of [IPV6]).
- There are three types of addresses:
-
- Unicast: An identifier for a single interface. A packet sent to a
- unicast address is delivered to the interface identified
- by that address.
-
- Anycast: An identifier for a set of interfaces (typically belonging
- to different nodes). A packet sent to an anycast address
- is delivered to one of the interfaces identified by that
- address (the "nearest" one, according to the routing
- protocols' measure of distance).
-
- Multicast: An identifier for a set of interfaces (typically belonging
- to different nodes). A packet sent to a multicast address
- is delivered to all interfaces identified by that address.
-
- There are no broadcast addresses in IPv6, their function being
- superseded by multicast addresses.
-
- In this document, fields in addresses are given a specific name, for
- example "subnet". When this name is used with the term "ID" for
- identifier after the name (e.g., "subnet ID"), it refers to the
- contents of the named field. When it is used with the term "prefix"
- (e.g., "subnet prefix") it refers to all of the address from the left
- up to and including this field.
-
- In IPv6, all zeros and all ones are legal values for any field,
- unless specifically excluded. Specifically, prefixes may contain, or
- end with, zero-valued fields.
-
-
-
-
-
-Hinden & Deering Standards Track [Page 3]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
-2.1 Addressing Model
-
- IPv6 addresses of all types are assigned to interfaces, not nodes.
- An IPv6 unicast address refers to a single interface. Since each
- interface belongs to a single node, any of that node's interfaces'
- unicast addresses may be used as an identifier for the node.
-
- All interfaces are required to have at least one link-local unicast
- address (see section 2.8 for additional required addresses). A
- single interface may also have multiple IPv6 addresses of any type
- (unicast, anycast, and multicast) or scope. Unicast addresses with
- scope greater than link-scope are not needed for interfaces that are
- not used as the origin or destination of any IPv6 packets to or from
- non-neighbors. This is sometimes convenient for point-to-point
- interfaces. There is one exception to this addressing model:
-
- A unicast address or a set of unicast addresses may be assigned to
- multiple physical interfaces if the implementation treats the
- multiple physical interfaces as one interface when presenting it
- to the internet layer. This is useful for load-sharing over
- multiple physical interfaces.
-
- Currently IPv6 continues the IPv4 model that a subnet prefix is
- associated with one link. Multiple subnet prefixes may be assigned
- to the same link.
-
-2.2 Text Representation of Addresses
-
- There are three conventional forms for representing IPv6 addresses as
- text strings:
-
- 1. The preferred form is x:x:x:x:x:x:x:x, where the 'x's are the
- hexadecimal values of the eight 16-bit pieces of the address.
-
- Examples:
-
- FEDC:BA98:7654:3210:FEDC:BA98:7654:3210
-
- 1080:0:0:0:8:800:200C:417A
-
- Note that it is not necessary to write the leading zeros in an
- individual field, but there must be at least one numeral in every
- field (except for the case described in 2.).
-
- 2. Due to some methods of allocating certain styles of IPv6
- addresses, it will be common for addresses to contain long strings
- of zero bits. In order to make writing addresses containing zero
- bits easier a special syntax is available to compress the zeros.
-
-
-
-Hinden & Deering Standards Track [Page 4]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
- The use of "::" indicates one or more groups of 16 bits of zeros.
- The "::" can only appear once in an address. The "::" can also be
- used to compress leading or trailing zeros in an address.
-
- For example, the following addresses:
-
- 1080:0:0:0:8:800:200C:417A a unicast address
- FF01:0:0:0:0:0:0:101 a multicast address
- 0:0:0:0:0:0:0:1 the loopback address
- 0:0:0:0:0:0:0:0 the unspecified addresses
-
- may be represented as:
-
- 1080::8:800:200C:417A a unicast address
- FF01::101 a multicast address
- ::1 the loopback address
- :: the unspecified addresses
-
- 3. An alternative form that is sometimes more convenient when dealing
- with a mixed environment of IPv4 and IPv6 nodes is
- x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values of
- the six high-order 16-bit pieces of the address, and the 'd's are
- the decimal values of the four low-order 8-bit pieces of the
- address (standard IPv4 representation). Examples:
-
- 0:0:0:0:0:0:13.1.68.3
-
- 0:0:0:0:0:FFFF:129.144.52.38
-
- or in compressed form:
-
- ::13.1.68.3
-
- ::FFFF:129.144.52.38
-
-2.3 Text Representation of Address Prefixes
-
- The text representation of IPv6 address prefixes is similar to the
- way IPv4 addresses prefixes are written in CIDR notation [CIDR]. An
- IPv6 address prefix is represented by the notation:
-
- ipv6-address/prefix-length
-
- where
-
- ipv6-address is an IPv6 address in any of the notations listed
- in section 2.2.
-
-
-
-
-Hinden & Deering Standards Track [Page 5]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
- prefix-length is a decimal value specifying how many of the
- leftmost contiguous bits of the address comprise
- the prefix.
-
- For example, the following are legal representations of the 60-bit
- prefix 12AB00000000CD3 (hexadecimal):
-
- 12AB:0000:0000:CD30:0000:0000:0000:0000/60
- 12AB::CD30:0:0:0:0/60
- 12AB:0:0:CD30::/60
-
- The following are NOT legal representations of the above prefix:
-
- 12AB:0:0:CD3/60 may drop leading zeros, but not trailing zeros,
- within any 16-bit chunk of the address
-
- 12AB::CD30/60 address to left of "/" expands to
- 12AB:0000:0000:0000:0000:000:0000:CD30
-
- 12AB::CD3/60 address to left of "/" expands to
- 12AB:0000:0000:0000:0000:000:0000:0CD3
-
- When writing both a node address and a prefix of that node address
- (e.g., the node's subnet prefix), the two can combined as follows:
-
- the node address 12AB:0:0:CD30:123:4567:89AB:CDEF
- and its subnet number 12AB:0:0:CD30::/60
-
- can be abbreviated as 12AB:0:0:CD30:123:4567:89AB:CDEF/60
-
-2.4 Address Type Identification
-
- The type of an IPv6 address is identified by the high-order bits of
- the address, as follows:
-
- Address type Binary prefix IPv6 notation Section
- ------------ ------------- ------------- -------
- Unspecified 00...0 (128 bits) ::/128 2.5.2
- Loopback 00...1 (128 bits) ::1/128 2.5.3
- Multicast 11111111 FF00::/8 2.7
- Link-local unicast 1111111010 FE80::/10 2.5.6
- Site-local unicast 1111111011 FEC0::/10 2.5.6
- Global unicast (everything else)
-
- Anycast addresses are taken from the unicast address spaces (of any
- scope) and are not syntactically distinguishable from unicast
- addresses.
-
-
-
-
-Hinden & Deering Standards Track [Page 6]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
- The general format of global unicast addresses is described in
- section 2.5.4. Some special-purpose subtypes of global unicast
- addresses which contain embedded IPv4 addresses (for the purposes of
- IPv4-IPv6 interoperation) are described in section 2.5.5.
-
- Future specifications may redefine one or more sub-ranges of the
- global unicast space for other purposes, but unless and until that
- happens, implementations must treat all addresses that do not start
- with any of the above-listed prefixes as global unicast addresses.
-
-2.5 Unicast Addresses
-
- IPv6 unicast addresses are aggregable with prefixes of arbitrary
- bit-length similar to IPv4 addresses under Classless Interdomain
- Routing.
-
- There are several types of unicast addresses in IPv6, in particular
- global unicast, site-local unicast, and link-local unicast. There
- are also some special-purpose subtypes of global unicast, such as
- IPv6 addresses with embedded IPv4 addresses or encoded NSAP
- addresses. Additional address types or subtypes can be defined in
- the future.
-
- IPv6 nodes may have considerable or little knowledge of the internal
- structure of the IPv6 address, depending on the role the node plays
- (for instance, host versus router). At a minimum, a node may
- consider that unicast addresses (including its own) have no internal
- structure:
-
- | 128 bits |
- +-----------------------------------------------------------------+
- | node address |
- +-----------------------------------------------------------------+
-
- A slightly sophisticated host (but still rather simple) may
- additionally be aware of subnet prefix(es) for the link(s) it is
- attached to, where different addresses may have different values for
- n:
-
- | n bits | 128-n bits |
- +------------------------------------------------+----------------+
- | subnet prefix | interface ID |
- +------------------------------------------------+----------------+
-
- Though a very simple router may have no knowledge of the internal
- structure of IPv6 unicast addresses, routers will more generally have
- knowledge of one or more of the hierarchical boundaries for the
- operation of routing protocols. The known boundaries will differ
-
-
-
-Hinden & Deering Standards Track [Page 7]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
- from router to router, depending on what positions the router holds
- in the routing hierarchy.
-
-2.5.1 Interface Identifiers
-
- Interface identifiers in IPv6 unicast addresses are used to identify
- interfaces on a link. They are required to be unique within a subnet
- prefix. It is recommended that the same interface identifier not be
- assigned to different nodes on a link. They may also be unique over
- a broader scope. In some cases an interface's identifier will be
- derived directly from that interface's link-layer address. The same
- interface identifier may be used on multiple interfaces on a single
- node, as long as they are attached to different subnets.
-
- Note that the uniqueness of interface identifiers is independent of
- the uniqueness of IPv6 addresses. For example, a global unicast
- address may be created with a non-global scope interface identifier
- and a site-local address may be created with a global scope interface
- identifier.
-
- For all unicast addresses, except those that start with binary value
- 000, Interface IDs are required to be 64 bits long and to be
- constructed in Modified EUI-64 format.
-
- Modified EUI-64 format based Interface identifiers may have global
- scope when derived from a global token (e.g., IEEE 802 48-bit MAC or
- IEEE EUI-64 identifiers [EUI64]) or may have local scope where a
- global token is not available (e.g., serial links, tunnel end-points,
- etc.) or where global tokens are undesirable (e.g., temporary tokens
- for privacy [PRIV]).
-
- Modified EUI-64 format interface identifiers are formed by inverting
- the "u" bit (universal/local bit in IEEE EUI-64 terminology) when
- forming the interface identifier from IEEE EUI-64 identifiers. In
- the resulting Modified EUI-64 format the "u" bit is set to one (1) to
- indicate global scope, and it is set to zero (0) to indicate local
- scope. The first three octets in binary of an IEEE EUI-64 identifier
- are as follows:
-
- 0 0 0 1 1 2
- |0 7 8 5 6 3|
- +----+----+----+----+----+----+
- |cccc|ccug|cccc|cccc|cccc|cccc|
- +----+----+----+----+----+----+
-
- written in Internet standard bit-order , where "u" is the
- universal/local bit, "g" is the individual/group bit, and "c" are the
- bits of the company_id. Appendix A: "Creating Modified EUI-64 format
-
-
-
-Hinden & Deering Standards Track [Page 8]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
- Interface Identifiers" provides examples on the creation of Modified
- EUI-64 format based interface identifiers.
-
- The motivation for inverting the "u" bit when forming an interface
- identifier is to make it easy for system administrators to hand
- configure non-global identifiers when hardware tokens are not
- available. This is expected to be case for serial links, tunnel end-
- points, etc. The alternative would have been for these to be of the
- form 0200:0:0:1, 0200:0:0:2, etc., instead of the much simpler 1, 2,
- etc.
-
- The use of the universal/local bit in the Modified EUI-64 format
- identifier is to allow development of future technology that can take
- advantage of interface identifiers with global scope.
-
- The details of forming interface identifiers are defined in the
- appropriate "IPv6 over <link>" specification such as "IPv6 over
- Ethernet" [ETHER], "IPv6 over FDDI" [FDDI], etc.
-
-2.5.2 The Unspecified Address
-
- The address 0:0:0:0:0:0:0:0 is called the unspecified address. It
- must never be assigned to any node. It indicates the absence of an
- address. One example of its use is in the Source Address field of
- any IPv6 packets sent by an initializing host before it has learned
- its own address.
-
- The unspecified address must not be used as the destination address
- of IPv6 packets or in IPv6 Routing Headers. An IPv6 packet with a
- source address of unspecified must never be forwarded by an IPv6
- router.
-
-2.5.3 The Loopback Address
-
- The unicast address 0:0:0:0:0:0:0:1 is called the loopback address.
- It may be used by a node to send an IPv6 packet to itself. It may
- never be assigned to any physical interface. It is treated as
- having link-local scope, and may be thought of as the link-local
- unicast address of a virtual interface (typically called "the
- loopback interface") to an imaginary link that goes nowhere.
-
- The loopback address must not be used as the source address in IPv6
- packets that are sent outside of a single node. An IPv6 packet with
- a destination address of loopback must never be sent outside of a
- single node and must never be forwarded by an IPv6 router. A packet
- received on an interface with destination address of loopback must be
- dropped.
-
-
-
-
-Hinden & Deering Standards Track [Page 9]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
-2.5.4 Global Unicast Addresses
-
- The general format for IPv6 global unicast addresses is as follows:
-
- | n bits | m bits | 128-n-m bits |
- +------------------------+-----------+----------------------------+
- | global routing prefix | subnet ID | interface ID |
- +------------------------+-----------+----------------------------+
-
- where the global routing prefix is a (typically hierarchically-
- structured) value assigned to a site (a cluster of subnets/links),
- the subnet ID is an identifier of a link within the site, and the
- interface ID is as defined in section 2.5.1.
-
- All global unicast addresses other than those that start with binary
- 000 have a 64-bit interface ID field (i.e., n + m = 64), formatted as
- described in section 2.5.1. Global unicast addresses that start with
- binary 000 have no such constraint on the size or structure of the
- interface ID field.
-
- Examples of global unicast addresses that start with binary 000 are
- the IPv6 address with embedded IPv4 addresses described in section
- 2.5.5 and the IPv6 address containing encoded NSAP addresses
- specified in [NSAP]. An example of global addresses starting with a
- binary value other than 000 (and therefore having a 64-bit interface
- ID field) can be found in [AGGR].
-
-2.5.5 IPv6 Addresses with Embedded IPv4 Addresses
-
- The IPv6 transition mechanisms [TRAN] include a technique for hosts
- and routers to dynamically tunnel IPv6 packets over IPv4 routing
- infrastructure. IPv6 nodes that use this technique are assigned
- special IPv6 unicast addresses that carry a global IPv4 address in
- the low-order 32 bits. This type of address is termed an "IPv4-
- compatible IPv6 address" and has the format:
-
- | 80 bits | 16 | 32 bits |
- +--------------------------------------+--------------------------+
- |0000..............................0000|0000| IPv4 address |
- +--------------------------------------+----+---------------------+
-
- Note: The IPv4 address used in the "IPv4-compatible IPv6 address"
- must be a globally-unique IPv4 unicast address.
-
- A second type of IPv6 address which holds an embedded IPv4 address is
- also defined. This address type is used to represent the addresses
- of IPv4 nodes as IPv6 addresses. This type of address is termed an
- "IPv4-mapped IPv6 address" and has the format:
-
-
-
-Hinden & Deering Standards Track [Page 10]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
- | 80 bits | 16 | 32 bits |
- +--------------------------------------+--------------------------+
- |0000..............................0000|FFFF| IPv4 address |
- +--------------------------------------+----+---------------------+
-
-2.5.6 Local-Use IPv6 Unicast Addresses
-
- There are two types of local-use unicast addresses defined. These
- are Link-Local and Site-Local. The Link-Local is for use on a single
- link and the Site-Local is for use in a single site. Link-Local
- addresses have the following format:
-
- | 10 |
- | bits | 54 bits | 64 bits |
- +----------+-------------------------+----------------------------+
- |1111111010| 0 | interface ID |
- +----------+-------------------------+----------------------------+
-
- Link-Local addresses are designed to be used for addressing on a
- single link for purposes such as automatic address configuration,
- neighbor discovery, or when no routers are present.
-
- Routers must not forward any packets with link-local source or
- destination addresses to other links.
-
- Site-Local addresses have the following format:
-
- | 10 |
- | bits | 54 bits | 64 bits |
- +----------+-------------------------+----------------------------+
- |1111111011| subnet ID | interface ID |
- +----------+-------------------------+----------------------------+
-
- Site-local addresses are designed to be used for addressing inside of
- a site without the need for a global prefix. Although a subnet ID
- may be up to 54-bits long, it is expected that globally-connected
- sites will use the same subnet IDs for site-local and global
- prefixes.
-
- Routers must not forward any packets with site-local source or
- destination addresses outside of the site.
-
-
-
-
-
-
-
-
-
-
-Hinden & Deering Standards Track [Page 11]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
-2.6 Anycast Addresses
-
- An IPv6 anycast address is an address that is assigned to more than
- one interface (typically belonging to different nodes), with the
- property that a packet sent to an anycast address is routed to the
- "nearest" interface having that address, according to the routing
- protocols' measure of distance.
-
- Anycast addresses are allocated from the unicast address space, using
- any of the defined unicast address formats. Thus, anycast addresses
- are syntactically indistinguishable from unicast addresses. When a
- unicast address is assigned to more than one interface, thus turning
- it into an anycast address, the nodes to which the address is
- assigned must be explicitly configured to know that it is an anycast
- address.
-
- For any assigned anycast address, there is a longest prefix P of that
- address that identifies the topological region in which all
- interfaces belonging to that anycast address reside. Within the
- region identified by P, the anycast address must be maintained as a
- separate entry in the routing system (commonly referred to as a "host
- route"); outside the region identified by P, the anycast address may
- be aggregated into the routing entry for prefix P.
-
- Note that in the worst case, the prefix P of an anycast set may be
- the null prefix, i.e., the members of the set may have no topological
- locality. In that case, the anycast address must be maintained as a
- separate routing entry throughout the entire internet, which presents
- a severe scaling limit on how many such "global" anycast sets may be
- supported. Therefore, it is expected that support for global anycast
- sets may be unavailable or very restricted.
-
- One expected use of anycast addresses is to identify the set of
- routers belonging to an organization providing internet service.
- Such addresses could be used as intermediate addresses in an IPv6
- Routing header, to cause a packet to be delivered via a particular
- service provider or sequence of service providers.
-
- Some other possible uses are to identify the set of routers attached
- to a particular subnet, or the set of routers providing entry into a
- particular routing domain.
-
- There is little experience with widespread, arbitrary use of internet
- anycast addresses, and some known complications and hazards when
- using them in their full generality [ANYCST]. Until more experience
- has been gained and solutions are specified, the following
- restrictions are imposed on IPv6 anycast addresses:
-
-
-
-
-Hinden & Deering Standards Track [Page 12]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
- o An anycast address must not be used as the source address of an
- IPv6 packet.
-
- o An anycast address must not be assigned to an IPv6 host, that is,
- it may be assigned to an IPv6 router only.
-
-2.6.1 Required Anycast Address
-
- The Subnet-Router anycast address is predefined. Its format is as
- follows:
-
- | n bits | 128-n bits |
- +------------------------------------------------+----------------+
- | subnet prefix | 00000000000000 |
- +------------------------------------------------+----------------+
-
- The "subnet prefix" in an anycast address is the prefix which
- identifies a specific link. This anycast address is syntactically
- the same as a unicast address for an interface on the link with the
- interface identifier set to zero.
-
- Packets sent to the Subnet-Router anycast address will be delivered
- to one router on the subnet. All routers are required to support the
- Subnet-Router anycast addresses for the subnets to which they have
- interfaces.
-
- The subnet-router anycast address is intended to be used for
- applications where a node needs to communicate with any one of the
- set of routers.
-
-2.7 Multicast Addresses
-
- An IPv6 multicast address is an identifier for a group of interfaces
- (typically on different nodes). An interface may belong to any
- number of multicast groups. Multicast addresses have the following
- format:
-
- | 8 | 4 | 4 | 112 bits |
- +------ -+----+----+---------------------------------------------+
- |11111111|flgs|scop| group ID |
- +--------+----+----+---------------------------------------------+
-
- binary 11111111 at the start of the address identifies the
- address as being a multicast address.
-
- +-+-+-+-+
- flgs is a set of 4 flags: |0|0|0|T|
- +-+-+-+-+
-
-
-
-Hinden & Deering Standards Track [Page 13]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
- The high-order 3 flags are reserved, and must be initialized
- to 0.
-
- T = 0 indicates a permanently-assigned ("well-known")
- multicast address, assigned by the Internet Assigned Number
- Authority (IANA).
-
- T = 1 indicates a non-permanently-assigned ("transient")
- multicast address.
-
- scop is a 4-bit multicast scope value used to limit the scope
- of the multicast group. The values are:
-
- 0 reserved
- 1 interface-local scope
- 2 link-local scope
- 3 reserved
- 4 admin-local scope
- 5 site-local scope
- 6 (unassigned)
- 7 (unassigned)
- 8 organization-local scope
- 9 (unassigned)
- A (unassigned)
- B (unassigned)
- C (unassigned)
- D (unassigned)
- E global scope
- F reserved
-
- interface-local scope spans only a single interface on a
- node, and is useful only for loopback transmission of
- multicast.
-
- link-local and site-local multicast scopes span the same
- topological regions as the corresponding unicast scopes.
-
- admin-local scope is the smallest scope that must be
- administratively configured, i.e., not automatically derived
- from physical connectivity or other, non- multicast-related
- configuration.
-
- organization-local scope is intended to span multiple sites
- belonging to a single organization.
-
- scopes labeled "(unassigned)" are available for
- administrators to define additional multicast regions.
-
-
-
-
-Hinden & Deering Standards Track [Page 14]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
- group ID identifies the multicast group, either permanent or
- transient, within the given scope.
-
- The "meaning" of a permanently-assigned multicast address is
- independent of the scope value. For example, if the "NTP servers
- group" is assigned a permanent multicast address with a group ID of
- 101 (hex), then:
-
- FF01:0:0:0:0:0:0:101 means all NTP servers on the same interface
- (i.e., the same node) as the sender.
-
- FF02:0:0:0:0:0:0:101 means all NTP servers on the same link as the
- sender.
-
- FF05:0:0:0:0:0:0:101 means all NTP servers in the same site as the
- sender.
-
- FF0E:0:0:0:0:0:0:101 means all NTP servers in the internet.
-
- Non-permanently-assigned multicast addresses are meaningful only
- within a given scope. For example, a group identified by the non-
- permanent, site-local multicast address FF15:0:0:0:0:0:0:101 at one
- site bears no relationship to a group using the same address at a
- different site, nor to a non-permanent group using the same group ID
- with different scope, nor to a permanent group with the same group
- ID.
-
- Multicast addresses must not be used as source addresses in IPv6
- packets or appear in any Routing header.
-
- Routers must not forward any multicast packets beyond of the scope
- indicated by the scop field in the destination multicast address.
-
- Nodes must not originate a packet to a multicast address whose scop
- field contains the reserved value 0; if such a packet is received, it
- must be silently dropped. Nodes should not originate a packet to a
- multicast address whose scop field contains the reserved value F; if
- such a packet is sent or received, it must be treated the same as
- packets destined to a global (scop E) multicast address.
-
-2.7.1 Pre-Defined Multicast Addresses
-
- The following well-known multicast addresses are pre-defined. The
- group ID's defined in this section are defined for explicit scope
- values.
-
- Use of these group IDs for any other scope values, with the T flag
- equal to 0, is not allowed.
-
-
-
-Hinden & Deering Standards Track [Page 15]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
- Reserved Multicast Addresses: FF00:0:0:0:0:0:0:0
- FF01:0:0:0:0:0:0:0
- FF02:0:0:0:0:0:0:0
- FF03:0:0:0:0:0:0:0
- FF04:0:0:0:0:0:0:0
- FF05:0:0:0:0:0:0:0
- FF06:0:0:0:0:0:0:0
- FF07:0:0:0:0:0:0:0
- FF08:0:0:0:0:0:0:0
- FF09:0:0:0:0:0:0:0
- FF0A:0:0:0:0:0:0:0
- FF0B:0:0:0:0:0:0:0
- FF0C:0:0:0:0:0:0:0
- FF0D:0:0:0:0:0:0:0
- FF0E:0:0:0:0:0:0:0
- FF0F:0:0:0:0:0:0:0
-
- The above multicast addresses are reserved and shall never be
- assigned to any multicast group.
-
- All Nodes Addresses: FF01:0:0:0:0:0:0:1
- FF02:0:0:0:0:0:0:1
-
- The above multicast addresses identify the group of all IPv6 nodes,
- within scope 1 (interface-local) or 2 (link-local).
-
- All Routers Addresses: FF01:0:0:0:0:0:0:2
- FF02:0:0:0:0:0:0:2
- FF05:0:0:0:0:0:0:2
-
- The above multicast addresses identify the group of all IPv6 routers,
- within scope 1 (interface-local), 2 (link-local), or 5 (site-local).
-
- Solicited-Node Address: FF02:0:0:0:0:1:FFXX:XXXX
-
- Solicited-node multicast address are computed as a function of a
- node's unicast and anycast addresses. A solicited-node multicast
- address is formed by taking the low-order 24 bits of an address
- (unicast or anycast) and appending those bits to the prefix
- FF02:0:0:0:0:1:FF00::/104 resulting in a multicast address in the
- range
-
- FF02:0:0:0:0:1:FF00:0000
-
- to
-
- FF02:0:0:0:0:1:FFFF:FFFF
-
-
-
-
-Hinden & Deering Standards Track [Page 16]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
- For example, the solicited node multicast address corresponding to
- the IPv6 address 4037::01:800:200E:8C6C is FF02::1:FF0E:8C6C. IPv6
- addresses that differ only in the high-order bits, e.g., due to
- multiple high-order prefixes associated with different aggregations,
- will map to the same solicited-node address thereby, reducing the
- number of multicast addresses a node must join.
-
- A node is required to compute and join (on the appropriate interface)
- the associated Solicited-Node multicast addresses for every unicast
- and anycast address it is assigned.
-
-2.8 A Node's Required Addresses
-
- A host is required to recognize the following addresses as
- identifying itself:
-
- o Its required Link-Local Address for each interface.
- o Any additional Unicast and Anycast Addresses that have been
- configured for the node's interfaces (manually or
- automatically).
- o The loopback address.
- o The All-Nodes Multicast Addresses defined in section 2.7.1.
- o The Solicited-Node Multicast Address for each of its unicast
- and anycast addresses.
- o Multicast Addresses of all other groups to which the node
- belongs.
-
- A router is required to recognize all addresses that a host is
- required to recognize, plus the following addresses as identifying
- itself:
-
- o The Subnet-Router Anycast Addresses for all interfaces for
- which it is configured to act as a router.
- o All other Anycast Addresses with which the router has been
- configured.
- o The All-Routers Multicast Addresses defined in section 2.7.1.
-
-3. Security Considerations
-
- IPv6 addressing documents do not have any direct impact on Internet
- infrastructure security. Authentication of IPv6 packets is defined
- in [AUTH].
-
-
-
-
-
-
-
-
-
-Hinden & Deering Standards Track [Page 17]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
-4. IANA Considerations
-
- The table and notes at http://www.isi.edu/in-
- notes/iana/assignments/ipv6-address-space.txt should be replaced with
- the following:
-
- INTERNET PROTOCOL VERSION 6 ADDRESS SPACE
-
- The initial assignment of IPv6 address space is as follows:
-
- Allocation Prefix Fraction of
- (binary) Address Space
- ----------------------------------- -------- -------------
- Unassigned (see Note 1 below) 0000 0000 1/256
- Unassigned 0000 0001 1/256
- Reserved for NSAP Allocation 0000 001 1/128 [RFC1888]
- Unassigned 0000 01 1/64
- Unassigned 0000 1 1/32
- Unassigned 0001 1/16
- Global Unicast 001 1/8 [RFC2374]
- Unassigned 010 1/8
- Unassigned 011 1/8
- Unassigned 100 1/8
- Unassigned 101 1/8
- Unassigned 110 1/8
- Unassigned 1110 1/16
- Unassigned 1111 0 1/32
- Unassigned 1111 10 1/64
- Unassigned 1111 110 1/128
- Unassigned 1111 1110 0 1/512
- Link-Local Unicast Addresses 1111 1110 10 1/1024
- Site-Local Unicast Addresses 1111 1110 11 1/1024
- Multicast Addresses 1111 1111 1/256
-
- Notes:
-
- 1. The "unspecified address", the "loopback address", and the IPv6
- Addresses with Embedded IPv4 Addresses are assigned out of the
- 0000 0000 binary prefix space.
-
- 2. For now, IANA should limit its allocation of IPv6 unicast address
- space to the range of addresses that start with binary value 001.
- The rest of the global unicast address space (approximately 85% of
- the IPv6 address space) is reserved for future definition and use,
- and is not to be assigned by IANA at this time.
-
-
-
-
-
-
-Hinden & Deering Standards Track [Page 18]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
-5. References
-
-5.1 Normative References
-
- [IPV6] Deering, S. and R. Hinden, "Internet Protocol, Version 6
- (IPv6) Specification", RFC 2460, December 1998.
-
- [RFC2026] Bradner, S., "The Internet Standards Process -- Revision
- 3", BCP 9 , RFC 2026, October 1996.
-
-5.2 Informative References
-
- [ANYCST] Partridge, C., Mendez, T. and W. Milliken, "Host Anycasting
- Service", RFC 1546, November 1993.
-
- [AUTH] Kent, S. and R. Atkinson, "IP Authentication Header", RFC
- 2402, November 1998.
-
- [AGGR] Hinden, R., O'Dell, M. and S. Deering, "An Aggregatable
- Global Unicast Address Format", RFC 2374, July 1998.
-
- [CIDR] Fuller, V., Li, T., Yu, J. and K. Varadhan, "Classless
- Inter-Domain Routing (CIDR): An Address Assignment and
- Aggregation Strategy", RFC 1519, September 1993.
-
- [ETHER] Crawford, M., "Transmission of IPv6 Packets over Ethernet
- Networks", RFC 2464, December 1998.
-
- [EUI64] IEEE, "Guidelines for 64-bit Global Identifier (EUI-64)
- Registration Authority",
- http://standards.ieee.org/regauth/oui/tutorials/EUI64.html,
- March 1997.
-
- [FDDI] Crawford, M., "Transmission of IPv6 Packets over FDDI
- Networks", RFC 2467, December 1998.
-
- [MASGN] Hinden, R. and S. Deering, "IPv6 Multicast Address
- Assignments", RFC 2375, July 1998.
-
- [NSAP] Bound, J., Carpenter, B., Harrington, D., Houldsworth, J.
- and A. Lloyd, "OSI NSAPs and IPv6", RFC 1888, August 1996.
-
- [PRIV] Narten, T. and R. Draves, "Privacy Extensions for Stateless
- Address Autoconfiguration in IPv6", RFC 3041, January 2001.
-
- [TOKEN] Crawford, M., Narten, T. and S. Thomas, "Transmission of
- IPv6 Packets over Token Ring Networks", RFC 2470, December
- 1998.
-
-
-
-Hinden & Deering Standards Track [Page 19]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
- [TRAN] Gilligan, R. and E. Nordmark, "Transition Mechanisms for
- IPv6 Hosts and Routers", RFC 2893, August 2000.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hinden & Deering Standards Track [Page 20]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
-APPENDIX A: Creating Modified EUI-64 format Interface Identifiers
-
- Depending on the characteristics of a specific link or node there are
- a number of approaches for creating Modified EUI-64 format interface
- identifiers. This appendix describes some of these approaches.
-
-Links or Nodes with IEEE EUI-64 Identifiers
-
- The only change needed to transform an IEEE EUI-64 identifier to an
- interface identifier is to invert the "u" (universal/local) bit. For
- example, a globally unique IEEE EUI-64 identifier of the form:
-
- |0 1|1 3|3 4|4 6|
- |0 5|6 1|2 7|8 3|
- +----------------+----------------+----------------+----------------+
- |cccccc0gcccccccc|ccccccccmmmmmmmm|mmmmmmmmmmmmmmmm|mmmmmmmmmmmmmmmm|
- +----------------+----------------+----------------+----------------+
-
- where "c" are the bits of the assigned company_id, "0" is the value
- of the universal/local bit to indicate global scope, "g" is
- individual/group bit, and "m" are the bits of the manufacturer-
- selected extension identifier. The IPv6 interface identifier would
- be of the form:
-
- |0 1|1 3|3 4|4 6|
- |0 5|6 1|2 7|8 3|
- +----------------+----------------+----------------+----------------+
- |cccccc1gcccccccc|ccccccccmmmmmmmm|mmmmmmmmmmmmmmmm|mmmmmmmmmmmmmmmm|
- +----------------+----------------+----------------+----------------+
-
- The only change is inverting the value of the universal/local bit.
-
-Links or Nodes with IEEE 802 48 bit MAC's
-
- [EUI64] defines a method to create a IEEE EUI-64 identifier from an
- IEEE 48bit MAC identifier. This is to insert two octets, with
- hexadecimal values of 0xFF and 0xFE, in the middle of the 48 bit MAC
- (between the company_id and vendor supplied id). For example, the 48
- bit IEEE MAC with global scope:
-
-
-
-
-
-
-
-
-
-
-
-
-Hinden & Deering Standards Track [Page 21]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
- |0 1|1 3|3 4|
- |0 5|6 1|2 7|
- +----------------+----------------+----------------+
- |cccccc0gcccccccc|ccccccccmmmmmmmm|mmmmmmmmmmmmmmmm|
- +----------------+----------------+----------------+
-
- where "c" are the bits of the assigned company_id, "0" is the value
- of the universal/local bit to indicate global scope, "g" is
- individual/group bit, and "m" are the bits of the manufacturer-
- selected extension identifier. The interface identifier would be of
- the form:
-
- |0 1|1 3|3 4|4 6|
- |0 5|6 1|2 7|8 3|
- +----------------+----------------+----------------+----------------+
- |cccccc1gcccccccc|cccccccc11111111|11111110mmmmmmmm|mmmmmmmmmmmmmmmm|
- +----------------+----------------+----------------+----------------+
-
- When IEEE 802 48bit MAC addresses are available (on an interface or a
- node), an implementation may use them to create interface identifiers
- due to their availability and uniqueness properties.
-
-Links with Other Kinds of Identifiers
-
- There are a number of types of links that have link-layer interface
- identifiers other than IEEE EIU-64 or IEEE 802 48-bit MACs. Examples
- include LocalTalk and Arcnet. The method to create an Modified EUI-
- 64 format identifier is to take the link identifier (e.g., the
- LocalTalk 8 bit node identifier) and zero fill it to the left. For
- example, a LocalTalk 8 bit node identifier of hexadecimal value 0x4F
- results in the following interface identifier:
-
- |0 1|1 3|3 4|4 6|
- |0 5|6 1|2 7|8 3|
- +----------------+----------------+----------------+----------------+
- |0000000000000000|0000000000000000|0000000000000000|0000000001001111|
- +----------------+----------------+----------------+----------------+
-
- Note that this results in the universal/local bit set to "0" to
- indicate local scope.
-
-Links without Identifiers
-
- There are a number of links that do not have any type of built-in
- identifier. The most common of these are serial links and configured
- tunnels. Interface identifiers must be chosen that are unique within
- a subnet-prefix.
-
-
-
-
-Hinden & Deering Standards Track [Page 22]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
- When no built-in identifier is available on a link the preferred
- approach is to use a global interface identifier from another
- interface or one which is assigned to the node itself. When using
- this approach no other interface connecting the same node to the same
- subnet-prefix may use the same identifier.
-
- If there is no global interface identifier available for use on the
- link the implementation needs to create a local-scope interface
- identifier. The only requirement is that it be unique within a
- subnet prefix. There are many possible approaches to select a
- subnet-prefix-unique interface identifier. These include:
-
- Manual Configuration
- Node Serial Number
- Other node-specific token
-
- The subnet-prefix-unique interface identifier should be generated in
- a manner that it does not change after a reboot of a node or if
- interfaces are added or deleted from the node.
-
- The selection of the appropriate algorithm is link and implementation
- dependent. The details on forming interface identifiers are defined
- in the appropriate "IPv6 over <link>" specification. It is strongly
- recommended that a collision detection algorithm be implemented as
- part of any automatic algorithm.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hinden & Deering Standards Track [Page 23]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
-APPENDIX B: Changes from RFC-2373
-
- The following changes were made from RFC-2373 "IP Version 6
- Addressing Architecture":
-
- - Clarified text in section 2.2 to allow "::" to represent one or
- more groups of 16 bits of zeros.
- - Changed uniqueness requirement of Interface Identifiers from
- unique on a link to unique within a subnet prefix. Also added a
- recommendation that the same interface identifier not be assigned
- to different machines on a link.
- - Change site-local format to make the subnet ID field 54-bit long
- and remove the 38-bit zero's field.
- - Added description of multicast scop values and rules to handle the
- reserved scop value 0.
- - Revised sections 2.4 and 2.5.6 to simplify and clarify how
- different address types are identified. This was done to insure
- that implementations do not build in any knowledge about global
- unicast format prefixes. Changes include:
- o Removed Format Prefix (FP) terminology
- o Revised list of address types to only include exceptions to
- global unicast and a singe entry that identifies everything
- else as Global Unicast.
- o Removed list of defined prefix exceptions from section 2.5.6
- as it is now the main part of section 2.4.
- - Clarified text relating to EUI-64 identifiers to distinguish
- between IPv6's "Modified EUI-64 format" identifiers and IEEE EUI-
- 64 identifiers.
- - Combined the sections on the Global Unicast Addresses and NSAP
- Addresses into a single section on Global Unicast Addresses,
- generalized the Global Unicast format, and cited [AGGR] and [NSAP]
- as examples.
- - Reordered sections 2.5.4 and 2.5.5.
- - Removed section 2.7.2 Assignment of New IPv6 Multicast Addresses
- because this is being redefined elsewhere.
- - Added an IANA considerations section that updates the IANA IPv6
- address allocations and documents the NSAP and AGGR allocations.
- - Added clarification that the "IPv4-compatible IPv6 address" must
- use global IPv4 unicast addresses.
- - Divided references in to normative and non-normative sections.
- - Added reference to [PRIV] in section 2.5.1
- - Added clarification that routers must not forward multicast
- packets outside of the scope indicated in the multicast address.
- - Added clarification that routers must not forward packets with
- source address of the unspecified address.
- - Added clarification that routers must drop packets received on an
- interface with destination address of loopback.
- - Clarified the definition of IPv4-mapped addresses.
-
-
-
-Hinden & Deering Standards Track [Page 24]
-\f
-RFC 3513 IPv6 Addressing Architecture April 2003
-
-
- - Removed the ABNF Description of Text Representations Appendix.
- - Removed the address block reserved for IPX addresses.
- - Multicast scope changes:
- o Changed name of scope value 1 from "node-local" to
- "interface-local"
- o Defined scope value 4 as "admin-local"
- - Corrected reference to RFC1933 and updated references.
- - Many small changes to clarify and make the text more consistent.
-
-Authors' Addresses
-
- Robert M. Hinden
- Nokia
- 313 Fairchild Drive
- Mountain View, CA 94043
- USA
-
- Phone: +1 650 625-2004
- EMail: hinden@iprg.nokia.com
-
-
- Stephen E. Deering
- Cisco Systems, Inc.
- 170 West Tasman Drive
- San Jose, CA 95134-1706
- USA
-
- Phone: +1 408 527-8213
- EMail: deering@cisco.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hinden & Deering Standards Track [Page 25]
-\f
-RFC 3513 IPv6 Addressing Architecture 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Hinden & Deering Standards Track [Page 26]
-\f
-
-
+++ /dev/null
-
-
-
-
-
-
-Network Working Group S. Thomson
-Request for Comments: 3596 Cisco
-Obsoletes: 3152, 1886 C. Huitema
-Category: Standards Track Microsoft
- V. Ksinant
- 6WIND
- M. Souissi
- AFNIC
- October 2003
-
-
- DNS Extensions to Support IP Version 6
-
-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 document defines the changes that need to be made to the Domain
- Name System (DNS) to support hosts running IP version 6 (IPv6). The
- changes include a resource record type to store an IPv6 address, a
- domain to support lookups based on an IPv6 address, and updated
- definitions of existing query types that return Internet addresses as
- part of additional section processing. The extensions are designed
- to be compatible with existing applications and, in particular, DNS
- implementations themselves.
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
- 2. New resource record definition and domain. . . . . . . . . . . 2
- 2.1. AAAA record type . . . . . . . . . . . . . . . . . . . . 3
- 2.2. AAAA data format . . . . . . . . . . . . . . . . . . . . 3
- 2.3. AAAA query . . . . . . . . . . . . . . . . . . . . . . . 3
- 2.4. Textual format of AAAA records . . . . . . . . . . . . . 3
- 2.5. IP6.ARPA domain. . . . . . . . . . . . . . . . . . . . . 3
- 3. Modifications to existing query types. . . . . . . . . . . . . 4
- 4. Security Considerations. . . . . . . . . . . . . . . . . . . . 4
- 5. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 4
-
-
-
-Thomson, et al. Standards Track [Page 1]
-\f
-RFC 3596 DNS Extensions to Support IPv6 October 2003
-
-
- 6. Intellectual Property Statement. . . . . . . . . . . . . . . . 4
- Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . . . 5
- Appendix A: Changes from RFC 1886. . . . . . . . . . . . . . . . . 6
- Normative References . . . . . . . . . . . . . . . . . . . . . . . 6
- Informative References . . . . . . . . . . . . . . . . . . . . . . 6
- Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 7
- Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 8
-
-1. Introduction
-
- Current support for the storage of Internet addresses in the Domain
- Name System (DNS) [1,2] cannot easily be extended to support IPv6
- addresses [3] since applications assume that address queries return
- 32-bit IPv4 addresses only.
-
- To support the storage of IPv6 addresses in the DNS, this document
- defines the following extensions:
-
- o A resource record type is defined to map a domain name to an
- IPv6 address.
-
- o A domain is defined to support lookups based on address.
-
- o Existing queries that perform additional section processing to
- locate IPv4 addresses are redefined to perform additional
- section processing on both IPv4 and IPv6 addresses.
-
- The changes are designed to be compatible with existing software.
- The existing support for IPv4 addresses is retained. Transition
- issues related to the co-existence of both IPv4 and IPv6 addresses in
- the DNS are discussed in [4].
-
- The IP protocol version used for querying resource records is
- independent of the protocol version of the resource records; e.g.,
- IPv4 transport can be used to query IPv6 records and vice versa.
-
- This document combines RFC 1886 [5] and changes to RFC 1886 made by
- RFC 3152 [6], obsoleting both. Changes mainly consist in replacing
- the IP6.INT domain by IP6.ARPA as defined in RFC 3152.
-
-2. New resource record definition and domain
-
- A record type is defined to store a host's IPv6 address. A host that
- has more than one IPv6 address must have more than one such record.
-
-
-
-
-
-
-
-Thomson, et al. Standards Track [Page 2]
-\f
-RFC 3596 DNS Extensions to Support IPv6 October 2003
-
-
-2.1 AAAA record type
-
- The AAAA resource record type is a record specific to the Internet
- class that stores a single IPv6 address.
-
- The IANA assigned value of the type is 28 (decimal).
-
-2.2 AAAA data format
-
- A 128 bit IPv6 address is encoded in the data portion of an AAAA
- resource record in network byte order (high-order byte first).
-
-2.3 AAAA query
-
- An AAAA query for a specified domain name in the Internet class
- returns all associated AAAA resource records in the answer section of
- a response.
-
- A type AAAA query does not trigger additional section processing.
-
-2.4 Textual format of AAAA records
-
- The textual representation of the data portion of the AAAA resource
- record used in a master database file is the textual representation
- of an IPv6 address as defined in [3].
-
-2.5 IP6.ARPA Domain
-
- A special domain is defined to look up a record given an IPv6
- address. The intent of this domain is to provide a way of mapping an
- IPv6 address to a host name, although it may be used for other
- purposes as well. The domain is rooted at IP6.ARPA.
-
- An IPv6 address is represented as a name in the IP6.ARPA domain by a
- sequence of nibbles separated by dots with the suffix ".IP6.ARPA".
- The sequence of nibbles is encoded in reverse order, i.e., the
- low-order nibble is encoded first, followed by the next low-order
- nibble and so on. Each nibble is represented by a hexadecimal digit.
- For example, the reverse lookup domain name corresponding to the
- address
-
- 4321:0:1:2:3:4:567:89ab
-
- would be
-
- b.a.9.8.7.6.5.0.4.0.0.0.3.0.0.0.2.0.0.0.1.0.0.0.0.0.0.0.1.2.3.4.IP6.
- ARPA.
-
-
-
-
-Thomson, et al. Standards Track [Page 3]
-\f
-RFC 3596 DNS Extensions to Support IPv6 October 2003
-
-
-3. Modifications to existing query types
-
- All existing query types that perform type A additional section
- processing, i.e., name server (NS), location of services (SRV) and
- mail exchange (MX) query types, must be redefined to perform both
- type A and type AAAA additional section processing. These
- definitions mean that a name server must add any relevant IPv4
- addresses and any relevant IPv6 addresses available locally to the
- additional section of a response when processing any one of the above
- queries.
-
-4. Security Considerations
-
- Any information obtained from the DNS must be regarded as unsafe
- unless techniques specified in [7] or [8] are used. The definitions
- of the AAAA record type and of the IP6.ARPA domain do not change the
- model for use of these techniques.
-
- So, this specification is not believed to cause any new security
- problems, nor to solve any existing ones.
-
-5. IANA Considerations
-
- There are no IANA assignments to be performed.
-
-6. Intellectual Property Statement
-
- 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.
-
-
-
-
-
-Thomson, et al. Standards Track [Page 4]
-\f
-RFC 3596 DNS Extensions to Support IPv6 October 2003
-
-
-Acknowledgments
-
- Vladimir Ksinant and Mohsen Souissi would like to thank Sebastien
- Barbin (IRISA), Luc Beloeil (France Telecom R&D), Jean-Mickael Guerin
- (6WIND), Vincent Levigneron (AFNIC), Alain Ritoux (6WIND), Frederic
- Roudaut (IRISA) and G6 group for their help during the RFC 1886
- Interop tests sessions.
-
- Many thanks to Alain Durand and Olafur Gudmundsson for their support.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Thomson, et al. Standards Track [Page 5]
-\f
-RFC 3596 DNS Extensions to Support IPv6 October 2003
-
-
-Appendix A: Changes from RFC 1886
-
- The following changes were made from RFC 1886 "DNS Extensions to
- support IP version 6":
-
- - Replaced the "IP6.INT" domain by "IP6.ARPA".
- - Mentioned SRV query types in section 3 "MODIFICATIONS TO
- EXISTING QUERY TYPES"
- - Added security considerations.
- - Updated references :
- * From RFC 1884 to RFC 3513 (IP Version 6 Addressing
- Architecture).
- * From "work in progress" to RFC 2893 (Transition Mechanisms for
- IPv6 Hosts and Routers).
- * Added reference to RFC 1886, RFC 3152, RFC 2535 and RFC 2845.
- - Updated document abstract
- - Added table of contents
- - Added full copyright statement
- - Added IANA considerations section
- - Added Intellectual Property Statement
-
-Normative References
-
- [1] Mockapetris, P., "Domain Names - Concepts and Facilities", STD
- 13, RFC 1034, November 1987.
-
- [2] Mockapetris, P., "Domain Names - Implementation and
- Specification", STD 13, RFC 1035, November 1987.
-
- [3] Hinden, R. and S. Deering, "Internet Protocol Version 6 (IPv6)
- Addressing Architecture", RFC 3513, April 2003.
-
-Informative References
-
- [4] Gilligan, R. and E. Nordmark, "Transition Mechanisms for IPv6
- Hosts and Routers", RFC 2893, August 2000.
-
- [5] Thomson, S. and C. Huitema, "DNS Extensions to support IP
- version 6", RFC 1886, December 1995.
-
- [6] Bush, R., "Delegation of IP6.ARPA", BCP 49, RFC 3152, August
- 2001.
-
- [7] Eastlake, D., "Domain Name System Security Extensions", RFC
- 2535, March 1999
-
-
-
-
-
-
-Thomson, et al. Standards Track [Page 6]
-\f
-RFC 3596 DNS Extensions to Support IPv6 October 2003
-
-
- [8] Vixie, P., Gudmundsson, O., Eastlake, D. and B. Wellington,
- "Secret Key Transaction Authentication for DNS (TSIG)", RFC
- 2845, May 2000.
-
-Authors' Addresses
-
- Susan Thomson
- Cisco Systems
- 499 Thornall Street, 8th floor
- Edison, NJ 08837
-
- Phone: +1 732-635-3086
- EMail: sethomso@cisco.com
-
-
- Christian Huitema
- Microsoft Corporation
- One Microsoft Way
- Redmond, WA 98052-6399
-
- EMail: huitema@microsoft.com
-
-
- Vladimir Ksinant
- 6WIND S.A.
- Immeuble Central Gare - Bat.C
- 1, place Charles de Gaulle
- 78180, Montigny-Le-Bretonneux - France
-
- Phone: +33 1 39 30 92 36
- EMail: vladimir.ksinant@6wind.com
-
-
- Mohsen Souissi
- AFNIC
- Immeuble International
- 2, rue Stephenson,
- 78181, Saint-Quentin en Yvelines Cedex - France
-
- Phone: +33 1 39 30 83 40
- EMail: Mohsen.Souissi@nic.fr
-
-
-
-
-
-
-
-
-
-
-Thomson, et al. Standards Track [Page 7]
-\f
-RFC 3596 DNS Extensions to Support IPv6 October 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 assignees.
-
- 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Thomson, et al. Standards Track [Page 8]
-\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 M. Daniele
-Request for Comments: 4001 SyAM Software, Inc.
-Obsoletes: 3291 B. Haberman
-Category: Standards Track Johns Hopkins University
- S. Routhier
- Wind River Systems, Inc.
- J. Schoenwaelder
- International University Bremen
- February 2005
-
-
- Textual Conventions for Internet Network Addresses
-
-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 MIB module defines textual conventions to represent commonly
- used Internet network layer addressing information. The intent is
- that these textual conventions will be imported and used in MIB
- modules that would otherwise define their own representations.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daniele, et al. Standards Track [Page 1]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
- 2. The Internet-Standard Management Framework . . . . . . . . . . 4
- 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5
- 4. Usage Hints . . . . . . . . . . . . . . . . . . . . . . . . . 13
- 4.1. Table Indexing . . . . . . . . . . . . . . . . . . . . . 14
- 4.2. Uniqueness of Addresses . . . . . . . . . . . . . . . . 14
- 4.3. Multiple Addresses per Host . . . . . . . . . . . . . . 15
- 4.4. Resolving DNS Names . . . . . . . . . . . . . . . . . . 15
- 5. Table Indexing Example . . . . . . . . . . . . . . . . . . . . 15
- 6. Security Considerations . . . . . . . . . . . . . . . . . . . 17
- 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18
- 8. Changes from RFC 3291 to RFC 4001 . . . . . . . . . . . . . . 18
- 9. Changes from RFC 2851 to RFC 3291 . . . . . . . . . . . . . . 18
- 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19
- 10.1. Normative References . . . . . . . . . . . . . . . . . . 19
- 10.2. Informative References . . . . . . . . . . . . . . . . . 20
- Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21
- Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 22
-
-1. Introduction
-
- Several standards-track MIB modules use the IpAddress SMIv2 base
- type. This limits the applicability of these MIB modules to IP
- Version 4 (IPv4), as the IpAddress SMIv2 base type can only contain
- 4-byte IPv4 addresses. The IpAddress SMIv2 base type has become
- problematic with the introduction of IP Version 6 (IPv6) addresses
- [RFC3513].
-
- This document defines multiple textual conventions (TCs) as a means
- to express generic Internet network layer addresses within MIB module
- specifications. The solution is compatible with SMIv2 (STD 58) and
- SMIv1 (STD 16). New MIB definitions that have to express network
- layer Internet addresses SHOULD use the textual conventions defined
- in this memo. New MIB modules SHOULD NOT use the SMIv2 IpAddress
- base type anymore.
-
- A generic Internet address consists of two objects: one whose syntax
- is InetAddressType, and another whose syntax is InetAddress. The
- value of the first object determines how the value of the second is
- encoded. The InetAddress textual convention represents an opaque
- Internet address value. The InetAddressType enumeration is used to
- "cast" the InetAddress value into a concrete textual convention for
- the address type. This usage of multiple textual conventions allows
- expression of the display characteristics of each address type and
- makes the set of defined Internet address types extensible.
-
-
-
-
-Daniele, et al. Standards Track [Page 2]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
- The textual conventions for well-known transport domains support
- scoped Internet addresses. The scope of an Internet address is a
- topological span within which the address may be used as a unique
- identifier for an interface or set of interfaces. A scope zone (or,
- simply, a zone) is a concrete connected region of topology of a given
- scope. Note that a zone is a particular instance of a topological
- region, whereas a scope is the size of a topological region
- [RFC4007]. Since Internet addresses on devices that connect multiple
- zones are not necessarily unique, an additional zone index is needed
- on these devices to select an interface. The textual conventions
- InetAddressIPv4z and InetAddressIPv6z are provided to support
- Internet addresses that include a zone index. To support arbitrary
- combinations of scoped Internet addresses, MIB authors SHOULD use a
- separate InetAddressType object for each InetAddress object.
-
- The textual conventions defined in this document can also be used to
- represent generic Internet subnets and Internet address ranges. A
- generic Internet subnet is represented by three objects: one whose
- syntax is InetAddressType, a second one whose syntax is InetAddress,
- and a third one whose syntax is InetAddressPrefixLength. The
- InetAddressType value again determines the concrete format of the
- InetAddress value, whereas the InetAddressPrefixLength identifies the
- Internet network address prefix.
-
- A generic range of consecutive Internet addresses is represented by
- three objects. The first one has the syntax InetAddressType, and the
- remaining objects have the syntax InetAddress and specify the start
- and end of the address range. Again, the InetAddressType value
- determines the format of the InetAddress values.
-
- The textual conventions defined in this document can be used to
- define Internet addresses by using DNS domain names in addition to
- IPv4 and IPv6 addresses. A MIB designer can write compliance
- statements to express that only a subset of the possible address
- types must be supported by a compliant implementation.
-
- MIB developers who need to represent Internet addresses SHOULD use
- these definitions whenever applicable, as opposed to defining their
- own constructs. Even MIB modules that only need to represent IPv4 or
- IPv6 addresses SHOULD use the InetAddressType/InetAddress textual
- conventions defined in this memo.
-
- There are many widely deployed MIB modules that use IPv4 addresses
- and that have to be revised to support IPv6. These MIB modules can
- be categorized as follows:
-
-
-
-
-
-
-Daniele, et al. Standards Track [Page 3]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
- 1. MIB modules that define management information that is, in
- principle, IP version neutral, but the MIB currently uses
- addressing constructs specific to a certain IP version.
-
- 2. MIB modules that define management information that is specific
- to a particular IP version (either IPv4 or IPv6) and that is very
- unlikely to ever be applicable to another IP version.
-
- MIB modules of the first type SHOULD provide object definitions
- (e.g., tables) that work with all versions of IP. In particular,
- when revising a MIB module that contains IPv4 specific tables, it is
- suggested to define new tables using the textual conventions defined
- in this memo that support all versions of IP. The status of the new
- tables SHOULD be "current", whereas the status of the old IP version
- specific tables SHOULD be changed to "deprecated". The other
- approach, of having multiple similar tables for different IP
- versions, is strongly discouraged.
-
- MIB modules of the second type, which are inherently IP version
- specific, do not need to be redefined. Note that even in this case,
- any additions to these MIB modules or to new IP version specific MIB
- modules SHOULD use the textual conventions defined in this memo.
-
- MIB developers SHOULD NOT use the textual conventions defined in this
- document to represent generic transport layer addresses. A special
- set of textual conventions for this purpose is defined in RFC 3419
- [RFC3419].
-
- The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY",
- in this document are to be interpreted as described in RFC 2119
- [RFC2119].
-
-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].
-
-
-
-
-
-Daniele, et al. Standards Track [Page 4]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
-3. Definitions
-
-INET-ADDRESS-MIB DEFINITIONS ::= BEGIN
-
-IMPORTS
- MODULE-IDENTITY, mib-2, Unsigned32 FROM SNMPv2-SMI
- TEXTUAL-CONVENTION FROM SNMPv2-TC;
-
-inetAddressMIB MODULE-IDENTITY
- LAST-UPDATED "200502040000Z"
- ORGANIZATION
- "IETF Operations and Management Area"
- CONTACT-INFO
- "Juergen Schoenwaelder (Editor)
- International University Bremen
- P.O. Box 750 561
- 28725 Bremen, Germany
-
- Phone: +49 421 200-3587
- EMail: j.schoenwaelder@iu-bremen.de
-
- Send comments to <ietfmibs@ops.ietf.org>."
- DESCRIPTION
- "This MIB module defines textual conventions for
- representing Internet addresses. An Internet
- address can be an IPv4 address, an IPv6 address,
- or a DNS domain name. This module also defines
- textual conventions for Internet port numbers,
- autonomous system numbers, and the length of an
- Internet address prefix.
-
- Copyright (C) The Internet Society (2005). This version
- of this MIB module is part of RFC 4001, see the RFC
- itself for full legal notices."
- REVISION "200502040000Z"
- DESCRIPTION
- "Third version, published as RFC 4001. This revision
- introduces the InetZoneIndex, InetScopeType, and
- InetVersion textual conventions."
- REVISION "200205090000Z"
- DESCRIPTION
- "Second version, published as RFC 3291. This
- revision contains several clarifications and
- introduces several new textual conventions:
- InetAddressPrefixLength, InetPortNumber,
- InetAutonomousSystemNumber, InetAddressIPv4z,
- and InetAddressIPv6z."
- REVISION "200006080000Z"
-
-
-
-Daniele, et al. Standards Track [Page 5]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
- DESCRIPTION
- "Initial version, published as RFC 2851."
- ::= { mib-2 76 }
-
-InetAddressType ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "A value that represents a type of Internet address.
-
- unknown(0) An unknown address type. This value MUST
- be used if the value of the corresponding
- InetAddress object is a zero-length string.
- It may also be used to indicate an IP address
- that is not in one of the formats defined
- below.
-
- ipv4(1) An IPv4 address as defined by the
- InetAddressIPv4 textual convention.
-
- ipv6(2) An IPv6 address as defined by the
- InetAddressIPv6 textual convention.
-
- ipv4z(3) A non-global IPv4 address including a zone
- index as defined by the InetAddressIPv4z
- textual convention.
-
- ipv6z(4) A non-global IPv6 address including a zone
- index as defined by the InetAddressIPv6z
- textual convention.
-
- dns(16) A DNS domain name as defined by the
- InetAddressDNS textual convention.
-
- Each definition of a concrete InetAddressType value must be
- accompanied by a definition of a textual convention for use
- with that InetAddressType.
-
- To support future extensions, the InetAddressType textual
- convention SHOULD NOT be sub-typed in object type definitions.
- It MAY be sub-typed in compliance statements in order to
- require only a subset of these address types for a compliant
- implementation.
-
- Implementations must ensure that InetAddressType objects
- and any dependent objects (e.g., InetAddress objects) are
- consistent. An inconsistentValue error must be generated
- if an attempt to change an InetAddressType object would,
- for example, lead to an undefined InetAddress value. In
-
-
-
-Daniele, et al. Standards Track [Page 6]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
- particular, InetAddressType/InetAddress pairs must be
- changed together if the address type changes (e.g., from
- ipv6(2) to ipv4(1))."
- SYNTAX INTEGER {
- unknown(0),
- ipv4(1),
- ipv6(2),
- ipv4z(3),
- ipv6z(4),
- dns(16)
- }
-
-InetAddress ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "Denotes a generic Internet address.
-
- An InetAddress value is always interpreted within the context
- of an InetAddressType value. Every usage of the InetAddress
- textual convention is required to specify the InetAddressType
- object that provides the context. It is suggested that the
- InetAddressType object be logically registered before the
- object(s) that use the InetAddress textual convention, if
- they appear in the same logical row.
-
- The value of an InetAddress object must always be
- consistent with the value of the associated InetAddressType
- object. Attempts to set an InetAddress object to a value
- inconsistent with the associated InetAddressType
- must fail with an inconsistentValue error.
-
- When this textual convention is used as the syntax of an
- index object, there may be issues with the limit of 128
- sub-identifiers specified in SMIv2, STD 58. In this case,
- the object definition MUST include a 'SIZE' clause to
- limit the number of potential instance sub-identifiers;
- otherwise the applicable constraints MUST be stated in
- the appropriate conceptual row DESCRIPTION clauses, or
- in the surrounding documentation if there is no single
- DESCRIPTION clause that is appropriate."
- SYNTAX OCTET STRING (SIZE (0..255))
-
-InetAddressIPv4 ::= TEXTUAL-CONVENTION
- DISPLAY-HINT "1d.1d.1d.1d"
- STATUS current
- DESCRIPTION
- "Represents an IPv4 network address:
-
-
-
-
-Daniele, et al. Standards Track [Page 7]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
- Octets Contents Encoding
- 1-4 IPv4 address network-byte order
-
- The corresponding InetAddressType value is ipv4(1).
-
- This textual convention SHOULD NOT be used directly in object
- definitions, as it restricts addresses to a specific format.
- However, if it is used, it MAY be used either on its own or in
- conjunction with InetAddressType, as a pair."
- SYNTAX OCTET STRING (SIZE (4))
-
-InetAddressIPv6 ::= TEXTUAL-CONVENTION
- DISPLAY-HINT "2x:2x:2x:2x:2x:2x:2x:2x"
- STATUS current
- DESCRIPTION
- "Represents an IPv6 network address:
-
- Octets Contents Encoding
- 1-16 IPv6 address network-byte order
-
- The corresponding InetAddressType value is ipv6(2).
-
- This textual convention SHOULD NOT be used directly in object
- definitions, as it restricts addresses to a specific format.
- However, if it is used, it MAY be used either on its own or in
- conjunction with InetAddressType, as a pair."
- SYNTAX OCTET STRING (SIZE (16))
-
-InetAddressIPv4z ::= TEXTUAL-CONVENTION
- DISPLAY-HINT "1d.1d.1d.1d%4d"
- STATUS current
- DESCRIPTION
- "Represents a non-global IPv4 network address, together
- with its zone index:
-
- Octets Contents Encoding
- 1-4 IPv4 address network-byte order
- 5-8 zone index network-byte order
-
- The corresponding InetAddressType value is ipv4z(3).
-
- The zone index (bytes 5-8) is used to disambiguate identical
- address values on nodes that have interfaces attached to
- different zones of the same scope. The zone index may contain
- the special value 0, which refers to the default zone for each
- scope.
-
- This textual convention SHOULD NOT be used directly in object
-
-
-
-Daniele, et al. Standards Track [Page 8]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
- definitions, as it restricts addresses to a specific format.
- However, if it is used, it MAY be used either on its own or in
- conjunction with InetAddressType, as a pair."
- SYNTAX OCTET STRING (SIZE (8))
-
-InetAddressIPv6z ::= TEXTUAL-CONVENTION
- DISPLAY-HINT "2x:2x:2x:2x:2x:2x:2x:2x%4d"
- STATUS current
- DESCRIPTION
- "Represents a non-global IPv6 network address, together
- with its zone index:
-
- Octets Contents Encoding
- 1-16 IPv6 address network-byte order
- 17-20 zone index network-byte order
-
- The corresponding InetAddressType value is ipv6z(4).
-
- The zone index (bytes 17-20) is used to disambiguate
- identical address values on nodes that have interfaces
- attached to different zones of the same scope. The zone index
- may contain the special value 0, which refers to the default
- zone for each scope.
-
- This textual convention SHOULD NOT be used directly in object
- definitions, as it restricts addresses to a specific format.
- However, if it is used, it MAY be used either on its own or in
- conjunction with InetAddressType, as a pair."
- SYNTAX OCTET STRING (SIZE (20))
-
-InetAddressDNS ::= TEXTUAL-CONVENTION
- DISPLAY-HINT "255a"
- STATUS current
- DESCRIPTION
- "Represents a DNS domain name. The name SHOULD be fully
- qualified whenever possible.
-
- The corresponding InetAddressType is dns(16).
-
- The DESCRIPTION clause of InetAddress objects that may have
- InetAddressDNS values MUST fully describe how (and when)
- these names are to be resolved to IP addresses.
-
- The resolution of an InetAddressDNS value may require to
- query multiple DNS records (e.g., A for IPv4 and AAAA for
- IPv6). The order of the resolution process and which DNS
- record takes precedence depends on the configuration of the
- resolver.
-
-
-
-Daniele, et al. Standards Track [Page 9]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
- This textual convention SHOULD NOT be used directly in object
- definitions, as it restricts addresses to a specific format.
- However, if it is used, it MAY be used either on its own or in
- conjunction with InetAddressType, as a pair."
- SYNTAX OCTET STRING (SIZE (1..255))
-
-InetAddressPrefixLength ::= TEXTUAL-CONVENTION
- DISPLAY-HINT "d"
- STATUS current
- DESCRIPTION
- "Denotes the length of a generic Internet network address
- prefix. A value of n corresponds to an IP address mask
- that has n contiguous 1-bits from the most significant
- bit (MSB), with all other bits set to 0.
-
- An InetAddressPrefixLength value is always interpreted within
- the context of an InetAddressType value. Every usage of the
- InetAddressPrefixLength textual convention is required to
- specify the InetAddressType object that provides the
- context. It is suggested that the InetAddressType object be
- logically registered before the object(s) that use the
- InetAddressPrefixLength textual convention, if they appear
- in the same logical row.
-
- InetAddressPrefixLength values larger than
- the maximum length of an IP address for a specific
- InetAddressType are treated as the maximum significant
- value applicable for the InetAddressType. The maximum
- significant value is 32 for the InetAddressType
- 'ipv4(1)' and 'ipv4z(3)' and 128 for the InetAddressType
- 'ipv6(2)' and 'ipv6z(4)'. The maximum significant value
- for the InetAddressType 'dns(16)' is 0.
-
- The value zero is object-specific and must be defined as
- part of the description of any object that uses this
- syntax. Examples of the usage of zero might include
- situations where the Internet network address prefix
- is unknown or does not apply.
-
- The upper bound of the prefix length has been chosen to
- be consistent with the maximum size of an InetAddress."
- SYNTAX Unsigned32 (0..2040)
-
-InetPortNumber ::= TEXTUAL-CONVENTION
- DISPLAY-HINT "d"
- STATUS current
- DESCRIPTION
- "Represents a 16 bit port number of an Internet transport
-
-
-
-Daniele, et al. Standards Track [Page 10]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
- layer protocol. Port numbers are assigned by IANA. A
- current list of all assignments is available from
- <http://www.iana.org/>.
-
- The value zero is object-specific and must be defined as
- part of the description of any object that uses this
- syntax. Examples of the usage of zero might include
- situations where a port number is unknown, or when the
- value zero is used as a wildcard in a filter."
- REFERENCE "STD 6 (RFC 768), STD 7 (RFC 793) and RFC 2960"
- SYNTAX Unsigned32 (0..65535)
-
-InetAutonomousSystemNumber ::= TEXTUAL-CONVENTION
- DISPLAY-HINT "d"
- STATUS current
- DESCRIPTION
- "Represents an autonomous system number that identifies an
- Autonomous System (AS). An AS is a set of routers under a
- single technical administration, using an interior gateway
- protocol and common metrics to route packets within the AS,
- and using an exterior gateway protocol to route packets to
- other ASes'. IANA maintains the AS number space and has
- delegated large parts to the regional registries.
-
- Autonomous system numbers are currently limited to 16 bits
- (0..65535). There is, however, work in progress to enlarge the
- autonomous system number space to 32 bits. Therefore, this
- textual convention uses an Unsigned32 value without a
- range restriction in order to support a larger autonomous
- system number space."
- REFERENCE "RFC 1771, RFC 1930"
- SYNTAX Unsigned32
-
-InetScopeType ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "Represents a scope type. This textual convention can be used
- in cases where a MIB has to represent different scope types
- and there is no context information, such as an InetAddress
- object, that implicitly defines the scope type.
-
- Note that not all possible values have been assigned yet, but
- they may be assigned in future revisions of this specification.
- Applications should therefore be able to deal with values
- not yet assigned."
- REFERENCE "RFC 3513"
- SYNTAX INTEGER {
- -- reserved(0),
-
-
-
-Daniele, et al. Standards Track [Page 11]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
- interfaceLocal(1),
- linkLocal(2),
- subnetLocal(3),
- adminLocal(4),
- siteLocal(5), -- site-local unicast addresses
- -- have been deprecated by RFC 3879
- -- unassigned(6),
- -- unassigned(7),
- organizationLocal(8),
- -- unassigned(9),
- -- unassigned(10),
- -- unassigned(11),
- -- unassigned(12),
- -- unassigned(13),
- global(14)
- -- reserved(15)
- }
-
-InetZoneIndex ::= TEXTUAL-CONVENTION
- DISPLAY-HINT "d"
- STATUS current
- DESCRIPTION
- "A zone index identifies an instance of a zone of a
- specific scope.
-
- The zone index MUST disambiguate identical address
- values. For link-local addresses, the zone index will
- typically be the interface index (ifIndex as defined in the
- IF-MIB) of the interface on which the address is configured.
-
- The zone index may contain the special value 0, which refers
- to the default zone. The default zone may be used in cases
- where the valid zone index is not known (e.g., when a
- management application has to write a link-local IPv6
- address without knowing the interface index value). The
- default zone SHOULD NOT be used as an easy way out in
- cases where the zone index for a non-global IPv6 address
- is known."
- REFERENCE "RFC4007"
- SYNTAX Unsigned32
-
-InetVersion ::= TEXTUAL-CONVENTION
- STATUS current
- DESCRIPTION
- "A value representing a version of the IP protocol.
-
- unknown(0) An unknown or unspecified version of the IP
- protocol.
-
-
-
-Daniele, et al. Standards Track [Page 12]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
- ipv4(1) The IPv4 protocol as defined in RFC 791 (STD 5).
-
- ipv6(2) The IPv6 protocol as defined in RFC 2460.
-
- Note that this textual convention SHOULD NOT be used to
- distinguish different address types associated with IP
- protocols. The InetAddressType has been designed for this
- purpose."
- REFERENCE "RFC 791, RFC 2460"
- SYNTAX INTEGER {
- unknown(0),
- ipv4(1),
- ipv6(2)
- }
-END
-
-4. Usage Hints
-
- The InetAddressType and InetAddress textual conventions have been
- introduced to avoid over-constraining an object definition by the use
- of the IpAddress SMI base type, which is IPv4 specific. An
- InetAddressType/InetAddress pair can represent IP addresses in
- various formats.
-
- The InetAddressType and InetAddress objects SHOULD NOT be sub-typed
- in object definitions. Sub-typing binds the MIB module to specific
- address formats, which may cause serious problems if new address
- formats need to be introduced. Note that it is possible to write
- compliance statements indicating that only a subset of the defined
- address types must be implemented to be compliant.
-
- Every usage of the InetAddress or InetAddressPrefixLength textual
- conventions must specify which InetAddressType object provides the
- context for the interpretation of the InetAddress or
- InetAddressPrefixLength textual convention.
-
- It is suggested that the InetAddressType object is logically
- registered before the object(s) that use(s) the InetAddress or
- InetAddressPrefixLength textual convention. An InetAddressType
- object is logically registered before an InetAddress or
- InetAddressPrefixLength object if it appears before the InetAddress
- or InetAddressPrefixLength object in the conceptual row (which
- includes any index objects). This rule allows programs such as MIB
- compilers to identify the InetAddressType of a given InetAddress or
- InetAddressPrefixLength object by searching for the InetAddressType
- object, which precedes an InetAddress or InetAddressPrefixLength
- object.
-
-
-
-
-Daniele, et al. Standards Track [Page 13]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
-4.1. Table Indexing
-
- When a generic Internet address is used as an index, both the
- InetAddressType and InetAddress objects MUST be used. The
- InetAddressType object MUST be listed before the InetAddress object
- in the INDEX clause.
-
- The IMPLIED keyword MUST NOT be used for an object of type
- InetAddress in an INDEX clause. Instance sub-identifiers are then of
- the form T.N.O1.O2...On, where T is the value of the InetAddressType
- object, O1...On are the octets in the InetAddress object, and N is
- the number of those octets.
-
- There is a meaningful lexicographical ordering to tables indexed in
- this fashion. Command generator applications may look up specific
- addresses of known type and value, issue GetNext requests for
- addresses of a single type, or issue GetNext requests for a specific
- type and address prefix.
-
-4.2. Uniqueness of Addresses
-
- IPv4 addresses were intended to be globally unique, current usage
- notwithstanding. IPv6 addresses were architected to have different
- scopes and hence uniqueness [RFC3513]. In particular, IPv6 "link-
- local" unicast addresses are not guaranteed to be unique on any
- particular node. In such cases, the duplicate addresses must be
- configured on different interfaces. So the combination of an IPv6
- address and a zone index is unique [RFC4007].
-
- The InetAddressIPv6 textual convention has been defined to represent
- global IPv6 addresses and non-global IPv6 addresses in cases where no
- zone index is needed (e.g., on end hosts with a single interface).
- The InetAddressIPv6z textual convention has been defined to represent
- non-global IPv6 addresses in cases where a zone index is needed
- (e.g., a router connecting multiple zones). Therefore, MIB designers
- who use InetAddressType/InetAddress pairs do not need to define
- additional objects in order to support non-global addresses on nodes
- that connect multiple zones.
-
- The InetAddressIPv4z is intended for use in MIB modules (such as the
- TCP-MIB) which report addresses in the address family used on the
- wire, but where the entity instrumented obtains these addresses from
- applications or administrators in a form that includes a zone index,
- such as v4-mapped IPv6 addresses.
-
-
-
-
-
-
-
-Daniele, et al. Standards Track [Page 14]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
- The size of the zone index has been chosen so that it is consistent
- with (i) the numerical zone index, defined in [RFC4007], and (ii) the
- sin6_scope_id field of the sockaddr_in6 structure, defined in RFC
- 2553 [RFC2553].
-
-4.3. Multiple Addresses per Host
-
- A single host system may be configured with multiple addresses (IPv4
- or IPv6), and possibly with multiple DNS names. Thus it is possible
- for a single host system to be accessible by multiple
- InetAddressType/InetAddress pairs.
-
- If this could be an implementation or usage issue, the DESCRIPTION
- clause of the relevant objects must fully describe which address is
- reported in a given InetAddressType/InetAddress pair.
-
-4.4. Resolving DNS Names
-
- DNS names MUST be resolved to IP addresses when communication with
- the named host is required. This raises a temporal aspect to
- defining MIB objects whose value is a DNS name: When is the name
- translated to an address?
-
- For example, consider an object defined to indicate a forwarding
- destination, and whose value is a DNS name. When does the forwarding
- entity resolve the DNS name? Each time forwarding occurs, or just
- once when the object was instantiated?
-
- The DESCRIPTION clause of these objects SHOULD precisely define how
- and when any required name to address resolution is done.
-
- Similarly, the DESCRIPTION clause of these objects SHOULD precisely
- define how and when a reverse lookup is being done, if an agent has
- accessed instrumentation that knows about an IP address, and if the
- MIB module or implementation requires it to map the IP address to a
- DNS name.
-
-5. Table Indexing Example
-
- This example shows a table listing communication peers that are
- identified by either an IPv4 address, an IPv6 address, or a DNS name.
- The table definition also prohibits entries with an empty address
- (whose type would be "unknown"). The size of a DNS name is limited
- to 64 characters in order to satisfy OID length constraints.
-
-
-
-
-
-
-
-Daniele, et al. Standards Track [Page 15]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
-peerTable OBJECT-TYPE
- SYNTAX SEQUENCE OF PeerEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "A list of communication peers."
- ::= { somewhere 1 }
-
-peerEntry OBJECT-TYPE
- SYNTAX PeerEntry
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "An entry containing information about a particular peer."
- INDEX { peerAddressType, peerAddress }
- ::= { peerTable 1 }
-
-PeerEntry ::= SEQUENCE {
- peerAddressType InetAddressType,
- peerAddress InetAddress,
- peerStatus INTEGER
-}
-
-peerAddressType OBJECT-TYPE
- SYNTAX InetAddressType
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The type of Internet address by which the peer
- is reachable."
-
- ::= { peerEntry 1 }
-
-peerAddress OBJECT-TYPE
- SYNTAX InetAddress (SIZE (1..64))
- MAX-ACCESS not-accessible
- STATUS current
- DESCRIPTION
- "The Internet address for the peer. The type of this
- address is determined by the value of the peerAddressType
- object. Note that implementations must limit themselves
- to a single entry in this table per reachable peer.
- The peerAddress may not be empty due to the SIZE
- restriction.
-
- If a row is created administratively by an SNMP
- operation and the address type value is dns(16), then
- the agent stores the DNS name internally. A DNS name
-
-
-
-Daniele, et al. Standards Track [Page 16]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
- lookup must be performed on the internally stored DNS
- name whenever it is being used to contact the peer.
-
- If a row is created by the managed entity itself and
- the address type value is dns(16), then the agent
- stores the IP address internally. A DNS reverse lookup
- must be performed on the internally stored IP address
- whenever the value is retrieved via SNMP."
- ::= { peerEntry 2 }
-
-
- The following compliance statement specifies that compliant
- implementations need only support IPv4/IPv6 addresses without zone
- indices. Support for DNS names or IPv4/IPv6 addresses with zone
- indices is not required.
-
- peerCompliance MODULE-COMPLIANCE
- STATUS current
- DESCRIPTION
- "The compliance statement of the peer MIB."
-
- MODULE -- this module
- MANDATORY-GROUPS { peerGroup }
-
- OBJECT peerAddressType
- SYNTAX InetAddressType { ipv4(1), ipv6(2) }
- DESCRIPTION
- "An implementation is only required to support IPv4
- and IPv6 addresses without zone indices."
-
- ::= { somewhere 2 }
-
- Note that the SMIv2 does not permit inclusion of objects that are not
- accessible in an object group (see section 3.1 in STD 58, RFC 2580
- [RFC2580]). It is therefore not possible to refine the syntax of
- auxiliary objects that are not accessible. It is suggested that the
- refinement be expressed informally in the DESCRIPTION clause of the
- MODULE-COMPLIANCE macro invocation.
-
-6. Security Considerations
-
- This module does not define any management objects. Instead, it
- defines a set of textual conventions which may be used by other MIB
- modules to define management objects.
-
-
-
-
-
-
-
-Daniele, et al. Standards Track [Page 17]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
- Meaningful security considerations can only be written in the MIB
- modules that define management objects. This document has therefore
- no impact on the security of the Internet.
-
-7. Acknowledgments
-
- This document was produced by the Operations and Management Area
- "IPv6MIB" design team. For their comments and suggestions, the
- authors would like to thank Fred Baker, Randy Bush, Richard Draves,
- Mark Ellison, Bill Fenner, Jun-ichiro Hagino, Mike Heard, Tim
- Jenkins, Allison Mankin, Glenn Mansfield, Keith McCloghrie, Thomas
- Narten, Erik Nordmark, Peder Chr. Norgaard, Randy Presuhn, Andrew
- Smith, Dave Thaler, Kenneth White, Bert Wijnen, and Brian Zill.
-
-8. Changes from RFC 3291 to RFC 4001
-
- The following changes have been made relative to RFC 3291:
-
- o Added a range restriction to the InetAddressPrefixLength textual
- convention.
-
- o Added new textual conventions InetZoneIndex, InetScopeType, and
- InetVersion.
-
- o Added explicit "d" DISPLAY-HINTs for textual conventions that did
- not have them.
-
- o Updated boilerplate text and references.
-
-9. Changes from RFC 2851 to RFC 3291
-
- The following changes have been made relative to RFC 2851:
-
- o Added new textual conventions InetAddressPrefixLength,
- InetPortNumber, and InetAutonomousSystemNumber.
-
- o Rewrote the introduction to say clearly that, in general, one
- should define MIB tables that work with all versions of IP. The
- other approach of multiple tables for different IP versions is
- strongly discouraged.
-
- o Added text to the InetAddressType and InetAddress descriptions
- requiring that implementations must reject set operations with an
- inconsistentValue error if they lead to inconsistencies.
-
- o Removed the strict ordering constraints. Description clauses now
- must explain which InetAddressType object provides the context for
- an InetAddress or InetAddressPrefixLength object.
-
-
-
-Daniele, et al. Standards Track [Page 18]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
- o Aligned wordings with the IPv6 scoping architecture document.
-
- o Split the InetAddressIPv6 textual convention into the two textual
- conventions (InetAddressIPv6 and InetAddressIPv6z) and introduced
- a new textual convention InetAddressIPv4z. Added ipv4z(3) and
- ipv6z(4) named numbers to the InetAddressType enumeration.
- Motivations for this change: (i) to enable the introduction of a
- textual conventions for non-global IPv4 addresses, (ii) alignment
- with the textual conventions for transport addresses, (iii)
- simpler compliance statements in cases where support for IPv6
- addresses with zone indices is not required, and (iv) to simplify
- implementations for host systems that will never have to report
- zone indices.
-
-10. References
-
-10.1. Normative References
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [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.
-
- [RFC3513] Hinden, R. and S. Deering, "Internet Protocol Version 6
- (IPv6) Addressing Architecture", RFC 3513, April 2003.
-
- [RFC4007] Deering, S., Haberman, B., Jinmei, T., Nordmark, E., and
- B. Zill, "IPv6 Scoped Address Architecture", RFC 4007,
- February 2005.
-
-
-
-
-
-
-
-
-
-
-
-
-Daniele, et al. Standards Track [Page 19]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
-10.2. Informative References
-
- [RFC2553] Gilligan, R., Thomson, S., Bound, J., and W. Stevens,
- "Basic Socket Interface Extensions for IPv6", RFC 2553,
- March 1999.
-
- [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group
- MIB", RFC 2863, June 2000.
-
- [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart,
- "Introduction and Applicability Statements for Internet-
- Standard Management Framework", RFC 3410, December 2002.
-
- [RFC3419] Daniele, M. and J. Schoenwaelder, "Textual Conventions for
- Transport Addresses", RFC 3419, December 2002.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daniele, et al. Standards Track [Page 20]
-\f
-RFC 4001 Internet Network Address Conventions February 2005
-
-
-Authors' Addresses
-
- Michael Daniele
- SyAM Software, Inc.
- 1 Chestnut St, Suite 3-I
- Nashua, NH 03060
- USA
-
- Phone: +1 603 598-9575
- EMail: michael.daniele@syamsoftware.com
-
-
- Brian Haberman
- Johns Hopkins University Applied Physics Laboratory
- 11100 Johns Hopkins Road
- Laurel, MD 20723-6099
- USA
-
- Phone: +1-443-778-1319
- EMail: brian@innovationslab.net
-
-
- Shawn A. Routhier
- Wind River Systems, Inc.
- 500 Wind River Way
- Alameda, CA 94501
- USA
-
- Phone: +1 510 749-2095
- EMail: shawn.routhier@windriver.com
-
-
- Juergen Schoenwaelder
- International University Bremen
- P.O. Box 750 561
- 28725 Bremen
- Germany
-
- Phone: +49 421 200-3587
- EMail: j.schoenwaelder@iu-bremen.de
-
-
-
-
-
-
-
-
-
-
-
-Daniele, et al. Standards Track [Page 21]
-\f
-RFC 4001 Internet Network Address Conventions February 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 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.
-
-
-
-
-
-
-
-Daniele, et al. Standards Track [Page 22]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group K. Jaganathan
-Request for Comments: 4559 L. Zhu
-Category: Informational J. Brezak
- Microsoft Corporation
- June 2006
-
-
- SPNEGO-based Kerberos and NTLM HTTP Authentication
- in Microsoft Windows
-
-
-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 (2006).
-
-Abstract
-
- This document describes how the Microsoft Internet Explorer (MSIE)
- and Internet Information Services (IIS) incorporated in Microsoft
- Windows 2000 use Kerberos for security enhancements of web
- transactions. The Hypertext Transport Protocol (HTTP) auth-scheme of
- "negotiate" is defined here; when the negotiation results in the
- selection of Kerberos, the security services of authentication and,
- optionally, impersonation (the IIS server assumes the windows
- identity of the principal that has been authenticated) are performed.
- This document explains how HTTP authentication utilizes the Simple
- and Protected GSS-API Negotiation mechanism. Details of Simple And
- Protected Negotiate (SPNEGO) implementation are not provided in this
- document.
-
-Table of Contents
-
- 1. Introduction ....................................................2
- 2. Conventions Used in This Document ...............................2
- 3. Access Authentication ...........................................2
- 3.1. Reliance on the HTTP/1.1 Specification .....................2
- 4. HTTP Negotiate Authentication Scheme ............................2
- 4.1. The WWW-Authenticate Response Header .......................2
- 5. Negotiate Operation Example .....................................4
- 6. Security Considerations .........................................5
- 7. Normative References ............................................6
-
-
-
-
-Jaganathan, et al. Informational [Page 1]
-\f
-RFC 4559 HTTP Authentication in Microsoft Windows June 2006
-
-
-1. Introduction
-
- Microsoft has provided support for Kerberos authentication in
- Microsoft Internet Explorer (MSIE) and Internet Information Services
- (IIS), in addition to other mechanisms. This provides the benefits
- of the Kerberos v5 protocol for Web applications.
-
- Support for Kerberos authentication is based on other previously
- defined mechanisms, such as SPNEGO Simple And Protected Negotiate
- (SPNEGO) [RFC4178] and the Generic Security Services Application
- Program Interface(GSSAPI).
-
-2. Conventions Used in This Document
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to
- be interpreted as described in [RFC2119].
-
-3. Access Authentication
-
-3.1. Reliance on the HTTP/1.1 Specification
-
- This specification is a companion to the HTTP/1.1 specification
- [RFC2616], and it builds on the authentication mechanisms defined in
- [RFC2617]. It uses the augmented BNF section of that document (2.1),
- and it relies on both the non-terminals defined in that document and
- other aspects of the HTTP/1.1 specification.
-
-4. HTTP Negotiate Authentication Scheme
-
- Use of Kerberos is wrapped in an HTTP auth-scheme of "Negotiate".
- The auth-params exchanged use data formats defined for use with the
- GSS-API [RFC2743]. In particular, they follow the formats set for
- the SPNEGO [RFC4178] and Kerberos [RFC4121] mechanisms for GSSAPI.
- The "Negotiate" auth-scheme calls for the use of SPNEGO GSSAPI tokens
- that the specific mechanism type specifies.
-
- The current implementation of this protocol is limited to the use of
- SPNEGO with the Kerberos and Microsoft(NT Lan Manager) NTLM
- protocols.
-
-4.1. The WWW-Authenticate Response Header
-
- If the server receives a request for an access-protected object, and
- if an acceptable Authorization header has not been sent, the server
- responds with a "401 Unauthorized" status code, and a "WWW-
- Authenticate:" header as per the framework described in [RFC2616].
- The initial WWW-Authenticate header will not carry any gssapi-data.
-
-
-
-Jaganathan, et al. Informational [Page 2]
-\f
-RFC 4559 HTTP Authentication in Microsoft Windows June 2006
-
-
- The negotiate scheme will operate as follows:
-
- challenge = "Negotiate" auth-data
- auth-data = 1#( [gssapi-data] )
-
- The meanings of the values of the directives used above are as
- follows:
-
- gssapi-data
-
- If the gss_accept_security_context returns a token for the client,
- this directive contains the base64 encoding of an
- initialContextToken, as defined in [RFC2743]. This is not present in
- the initial response from the server.
-
- A status code 200 status response can also carry a "WWW-Authenticate"
- response header containing the final leg of an authentication. In
- this case, the gssapi-data will be present. Before using the
- contents of the response, the gssapi-data should be processed by
- gss_init_security_context to determine the state of the security
- context. If this function indicates success, the response can be
- used by the application. Otherwise, an appropriate action, based on
- the authentication status, should be taken.
-
- For example, the authentication could have failed on the final leg if
- mutual authentication was requested and the server was not able to
- prove its identity. In this case, the returned results are suspect.
- It is not always possible to mutually authenticate the server before
- the HTTP operation. POST methods are in this category.
-
- When the Kerberos Version 5 GSSAPI mechanism [RFC4121] is being used,
- the HTTP server will be using a principal name of the form of
- "HTTP/hostname".
-
-4.2. The Authorization Request Header
-
- Upon receipt of the response containing a "WWW-Authenticate" header
- from the server, the client is expected to retry the HTTP request,
- passing a HTTP "Authorization" header line. This is defined
- according to the framework described in [RFC2616] and is utilized as
- follows:
-
- credentials = "Negotiate" auth-data2
- auth-data2 = 1#( gssapi-data )
-
- gssapi-data
-
-
-
-
-
-Jaganathan, et al. Informational [Page 3]
-\f
-RFC 4559 HTTP Authentication in Microsoft Windows June 2006
-
-
- This directive contains the base64 encoding of an
- InitialContextToken, as defined in [RFC2743].
-
- Any returned code other than a success 2xx code represents an
- authentication error. If a 401 containing a "WWW-Authenticate"
- header with "Negotiate" and gssapi-data is returned from the server,
- it is a continuation of the authentication request.
-
- A client may initiate a connection to the server with an
- "Authorization" header containing the initial token for the server.
- This form will bypass the initial 401 error from the server when the
- client knows that the server will accept the Negotiate HTTP
- authentication type.
-
-5. Negotiate Operation Example
-
- The client requests an access-protected document from server via a
- GET method request. The URI of the document is
- "http://www.nowhere.org/dir/index.html".
-
- C: GET dir/index.html
-
- The first time the client requests the document, no Authorization
- header is sent, so the server responds with
-
- S: HTTP/1.1 401 Unauthorized
- S: WWW-Authenticate: Negotiate
-
- The client will obtain the user credentials using the SPNEGO GSSAPI
- mechanism type to identify generate a GSSAPI message to be sent to
- the server with a new request, including the following Authorization
- header:
-
- C: GET dir/index.html
- C: Authorization: Negotiate a87421000492aa874209af8bc028
-
- The server will decode the gssapi-data and pass this to the SPNEGO
- GSSAPI mechanism in the gss_accept_security_context function. If the
- context is not complete, the server will respond with a 401 status
- code with a WWW-Authenticate header containing the gssapi-data.
-
- S: HTTP/1.1 401 Unauthorized
- S: WWW-Authenticate: Negotiate 749efa7b23409c20b92356
-
- The client will decode the gssapi-data, pass this into
- Gss_Init_security_context, and return the new gssapi-data to the
- server.
-
-
-
-
-Jaganathan, et al. Informational [Page 4]
-\f
-RFC 4559 HTTP Authentication in Microsoft Windows June 2006
-
-
- C: GET dir/index.html
- C: Authorization: Negotiate 89a8742aa8729a8b028
-
- This cycle can continue until the security context is complete. When
- the return value from the gss_accept_security_context function
- indicates that the security context is complete, it may supply final
- authentication data to be returned to the client. If the server has
- more gssapi data to send to the client to complete the context, it is
- to be carried in a WWW-Authenticate header with the final response
- containing the HTTP body.
-
- S: HTTP/1.1 200 Success
- S: WWW-Authenticate: Negotiate ade0234568a4209af8bc0280289eca
-
- The client will decode the gssapi-data and supply it to
- gss_init_security_context using the context for this server. If the
- status is successful from the final gss_init_security_context, the
- response can be used by the application.
-
-6. Security Considerations
-
- The SPNEGO HTTP authentication facility is only used to provide
- authentication of a user to a server. It provides no facilities for
- protecting the HTTP headers or data including the Authorization and
- WWW-Authenticate headers that are used to implement this mechanism.
-
- Alternate mechanisms such as TLS can be used to provide
- confidentiality. Hashes of the TLS certificates can be used as
- channel bindings to secure the channel. In this case clients would
- need to enforce that the channel binding information is valid. Note
- that Kerb-TLS [RFC2712] could be used to provide both authentication
- and confidentiality, but this requires a change to the TLS provider.
-
- This mechanism is not used for HTTP authentication to HTTP proxies.
-
- If an HTTP proxy is used between the client and server, it must take
- care to not share authenticated connections between different
- authenticated clients to the same server. If this is not honored,
- then the server can easily lose track of security context
- associations. A proxy that correctly honors client to server
- authentication integrity will supply the "Proxy-support: Session-
- Based-Authentication" HTTP header to the client in HTTP responses
- from the proxy. The client MUST NOT utilize the SPNEGO HTTP
- authentication mechanism through a proxy unless the proxy supplies
- this header with the "401 Unauthorized" response from the server.
-
-
-
-
-
-
-Jaganathan, et al. Informational [Page 5]
-\f
-RFC 4559 HTTP Authentication in Microsoft Windows June 2006
-
-
- When using the SPNEGO HTTP authentication facility with client-
- supplied data such as PUT and POST, the authentication should be
- complete between the client and server before sending the user data.
- The return status from the gss_init_security_context will indicate
- that the security context is complete. At this point, the data can
- be sent to the server.
-
-7. Normative References
-
- [RFC2743] Linn, J., "Generic Security Service Application Program
- Interface Version 2", 2, Update 1", 2743, January 2000.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC4178] Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The
- Simple and Protected GSS-API Generic Security Service
- Application Program Interface (GSS-API) Negotiation
- Mechanism", 4178, October 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.
-
- [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.
-
- [RFC2712] Medvinsky, A. and M. Hur, "Addition of Kerberos Cipher
- Suites to Transport Layer Security (TLS)", RFC 2712,
- October 1999.
-
- [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos
- Version 5 Generic Security Service Application Program
- Interface (GSS-API) Mechanism: Version 2", RFC 4121, July
- 2005.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Jaganathan, et al. Informational [Page 6]
-\f
-RFC 4559 HTTP Authentication in Microsoft Windows June 2006
-
-
-Authors' Addresses
-
- Karthik Jaganathan
- Microsoft Corporation
- One Microsoft Way
- Redmond, WA 98052
- US
-
- EMail: karthikj@microsoft.com
-
-
- Larry Zhu
- Microsoft Corporation
- One Microsoft Way
- Redmond, WA 98052
- US
-
- EMail: lzhu@microsoft.com
-
-
- John Brezak
- Microsoft Corporation
- One Microsoft Way
- Redmond, WA 98052
- US
-
- EMail: jbrezak@microsoft.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Jaganathan, et al. Informational [Page 7]
-\f
-RFC 4559 HTTP Authentication in Microsoft Windows June 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 at www.rfc-editor.org/copyright.html, 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).
-
-
-
-
-
-
-
-Jaganathan, et al. Informational [Page 8]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group L. Dusseault, Ed.
-Request for Comments: 4918 CommerceNet
-Obsoletes: 2518 June 2007
-Category: Standards Track
-
-
- HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)
-
-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 IETF Trust (2007).
-
-Abstract
-
- Web Distributed Authoring and Versioning (WebDAV) consists of a set
- of methods, headers, and content-types ancillary to HTTP/1.1 for the
- management of resource properties, creation and management of
- resource collections, URL namespace manipulation, and resource
- locking (collision avoidance).
-
- RFC 2518 was published in February 1999, and this specification
- obsoletes RFC 2518 with minor revisions mostly due to
- interoperability experience.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 1]
-\f
-RFC 4918 WebDAV June 2007
-
-
-Table of Contents
-
- 1. Introduction ....................................................7
- 2. Notational Conventions ..........................................8
- 3. Terminology .....................................................8
- 4. Data Model for Resource Properties .............................10
- 4.1. The Resource Property Model ...............................10
- 4.2. Properties and HTTP Headers ...............................10
- 4.3. Property Values ...........................................10
- 4.3.1. Example - Property with Mixed Content ..............12
- 4.4. Property Names ............................................14
- 4.5. Source Resources and Output Resources .....................14
- 5. Collections of Web Resources ...................................14
- 5.1. HTTP URL Namespace Model ..................................15
- 5.2. Collection Resources ......................................15
- 6. Locking ........................................................17
- 6.1. Lock Model ................................................18
- 6.2. Exclusive vs. Shared Locks ................................19
- 6.3. Required Support ..........................................20
- 6.4. Lock Creator and Privileges ...............................20
- 6.5. Lock Tokens ...............................................21
- 6.6. Lock Timeout ..............................................21
- 6.7. Lock Capability Discovery .................................22
- 6.8. Active Lock Discovery .....................................22
- 7. Write Lock .....................................................23
- 7.1. Write Locks and Properties ................................24
- 7.2. Avoiding Lost Updates .....................................24
- 7.3. Write Locks and Unmapped URLs .............................25
- 7.4. Write Locks and Collections ...............................26
- 7.5. Write Locks and the If Request Header .....................28
- 7.5.1. Example - Write Lock and COPY ......................28
- 7.5.2. Example - Deleting a Member of a Locked
- Collection .........................................29
- 7.6. Write Locks and COPY/MOVE .................................30
- 7.7. Refreshing Write Locks ....................................30
- 8. General Request and Response Handling ..........................31
- 8.1. Precedence in Error Handling ..............................31
- 8.2. Use of XML ................................................31
- 8.3. URL Handling ..............................................32
- 8.3.1. Example - Correct URL Handling .....................32
- 8.4. Required Bodies in Requests ...............................33
- 8.5. HTTP Headers for Use in WebDAV ............................33
- 8.6. ETag ......................................................33
- 8.7. Including Error Response Bodies ...........................34
- 8.8. Impact of Namespace Operations on Cache Validators ........34
- 9. HTTP Methods for Distributed Authoring .........................35
- 9.1. PROPFIND Method ...........................................35
- 9.1.1. PROPFIND Status Codes ..............................37
-
-
-
-Dusseault Standards Track [Page 2]
-\f
-RFC 4918 WebDAV June 2007
-
-
- 9.1.2. Status Codes for Use in 'propstat' Element .........37
- 9.1.3. Example - Retrieving Named Properties ..............38
- 9.1.4. Example - Using 'propname' to Retrieve All
- Property Names .....................................39
- 9.1.5. Example - Using So-called 'allprop' ................41
- 9.1.6. Example - Using 'allprop' with 'include' ...........43
- 9.2. PROPPATCH Method ..........................................44
- 9.2.1. Status Codes for Use in 'propstat' Element .........44
- 9.2.2. Example - PROPPATCH ................................45
- 9.3. MKCOL Method ..............................................46
- 9.3.1. MKCOL Status Codes .................................47
- 9.3.2. Example - MKCOL ....................................47
- 9.4. GET, HEAD for Collections .................................48
- 9.5. POST for Collections ......................................48
- 9.6. DELETE Requirements .......................................48
- 9.6.1. DELETE for Collections .............................49
- 9.6.2. Example - DELETE ...................................49
- 9.7. PUT Requirements ..........................................50
- 9.7.1. PUT for Non-Collection Resources ...................50
- 9.7.2. PUT for Collections ................................51
- 9.8. COPY Method ...............................................51
- 9.8.1. COPY for Non-collection Resources ..................51
- 9.8.2. COPY for Properties ................................52
- 9.8.3. COPY for Collections ...............................52
- 9.8.4. COPY and Overwriting Destination Resources .........53
- 9.8.5. Status Codes .......................................54
- 9.8.6. Example - COPY with Overwrite ......................55
- 9.8.7. Example - COPY with No Overwrite ...................55
- 9.8.8. Example - COPY of a Collection .....................56
- 9.9. MOVE Method ...............................................56
- 9.9.1. MOVE for Properties ................................57
- 9.9.2. MOVE for Collections ...............................57
- 9.9.3. MOVE and the Overwrite Header ......................58
- 9.9.4. Status Codes .......................................59
- 9.9.5. Example - MOVE of a Non-Collection .................60
- 9.9.6. Example - MOVE of a Collection .....................60
- 9.10. LOCK Method ..............................................61
- 9.10.1. Creating a Lock on an Existing Resource ...........61
- 9.10.2. Refreshing Locks ..................................62
- 9.10.3. Depth and Locking .................................62
- 9.10.4. Locking Unmapped URLs .............................63
- 9.10.5. Lock Compatibility Table ..........................63
- 9.10.6. LOCK Responses ....................................63
- 9.10.7. Example - Simple Lock Request .....................64
- 9.10.8. Example - Refreshing a Write Lock .................65
- 9.10.9. Example - Multi-Resource Lock Request .............66
- 9.11. UNLOCK Method ............................................68
- 9.11.1. Status Codes ......................................68
-
-
-
-Dusseault Standards Track [Page 3]
-\f
-RFC 4918 WebDAV June 2007
-
-
- 9.11.2. Example - UNLOCK ..................................69
- 10. HTTP Headers for Distributed Authoring ........................69
- 10.1. DAV Header ...............................................69
- 10.2. Depth Header .............................................70
- 10.3. Destination Header .......................................71
- 10.4. If Header ................................................72
- 10.4.1. Purpose ...........................................72
- 10.4.2. Syntax ............................................72
- 10.4.3. List Evaluation ...................................73
- 10.4.4. Matching State Tokens and ETags ...................74
- 10.4.5. If Header and Non-DAV-Aware Proxies ...............74
- 10.4.6. Example - No-tag Production .......................75
- 10.4.7. Example - Using "Not" with No-tag Production ......75
- 10.4.8. Example - Causing a Condition to Always
- Evaluate to True ..................................75
- 10.4.9. Example - Tagged List If Header in COPY ...........76
- 10.4.10. Example - Matching Lock Tokens with
- Collection Locks .................................76
- 10.4.11. Example - Matching ETags on Unmapped URLs ........76
- 10.5. Lock-Token Header ........................................77
- 10.6. Overwrite Header .........................................77
- 10.7. Timeout Request Header ...................................78
- 11. Status Code Extensions to HTTP/1.1 ............................78
- 11.1. 207 Multi-Status .........................................78
- 11.2. 422 Unprocessable Entity .................................78
- 11.3. 423 Locked ...............................................78
- 11.4. 424 Failed Dependency ....................................79
- 11.5. 507 Insufficient Storage .................................79
- 12. Use of HTTP Status Codes ......................................79
- 12.1. 412 Precondition Failed ..................................79
- 12.2. 414 Request-URI Too Long .................................79
- 13. Multi-Status Response .........................................80
- 13.1. Response Headers .........................................80
- 13.2. Handling Redirected Child Resources ......................81
- 13.3. Internal Status Codes ....................................81
- 14. XML Element Definitions .......................................81
- 14.1. activelock XML Element ...................................81
- 14.2. allprop XML Element ......................................82
- 14.3. collection XML Element ...................................82
- 14.4. depth XML Element ........................................82
- 14.5. error XML Element ........................................82
- 14.6. exclusive XML Element ....................................83
- 14.7. href XML Element .........................................83
- 14.8. include XML Element ......................................83
- 14.9. location XML Element .....................................83
- 14.10. lockentry XML Element ...................................84
- 14.11. lockinfo XML Element ....................................84
- 14.12. lockroot XML Element ....................................84
-
-
-
-Dusseault Standards Track [Page 4]
-\f
-RFC 4918 WebDAV June 2007
-
-
- 14.13. lockscope XML Element ...................................84
- 14.14. locktoken XML Element ...................................85
- 14.15. locktype XML Element ....................................85
- 14.16. multistatus XML Element .................................85
- 14.17. owner XML Element .......................................85
- 14.18. prop XML Element ........................................86
- 14.19. propertyupdate XML Element ..............................86
- 14.20. propfind XML Element ....................................86
- 14.21. propname XML Element ....................................87
- 14.22. propstat XML Element ....................................87
- 14.23. remove XML Element ......................................87
- 14.24. response XML Element ....................................88
- 14.25. responsedescription XML Element .........................88
- 14.26. set XML Element .........................................88
- 14.27. shared XML Element ......................................89
- 14.28. status XML Element ......................................89
- 14.29. timeout XML Element .....................................89
- 14.30. write XML Element .......................................89
- 15. DAV Properties ................................................90
- 16. Precondition/Postcondition XML Elements .......................98
- 17. XML Extensibility in DAV .....................................101
- 18. DAV Compliance Classes .......................................103
- 18.1. Class 1 .................................................103
- 18.2. Class 2 .................................................103
- 18.3. Class 3 .................................................103
- 19. Internationalization Considerations ..........................104
- 20. Security Considerations ......................................105
- 20.1. Authentication of Clients ...............................105
- 20.2. Denial of Service .......................................106
- 20.3. Security through Obscurity ..............................106
- 20.4. Privacy Issues Connected to Locks .......................106
- 20.5. Privacy Issues Connected to Properties ..................107
- 20.6. Implications of XML Entities ............................107
- 20.7. Risks Connected with Lock Tokens ........................108
- 20.8. Hosting Malicious Content ...............................108
- 21. IANA Considerations ..........................................109
- 21.1. New URI Schemes .........................................109
- 21.2. XML Namespaces ..........................................109
- 21.3. Message Header Fields ...................................109
- 21.3.1. DAV ..............................................109
- 21.3.2. Depth ............................................110
- 21.3.3. Destination ......................................110
- 21.3.4. If ...............................................110
- 21.3.5. Lock-Token .......................................110
- 21.3.6. Overwrite ........................................111
- 21.3.7. Timeout ..........................................111
- 21.4. HTTP Status Codes .......................................111
- 22. Acknowledgements .............................................112
-
-
-
-Dusseault Standards Track [Page 5]
-\f
-RFC 4918 WebDAV June 2007
-
-
- 23. Contributors to This Specification ...........................113
- 24. Authors of RFC 2518 ..........................................113
- 25. References ...................................................114
- 25.1. Normative References.....................................114
- 25.2. Informative References ..................................115
- Appendix A. Notes on Processing XML Elements ....................117
- A.1. Notes on Empty XML Elements ..............................117
- A.2. Notes on Illegal XML Processing ..........................117
- A.3. Example - XML Syntax Error ...............................117
- A.4. Example - Unexpected XML Element .........................118
- Appendix B. Notes on HTTP Client Compatibility ...................119
- Appendix C. The 'opaquelocktoken' Scheme and URIs ................120
- Appendix D. Lock-null Resources ..................................120
- D.1. Guidance for Clients Using LOCK to Create Resources ......121
- Appendix E. Guidance for Clients Desiring to Authenticate ........121
- Appendix F. Summary of Changes from RFC 2518 .....................123
- F.1. Changes for Both Client and Server Implementations .......123
- F.2. Changes for Server Implementations .......................125
- F.3. Other Changes ............................................126
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 6]
-\f
-RFC 4918 WebDAV June 2007
-
-
-1. Introduction
-
- This document describes an extension to the HTTP/1.1 protocol that
- allows clients to perform remote Web content authoring operations.
- This extension provides a coherent set of methods, headers, request
- entity body formats, and response entity body formats that provide
- operations for:
-
- Properties: The ability to create, remove, and query information
- about Web pages, such as their authors, creation dates, etc.
-
- Collections: The ability to create sets of documents and to retrieve
- a hierarchical membership listing (like a directory listing in a file
- system).
-
- Locking: The ability to keep more than one person from working on a
- document at the same time. This prevents the "lost update problem",
- in which modifications are lost as first one author, then another,
- writes changes without merging the other author's changes.
-
- Namespace Operations: The ability to instruct the server to copy and
- move Web resources, operations that change the mapping from URLs to
- resources.
-
- Requirements and rationale for these operations are described in a
- companion document, "Requirements for a Distributed Authoring and
- Versioning Protocol for the World Wide Web" [RFC2291].
-
- This document does not specify the versioning operations suggested by
- [RFC2291]. That work was done in a separate document, "Versioning
- Extensions to WebDAV" [RFC3253].
-
- The sections below provide a detailed introduction to various WebDAV
- abstractions: resource properties (Section 4), collections of
- resources (Section 5), locks (Section 6) in general, and write locks
- (Section 7) specifically.
-
- These abstractions are manipulated by the WebDAV-specific HTTP
- methods (Section 9) and the extra HTTP headers (Section 10) used with
- WebDAV methods. General considerations for handling HTTP requests
- and responses in WebDAV are found in Section 8.
-
- While the status codes provided by HTTP/1.1 are sufficient to
- describe most error conditions encountered by WebDAV methods, there
- are some errors that do not fall neatly into the existing categories.
- This specification defines extra status codes developed for WebDAV
- methods (Section 11) and describes existing HTTP status codes
- (Section 12) as used in WebDAV. Since some WebDAV methods may
-
-
-
-Dusseault Standards Track [Page 7]
-\f
-RFC 4918 WebDAV June 2007
-
-
- operate over many resources, the Multi-Status response (Section 13)
- has been introduced to return status information for multiple
- resources. Finally, this version of WebDAV introduces precondition
- and postcondition (Section 16) XML elements in error response bodies.
-
- WebDAV uses XML ([REC-XML]) for property names and some values, and
- also uses XML to marshal complicated requests and responses. This
- specification contains DTD and text definitions of all properties
- (Section 15) and all other XML elements (Section 14) used in
- marshalling. WebDAV includes a few special rules on extending WebDAV
- XML marshalling in backwards-compatible ways (Section 17).
-
- Finishing off the specification are sections on what it means for a
- resource to be compliant with this specification (Section 18), on
- internationalization support (Section 19), and on security
- (Section 20).
-
-2. Notational Conventions
-
- Since this document describes a set of extensions to the HTTP/1.1
- protocol, the augmented BNF used herein to describe protocol elements
- is exactly the same as described in Section 2.1 of [RFC2616],
- including the rules about implied linear whitespace. Since this
- augmented BNF uses the basic production rules provided in Section 2.2
- of [RFC2616], these rules apply to this document as well. Note this
- is not the standard BNF syntax used in other RFCs.
-
- 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].
-
- Note that in natural language, a property like the "creationdate"
- property in the "DAV:" XML namespace is sometimes referred to as
- "DAV:creationdate" for brevity.
-
-3. Terminology
-
- URI/URL - A Uniform Resource Identifier and Uniform Resource Locator,
- respectively. These terms (and the distinction between them) are
- defined in [RFC3986].
-
- URI/URL Mapping - A relation between an absolute URI and a resource.
- Since a resource can represent items that are not network
- retrievable, as well as those that are, it is possible for a resource
- to have zero, one, or many URI mappings. Mapping a resource to an
- "http" scheme URI makes it possible to submit HTTP protocol requests
- to the resource using the URI.
-
-
-
-
-Dusseault Standards Track [Page 8]
-\f
-RFC 4918 WebDAV June 2007
-
-
- Path Segment - Informally, the characters found between slashes ("/")
- in a URI. Formally, as defined in Section 3.3 of [RFC3986].
-
- Collection - Informally, a resource that also acts as a container of
- references to child resources. Formally, a resource that contains a
- set of mappings between path segments and resources and meets the
- requirements defined in Section 5.
-
- Internal Member (of a Collection) - Informally, a child resource of a
- collection. Formally, a resource referenced by a path segment
- mapping contained in the collection.
-
- Internal Member URL (of a Collection) - A URL of an internal member,
- consisting of the URL of the collection (including trailing slash)
- plus the path segment identifying the internal member.
-
- Member (of a Collection) - Informally, a "descendant" of a
- collection. Formally, an internal member of the collection, or,
- recursively, a member of an internal member.
-
- Member URL (of a Collection) - A URL that is either an internal
- member URL of the collection itself, or is an internal member URL of
- a member of that collection.
-
- Property - A name/value pair that contains descriptive information
- about a resource.
-
- Live Property - A property whose semantics and syntax are enforced by
- the server. For example, the live property DAV:getcontentlength has
- its value, the length of the entity returned by a GET request,
- automatically calculated by the server.
-
- Dead Property - A property whose semantics and syntax are not
- enforced by the server. The server only records the value of a dead
- property; the client is responsible for maintaining the consistency
- of the syntax and semantics of a dead property.
-
- Principal - A distinct human or computational actor that initiates
- access to network resources.
-
- State Token - A URI that represents a state of a resource. Lock
- tokens are the only state tokens defined in this specification.
-
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 9]
-\f
-RFC 4918 WebDAV June 2007
-
-
-4. Data Model for Resource Properties
-
-4.1. The Resource Property Model
-
- Properties are pieces of data that describe the state of a resource.
- Properties are data about data.
-
- Properties are used in distributed authoring environments to provide
- for efficient discovery and management of resources. For example, a
- 'subject' property might allow for the indexing of all resources by
- their subject, and an 'author' property might allow for the discovery
- of what authors have written which documents.
-
- The DAV property model consists of name/value pairs. The name of a
- property identifies the property's syntax and semantics, and provides
- an address by which to refer to its syntax and semantics.
-
- There are two categories of properties: "live" and "dead". A live
- property has its syntax and semantics enforced by the server. Live
- properties include cases where a) the value of a property is
- protected and maintained by the server, and b) the value of the
- property is maintained by the client, but the server performs syntax
- checking on submitted values. All instances of a given live property
- MUST comply with the definition associated with that property name.
- A dead property has its syntax and semantics enforced by the client;
- the server merely records the value of the property verbatim.
-
-4.2. Properties and HTTP Headers
-
- Properties already exist, in a limited sense, in HTTP message
- headers. However, in distributed authoring environments, a
- relatively large number of properties are needed to describe the
- state of a resource, and setting/returning them all through HTTP
- headers is inefficient. Thus, a mechanism is needed that allows a
- principal to identify a set of properties in which the principal is
- interested and to set or retrieve just those properties.
-
-4.3. Property Values
-
- The value of a property is always a (well-formed) XML fragment.
-
- XML has been chosen because it is a flexible, self-describing,
- structured data format that supports rich schema definitions, and
- because of its support for multiple character sets. XML's self-
- describing nature allows any property's value to be extended by
- adding elements. Clients will not break when they encounter
- extensions because they will still have the data specified in the
- original schema and MUST ignore elements they do not understand.
-
-
-
-Dusseault Standards Track [Page 10]
-\f
-RFC 4918 WebDAV June 2007
-
-
- XML's support for multiple character sets allows any human-readable
- property to be encoded and read in a character set familiar to the
- user. XML's support for multiple human languages, using the "xml:
- lang" attribute, handles cases where the same character set is
- employed by multiple human languages. Note that xml:lang scope is
- recursive, so an xml:lang attribute on any element containing a
- property name element applies to the property value unless it has
- been overridden by a more locally scoped attribute. Note that a
- property only has one value, in one language (or language MAY be left
- undefined); a property does not have multiple values in different
- languages or a single value in multiple languages.
-
- A property is always represented with an XML element consisting of
- the property name, called the "property name element". The simplest
- example is an empty property, which is different from a property that
- does not exist:
-
- <R:title xmlns:R="http://www.example.com/ns/"></R:title>
-
- The value of the property appears inside the property name element.
- The value may be any kind of well-formed XML content, including both
- text-only and mixed content. Servers MUST preserve the following XML
- Information Items (using the terminology from [REC-XML-INFOSET]) in
- storage and transmission of dead properties:
-
- For the property name Element Information Item itself:
-
- [namespace name]
-
- [local name]
-
- [attributes] named "xml:lang" or any such attribute in scope
-
- [children] of type element or character
-
- On all Element Information Items in the property value:
-
- [namespace name]
-
- [local name]
-
- [attributes]
-
- [children] of type element or character
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 11]
-\f
-RFC 4918 WebDAV June 2007
-
-
- On Attribute Information Items in the property value:
-
- [namespace name]
-
- [local name]
-
- [normalized value]
-
- On Character Information Items in the property value:
-
- [character code]
-
- Since prefixes are used in some XML vocabularies (XPath and XML
- Schema, for example), servers SHOULD preserve, for any Information
- Item in the value:
-
- [prefix]
-
- XML Infoset attributes not listed above MAY be preserved by the
- server, but clients MUST NOT rely on them being preserved. The above
- rules would also apply by default to live properties, unless defined
- otherwise.
-
- Servers MUST ignore the XML attribute xml:space if present and never
- use it to change whitespace handling. Whitespace in property values
- is significant.
-
-4.3.1. Example - Property with Mixed Content
-
- Consider a dead property 'author' created by the client as follows:
-
- <D:prop xml:lang="en" xmlns:D="DAV:">
- <x:author xmlns:x='http://example.com/ns'>
- <x:name>Jane Doe</x:name>
- <!-- Jane's contact info -->
- <x:uri type='email'
- added='2005-11-26'>mailto:jane.doe@example.com</x:uri>
- <x:uri type='web'
- added='2005-11-27'>http://www.example.com</x:uri>
- <x:notes xmlns:h='http://www.w3.org/1999/xhtml'>
- Jane has been working way <h:em>too</h:em> long on the
- long-awaited revision of <![CDATA[<RFC2518>]]>.
- </x:notes>
- </x:author>
- </D:prop>
-
-
-
-
-
-
-Dusseault Standards Track [Page 12]
-\f
-RFC 4918 WebDAV June 2007
-
-
- When this property is requested, a server might return:
-
- <D:prop xmlns:D='DAV:'><author
- xml:lang='en'
- xmlns:x='http://example.com/ns'
- xmlns='http://example.com/ns'
- xmlns:h='http://www.w3.org/1999/xhtml'>
- <x:name>Jane Doe</x:name>
- <x:uri added="2005-11-26" type="email"
- >mailto:jane.doe@example.com</x:uri>
- <x:uri added="2005-11-27" type="web"
- >http://www.example.com</x:uri>
- <x:notes>
- Jane has been working way <h:em>too</h:em> long on the
- long-awaited revision of <RFC2518>.
- </x:notes>
- </author>
- </D:prop>
-
- Note in this example:
-
- o The [prefix] for the property name itself was not preserved, being
- non-significant, whereas all other [prefix] values have been
- preserved,
-
- o attribute values have been rewritten with double quotes instead of
- single quotes (quoting style is not significant), and attribute
- order has not been preserved,
-
- o the xml:lang attribute has been returned on the property name
- element itself (it was in scope when the property was set, but the
- exact position in the response is not considered significant as
- long as it is in scope),
-
- o whitespace between tags has been preserved everywhere (whitespace
- between attributes not so),
-
- o CDATA encapsulation was replaced with character escaping (the
- reverse would also be legal),
-
- o the comment item was stripped (as would have been a processing
- instruction item).
-
- Implementation note: there are cases such as editing scenarios where
- clients may require that XML content is preserved character by
- character (such as attribute ordering or quoting style). In this
- case, clients should consider using a text-only property value by
- escaping all characters that have a special meaning in XML parsing.
-
-
-
-Dusseault Standards Track [Page 13]
-\f
-RFC 4918 WebDAV June 2007
-
-
-4.4. Property Names
-
- A property name is a universally unique identifier that is associated
- with a schema that provides information about the syntax and
- semantics of the property.
-
- Because a property's name is universally unique, clients can depend
- upon consistent behavior for a particular property across multiple
- resources, on the same and across different servers, so long as that
- property is "live" on the resources in question, and the
- implementation of the live property is faithful to its definition.
-
- The XML namespace mechanism, which is based on URIs ([RFC3986]), is
- used to name properties because it prevents namespace collisions and
- provides for varying degrees of administrative control.
-
- The property namespace is flat; that is, no hierarchy of properties
- is explicitly recognized. Thus, if a property A and a property A/B
- exist on a resource, there is no recognition of any relationship
- between the two properties. It is expected that a separate
- specification will eventually be produced that will address issues
- relating to hierarchical properties.
-
- Finally, it is not possible to define the same property twice on a
- single resource, as this would cause a collision in the resource's
- property namespace.
-
-4.5. Source Resources and Output Resources
-
- Some HTTP resources are dynamically generated by the server. For
- these resources, there presumably exists source code somewhere
- governing how that resource is generated. The relationship of source
- files to output HTTP resources may be one to one, one to many, many
- to one, or many to many. There is no mechanism in HTTP to determine
- whether a resource is even dynamic, let alone where its source files
- exist or how to author them. Although this problem would usefully be
- solved, interoperable WebDAV implementations have been widely
- deployed without actually solving this problem, by dealing only with
- static resources. Thus, the source vs. output problem is not solved
- in this specification and has been deferred to a separate document.
-
-5. Collections of Web Resources
-
- This section provides a description of a type of Web resource, the
- collection, and discusses its interactions with the HTTP URL
- namespace and with HTTP methods. The purpose of a collection
- resource is to model collection-like objects (e.g., file system
- directories) within a server's namespace.
-
-
-
-Dusseault Standards Track [Page 14]
-\f
-RFC 4918 WebDAV June 2007
-
-
- All DAV-compliant resources MUST support the HTTP URL namespace model
- specified herein.
-
-5.1. HTTP URL Namespace Model
-
- The HTTP URL namespace is a hierarchical namespace where the
- hierarchy is delimited with the "/" character.
-
- An HTTP URL namespace is said to be consistent if it meets the
- following conditions: for every URL in the HTTP hierarchy there
- exists a collection that contains that URL as an internal member URL.
- The root, or top-level collection of the namespace under
- consideration, is exempt from the previous rule. The top-level
- collection of the namespace under consideration is not necessarily
- the collection identified by the absolute path '/' -- it may be
- identified by one or more path segments (e.g., /servlets/webdav/...)
-
- Neither HTTP/1.1 nor WebDAV requires that the entire HTTP URL
- namespace be consistent -- a WebDAV-compatible resource may not have
- a parent collection. However, certain WebDAV methods are prohibited
- from producing results that cause namespace inconsistencies.
-
- As is implicit in [RFC2616] and [RFC3986], any resource, including
- collection resources, MAY be identified by more than one URI. For
- example, a resource could be identified by multiple HTTP URLs.
-
-5.2. Collection Resources
-
- Collection resources differ from other resources in that they also
- act as containers. Some HTTP methods apply only to a collection, but
- some apply to some or all of the resources inside the container
- defined by the collection. When the scope of a method is not clear,
- the client can specify what depth to apply. Depth can be either zero
- levels (only the collection), one level (the collection and directly
- contained resources), or infinite levels (the collection and all
- contained resources recursively).
-
- A collection's state consists of at least a set of mappings between
- path segments and resources, and a set of properties on the
- collection itself. In this document, a resource B will be said to be
- contained in the collection resource A if there is a path segment
- mapping that maps to B and that is contained in A. A collection MUST
- contain at most one mapping for a given path segment, i.e., it is
- illegal to have the same path segment mapped to more than one
- resource.
-
-
-
-
-
-
-Dusseault Standards Track [Page 15]
-\f
-RFC 4918 WebDAV June 2007
-
-
- Properties defined on collections behave exactly as do properties on
- non-collection resources. A collection MAY have additional state
- such as entity bodies returned by GET.
-
- For all WebDAV-compliant resources A and B, identified by URLs "U"
- and "V", respectively, such that "V" is equal to "U/SEGMENT", A MUST
- be a collection that contains a mapping from "SEGMENT" to B. So, if
- resource B with URL "http://example.com/bar/blah" is WebDAV compliant
- and if resource A with URL "http://example.com/bar/" is WebDAV
- compliant, then resource A must be a collection and must contain
- exactly one mapping from "blah" to B.
-
- Although commonly a mapping consists of a single segment and a
- resource, in general, a mapping consists of a set of segments and a
- resource. This allows a server to treat a set of segments as
- equivalent (i.e., either all of the segments are mapped to the same
- resource, or none of the segments are mapped to a resource). For
- example, a server that performs case-folding on segments will treat
- the segments "ab", "Ab", "aB", and "AB" as equivalent. A client can
- then use any of these segments to identify the resource. Note that a
- PROPFIND result will select one of these equivalent segments to
- identify the mapping, so there will be one PROPFIND response element
- per mapping, not one per segment in the mapping.
-
- Collection resources MAY have mappings to non-WebDAV-compliant
- resources in the HTTP URL namespace hierarchy but are not required to
- do so. For example, if resource X with URL
- "http://example.com/bar/blah" is not WebDAV compliant and resource A
- with "URL http://example.com/bar/" identifies a WebDAV collection,
- then A may or may not have a mapping from "blah" to X.
-
- If a WebDAV-compliant resource has no WebDAV-compliant internal
- members in the HTTP URL namespace hierarchy, then the WebDAV-
- compliant resource is not required to be a collection.
-
- There is a standing convention that when a collection is referred to
- by its name without a trailing slash, the server MAY handle the
- request as if the trailing slash were present. In this case, it
- SHOULD return a Content-Location header in the response, pointing to
- the URL ending with the "/". For example, if a client invokes a
- method on http://example.com/blah (no trailing slash), the server may
- respond as if the operation were invoked on http://example.com/blah/
- (trailing slash), and should return a Content-Location header with
- the value http://example.com/blah/. Wherever a server produces a URL
- referring to a collection, the server SHOULD include the trailing
- slash. In general, clients SHOULD use the trailing slash form of
- collection names. If clients do not use the trailing slash form the
- client needs to be prepared to see a redirect response. Clients will
-
-
-
-Dusseault Standards Track [Page 16]
-\f
-RFC 4918 WebDAV June 2007
-
-
- find the DAV:resourcetype property more reliable than the URL to find
- out if a resource is a collection.
-
- Clients MUST be able to support the case where WebDAV resources are
- contained inside non-WebDAV resources. For example, if an OPTIONS
- response from "http://example.com/servlet/dav/collection" indicates
- WebDAV support, the client cannot assume that
- "http://example.com/servlet/dav/" or its parent necessarily are
- WebDAV collections.
-
- A typical scenario in which mapped URLs do not appear as members of
- their parent collection is the case where a server allows links or
- redirects to non-WebDAV resources. For instance, "/col/link" might
- not appear as a member of "/col/", although the server would respond
- with a 302 status to a GET request to "/col/link"; thus, the URL
- "/col/link" would indeed be mapped. Similarly, a dynamically-
- generated page might have a URL mapping from "/col/index.html", thus
- this resource might respond with a 200 OK to a GET request yet not
- appear as a member of "/col/".
-
- Some mappings to even WebDAV-compliant resources might not appear in
- the parent collection. An example for this case are servers that
- support multiple alias URLs for each WebDAV-compliant resource. A
- server may implement case-insensitive URLs, thus "/col/a" and
- "/col/A" identify the same resource, yet only either "a" or "A" is
- reported upon listing the members of "/col". In cases where a server
- treats a set of segments as equivalent, the server MUST expose only
- one preferred segment per mapping, consistently chosen, in PROPFIND
- responses.
-
-6. Locking
-
- The ability to lock a resource provides a mechanism for serializing
- access to that resource. Using a lock, an authoring client can
- provide a reasonable guarantee that another principal will not modify
- a resource while it is being edited. In this way, a client can
- prevent the "lost update" problem.
-
- This specification allows locks to vary over two client-specified
- parameters, the number of principals involved (exclusive vs. shared)
- and the type of access to be granted. This document defines locking
- for only one access type, write. However, the syntax is extensible,
- and permits the eventual specification of locking for other access
- types.
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 17]
-\f
-RFC 4918 WebDAV June 2007
-
-
-6.1. Lock Model
-
- This section provides a concise model for how locking behaves. Later
- sections will provide more detail on some of the concepts and refer
- back to these model statements. Normative statements related to LOCK
- and UNLOCK method handling can be found in the sections on those
- methods, whereas normative statements that cover any method are
- gathered here.
-
- 1. A lock either directly or indirectly locks a resource.
-
- 2. A resource becomes directly locked when a LOCK request to a URL
- of that resource creates a new lock. The "lock-root" of the new
- lock is that URL. If at the time of the request, the URL is not
- mapped to a resource, a new empty resource is created and
- directly locked.
-
- 3. An exclusive lock (Section 6.2) conflicts with any other kind of
- lock on the same resource, whether either lock is direct or
- indirect. A server MUST NOT create conflicting locks on a
- resource.
-
- 4. For a collection that is locked with a depth-infinity lock L, all
- member resources are indirectly locked. Changes in membership of
- such a collection affect the set of indirectly locked resources:
-
- * If a member resource is added to the collection, the new
- member resource MUST NOT already have a conflicting lock,
- because the new resource MUST become indirectly locked by L.
-
- * If a member resource stops being a member of the collection,
- then the resource MUST no longer be indirectly locked by L.
-
- 5. Each lock is identified by a single globally unique lock token
- (Section 6.5).
-
- 6. An UNLOCK request deletes the lock with the specified lock token.
- After a lock is deleted, no resource is locked by that lock.
-
- 7. A lock token is "submitted" in a request when it appears in an
- "If" header (Section 7, "Write Lock", discusses when token
- submission is required for write locks).
-
- 8. If a request causes the lock-root of any lock to become an
- unmapped URL, then the lock MUST also be deleted by that request.
-
-
-
-
-
-
-Dusseault Standards Track [Page 18]
-\f
-RFC 4918 WebDAV June 2007
-
-
-6.2. Exclusive vs. Shared Locks
-
- The most basic form of lock is an exclusive lock. Exclusive locks
- avoid having to deal with content change conflicts, without requiring
- any coordination other than the methods described in this
- specification.
-
- However, there are times when the goal of a lock is not to exclude
- others from exercising an access right but rather to provide a
- mechanism for principals to indicate that they intend to exercise
- their access rights. Shared locks are provided for this case. A
- shared lock allows multiple principals to receive a lock. Hence any
- principal that has both access privileges and a valid lock can use
- the locked resource.
-
- With shared locks, there are two trust sets that affect a resource.
- The first trust set is created by access permissions. Principals who
- are trusted, for example, may have permission to write to the
- resource. Among those who have access permission to write to the
- resource, the set of principals who have taken out a shared lock also
- must trust each other, creating a (typically) smaller trust set
- within the access permission write set.
-
- Starting with every possible principal on the Internet, in most
- situations the vast majority of these principals will not have write
- access to a given resource. Of the small number who do have write
- access, some principals may decide to guarantee their edits are free
- from overwrite conflicts by using exclusive write locks. Others may
- decide they trust their collaborators will not overwrite their work
- (the potential set of collaborators being the set of principals who
- have write permission) and use a shared lock, which informs their
- collaborators that a principal may be working on the resource.
-
- The WebDAV extensions to HTTP do not need to provide all of the
- communications paths necessary for principals to coordinate their
- activities. When using shared locks, principals may use any out-of-
- band communication channel to coordinate their work (e.g., face-to-
- face interaction, written notes, post-it notes on the screen,
- telephone conversation, email, etc.) The intent of a shared lock is
- to let collaborators know who else may be working on a resource.
-
- Shared locks are included because experience from Web-distributed
- authoring systems has indicated that exclusive locks are often too
- rigid. An exclusive lock is used to enforce a particular editing
- process: take out an exclusive lock, read the resource, perform
- edits, write the resource, release the lock. This editing process
- has the problem that locks are not always properly released, for
- example, when a program crashes or when a lock creator leaves without
-
-
-
-Dusseault Standards Track [Page 19]
-\f
-RFC 4918 WebDAV June 2007
-
-
- unlocking a resource. While both timeouts (Section 6.6) and
- administrative action can be used to remove an offending lock,
- neither mechanism may be available when needed; the timeout may be
- long or the administrator may not be available.
-
- A successful request for a new shared lock MUST result in the
- generation of a unique lock associated with the requesting principal.
- Thus, if five principals have taken out shared write locks on the
- same resource, there will be five locks and five lock tokens, one for
- each principal.
-
-6.3. Required Support
-
- A WebDAV-compliant resource is not required to support locking in any
- form. If the resource does support locking, it may choose to support
- any combination of exclusive and shared locks for any access types.
-
- The reason for this flexibility is that locking policy strikes to the
- very heart of the resource management and versioning systems employed
- by various storage repositories. These repositories require control
- over what sort of locking will be made available. For example, some
- repositories only support shared write locks, while others only
- provide support for exclusive write locks, while yet others use no
- locking at all. As each system is sufficiently different to merit
- exclusion of certain locking features, this specification leaves
- locking as the sole axis of negotiation within WebDAV.
-
-6.4. Lock Creator and Privileges
-
- The creator of a lock has special privileges to use the lock to
- modify the resource. When a locked resource is modified, a server
- MUST check that the authenticated principal matches the lock creator
- (in addition to checking for valid lock token submission).
-
- The server MAY allow privileged users other than the lock creator to
- destroy a lock (for example, the resource owner or an administrator).
- The 'unlock' privilege in [RFC3744] was defined to provide that
- permission.
-
- There is no requirement for servers to accept LOCK requests from all
- users or from anonymous users.
-
- Note that having a lock does not confer full privilege to modify the
- locked resource. Write access and other privileges MUST be enforced
- through normal privilege or authentication mechanisms, not based on
- the possible obscurity of lock token values.
-
-
-
-
-
-Dusseault Standards Track [Page 20]
-\f
-RFC 4918 WebDAV June 2007
-
-
-6.5. Lock Tokens
-
- A lock token is a type of state token that identifies a particular
- lock. Each lock has exactly one unique lock token generated by the
- server. Clients MUST NOT attempt to interpret lock tokens in any
- way.
-
- Lock token URIs MUST be unique across all resources for all time.
- This uniqueness constraint allows lock tokens to be submitted across
- resources and servers without fear of confusion. Since lock tokens
- are unique, a client MAY submit a lock token in an If header on a
- resource other than the one that returned it.
-
- When a LOCK operation creates a new lock, the new lock token is
- returned in the Lock-Token response header defined in Section 10.5,
- and also in the body of the response.
-
- Servers MAY make lock tokens publicly readable (e.g., in the DAV:
- lockdiscovery property). One use case for making lock tokens
- readable is so that a long-lived lock can be removed by the resource
- owner (the client that obtained the lock might have crashed or
- disconnected before cleaning up the lock). Except for the case of
- using UNLOCK under user guidance, a client SHOULD NOT use a lock
- token created by another client instance.
-
- This specification encourages servers to create Universally Unique
- Identifiers (UUIDs) for lock tokens, and to use the URI form defined
- by "A Universally Unique Identifier (UUID) URN Namespace"
- ([RFC4122]). However, servers are free to use any URI (e.g., from
- another scheme) so long as it meets the uniqueness requirements. For
- example, a valid lock token might be constructed using the
- "opaquelocktoken" scheme defined in Appendix C.
-
- Example: "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
-
-6.6. Lock Timeout
-
- A lock MAY have a limited lifetime. The lifetime is suggested by the
- client when creating or refreshing the lock, but the server
- ultimately chooses the timeout value. Timeout is measured in seconds
- remaining until lock expiration.
-
- The timeout counter MUST be restarted if a refresh lock request is
- successful (see Section 9.10.2). The timeout counter SHOULD NOT be
- restarted at any other time.
-
- If the timeout expires, then the lock SHOULD be removed. In this
- case the server SHOULD act as if an UNLOCK method was executed by the
-
-
-
-Dusseault Standards Track [Page 21]
-\f
-RFC 4918 WebDAV June 2007
-
-
- server on the resource using the lock token of the timed-out lock,
- performed with its override authority.
-
- Servers are advised to pay close attention to the values submitted by
- clients, as they will be indicative of the type of activity the
- client intends to perform. For example, an applet running in a
- browser may need to lock a resource, but because of the instability
- of the environment within which the applet is running, the applet may
- be turned off without warning. As a result, the applet is likely to
- ask for a relatively small timeout value so that if the applet dies,
- the lock can be quickly harvested. However, a document management
- system is likely to ask for an extremely long timeout because its
- user may be planning on going offline.
-
- A client MUST NOT assume that just because the timeout has expired,
- the lock has immediately been removed.
-
- Likewise, a client MUST NOT assume that just because the timeout has
- not expired, the lock still exists. Clients MUST assume that locks
- can arbitrarily disappear at any time, regardless of the value given
- in the Timeout header. The Timeout header only indicates the
- behavior of the server if extraordinary circumstances do not occur.
- For example, a sufficiently privileged user may remove a lock at any
- time, or the system may crash in such a way that it loses the record
- of the lock's existence.
-
-6.7. Lock Capability Discovery
-
- Since server lock support is optional, a client trying to lock a
- resource on a server can either try the lock and hope for the best,
- or perform some form of discovery to determine what lock capabilities
- the server supports. This is known as lock capability discovery. A
- client can determine what lock types the server supports by
- retrieving the DAV:supportedlock property.
-
- Any DAV-compliant resource that supports the LOCK method MUST support
- the DAV:supportedlock property.
-
-6.8. Active Lock Discovery
-
- If another principal locks a resource that a principal wishes to
- access, it is useful for the second principal to be able to find out
- who the first principal is. For this purpose the DAV:lockdiscovery
- property is provided. This property lists all outstanding locks,
- describes their type, and MAY even provide the lock tokens.
-
- Any DAV-compliant resource that supports the LOCK method MUST support
- the DAV:lockdiscovery property.
-
-
-
-Dusseault Standards Track [Page 22]
-\f
-RFC 4918 WebDAV June 2007
-
-
-7. Write Lock
-
- This section describes the semantics specific to the write lock type.
- The write lock is a specific instance of a lock type, and is the only
- lock type described in this specification.
-
- An exclusive write lock protects a resource: it prevents changes by
- any principal other than the lock creator and in any case where the
- lock token is not submitted (e.g., by a client process other than the
- one holding the lock).
-
- Clients MUST submit a lock-token they are authorized to use in any
- request that modifies a write-locked resource. The list of
- modifications covered by a write-lock include:
-
- 1. A change to any of the following aspects of any write-locked
- resource:
-
- * any variant,
-
- * any dead property,
-
- * any live property that is lockable (a live property is
- lockable unless otherwise defined.)
-
- 2. For collections, any modification of an internal member URI. An
- internal member URI of a collection is considered to be modified
- if it is added, removed, or identifies a different resource.
- More discussion on write locks and collections is found in
- Section 7.4.
-
- 3. A modification of the mapping of the root of the write lock,
- either to another resource or to no resource (e.g., DELETE).
-
- Of the methods defined in HTTP and WebDAV, PUT, POST, PROPPATCH,
- LOCK, UNLOCK, MOVE, COPY (for the destination resource), DELETE, and
- MKCOL are affected by write locks. All other HTTP/WebDAV methods
- defined so far -- GET in particular -- function independently of a
- write lock.
-
- The next few sections describe in more specific terms how write locks
- interact with various operations.
-
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 23]
-\f
-RFC 4918 WebDAV June 2007
-
-
-7.1. Write Locks and Properties
-
- While those without a write lock may not alter a property on a
- resource it is still possible for the values of live properties to
- change, even while locked, due to the requirements of their schemas.
- Only dead properties and live properties defined as lockable are
- guaranteed not to change while write locked.
-
-7.2. Avoiding Lost Updates
-
- Although the write locks provide some help in preventing lost
- updates, they cannot guarantee that updates will never be lost.
- Consider the following scenario:
-
- Two clients A and B are interested in editing the resource
- 'index.html'. Client A is an HTTP client rather than a WebDAV
- client, and so does not know how to perform locking.
-
- Client A doesn't lock the document, but does a GET, and begins
- editing.
-
- Client B does LOCK, performs a GET and begins editing.
-
- Client B finishes editing, performs a PUT, then an UNLOCK.
-
- Client A performs a PUT, overwriting and losing all of B's changes.
-
- There are several reasons why the WebDAV protocol itself cannot
- prevent this situation. First, it cannot force all clients to use
- locking because it must be compatible with HTTP clients that do not
- comprehend locking. Second, it cannot require servers to support
- locking because of the variety of repository implementations, some of
- which rely on reservations and merging rather than on locking.
- Finally, being stateless, it cannot enforce a sequence of operations
- like LOCK / GET / PUT / UNLOCK.
-
- WebDAV servers that support locking can reduce the likelihood that
- clients will accidentally overwrite each other's changes by requiring
- clients to lock resources before modifying them. Such servers would
- effectively prevent HTTP 1.0 and HTTP 1.1 clients from modifying
- resources.
-
- WebDAV clients can be good citizens by using a lock / retrieve /
- write /unlock sequence of operations (at least by default) whenever
- they interact with a WebDAV server that supports locking.
-
-
-
-
-
-
-Dusseault Standards Track [Page 24]
-\f
-RFC 4918 WebDAV June 2007
-
-
- HTTP 1.1 clients can be good citizens, avoiding overwriting other
- clients' changes, by using entity tags in If-Match headers with any
- requests that would modify resources.
-
- Information managers may attempt to prevent overwrites by
- implementing client-side procedures requiring locking before
- modifying WebDAV resources.
-
-7.3. Write Locks and Unmapped URLs
-
- WebDAV provides the ability to send a LOCK request to an unmapped URL
- in order to reserve the name for use. This is a simple way to avoid
- the lost-update problem on the creation of a new resource (another
- way is to use If-None-Match header specified in Section 14.26 of
- [RFC2616]). It has the side benefit of locking the new resource
- immediately for use of the creator.
-
- Note that the lost-update problem is not an issue for collections
- because MKCOL can only be used to create a collection, not to
- overwrite an existing collection. When trying to lock a collection
- upon creation, clients can attempt to increase the likelihood of
- getting the lock by pipelining the MKCOL and LOCK requests together
- (but because this doesn't convert two separate operations into one
- atomic operation, there's no guarantee this will work).
-
- A successful lock request to an unmapped URL MUST result in the
- creation of a locked (non-collection) resource with empty content.
- Subsequently, a successful PUT request (with the correct lock token)
- provides the content for the resource. Note that the LOCK request
- has no mechanism for the client to provide Content-Type or Content-
- Language, thus the server will use defaults or empty values and rely
- on the subsequent PUT request for correct values.
-
- A resource created with a LOCK is empty but otherwise behaves in
- every way as a normal resource. It behaves the same way as a
- resource created by a PUT request with an empty body (and where a
- Content-Type and Content-Language was not specified), followed by a
- LOCK request to the same resource. Following from this model, a
- locked empty resource:
-
- o Can be read, deleted, moved, and copied, and in all ways behaves
- as a regular non-collection resource.
-
- o Appears as a member of its parent collection.
-
- o SHOULD NOT disappear when its lock goes away (clients must
- therefore be responsible for cleaning up their own mess, as with
- any other operation or any non-empty resource).
-
-
-
-Dusseault Standards Track [Page 25]
-\f
-RFC 4918 WebDAV June 2007
-
-
- o MAY NOT have values for properties like DAV:getcontentlanguage
- that haven't been specified yet by the client.
-
- o Can be updated (have content added) with a PUT request.
-
- o MUST NOT be converted into a collection. The server MUST fail a
- MKCOL request (as it would with a MKCOL request to any existing
- non-collection resource).
-
- o MUST have defined values for DAV:lockdiscovery and DAV:
- supportedlock properties.
-
- o The response MUST indicate that a resource was created, by use of
- the "201 Created" response code (a LOCK request to an existing
- resource instead will result in 200 OK). The body must still
- include the DAV:lockdiscovery property, as with a LOCK request to
- an existing resource.
-
- The client is expected to update the locked empty resource shortly
- after locking it, using PUT and possibly PROPPATCH.
-
- Alternatively and for backwards compatibility to [RFC2518], servers
- MAY implement Lock-Null Resources (LNRs) instead (see definition in
- Appendix D). Clients can easily interoperate both with servers that
- support the old model LNRs and the recommended model of "locked empty
- resources" by only attempting PUT after a LOCK to an unmapped URL,
- not MKCOL or GET, and by not relying on specific properties of LNRs.
-
-7.4. Write Locks and Collections
-
- There are two kinds of collection write locks. A depth-0 write lock
- on a collection protects the collection properties plus the internal
- member URLs of that one collection, while not protecting the content
- or properties of member resources (if the collection itself has any
- entity bodies, those are also protected). A depth-infinity write
- lock on a collection provides the same protection on that collection
- and also provides write lock protection on every member resource.
-
- Expressed otherwise, a write lock of either kind protects any request
- that would create a new resource in a write locked collection, any
- request that would remove an internal member URL of a write locked
- collection, and any request that would change the segment name of any
- internal member.
-
- Thus, a collection write lock protects all the following actions:
-
- o DELETE a collection's direct internal member,
-
-
-
-
-Dusseault Standards Track [Page 26]
-\f
-RFC 4918 WebDAV June 2007
-
-
- o MOVE an internal member out of the collection,
-
- o MOVE an internal member into the collection,
-
- o MOVE to rename an internal member within a collection,
-
- o COPY an internal member into a collection, and
-
- o PUT or MKCOL request that would create a new internal member.
-
- The collection's lock token is required in addition to the lock token
- on the internal member itself, if it is locked separately.
-
- In addition, a depth-infinity lock affects all write operations to
- all members of the locked collection. With a depth-infinity lock,
- the resource identified by the root of the lock is directly locked,
- and all its members are indirectly locked.
-
- o Any new resource added as a descendant of a depth-infinity locked
- collection becomes indirectly locked.
-
- o Any indirectly locked resource moved out of the locked collection
- into an unlocked collection is thereafter unlocked.
-
- o Any indirectly locked resource moved out of a locked source
- collection into a depth-infinity locked target collection remains
- indirectly locked but is now protected by the lock on the target
- collection (the target collection's lock token will thereafter be
- required to make further changes).
-
- If a depth-infinity write LOCK request is issued to a collection
- containing member URLs identifying resources that are currently
- locked in a manner that conflicts with the new lock (see Section 6.1,
- point 3), the request MUST fail with a 423 (Locked) status code, and
- the response SHOULD contain the 'no-conflicting-lock' precondition.
-
- If a lock request causes the URL of a resource to be added as an
- internal member URL of a depth-infinity locked collection, then the
- new resource MUST be automatically protected by the lock. For
- example, if the collection /a/b/ is write locked and the resource /c
- is moved to /a/b/c, then resource /a/b/c will be added to the write
- lock.
-
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 27]
-\f
-RFC 4918 WebDAV June 2007
-
-
-7.5. Write Locks and the If Request Header
-
- A user agent has to demonstrate knowledge of a lock when requesting
- an operation on a locked resource. Otherwise, the following scenario
- might occur. In the scenario, program A, run by User A, takes out a
- write lock on a resource. Program B, also run by User A, has no
- knowledge of the lock taken out by program A, yet performs a PUT to
- the locked resource. In this scenario, the PUT succeeds because
- locks are associated with a principal, not a program, and thus
- program B, because it is acting with principal A's credential, is
- allowed to perform the PUT. However, had program B known about the
- lock, it would not have overwritten the resource, preferring instead
- to present a dialog box describing the conflict to the user. Due to
- this scenario, a mechanism is needed to prevent different programs
- from accidentally ignoring locks taken out by other programs with the
- same authorization.
-
- In order to prevent these collisions, a lock token MUST be submitted
- by an authorized principal for all locked resources that a method may
- change or the method MUST fail. A lock token is submitted when it
- appears in an If header. For example, if a resource is to be moved
- and both the source and destination are locked, then two lock tokens
- must be submitted in the If header, one for the source and the other
- for the destination.
-
-7.5.1. Example - Write Lock and COPY
-
- >>Request
-
- COPY /~fielding/index.html HTTP/1.1
- Host: www.example.com
- Destination: http://www.example.com/users/f/fielding/index.html
- If: <http://www.example.com/users/f/fielding/index.html>
- (<urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6>)
-
- >>Response
-
- HTTP/1.1 204 No Content
-
- In this example, even though both the source and destination are
- locked, only one lock token must be submitted (the one for the lock
- on the destination). This is because the source resource is not
- modified by a COPY, and hence unaffected by the write lock. In this
- example, user agent authentication has previously occurred via a
- mechanism outside the scope of the HTTP protocol, in the underlying
- transport layer.
-
-
-
-
-
-Dusseault Standards Track [Page 28]
-\f
-RFC 4918 WebDAV June 2007
-
-
-7.5.2. Example - Deleting a Member of a Locked Collection
-
- Consider a collection "/locked" with an exclusive, depth-infinity
- write lock, and an attempt to delete an internal member "/locked/
- member":
-
- >>Request
-
- DELETE /locked/member HTTP/1.1
- Host: example.com
-
- >>Response
-
- HTTP/1.1 423 Locked
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:error xmlns:D="DAV:">
- <D:lock-token-submitted>
- <D:href>/locked/</D:href>
- </D:lock-token-submitted>
- </D:error>
-
- Thus, the client would need to submit the lock token with the request
- to make it succeed. To do that, various forms of the If header (see
- Section 10.4) could be used.
-
- "No-Tag-List" format:
-
- If: (<urn:uuid:150852e2-3847-42d5-8cbe-0f4f296f26cf>)
-
- "Tagged-List" format, for "http://example.com/locked/":
-
- If: <http://example.com/locked/>
- (<urn:uuid:150852e2-3847-42d5-8cbe-0f4f296f26cf>)
-
- "Tagged-List" format, for "http://example.com/locked/member":
-
- If: <http://example.com/locked/member>
- (<urn:uuid:150852e2-3847-42d5-8cbe-0f4f296f26cf>)
-
- Note that, for the purpose of submitting the lock token, the actual
- form doesn't matter; what's relevant is that the lock token appears
- in the If header, and that the If header itself evaluates to true.
-
-
-
-
-
-
-Dusseault Standards Track [Page 29]
-\f
-RFC 4918 WebDAV June 2007
-
-
-7.6. Write Locks and COPY/MOVE
-
- A COPY method invocation MUST NOT duplicate any write locks active on
- the source. However, as previously noted, if the COPY copies the
- resource into a collection that is locked with a depth-infinity lock,
- then the resource will be added to the lock.
-
- A successful MOVE request on a write locked resource MUST NOT move
- the write lock with the resource. However, if there is an existing
- lock at the destination, the server MUST add the moved resource to
- the destination lock scope. For example, if the MOVE makes the
- resource a child of a collection that has a depth-infinity lock, then
- the resource will be added to that collection's lock. Additionally,
- if a resource with a depth-infinity lock is moved to a destination
- that is within the scope of the same lock (e.g., within the URL
- namespace tree covered by the lock), the moved resource will again be
- added to the lock. In both these examples, as specified in
- Section 7.5, an If header must be submitted containing a lock token
- for both the source and destination.
-
-7.7. Refreshing Write Locks
-
- A client MUST NOT submit the same write lock request twice. Note
- that a client is always aware it is resubmitting the same lock
- request because it must include the lock token in the If header in
- order to make the request for a resource that is already locked.
-
- However, a client may submit a LOCK request with an If header but
- without a body. A server receiving a LOCK request with no body MUST
- NOT create a new lock -- this form of the LOCK request is only to be
- used to "refresh" an existing lock (meaning, at minimum, that any
- timers associated with the lock MUST be reset).
-
- Clients may submit Timeout headers of arbitrary value with their lock
- refresh requests. Servers, as always, may ignore Timeout headers
- submitted by the client, and a server MAY refresh a lock with a
- timeout period that is different than the previous timeout period
- used for the lock, provided it advertises the new value in the LOCK
- refresh response.
-
- If an error is received in response to a refresh LOCK request, the
- client MUST NOT assume that the lock was refreshed.
-
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 30]
-\f
-RFC 4918 WebDAV June 2007
-
-
-8. General Request and Response Handling
-
-8.1. Precedence in Error Handling
-
- Servers MUST return authorization errors in preference to other
- errors. This avoids leaking information about protected resources
- (e.g., a client that finds that a hidden resource exists by seeing a
- 423 Locked response to an anonymous request to the resource).
-
-8.2. Use of XML
-
- In HTTP/1.1, method parameter information was exclusively encoded in
- HTTP headers. Unlike HTTP/1.1, WebDAV encodes method parameter
- information either in an XML ([REC-XML]) request entity body, or in
- an HTTP header. The use of XML to encode method parameters was
- motivated by the ability to add extra XML elements to existing
- structures, providing extensibility; and by XML's ability to encode
- information in ISO 10646 character sets, providing
- internationalization support.
-
- In addition to encoding method parameters, XML is used in WebDAV to
- encode the responses from methods, providing the extensibility and
- internationalization advantages of XML for method output, as well as
- input.
-
- When XML is used for a request or response body, the Content-Type
- type SHOULD be application/xml. Implementations MUST accept both
- text/xml and application/xml in request and response bodies. Use of
- text/xml is deprecated.
-
- All DAV-compliant clients and resources MUST use XML parsers that are
- compliant with [REC-XML] and [REC-XML-NAMES]. All XML used in either
- requests or responses MUST be, at minimum, well formed and use
- namespaces correctly. If a server receives XML that is not well-
- formed, then the server MUST reject the entire request with a 400
- (Bad Request). If a client receives XML that is not well-formed in a
- response, then the client MUST NOT assume anything about the outcome
- of the executed method and SHOULD treat the server as malfunctioning.
-
- Note that processing XML submitted by an untrusted source may cause
- risks connected to privacy, security, and service quality (see
- Section 20). Servers MAY reject questionable requests (even though
- they consist of well-formed XML), for instance, with a 400 (Bad
- Request) status code and an optional response body explaining the
- problem.
-
-
-
-
-
-
-Dusseault Standards Track [Page 31]
-\f
-RFC 4918 WebDAV June 2007
-
-
-8.3. URL Handling
-
- URLs appear in many places in requests and responses.
- Interoperability experience with [RFC2518] showed that many clients
- parsing Multi-Status responses did not fully implement the full
- Reference Resolution defined in Section 5 of [RFC3986]. Thus,
- servers in particular need to be careful in handling URLs in
- responses, to ensure that clients have enough context to be able to
- interpret all the URLs. The rules in this section apply not only to
- resource URLs in the 'href' element in Multi-Status responses, but
- also to the Destination and If header resource URLs.
-
- The sender has a choice between two approaches: using a relative
- reference, which is resolved against the Request-URI, or a full URI.
- A server MUST ensure that every 'href' value within a Multi-Status
- response uses the same format.
-
- WebDAV only uses one form of relative reference in its extensions,
- the absolute path.
-
- Simple-ref = absolute-URI | ( path-absolute [ "?" query ] )
-
- The absolute-URI, path-absolute and query productions are defined in
- Sections 4.3, 3.3, and 3.4 of [RFC3986].
-
- Within Simple-ref productions, senders MUST NOT:
-
- o use dot-segments ("." or ".."), or
-
- o have prefixes that do not match the Request-URI (using the
- comparison rules defined in Section 3.2.3 of [RFC2616]).
-
- Identifiers for collections SHOULD end in a '/' character.
-
-8.3.1. Example - Correct URL Handling
-
- Consider the collection http://example.com/sample/ with the internal
- member URL http://example.com/sample/a%20test and the PROPFIND
- request below:
-
- >>Request:
-
- PROPFIND /sample/ HTTP/1.1
- Host: example.com
- Depth: 1
-
-
-
-
-
-
-Dusseault Standards Track [Page 32]
-\f
-RFC 4918 WebDAV June 2007
-
-
- In this case, the server should return two 'href' elements containing
- either
-
- o 'http://example.com/sample/' and
- 'http://example.com/sample/a%20test', or
-
- o '/sample/' and '/sample/a%20test'
-
- Note that even though the server may be storing the member resource
- internally as 'a test', it has to be percent-encoded when used inside
- a URI reference (see Section 2.1 of [RFC3986]). Also note that a
- legal URI may still contain characters that need to be escaped within
- XML character data, such as the ampersand character.
-
-8.4. Required Bodies in Requests
-
- Some of these new methods do not define bodies. Servers MUST examine
- all requests for a body, even when a body was not expected. In cases
- where a request body is present but would be ignored by a server, the
- server MUST reject the request with 415 (Unsupported Media Type).
- This informs the client (which may have been attempting to use an
- extension) that the body could not be processed as the client
- intended.
-
-8.5. HTTP Headers for Use in WebDAV
-
- HTTP defines many headers that can be used in WebDAV requests and
- responses. Not all of these are appropriate in all situations and
- some interactions may be undefined. Note that HTTP 1.1 requires the
- Date header in all responses if possible (see Section 14.18,
- [RFC2616]).
-
- The server MUST do authorization checks before checking any HTTP
- conditional header.
-
-8.6. ETag
-
- HTTP 1.1 recommends the use of ETags rather than modification dates,
- for cache control, and there are even stronger reasons to prefer
- ETags for authoring. Correct use of ETags is even more important in
- a distributed authoring environment, because ETags are necessary
- along with locks to avoid the lost-update problem. A client might
- fail to renew a lock, for example, when the lock times out and the
- client is accidentally offline or in the middle of a long upload.
- When a client fails to renew the lock, it's quite possible the
- resource can still be relocked and the user can go on editing, as
- long as no changes were made in the meantime. ETags are required for
- the client to be able to distinguish this case. Otherwise, the
-
-
-
-Dusseault Standards Track [Page 33]
-\f
-RFC 4918 WebDAV June 2007
-
-
- client is forced to ask the user whether to overwrite the resource on
- the server without even being able to tell the user if it has
- changed. Timestamps do not solve this problem nearly as well as
- ETags.
-
- Strong ETags are much more useful for authoring use cases than weak
- ETags (see Section 13.3.3 of [RFC2616]). Semantic equivalence can be
- a useful concept but that depends on the document type and the
- application type, and interoperability might require some agreement
- or standard outside the scope of this specification and HTTP. Note
- also that weak ETags have certain restrictions in HTTP, e.g., these
- cannot be used in If-Match headers.
-
- Note that the meaning of an ETag in a PUT response is not clearly
- defined either in this document or in RFC 2616 (i.e., whether the
- ETag means that the resource is octet-for-octet equivalent to the
- body of the PUT request, or whether the server could have made minor
- changes in the formatting or content of the document upon storage).
- This is an HTTP issue, not purely a WebDAV issue.
-
- Because clients may be forced to prompt users or throw away changed
- content if the ETag changes, a WebDAV server SHOULD NOT change the
- ETag (or the Last-Modified time) for a resource that has an unchanged
- body and location. The ETag represents the state of the body or
- contents of the resource. There is no similar way to tell if
- properties have changed.
-
-8.7. Including Error Response Bodies
-
- HTTP and WebDAV did not use the bodies of most error responses for
- machine-parsable information until the specification for Versioning
- Extensions to WebDAV introduced a mechanism to include more specific
- information in the body of an error response (Section 1.6 of
- [RFC3253]). The error body mechanism is appropriate to use with any
- error response that may take a body but does not already have a body
- defined. The mechanism is particularly appropriate when a status
- code can mean many things (for example, 400 Bad Request can mean
- required headers are missing, headers are incorrectly formatted, or
- much more). This error body mechanism is covered in Section 16.
-
-8.8. Impact of Namespace Operations on Cache Validators
-
- Note that the HTTP response headers "Etag" and "Last-Modified" (see
- [RFC2616], Sections 14.19 and 14.29) are defined per URL (not per
- resource), and are used by clients for caching. Therefore servers
- must ensure that executing any operation that affects the URL
- namespace (such as COPY, MOVE, DELETE, PUT, or MKCOL) does preserve
- their semantics, in particular:
-
-
-
-Dusseault Standards Track [Page 34]
-\f
-RFC 4918 WebDAV June 2007
-
-
- o For any given URL, the "Last-Modified" value MUST increment every
- time the representation returned upon GET changes (within the
- limits of timestamp resolution).
-
- o For any given URL, an "ETag" value MUST NOT be reused for
- different representations returned by GET.
-
- In practice this means that servers
-
- o might have to increment "Last-Modified" timestamps for every
- resource inside the destination namespace of a namespace operation
- unless it can do so more selectively, and
-
- o similarly, might have to re-assign "ETag" values for these
- resources (unless the server allocates entity tags in a way so
- that they are unique across the whole URL namespace managed by the
- server).
-
- Note that these considerations also apply to specific use cases, such
- as using PUT to create a new resource at a URL that has been mapped
- before, but has been deleted since then.
-
- Finally, WebDAV properties (such as DAV:getetag and DAV:
- getlastmodified) that inherit their semantics from HTTP headers must
- behave accordingly.
-
-9. HTTP Methods for Distributed Authoring
-
-9.1. PROPFIND Method
-
- The PROPFIND method retrieves properties defined on the resource
- identified by the Request-URI, if the resource does not have any
- internal members, or on the resource identified by the Request-URI
- and potentially its member resources, if the resource is a collection
- that has internal member URLs. All DAV-compliant resources MUST
- support the PROPFIND method and the propfind XML element
- (Section 14.20) along with all XML elements defined for use with that
- element.
-
- A client MUST submit a Depth header with a value of "0", "1", or
- "infinity" with a PROPFIND request. Servers MUST support "0" and "1"
- depth requests on WebDAV-compliant resources and SHOULD support
- "infinity" requests. In practice, support for infinite-depth
- requests MAY be disabled, due to the performance and security
- concerns associated with this behavior. Servers SHOULD treat a
- request without a Depth header as if a "Depth: infinity" header was
- included.
-
-
-
-
-Dusseault Standards Track [Page 35]
-\f
-RFC 4918 WebDAV June 2007
-
-
- A client may submit a 'propfind' XML element in the body of the
- request method describing what information is being requested. It is
- possible to:
-
- o Request particular property values, by naming the properties
- desired within the 'prop' element (the ordering of properties in
- here MAY be ignored by the server),
-
- o Request property values for those properties defined in this
- specification (at a minimum) plus dead properties, by using the
- 'allprop' element (the 'include' element can be used with
- 'allprop' to instruct the server to also include additional live
- properties that may not have been returned otherwise),
-
- o Request a list of names of all the properties defined on the
- resource, by using the 'propname' element.
-
- A client may choose not to submit a request body. An empty PROPFIND
- request body MUST be treated as if it were an 'allprop' request.
-
- Note that 'allprop' does not return values for all live properties.
- WebDAV servers increasingly have expensively-calculated or lengthy
- properties (see [RFC3253] and [RFC3744]) and do not return all
- properties already. Instead, WebDAV clients can use propname
- requests to discover what live properties exist, and request named
- properties when retrieving values. For a live property defined
- elsewhere, that definition can specify whether or not that live
- property would be returned in 'allprop' requests.
-
- All servers MUST support returning a response of content type text/
- xml or application/xml that contains a multistatus XML element that
- describes the results of the attempts to retrieve the various
- properties.
-
- If there is an error retrieving a property, then a proper error
- result MUST be included in the response. A request to retrieve the
- value of a property that does not exist is an error and MUST be noted
- with a 'response' XML element that contains a 404 (Not Found) status
- value.
-
- Consequently, the 'multistatus' XML element for a collection resource
- MUST include a 'response' XML element for each member URL of the
- collection, to whatever depth was requested. It SHOULD NOT include
- any 'response' elements for resources that are not WebDAV-compliant.
- Each 'response' element MUST contain an 'href' element that contains
- the URL of the resource on which the properties in the prop XML
- element are defined. Results for a PROPFIND on a collection resource
- are returned as a flat list whose order of entries is not
-
-
-
-Dusseault Standards Track [Page 36]
-\f
-RFC 4918 WebDAV June 2007
-
-
- significant. Note that a resource may have only one value for a
- property of a given name, so the property may only show up once in
- PROPFIND responses.
-
- Properties may be subject to access control. In the case of
- 'allprop' and 'propname' requests, if a principal does not have the
- right to know whether a particular property exists, then the property
- MAY be silently excluded from the response.
-
- Some PROPFIND results MAY be cached, with care, as there is no cache
- validation mechanism for most properties. This method is both safe
- and idempotent (see Section 9.1 of [RFC2616]).
-
-9.1.1. PROPFIND Status Codes
-
- This section, as with similar sections for other methods, provides
- some guidance on error codes and preconditions or postconditions
- (defined in Section 16) that might be particularly useful with
- PROPFIND.
-
- 403 Forbidden - A server MAY reject PROPFIND requests on collections
- with depth header of "Infinity", in which case it SHOULD use this
- error with the precondition code 'propfind-finite-depth' inside the
- error body.
-
-9.1.2. Status Codes for Use in 'propstat' Element
-
- In PROPFIND responses, information about individual properties is
- returned inside 'propstat' elements (see Section 14.22), each
- containing an individual 'status' element containing information
- about the properties appearing in it. The list below summarizes the
- most common status codes used inside 'propstat'; however, clients
- should be prepared to handle other 2/3/4/5xx series status codes as
- well.
-
- 200 OK - A property exists and/or its value is successfully returned.
-
- 401 Unauthorized - The property cannot be viewed without appropriate
- authorization.
-
- 403 Forbidden - The property cannot be viewed regardless of
- authentication.
-
- 404 Not Found - The property does not exist.
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 37]
-\f
-RFC 4918 WebDAV June 2007
-
-
-9.1.3. Example - Retrieving Named Properties
-
- >>Request
-
- PROPFIND /file HTTP/1.1
- Host: www.example.com
- Content-type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:prop xmlns:R="http://ns.example.com/boxschema/">
- <R:bigbox/>
- <R:author/>
- <R:DingALing/>
- <R:Random/>
- </D:prop>
- </D:propfind>
-
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response xmlns:R="http://ns.example.com/boxschema/">
- <D:href>http://www.example.com/file</D:href>
- <D:propstat>
- <D:prop>
- <R:bigbox>
- <R:BoxType>Box type A</R:BoxType>
- </R:bigbox>
- <R:author>
- <R:Name>J.J. Johnson</R:Name>
- </R:author>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- <D:propstat>
- <D:prop><R:DingALing/><R:Random/></D:prop>
- <D:status>HTTP/1.1 403 Forbidden</D:status>
- <D:responsedescription> The user does not have access to the
- DingALing property.
- </D:responsedescription>
- </D:propstat>
-
-
-
-Dusseault Standards Track [Page 38]
-\f
-RFC 4918 WebDAV June 2007
-
-
- </D:response>
- <D:responsedescription> There has been an access violation error.
- </D:responsedescription>
- </D:multistatus>
-
-
- In this example, PROPFIND is executed on a non-collection resource
- http://www.example.com/file. The propfind XML element specifies the
- name of four properties whose values are being requested. In this
- case, only two properties were returned, since the principal issuing
- the request did not have sufficient access rights to see the third
- and fourth properties.
-
-9.1.4. Example - Using 'propname' to Retrieve All Property Names
-
- >>Request
-
- PROPFIND /container/ HTTP/1.1
- Host: www.example.com
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <propfind xmlns="DAV:">
- <propname/>
- </propfind>
-
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <multistatus xmlns="DAV:">
- <response>
- <href>http://www.example.com/container/</href>
- <propstat>
- <prop xmlns:R="http://ns.example.com/boxschema/">
- <R:bigbox/>
- <R:author/>
- <creationdate/>
- <displayname/>
- <resourcetype/>
- <supportedlock/>
- </prop>
- <status>HTTP/1.1 200 OK</status>
-
-
-
-Dusseault Standards Track [Page 39]
-\f
-RFC 4918 WebDAV June 2007
-
-
- </propstat>
- </response>
- <response>
- <href>http://www.example.com/container/front.html</href>
- <propstat>
- <prop xmlns:R="http://ns.example.com/boxschema/">
- <R:bigbox/>
- <creationdate/>
- <displayname/>
- <getcontentlength/>
- <getcontenttype/>
- <getetag/>
- <getlastmodified/>
- <resourcetype/>
- <supportedlock/>
- </prop>
- <status>HTTP/1.1 200 OK</status>
- </propstat>
- </response>
- </multistatus>
-
- In this example, PROPFIND is invoked on the collection resource
- http://www.example.com/container/, with a propfind XML element
- containing the propname XML element, meaning the name of all
- properties should be returned. Since no Depth header is present, it
- assumes its default value of "infinity", meaning the name of the
- properties on the collection and all its descendants should be
- returned.
-
- Consistent with the previous example, resource
- http://www.example.com/container/ has six properties defined on it:
- bigbox and author in the "http://ns.example.com/boxschema/"
- namespace, and creationdate, displayname, resourcetype, and
- supportedlock in the "DAV:" namespace.
-
- The resource http://www.example.com/container/index.html, a member of
- the "container" collection, has nine properties defined on it, bigbox
- in the "http://ns.example.com/boxschema/" namespace and creationdate,
- displayname, getcontentlength, getcontenttype, getetag,
- getlastmodified, resourcetype, and supportedlock in the "DAV:"
- namespace.
-
- This example also demonstrates the use of XML namespace scoping and
- the default namespace. Since the "xmlns" attribute does not contain
- a prefix, the namespace applies by default to all enclosed elements.
- Hence, all elements that do not explicitly state the namespace to
- which they belong are members of the "DAV:" namespace.
-
-
-
-
-Dusseault Standards Track [Page 40]
-\f
-RFC 4918 WebDAV June 2007
-
-
-9.1.5. Example - Using So-called 'allprop'
-
- Note that 'allprop', despite its name, which remains for backward-
- compatibility, does not return every property, but only dead
- properties and the live properties defined in this specification.
-
- >>Request
-
- PROPFIND /container/ HTTP/1.1
- Host: www.example.com
- Depth: 1
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:allprop/>
- </D:propfind>
-
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>/container/</D:href>
- <D:propstat>
- <D:prop xmlns:R="http://ns.example.com/boxschema/">
- <R:bigbox><R:BoxType>Box type A</R:BoxType></R:bigbox>
- <R:author><R:Name>Hadrian</R:Name></R:author>
- <D:creationdate>1997-12-01T17:42:21-08:00</D:creationdate>
- <D:displayname>Example collection</D:displayname>
- <D:resourcetype><D:collection/></D:resourcetype>
- <D:supportedlock>
- <D:lockentry>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- <D:lockentry>
- <D:lockscope><D:shared/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- </D:supportedlock>
- </D:prop>
-
-
-
-Dusseault Standards Track [Page 41]
-\f
-RFC 4918 WebDAV June 2007
-
-
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- <D:response>
- <D:href>/container/front.html</D:href>
- <D:propstat>
- <D:prop xmlns:R="http://ns.example.com/boxschema/">
- <R:bigbox><R:BoxType>Box type B</R:BoxType>
- </R:bigbox>
- <D:creationdate>1997-12-01T18:27:21-08:00</D:creationdate>
- <D:displayname>Example HTML resource</D:displayname>
- <D:getcontentlength>4525</D:getcontentlength>
- <D:getcontenttype>text/html</D:getcontenttype>
- <D:getetag>"zzyzx"</D:getetag>
- <D:getlastmodified
- >Mon, 12 Jan 1998 09:25:56 GMT</D:getlastmodified>
- <D:resourcetype/>
- <D:supportedlock>
- <D:lockentry>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- <D:lockentry>
- <D:lockscope><D:shared/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- </D:supportedlock>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
- In this example, PROPFIND was invoked on the resource
- http://www.example.com/container/ with a Depth header of 1, meaning
- the request applies to the resource and its children, and a propfind
- XML element containing the allprop XML element, meaning the request
- should return the name and value of all the dead properties defined
- on the resources, plus the name and value of all the properties
- defined in this specification. This example illustrates the use of
- relative references in the 'href' elements of the response.
-
- The resource http://www.example.com/container/ has six properties
- defined on it: 'bigbox' and 'author in the
- "http://ns.example.com/boxschema/" namespace, DAV:creationdate, DAV:
- displayname, DAV:resourcetype, and DAV:supportedlock.
-
-
-
-
-
-Dusseault Standards Track [Page 42]
-\f
-RFC 4918 WebDAV June 2007
-
-
- The last four properties are WebDAV-specific, defined in Section 15.
- Since GET is not supported on this resource, the get* properties
- (e.g., DAV:getcontentlength) are not defined on this resource. The
- WebDAV-specific properties assert that "container" was created on
- December 1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT
- (DAV:creationdate), has a name of "Example collection" (DAV:
- displayname), a collection resource type (DAV:resourcetype), and
- supports exclusive write and shared write locks (DAV:supportedlock).
-
- The resource http://www.example.com/container/front.html has nine
- properties defined on it:
-
- 'bigbox' in the "http://ns.example.com/boxschema/" namespace (another
- instance of the "bigbox" property type), DAV:creationdate, DAV:
- displayname, DAV:getcontentlength, DAV:getcontenttype, DAV:getetag,
- DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock.
-
- The DAV-specific properties assert that "front.html" was created on
- December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT
- (DAV:creationdate), has a name of "Example HTML resource" (DAV:
- displayname), a content length of 4525 bytes (DAV:getcontentlength),
- a MIME type of "text/html" (DAV:getcontenttype), an entity tag of
- "zzyzx" (DAV:getetag), was last modified on Monday, January 12, 1998,
- at 09:25:56 GMT (DAV:getlastmodified), has an empty resource type,
- meaning that it is not a collection (DAV:resourcetype), and supports
- both exclusive write and shared write locks (DAV:supportedlock).
-
-9.1.6. Example - Using 'allprop' with 'include'
-
- >>Request
-
- PROPFIND /mycol/ HTTP/1.1
- Host: www.example.com
- Depth: 1
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:allprop/>
- <D:include>
- <D:supported-live-property-set/>
- <D:supported-report-set/>
- </D:include>
- </D:propfind>
-
-
-
-
-
-
-Dusseault Standards Track [Page 43]
-\f
-RFC 4918 WebDAV June 2007
-
-
- In this example, PROPFIND is executed on the resource
- http://www.example.com/mycol/ and its internal member resources. The
- client requests the values of all live properties defined in this
- specification, plus all dead properties, plus two more live
- properties defined in [RFC3253]. The response is not shown.
-
-9.2. PROPPATCH Method
-
- The PROPPATCH method processes instructions specified in the request
- body to set and/or remove properties defined on the resource
- identified by the Request-URI.
-
- All DAV-compliant resources MUST support the PROPPATCH method and
- MUST process instructions that are specified using the
- propertyupdate, set, and remove XML elements. Execution of the
- directives in this method is, of course, subject to access control
- constraints. DAV-compliant resources SHOULD support the setting of
- arbitrary dead properties.
-
- The request message body of a PROPPATCH method MUST contain the
- propertyupdate XML element.
-
- Servers MUST process PROPPATCH instructions in document order (an
- exception to the normal rule that ordering is irrelevant).
- Instructions MUST either all be executed or none executed. Thus, if
- any error occurs during processing, all executed instructions MUST be
- undone and a proper error result returned. Instruction processing
- details can be found in the definition of the set and remove
- instructions in Sections 14.23 and 14.26.
-
- If a server attempts to make any of the property changes in a
- PROPPATCH request (i.e., the request is not rejected for high-level
- errors before processing the body), the response MUST be a Multi-
- Status response as described in Section 9.2.1.
-
- This method is idempotent, but not safe (see Section 9.1 of
- [RFC2616]). Responses to this method MUST NOT be cached.
-
-9.2.1. Status Codes for Use in 'propstat' Element
-
- In PROPPATCH responses, information about individual properties is
- returned inside 'propstat' elements (see Section 14.22), each
- containing an individual 'status' element containing information
- about the properties appearing in it. The list below summarizes the
- most common status codes used inside 'propstat'; however, clients
- should be prepared to handle other 2/3/4/5xx series status codes as
- well.
-
-
-
-
-Dusseault Standards Track [Page 44]
-\f
-RFC 4918 WebDAV June 2007
-
-
- 200 (OK) - The property set or change succeeded. Note that if this
- appears for one property, it appears for every property in the
- response, due to the atomicity of PROPPATCH.
-
- 403 (Forbidden) - The client, for reasons the server chooses not to
- specify, cannot alter one of the properties.
-
- 403 (Forbidden): The client has attempted to set a protected
- property, such as DAV:getetag. If returning this error, the server
- SHOULD use the precondition code 'cannot-modify-protected-property'
- inside the response body.
-
- 409 (Conflict) - The client has provided a value whose semantics are
- not appropriate for the property.
-
- 424 (Failed Dependency) - The property change could not be made
- because of another property change that failed.
-
- 507 (Insufficient Storage) - The server did not have sufficient space
- to record the property.
-
-9.2.2. Example - PROPPATCH
-
- >>Request
-
- PROPPATCH /bar.html HTTP/1.1
- Host: www.example.com
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propertyupdate xmlns:D="DAV:"
- xmlns:Z="http://ns.example.com/standards/z39.50/">
- <D:set>
- <D:prop>
- <Z:Authors>
- <Z:Author>Jim Whitehead</Z:Author>
- <Z:Author>Roy Fielding</Z:Author>
- </Z:Authors>
- </D:prop>
- </D:set>
- <D:remove>
- <D:prop><Z:Copyright-Owner/></D:prop>
- </D:remove>
- </D:propertyupdate>
-
-
-
-
-
-
-Dusseault Standards Track [Page 45]
-\f
-RFC 4918 WebDAV June 2007
-
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:"
- xmlns:Z="http://ns.example.com/standards/z39.50/">
- <D:response>
- <D:href>http://www.example.com/bar.html</D:href>
- <D:propstat>
- <D:prop><Z:Authors/></D:prop>
- <D:status>HTTP/1.1 424 Failed Dependency</D:status>
- </D:propstat>
- <D:propstat>
- <D:prop><Z:Copyright-Owner/></D:prop>
- <D:status>HTTP/1.1 409 Conflict</D:status>
- </D:propstat>
- <D:responsedescription> Copyright Owner cannot be deleted or
- altered.</D:responsedescription>
- </D:response>
- </D:multistatus>
-
- In this example, the client requests the server to set the value of
- the "Authors" property in the
- "http://ns.example.com/standards/z39.50/" namespace, and to remove
- the property "Copyright-Owner" in the same namespace. Since the
- Copyright-Owner property could not be removed, no property
- modifications occur. The 424 (Failed Dependency) status code for the
- Authors property indicates this action would have succeeded if it
- were not for the conflict with removing the Copyright-Owner property.
-
-9.3. MKCOL Method
-
- MKCOL creates a new collection resource at the location specified by
- the Request-URI. If the Request-URI is already mapped to a resource,
- then the MKCOL MUST fail. During MKCOL processing, a server MUST
- make the Request-URI an internal member of its parent collection,
- unless the Request-URI is "/". If no such ancestor exists, the
- method MUST fail. When the MKCOL operation creates a new collection
- resource, all ancestors MUST already exist, or the method MUST fail
- with a 409 (Conflict) status code. For example, if a request to
- create collection /a/b/c/d/ is made, and /a/b/c/ does not exist, the
- request must fail.
-
- When MKCOL is invoked without a request body, the newly created
- collection SHOULD have no members.
-
-
-
-Dusseault Standards Track [Page 46]
-\f
-RFC 4918 WebDAV June 2007
-
-
- A MKCOL request message may contain a message body. The precise
- behavior of a MKCOL request when the body is present is undefined,
- but limited to creating collections, members of a collection, bodies
- of members, and properties on the collections or members. If the
- server receives a MKCOL request entity type it does not support or
- understand, it MUST respond with a 415 (Unsupported Media Type)
- status code. If the server decides to reject the request based on
- the presence of an entity or the type of an entity, it should use the
- 415 (Unsupported Media Type) status code.
-
- This method is idempotent, but not safe (see Section 9.1 of
- [RFC2616]). Responses to this method MUST NOT be cached.
-
-9.3.1. MKCOL Status Codes
-
- In addition to the general status codes possible, the following
- status codes have specific applicability to MKCOL:
-
- 201 (Created) - The collection was created.
-
- 403 (Forbidden) - This indicates at least one of two conditions: 1)
- the server does not allow the creation of collections at the given
- location in its URL namespace, or 2) the parent collection of the
- Request-URI exists but cannot accept members.
-
- 405 (Method Not Allowed) - MKCOL can only be executed on an unmapped
- URL.
-
- 409 (Conflict) - A collection cannot be made at the Request-URI until
- one or more intermediate collections have been created. The server
- MUST NOT create those intermediate collections automatically.
-
- 415 (Unsupported Media Type) - The server does not support the
- request body type (although bodies are legal on MKCOL requests, since
- this specification doesn't define any, the server is likely not to
- support any given body type).
-
- 507 (Insufficient Storage) - The resource does not have sufficient
- space to record the state of the resource after the execution of this
- method.
-
-9.3.2. Example - MKCOL
-
- This example creates a collection called /webdisc/xfiles/ on the
- server www.example.com.
-
-
-
-
-
-
-Dusseault Standards Track [Page 47]
-\f
-RFC 4918 WebDAV June 2007
-
-
- >>Request
-
- MKCOL /webdisc/xfiles/ HTTP/1.1
- Host: www.example.com
-
-
- >>Response
-
- HTTP/1.1 201 Created
-
-9.4. GET, HEAD for Collections
-
- The semantics of GET are unchanged when applied to a collection,
- since GET is defined as, "retrieve whatever information (in the form
- of an entity) is identified by the Request-URI" [RFC2616]. GET, when
- applied to a collection, may return the contents of an "index.html"
- resource, a human-readable view of the contents of the collection, or
- something else altogether. Hence, it is possible that the result of
- a GET on a collection will bear no correlation to the membership of
- the collection.
-
- Similarly, since the definition of HEAD is a GET without a response
- message body, the semantics of HEAD are unmodified when applied to
- collection resources.
-
-9.5. POST for Collections
-
- Since by definition the actual function performed by POST is
- determined by the server and often depends on the particular
- resource, the behavior of POST when applied to collections cannot be
- meaningfully modified because it is largely undefined. Thus, the
- semantics of POST are unmodified when applied to a collection.
-
-9.6. DELETE Requirements
-
- DELETE is defined in [RFC2616], Section 9.7, to "delete the resource
- identified by the Request-URI". However, WebDAV changes some DELETE
- handling requirements.
-
- A server processing a successful DELETE request:
-
- MUST destroy locks rooted on the deleted resource
-
- MUST remove the mapping from the Request-URI to any resource.
-
- Thus, after a successful DELETE operation (and in the absence of
- other actions), a subsequent GET/HEAD/PROPFIND request to the target
- Request-URI MUST return 404 (Not Found).
-
-
-
-Dusseault Standards Track [Page 48]
-\f
-RFC 4918 WebDAV June 2007
-
-
-9.6.1. DELETE for Collections
-
- The DELETE method on a collection MUST act as if a "Depth: infinity"
- header was used on it. A client MUST NOT submit a Depth header with
- a DELETE on a collection with any value but infinity.
-
- DELETE instructs that the collection specified in the Request-URI and
- all resources identified by its internal member URLs are to be
- deleted.
-
- If any resource identified by a member URL cannot be deleted, then
- all of the member's ancestors MUST NOT be deleted, so as to maintain
- URL namespace consistency.
-
- Any headers included with DELETE MUST be applied in processing every
- resource to be deleted.
-
- When the DELETE method has completed processing, it MUST result in a
- consistent URL namespace.
-
- If an error occurs deleting a member resource (a resource other than
- the resource identified in the Request-URI), then the response can be
- a 207 (Multi-Status). Multi-Status is used here to indicate which
- internal resources could NOT be deleted, including an error code,
- which should help the client understand which resources caused the
- failure. For example, the Multi-Status body could include a response
- with status 423 (Locked) if an internal resource was locked.
-
- The server MAY return a 4xx status response, rather than a 207, if
- the request failed completely.
-
- 424 (Failed Dependency) status codes SHOULD NOT be in the 207 (Multi-
- Status) response for DELETE. They can be safely left out because the
- client will know that the ancestors of a resource could not be
- deleted when the client receives an error for the ancestor's progeny.
- Additionally, 204 (No Content) errors SHOULD NOT be returned in the
- 207 (Multi-Status). The reason for this prohibition is that 204 (No
- Content) is the default success code.
-
-9.6.2. Example - DELETE
-
- >>Request
-
- DELETE /container/ HTTP/1.1
- Host: www.example.com
-
-
-
-
-
-
-Dusseault Standards Track [Page 49]
-\f
-RFC 4918 WebDAV June 2007
-
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <d:multistatus xmlns:d="DAV:">
- <d:response>
- <d:href>http://www.example.com/container/resource3</d:href>
- <d:status>HTTP/1.1 423 Locked</d:status>
- <d:error><d:lock-token-submitted/></d:error>
- </d:response>
- </d:multistatus>
-
- In this example, the attempt to delete
- http://www.example.com/container/resource3 failed because it is
- locked, and no lock token was submitted with the request.
- Consequently, the attempt to delete http://www.example.com/container/
- also failed. Thus, the client knows that the attempt to delete
- http://www.example.com/container/ must have also failed since the
- parent cannot be deleted unless its child has also been deleted.
- Even though a Depth header has not been included, a depth of infinity
- is assumed because the method is on a collection.
-
-9.7. PUT Requirements
-
-9.7.1. PUT for Non-Collection Resources
-
- A PUT performed on an existing resource replaces the GET response
- entity of the resource. Properties defined on the resource may be
- recomputed during PUT processing but are not otherwise affected. For
- example, if a server recognizes the content type of the request body,
- it may be able to automatically extract information that could be
- profitably exposed as properties.
-
- A PUT that would result in the creation of a resource without an
- appropriately scoped parent collection MUST fail with a 409
- (Conflict).
-
- A PUT request allows a client to indicate what media type an entity
- body has, and whether it should change if overwritten. Thus, a
- client SHOULD provide a Content-Type for a new resource if any is
- known. If the client does not provide a Content-Type for a new
- resource, the server MAY create a resource with no Content-Type
- assigned, or it MAY attempt to assign a Content-Type.
-
-
-
-
-
-Dusseault Standards Track [Page 50]
-\f
-RFC 4918 WebDAV June 2007
-
-
- Note that although a recipient ought generally to treat metadata
- supplied with an HTTP request as authoritative, in practice there's
- no guarantee that a server will accept client-supplied metadata
- (e.g., any request header beginning with "Content-"). Many servers
- do not allow configuring the Content-Type on a per-resource basis in
- the first place. Thus, clients can't always rely on the ability to
- directly influence the content type by including a Content-Type
- request header.
-
-9.7.2. PUT for Collections
-
- This specification does not define the behavior of the PUT method for
- existing collections. A PUT request to an existing collection MAY be
- treated as an error (405 Method Not Allowed).
-
- The MKCOL method is defined to create collections.
-
-9.8. COPY Method
-
- The COPY method creates a duplicate of the source resource identified
- by the Request-URI, in the destination resource identified by the URI
- in the Destination header. The Destination header MUST be present.
- The exact behavior of the COPY method depends on the type of the
- source resource.
-
- All WebDAV-compliant resources MUST support the COPY method.
- However, support for the COPY method does not guarantee the ability
- to copy a resource. For example, separate programs may control
- resources on the same server. As a result, it may not be possible to
- copy a resource to a location that appears to be on the same server.
-
- This method is idempotent, but not safe (see Section 9.1 of
- [RFC2616]). Responses to this method MUST NOT be cached.
-
-9.8.1. COPY for Non-collection Resources
-
- When the source resource is not a collection, the result of the COPY
- method is the creation of a new resource at the destination whose
- state and behavior match that of the source resource as closely as
- possible. Since the environment at the destination may be different
- than at the source due to factors outside the scope of control of the
- server, such as the absence of resources required for correct
- operation, it may not be possible to completely duplicate the
- behavior of the resource at the destination. Subsequent alterations
- to the destination resource will not modify the source resource.
- Subsequent alterations to the source resource will not modify the
- destination resource.
-
-
-
-
-Dusseault Standards Track [Page 51]
-\f
-RFC 4918 WebDAV June 2007
-
-
-9.8.2. COPY for Properties
-
- After a successful COPY invocation, all dead properties on the source
- resource SHOULD be duplicated on the destination resource. Live
- properties described in this document SHOULD be duplicated as
- identically behaving live properties at the destination resource, but
- not necessarily with the same values. Servers SHOULD NOT convert
- live properties into dead properties on the destination resource,
- because clients may then draw incorrect conclusions about the state
- or functionality of a resource. Note that some live properties are
- defined such that the absence of the property has a specific meaning
- (e.g., a flag with one meaning if present, and the opposite if
- absent), and in these cases, a successful COPY might result in the
- property being reported as "Not Found" in subsequent requests.
-
- When the destination is an unmapped URL, a COPY operation creates a
- new resource much like a PUT operation does. Live properties that
- are related to resource creation (such as DAV:creationdate) should
- have their values set accordingly.
-
-9.8.3. COPY for Collections
-
- The COPY method on a collection without a Depth header MUST act as if
- a Depth header with value "infinity" was included. A client may
- submit a Depth header on a COPY on a collection with a value of "0"
- or "infinity". Servers MUST support the "0" and "infinity" Depth
- header behaviors on WebDAV-compliant resources.
-
- An infinite-depth COPY instructs that the collection resource
- identified by the Request-URI is to be copied to the location
- identified by the URI in the Destination header, and all its internal
- member resources are to be copied to a location relative to it,
- recursively through all levels of the collection hierarchy. Note
- that an infinite-depth COPY of /A/ into /A/B/ could lead to infinite
- recursion if not handled correctly.
-
- A COPY of "Depth: 0" only instructs that the collection and its
- properties, but not resources identified by its internal member URLs,
- are to be copied.
-
- Any headers included with a COPY MUST be applied in processing every
- resource to be copied with the exception of the Destination header.
-
- The Destination header only specifies the destination URI for the
- Request-URI. When applied to members of the collection identified by
- the Request-URI, the value of Destination is to be modified to
- reflect the current location in the hierarchy. So, if the Request-
- URI is /a/ with Host header value http://example.com/ and the
-
-
-
-Dusseault Standards Track [Page 52]
-\f
-RFC 4918 WebDAV June 2007
-
-
- Destination is http://example.com/b/, then when
- http://example.com/a/c/d is processed, it must use a Destination of
- http://example.com/b/c/d.
-
- When the COPY method has completed processing, it MUST have created a
- consistent URL namespace at the destination (see Section 5.1 for the
- definition of namespace consistency). However, if an error occurs
- while copying an internal collection, the server MUST NOT copy any
- resources identified by members of this collection (i.e., the server
- must skip this subtree), as this would create an inconsistent
- namespace. After detecting an error, the COPY operation SHOULD try
- to finish as much of the original copy operation as possible (i.e.,
- the server should still attempt to copy other subtrees and their
- members that are not descendants of an error-causing collection).
-
- So, for example, if an infinite-depth copy operation is performed on
- collection /a/, which contains collections /a/b/ and /a/c/, and an
- error occurs copying /a/b/, an attempt should still be made to copy
- /a/c/. Similarly, after encountering an error copying a non-
- collection resource as part of an infinite-depth copy, the server
- SHOULD try to finish as much of the original copy operation as
- possible.
-
- If an error in executing the COPY method occurs with a resource other
- than the resource identified in the Request-URI, then the response
- MUST be a 207 (Multi-Status), and the URL of the resource causing the
- failure MUST appear with the specific error.
-
- The 424 (Failed Dependency) status code SHOULD NOT be returned in the
- 207 (Multi-Status) response from a COPY method. These responses can
- be safely omitted because the client will know that the progeny of a
- resource could not be copied when the client receives an error for
- the parent. Additionally, 201 (Created)/204 (No Content) status
- codes SHOULD NOT be returned as values in 207 (Multi-Status)
- responses from COPY methods. They, too, can be safely omitted
- because they are the default success codes.
-
-9.8.4. COPY and Overwriting Destination Resources
-
- If a COPY request has an Overwrite header with a value of "F", and a
- resource exists at the Destination URL, the server MUST fail the
- request.
-
- When a server executes a COPY request and overwrites a destination
- resource, the exact behavior MAY depend on many factors, including
- WebDAV extension capabilities (see particularly [RFC3253]). For
-
-
-
-
-
-Dusseault Standards Track [Page 53]
-\f
-RFC 4918 WebDAV June 2007
-
-
- example, when an ordinary resource is overwritten, the server could
- delete the target resource before doing the copy, or could do an in-
- place overwrite to preserve live properties.
-
- When a collection is overwritten, the membership of the destination
- collection after the successful COPY request MUST be the same
- membership as the source collection immediately before the COPY.
- Thus, merging the membership of the source and destination
- collections together in the destination is not a compliant behavior.
-
- In general, if clients require the state of the destination URL to be
- wiped out prior to a COPY (e.g., to force live properties to be
- reset), then the client could send a DELETE to the destination before
- the COPY request to ensure this reset.
-
-9.8.5. Status Codes
-
- In addition to the general status codes possible, the following
- status codes have specific applicability to COPY:
-
- 201 (Created) - The source resource was successfully copied. The
- COPY operation resulted in the creation of a new resource.
-
- 204 (No Content) - The source resource was successfully copied to a
- preexisting destination resource.
-
- 207 (Multi-Status) - Multiple resources were to be affected by the
- COPY, but errors on some of them prevented the operation from taking
- place. Specific error messages, together with the most appropriate
- of the source and destination URLs, appear in the body of the multi-
- status response. For example, if a destination resource was locked
- and could not be overwritten, then the destination resource URL
- appears with the 423 (Locked) status.
-
- 403 (Forbidden) - The operation is forbidden. A special case for
- COPY could be that the source and destination resources are the same
- resource.
-
- 409 (Conflict) - A resource cannot be created at the destination
- until one or more intermediate collections have been created. The
- server MUST NOT create those intermediate collections automatically.
-
- 412 (Precondition Failed) - A precondition header check failed, e.g.,
- the Overwrite header is "F" and the destination URL is already mapped
- to a resource.
-
-
-
-
-
-
-Dusseault Standards Track [Page 54]
-\f
-RFC 4918 WebDAV June 2007
-
-
- 423 (Locked) - The destination resource, or resource within the
- destination collection, was locked. This response SHOULD contain the
- 'lock-token-submitted' precondition element.
-
- 502 (Bad Gateway) - This may occur when the destination is on another
- server, repository, or URL namespace. Either the source namespace
- does not support copying to the destination namespace, or the
- destination namespace refuses to accept the resource. The client may
- wish to try GET/PUT and PROPFIND/PROPPATCH instead.
-
- 507 (Insufficient Storage) - The destination resource does not have
- sufficient space to record the state of the resource after the
- execution of this method.
-
-9.8.6. Example - COPY with Overwrite
-
- This example shows resource
- http://www.example.com/~fielding/index.html being copied to the
- location http://www.example.com/users/f/fielding/index.html. The 204
- (No Content) status code indicates that the existing resource at the
- destination was overwritten.
-
- >>Request
-
- COPY /~fielding/index.html HTTP/1.1
- Host: www.example.com
- Destination: http://www.example.com/users/f/fielding/index.html
-
- >>Response
-
- HTTP/1.1 204 No Content
-
-9.8.7. Example - COPY with No Overwrite
-
- The following example shows the same copy operation being performed,
- but with the Overwrite header set to "F." A response of 412
- (Precondition Failed) is returned because the destination URL is
- already mapped to a resource.
-
- >>Request
-
- COPY /~fielding/index.html HTTP/1.1
- Host: www.example.com
- Destination: http://www.example.com/users/f/fielding/index.html
- Overwrite: F
-
-
-
-
-
-
-Dusseault Standards Track [Page 55]
-\f
-RFC 4918 WebDAV June 2007
-
-
- >>Response
-
- HTTP/1.1 412 Precondition Failed
-
-9.8.8. Example - COPY of a Collection
-
- >>Request
-
- COPY /container/ HTTP/1.1
- Host: www.example.com
- Destination: http://www.example.com/othercontainer/
- Depth: infinity
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
-
- <d:multistatus xmlns:d="DAV:">
- <d:response>
- <d:href>http://www.example.com/othercontainer/R2/</d:href>
- <d:status>HTTP/1.1 423 Locked</d:status>
- <d:error><d:lock-token-submitted/></d:error>
- </d:response>
- </d:multistatus>
-
- The Depth header is unnecessary as the default behavior of COPY on a
- collection is to act as if a "Depth: infinity" header had been
- submitted. In this example, most of the resources, along with the
- collection, were copied successfully. However, the collection R2
- failed because the destination R2 is locked. Because there was an
- error copying R2, none of R2's members were copied. However, no
- errors were listed for those members due to the error minimization
- rules.
-
-9.9. MOVE Method
-
- The MOVE operation on a non-collection resource is the logical
- equivalent of a copy (COPY), followed by consistency maintenance
- processing, followed by a delete of the source, where all three
- actions are performed in a single operation. The consistency
- maintenance step allows the server to perform updates caused by the
- move, such as updating all URLs, other than the Request-URI that
- identifies the source resource, to point to the new destination
- resource.
-
-
-
-Dusseault Standards Track [Page 56]
-\f
-RFC 4918 WebDAV June 2007
-
-
- The Destination header MUST be present on all MOVE methods and MUST
- follow all COPY requirements for the COPY part of the MOVE method.
- All WebDAV-compliant resources MUST support the MOVE method.
-
- Support for the MOVE method does not guarantee the ability to move a
- resource to a particular destination. For example, separate programs
- may actually control different sets of resources on the same server.
- Therefore, it may not be possible to move a resource within a
- namespace that appears to belong to the same server.
-
- If a resource exists at the destination, the destination resource
- will be deleted as a side-effect of the MOVE operation, subject to
- the restrictions of the Overwrite header.
-
- This method is idempotent, but not safe (see Section 9.1 of
- [RFC2616]). Responses to this method MUST NOT be cached.
-
-9.9.1. MOVE for Properties
-
- Live properties described in this document SHOULD be moved along with
- the resource, such that the resource has identically behaving live
- properties at the destination resource, but not necessarily with the
- same values. Note that some live properties are defined such that
- the absence of the property has a specific meaning (e.g., a flag with
- one meaning if present, and the opposite if absent), and in these
- cases, a successful MOVE might result in the property being reported
- as "Not Found" in subsequent requests. If the live properties will
- not work the same way at the destination, the server MAY fail the
- request.
-
- MOVE is frequently used by clients to rename a file without changing
- its parent collection, so it's not appropriate to reset all live
- properties that are set at resource creation. For example, the DAV:
- creationdate property value SHOULD remain the same after a MOVE.
-
- Dead properties MUST be moved along with the resource.
-
-9.9.2. MOVE for Collections
-
- A MOVE with "Depth: infinity" instructs that the collection
- identified by the Request-URI be moved to the address specified in
- the Destination header, and all resources identified by its internal
- member URLs are to be moved to locations relative to it, recursively
- through all levels of the collection hierarchy.
-
- The MOVE method on a collection MUST act as if a "Depth: infinity"
- header was used on it. A client MUST NOT submit a Depth header on a
- MOVE on a collection with any value but "infinity".
-
-
-
-Dusseault Standards Track [Page 57]
-\f
-RFC 4918 WebDAV June 2007
-
-
- Any headers included with MOVE MUST be applied in processing every
- resource to be moved with the exception of the Destination header.
- The behavior of the Destination header is the same as given for COPY
- on collections.
-
- When the MOVE method has completed processing, it MUST have created a
- consistent URL namespace at both the source and destination (see
- Section 5.1 for the definition of namespace consistency). However,
- if an error occurs while moving an internal collection, the server
- MUST NOT move any resources identified by members of the failed
- collection (i.e., the server must skip the error-causing subtree), as
- this would create an inconsistent namespace. In this case, after
- detecting the error, the move operation SHOULD try to finish as much
- of the original move as possible (i.e., the server should still
- attempt to move other subtrees and the resources identified by their
- members that are not descendants of an error-causing collection).
- So, for example, if an infinite-depth move is performed on collection
- /a/, which contains collections /a/b/ and /a/c/, and an error occurs
- moving /a/b/, an attempt should still be made to try moving /a/c/.
- Similarly, after encountering an error moving a non-collection
- resource as part of an infinite-depth move, the server SHOULD try to
- finish as much of the original move operation as possible.
-
- If an error occurs with a resource other than the resource identified
- in the Request-URI, then the response MUST be a 207 (Multi-Status),
- and the errored resource's URL MUST appear with the specific error.
-
- The 424 (Failed Dependency) status code SHOULD NOT be returned in the
- 207 (Multi-Status) response from a MOVE method. These errors can be
- safely omitted because the client will know that the progeny of a
- resource could not be moved when the client receives an error for the
- parent. Additionally, 201 (Created)/204 (No Content) responses
- SHOULD NOT be returned as values in 207 (Multi-Status) responses from
- a MOVE. These responses can be safely omitted because they are the
- default success codes.
-
-9.9.3. MOVE and the Overwrite Header
-
- If a resource exists at the destination and the Overwrite header is
- "T", then prior to performing the move, the server MUST perform a
- DELETE with "Depth: infinity" on the destination resource. If the
- Overwrite header is set to "F", then the operation will fail.
-
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 58]
-\f
-RFC 4918 WebDAV June 2007
-
-
-9.9.4. Status Codes
-
- In addition to the general status codes possible, the following
- status codes have specific applicability to MOVE:
-
- 201 (Created) - The source resource was successfully moved, and a new
- URL mapping was created at the destination.
-
- 204 (No Content) - The source resource was successfully moved to a
- URL that was already mapped.
-
- 207 (Multi-Status) - Multiple resources were to be affected by the
- MOVE, but errors on some of them prevented the operation from taking
- place. Specific error messages, together with the most appropriate
- of the source and destination URLs, appear in the body of the multi-
- status response. For example, if a source resource was locked and
- could not be moved, then the source resource URL appears with the 423
- (Locked) status.
-
- 403 (Forbidden) - Among many possible reasons for forbidding a MOVE
- operation, this status code is recommended for use when the source
- and destination resources are the same.
-
- 409 (Conflict) - A resource cannot be created at the destination
- until one or more intermediate collections have been created. The
- server MUST NOT create those intermediate collections automatically.
- Or, the server was unable to preserve the behavior of the live
- properties and still move the resource to the destination (see
- 'preserved-live-properties' postcondition).
-
- 412 (Precondition Failed) - A condition header failed. Specific to
- MOVE, this could mean that the Overwrite header is "F" and the
- destination URL is already mapped to a resource.
-
- 423 (Locked) - The source or the destination resource, the source or
- destination resource parent, or some resource within the source or
- destination collection, was locked. This response SHOULD contain the
- 'lock-token-submitted' precondition element.
-
- 502 (Bad Gateway) - This may occur when the destination is on another
- server and the destination server refuses to accept the resource.
- This could also occur when the destination is on another sub-section
- of the same server namespace.
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 59]
-\f
-RFC 4918 WebDAV June 2007
-
-
-9.9.5. Example - MOVE of a Non-Collection
-
- This example shows resource
- http://www.example.com/~fielding/index.html being moved to the
- location http://www.example.com/users/f/fielding/index.html. The
- contents of the destination resource would have been overwritten if
- the destination URL was already mapped to a resource. In this case,
- since there was nothing at the destination resource, the response
- code is 201 (Created).
-
- >>Request
-
- MOVE /~fielding/index.html HTTP/1.1
- Host: www.example.com
- Destination: http://www.example/users/f/fielding/index.html
-
- >>Response
-
- HTTP/1.1 201 Created
- Location: http://www.example.com/users/f/fielding/index.html
-
-9.9.6. Example - MOVE of a Collection
-
- >>Request
-
- MOVE /container/ HTTP/1.1
- Host: www.example.com
- Destination: http://www.example.com/othercontainer/
- Overwrite: F
- If: (<urn:uuid:fe184f2e-6eec-41d0-c765-01adc56e6bb4>)
- (<urn:uuid:e454f3f3-acdc-452a-56c7-00a5c91e4b77>)
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <d:multistatus xmlns:d='DAV:'>
- <d:response>
- <d:href>http://www.example.com/othercontainer/C2/</d:href>
- <d:status>HTTP/1.1 423 Locked</d:status>
- <d:error><d:lock-token-submitted/></d:error>
- </d:response>
- </d:multistatus>
-
-
-
-
-
-Dusseault Standards Track [Page 60]
-\f
-RFC 4918 WebDAV June 2007
-
-
- In this example, the client has submitted a number of lock tokens
- with the request. A lock token will need to be submitted for every
- resource, both source and destination, anywhere in the scope of the
- method, that is locked. In this case, the proper lock token was not
- submitted for the destination
- http://www.example.com/othercontainer/C2/. This means that the
- resource /container/C2/ could not be moved. Because there was an
- error moving /container/C2/, none of /container/C2's members were
- moved. However, no errors were listed for those members due to the
- error minimization rules. User agent authentication has previously
- occurred via a mechanism outside the scope of the HTTP protocol, in
- an underlying transport layer.
-
-9.10. LOCK Method
-
- The following sections describe the LOCK method, which is used to
- take out a lock of any access type and to refresh an existing lock.
- These sections on the LOCK method describe only those semantics that
- are specific to the LOCK method and are independent of the access
- type of the lock being requested.
-
- Any resource that supports the LOCK method MUST, at minimum, support
- the XML request and response formats defined herein.
-
- This method is neither idempotent nor safe (see Section 9.1 of
- [RFC2616]). Responses to this method MUST NOT be cached.
-
-9.10.1. Creating a Lock on an Existing Resource
-
- A LOCK request to an existing resource will create a lock on the
- resource identified by the Request-URI, provided the resource is not
- already locked with a conflicting lock. The resource identified in
- the Request-URI becomes the root of the lock. LOCK method requests
- to create a new lock MUST have an XML request body. The server MUST
- preserve the information provided by the client in the 'owner'
- element in the LOCK request. The LOCK request MAY have a Timeout
- header.
-
- When a new lock is created, the LOCK response:
-
- o MUST contain a body with the value of the DAV:lockdiscovery
- property in a prop XML element. This MUST contain the full
- information about the lock just granted, while information about
- other (shared) locks is OPTIONAL.
-
- o MUST include the Lock-Token response header with the token
- associated with the new lock.
-
-
-
-
-Dusseault Standards Track [Page 61]
-\f
-RFC 4918 WebDAV June 2007
-
-
-9.10.2. Refreshing Locks
-
- A lock is refreshed by sending a LOCK request to the URL of a
- resource within the scope of the lock. This request MUST NOT have a
- body and it MUST specify which lock to refresh by using the 'If'
- header with a single lock token (only one lock may be refreshed at a
- time). The request MAY contain a Timeout header, which a server MAY
- accept to change the duration remaining on the lock to the new value.
- A server MUST ignore the Depth header on a LOCK refresh.
-
- If the resource has other (shared) locks, those locks are unaffected
- by a lock refresh. Additionally, those locks do not prevent the
- named lock from being refreshed.
-
- The Lock-Token header is not returned in the response for a
- successful refresh LOCK request, but the LOCK response body MUST
- contain the new value for the DAV:lockdiscovery property.
-
-9.10.3. Depth and Locking
-
- The Depth header may be used with the LOCK method. Values other than
- 0 or infinity MUST NOT be used with the Depth header on a LOCK
- method. All resources that support the LOCK method MUST support the
- Depth header.
-
- A Depth header of value 0 means to just lock the resource specified
- by the Request-URI.
-
- If the Depth header is set to infinity, then the resource specified
- in the Request-URI along with all its members, all the way down the
- hierarchy, are to be locked. A successful result MUST return a
- single lock token. Similarly, if an UNLOCK is successfully executed
- on this token, all associated resources are unlocked. Hence, partial
- success is not an option for LOCK or UNLOCK. Either the entire
- hierarchy is locked or no resources are locked.
-
- If the lock cannot be granted to all resources, the server MUST
- return a Multi-Status response with a 'response' element for at least
- one resource that prevented the lock from being granted, along with a
- suitable status code for that failure (e.g., 403 (Forbidden) or 423
- (Locked)). Additionally, if the resource causing the failure was not
- the resource requested, then the server SHOULD include a 'response'
- element for the Request-URI as well, with a 'status' element
- containing 424 Failed Dependency.
-
- If no Depth header is submitted on a LOCK request, then the request
- MUST act as if a "Depth:infinity" had been submitted.
-
-
-
-
-Dusseault Standards Track [Page 62]
-\f
-RFC 4918 WebDAV June 2007
-
-
-9.10.4. Locking Unmapped URLs
-
- A successful LOCK method MUST result in the creation of an empty
- resource that is locked (and that is not a collection) when a
- resource did not previously exist at that URL. Later on, the lock
- may go away but the empty resource remains. Empty resources MUST
- then appear in PROPFIND responses including that URL in the response
- scope. A server MUST respond successfully to a GET request to an
- empty resource, either by using a 204 No Content response, or by
- using 200 OK with a Content-Length header indicating zero length
-
-9.10.5. Lock Compatibility Table
-
- The table below describes the behavior that occurs when a lock
- request is made on a resource.
-
- +--------------------------+----------------+-------------------+
- | Current State | Shared Lock OK | Exclusive Lock OK |
- +--------------------------+----------------+-------------------+
- | None | True | True |
- | Shared Lock | True | False |
- | Exclusive Lock | False | False* |
- +--------------------------+----------------+-------------------+
-
- Legend: True = lock may be granted. False = lock MUST NOT be
- granted. *=It is illegal for a principal to request the same lock
- twice.
-
- The current lock state of a resource is given in the leftmost column,
- and lock requests are listed in the first row. The intersection of a
- row and column gives the result of a lock request. For example, if a
- shared lock is held on a resource, and an exclusive lock is
- requested, the table entry is "false", indicating that the lock must
- not be granted.
-
-9.10.6. LOCK Responses
-
- In addition to the general status codes possible, the following
- status codes have specific applicability to LOCK:
-
- 200 (OK) - The LOCK request succeeded and the value of the DAV:
- lockdiscovery property is included in the response body.
-
- 201 (Created) - The LOCK request was to an unmapped URL, the request
- succeeded and resulted in the creation of a new resource, and the
- value of the DAV:lockdiscovery property is included in the response
- body.
-
-
-
-
-Dusseault Standards Track [Page 63]
-\f
-RFC 4918 WebDAV June 2007
-
-
- 409 (Conflict) - A resource cannot be created at the destination
- until one or more intermediate collections have been created. The
- server MUST NOT create those intermediate collections automatically.
-
- 423 (Locked), potentially with 'no-conflicting-lock' precondition
- code - There is already a lock on the resource that is not compatible
- with the requested lock (see lock compatibility table above).
-
- 412 (Precondition Failed), with 'lock-token-matches-request-uri'
- precondition code - The LOCK request was made with an If header,
- indicating that the client wishes to refresh the given lock.
- However, the Request-URI did not fall within the scope of the lock
- identified by the token. The lock may have a scope that does not
- include the Request-URI, or the lock could have disappeared, or the
- token may be invalid.
-
-9.10.7. Example - Simple Lock Request
-
- >>Request
-
- LOCK /workspace/webdav/proposal.doc HTTP/1.1
- Host: example.com
- Timeout: Infinite, Second-4100000000
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
- Authorization: Digest username="ejw",
- realm="ejw@example.com", nonce="...",
- uri="/workspace/webdav/proposal.doc",
- response="...", opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:lockinfo xmlns:D='DAV:'>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- <D:owner>
- <D:href>http://example.org/~ejw/contact.html</D:href>
- </D:owner>
- </D:lockinfo>
-
- >>Response
-
- HTTP/1.1 200 OK
- Lock-Token: <urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:prop xmlns:D="DAV:">
-
-
-
-Dusseault Standards Track [Page 64]
-\f
-RFC 4918 WebDAV June 2007
-
-
- <D:lockdiscovery>
- <D:activelock>
- <D:locktype><D:write/></D:locktype>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:depth>infinity</D:depth>
- <D:owner>
- <D:href>http://example.org/~ejw/contact.html</D:href>
- </D:owner>
- <D:timeout>Second-604800</D:timeout>
- <D:locktoken>
- <D:href
- >urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href>
- </D:locktoken>
- <D:lockroot>
- <D:href
- >http://example.com/workspace/webdav/proposal.doc</D:href>
- </D:lockroot>
- </D:activelock>
- </D:lockdiscovery>
- </D:prop>
-
-
- This example shows the successful creation of an exclusive write lock
- on resource http://example.com/workspace/webdav/proposal.doc. The
- resource http://example.org/~ejw/contact.html contains contact
- information for the creator of the lock. The server has an activity-
- based timeout policy in place on this resource, which causes the lock
- to automatically be removed after 1 week (604800 seconds). Note that
- the nonce, response, and opaque fields have not been calculated in
- the Authorization request header.
-
-9.10.8. Example - Refreshing a Write Lock
-
- >>Request
-
- LOCK /workspace/webdav/proposal.doc HTTP/1.1
- Host: example.com
- Timeout: Infinite, Second-4100000000
- If: (<urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>)
- Authorization: Digest username="ejw",
- realm="ejw@example.com", nonce="...",
- uri="/workspace/webdav/proposal.doc",
- response="...", opaque="..."
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 65]
-\f
-RFC 4918 WebDAV June 2007
-
-
- >>Response
-
- HTTP/1.1 200 OK
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:prop xmlns:D="DAV:">
- <D:lockdiscovery>
- <D:activelock>
- <D:locktype><D:write/></D:locktype>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:depth>infinity</D:depth>
- <D:owner>
- <D:href>http://example.org/~ejw/contact.html</D:href>
- </D:owner>
- <D:timeout>Second-604800</D:timeout>
- <D:locktoken>
- <D:href
- >urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href>
- </D:locktoken>
- <D:lockroot>
- <D:href
- >http://example.com/workspace/webdav/proposal.doc</D:href>
- </D:lockroot>
- </D:activelock>
- </D:lockdiscovery>
- </D:prop>
-
-
- This request would refresh the lock, attempting to reset the timeout
- to the new value specified in the timeout header. Notice that the
- client asked for an infinite time out but the server choose to ignore
- the request. In this example, the nonce, response, and opaque fields
- have not been calculated in the Authorization request header.
-
-9.10.9. Example - Multi-Resource Lock Request
-
- >>Request
-
- LOCK /webdav/ HTTP/1.1
- Host: example.com
- Timeout: Infinite, Second-4100000000
- Depth: infinity
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
- Authorization: Digest username="ejw",
- realm="ejw@example.com", nonce="...",
-
-
-
-Dusseault Standards Track [Page 66]
-\f
-RFC 4918 WebDAV June 2007
-
-
- uri="/workspace/webdav/proposal.doc",
- response="...", opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:lockinfo xmlns:D="DAV:">
- <D:locktype><D:write/></D:locktype>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:owner>
- <D:href>http://example.org/~ejw/contact.html</D:href>
- </D:owner>
- </D:lockinfo>
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://example.com/webdav/secret</D:href>
- <D:status>HTTP/1.1 403 Forbidden</D:status>
- </D:response>
- <D:response>
- <D:href>http://example.com/webdav/</D:href>
- <D:status>HTTP/1.1 424 Failed Dependency</D:status>
- </D:response>
- </D:multistatus>
-
-
- This example shows a request for an exclusive write lock on a
- collection and all its children. In this request, the client has
- specified that it desires an infinite-length lock, if available,
- otherwise a timeout of 4.1 billion seconds, if available. The
- request entity body contains the contact information for the
- principal taking out the lock -- in this case, a Web page URL.
-
- The error is a 403 (Forbidden) response on the resource
- http://example.com/webdav/secret. Because this resource could not be
- locked, none of the resources were locked. Note also that the a
- 'response' element for the Request-URI itself has been included as
- required.
-
- In this example, the nonce, response, and opaque fields have not been
- calculated in the Authorization request header.
-
-
-
-
-
-Dusseault Standards Track [Page 67]
-\f
-RFC 4918 WebDAV June 2007
-
-
-9.11. UNLOCK Method
-
- The UNLOCK method removes the lock identified by the lock token in
- the Lock-Token request header. The Request-URI MUST identify a
- resource within the scope of the lock.
-
- Note that use of the Lock-Token header to provide the lock token is
- not consistent with other state-changing methods, which all require
- an If header with the lock token. Thus, the If header is not needed
- to provide the lock token. Naturally, when the If header is present,
- it has its normal meaning as a conditional header.
-
- For a successful response to this method, the server MUST delete the
- lock entirely.
-
- If all resources that have been locked under the submitted lock token
- cannot be unlocked, then the UNLOCK request MUST fail.
-
- A successful response to an UNLOCK method does not mean that the
- resource is necessarily unlocked. It means that the specific lock
- corresponding to the specified token no longer exists.
-
- Any DAV-compliant resource that supports the LOCK method MUST support
- the UNLOCK method.
-
- This method is idempotent, but not safe (see Section 9.1 of
- [RFC2616]). Responses to this method MUST NOT be cached.
-
-9.11.1. Status Codes
-
- In addition to the general status codes possible, the following
- status codes have specific applicability to UNLOCK:
-
- 204 (No Content) - Normal success response (rather than 200 OK, since
- 200 OK would imply a response body, and an UNLOCK success response
- does not normally contain a body).
-
- 400 (Bad Request) - No lock token was provided.
-
- 403 (Forbidden) - The currently authenticated principal does not have
- permission to remove the lock.
-
- 409 (Conflict), with 'lock-token-matches-request-uri' precondition -
- The resource was not locked, or the request was made to a Request-URI
- that was not within the scope of the lock.
-
-
-
-
-
-
-Dusseault Standards Track [Page 68]
-\f
-RFC 4918 WebDAV June 2007
-
-
-9.11.2. Example - UNLOCK
-
- >>Request
-
- UNLOCK /workspace/webdav/info.doc HTTP/1.1
- Host: example.com
- Lock-Token: <urn:uuid:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7>
- Authorization: Digest username="ejw"
- realm="ejw@example.com", nonce="...",
- uri="/workspace/webdav/proposal.doc",
- response="...", opaque="..."
-
- >>Response
-
- HTTP/1.1 204 No Content
-
- In this example, the lock identified by the lock token
- "urn:uuid:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is successfully
- removed from the resource
- http://example.com/workspace/webdav/info.doc. If this lock included
- more than just one resource, the lock is removed from all resources
- included in the lock.
-
- In this example, the nonce, response, and opaque fields have not been
- calculated in the Authorization request header.
-
-10. HTTP Headers for Distributed Authoring
-
- All DAV headers follow the same basic formatting rules as HTTP
- headers. This includes rules like line continuation and how to
- combine (or separate) multiple instances of the same header using
- commas.
-
- WebDAV adds two new conditional headers to the set defined in HTTP:
- the If and Overwrite headers.
-
-10.1. DAV Header
-
- DAV = "DAV" ":" #( compliance-class )
- compliance-class = ( "1" | "2" | "3" | extend )
- extend = Coded-URL | token
- ; token is defined in RFC 2616, Section 2.2
- Coded-URL = "<" absolute-URI ">"
- ; No linear whitespace (LWS) allowed in Coded-URL
- ; absolute-URI defined in RFC 3986, Section 4.3
-
-
-
-
-
-
-Dusseault Standards Track [Page 69]
-\f
-RFC 4918 WebDAV June 2007
-
-
- This general-header appearing in the response indicates that the
- resource supports the DAV schema and protocol as specified. All DAV-
- compliant resources MUST return the DAV header with compliance-class
- "1" on all OPTIONS responses. In cases where WebDAV is only
- supported in part of the server namespace, an OPTIONS request to non-
- WebDAV resources (including "/") SHOULD NOT advertise WebDAV support.
-
- The value is a comma-separated list of all compliance class
- identifiers that the resource supports. Class identifiers may be
- Coded-URLs or tokens (as defined by [RFC2616]). Identifiers can
- appear in any order. Identifiers that are standardized through the
- IETF RFC process are tokens, but other identifiers SHOULD be Coded-
- URLs to encourage uniqueness.
-
- A resource must show class 1 compliance if it shows class 2 or 3
- compliance. In general, support for one compliance class does not
- entail support for any other, and in particular, support for
- compliance class 3 does not require support for compliance class 2.
- Please refer to Section 18 for more details on compliance classes
- defined in this specification.
-
- Note that many WebDAV servers do not advertise WebDAV support in
- response to "OPTIONS *".
-
- As a request header, this header allows the client to advertise
- compliance with named features when the server needs that
- information. Clients SHOULD NOT send this header unless a standards
- track specification requires it. Any extension that makes use of
- this as a request header will need to carefully consider caching
- implications.
-
-10.2. Depth Header
-
- Depth = "Depth" ":" ("0" | "1" | "infinity")
-
- The Depth request header is used with methods executed on resources
- that could potentially have internal members to indicate whether the
- method is to be applied only to the resource ("Depth: 0"), to the
- resource and its internal members only ("Depth: 1"), or the resource
- and all its members ("Depth: infinity").
-
- The Depth header is only supported if a method's definition
- explicitly provides for such support.
-
- The following rules are the default behavior for any method that
- supports the Depth header. A method may override these defaults by
- defining different behavior in its definition.
-
-
-
-
-Dusseault Standards Track [Page 70]
-\f
-RFC 4918 WebDAV June 2007
-
-
- Methods that support the Depth header may choose not to support all
- of the header's values and may define, on a case-by-case basis, the
- behavior of the method if a Depth header is not present. For
- example, the MOVE method only supports "Depth: infinity", and if a
- Depth header is not present, it will act as if a "Depth: infinity"
- header had been applied.
-
- Clients MUST NOT rely upon methods executing on members of their
- hierarchies in any particular order or on the execution being atomic
- unless the particular method explicitly provides such guarantees.
-
- Upon execution, a method with a Depth header will perform as much of
- its assigned task as possible and then return a response specifying
- what it was able to accomplish and what it failed to do.
-
- So, for example, an attempt to COPY a hierarchy may result in some of
- the members being copied and some not.
-
- By default, the Depth header does not interact with other headers.
- That is, each header on a request with a Depth header MUST be applied
- only to the Request-URI if it applies to any resource, unless
- specific Depth behavior is defined for that header.
-
- If a source or destination resource within the scope of the Depth
- header is locked in such a way as to prevent the successful execution
- of the method, then the lock token for that resource MUST be
- submitted with the request in the If request header.
-
- The Depth header only specifies the behavior of the method with
- regards to internal members. If a resource does not have internal
- members, then the Depth header MUST be ignored.
-
-10.3. Destination Header
-
- The Destination request header specifies the URI that identifies a
- destination resource for methods such as COPY and MOVE, which take
- two URIs as parameters.
-
- Destination = "Destination" ":" Simple-ref
-
-
- If the Destination value is an absolute-URI (Section 4.3 of
- [RFC3986]), it may name a different server (or different port or
- scheme). If the source server cannot attempt a copy to the remote
- server, it MUST fail the request. Note that copying and moving
- resources to remote servers is not fully defined in this
- specification (e.g., specific error conditions).
-
-
-
-
-Dusseault Standards Track [Page 71]
-\f
-RFC 4918 WebDAV June 2007
-
-
- If the Destination value is too long or otherwise unacceptable, the
- server SHOULD return 400 (Bad Request), ideally with helpful
- information in an error body.
-
-10.4. If Header
-
- The If request header is intended to have similar functionality to
- the If-Match header defined in Section 14.24 of [RFC2616]. However,
- the If header handles any state token as well as ETags. A typical
- example of a state token is a lock token, and lock tokens are the
- only state tokens defined in this specification.
-
-10.4.1. Purpose
-
- The If header has two distinct purposes:
-
- o The first purpose is to make a request conditional by supplying a
- series of state lists with conditions that match tokens and ETags
- to a specific resource. If this header is evaluated and all state
- lists fail, then the request MUST fail with a 412 (Precondition
- Failed) status. On the other hand, the request can succeed only
- if one of the described state lists succeeds. The success
- criteria for state lists and matching functions are defined in
- Sections 10.4.3 and 10.4.4.
-
- o Additionally, the mere fact that a state token appears in an If
- header means that it has been "submitted" with the request. In
- general, this is used to indicate that the client has knowledge of
- that state token. The semantics for submitting a state token
- depend on its type (for lock tokens, please refer to Section 6).
-
- Note that these two purposes need to be treated distinctly: a state
- token counts as being submitted independently of whether the server
- actually has evaluated the state list it appears in, and also
- independently of whether or not the condition it expressed was found
- to be true.
-
-10.4.2. Syntax
-
- If = "If" ":" ( 1*No-tag-list | 1*Tagged-list )
-
- No-tag-list = List
- Tagged-list = Resource-Tag 1*List
-
- List = "(" 1*Condition ")"
- Condition = ["Not"] (State-token | "[" entity-tag "]")
- ; entity-tag: see Section 3.11 of [RFC2616]
- ; No LWS allowed between "[", entity-tag and "]"
-
-
-
-Dusseault Standards Track [Page 72]
-\f
-RFC 4918 WebDAV June 2007
-
-
- State-token = Coded-URL
-
- Resource-Tag = "<" Simple-ref ">"
- ; Simple-ref: see Section 8.3
- ; No LWS allowed in Resource-Tag
-
- The syntax distinguishes between untagged lists ("No-tag-list") and
- tagged lists ("Tagged-list"). Untagged lists apply to the resource
- identified by the Request-URI, while tagged lists apply to the
- resource identified by the preceding Resource-Tag.
-
- A Resource-Tag applies to all subsequent Lists, up to the next
- Resource-Tag.
-
- Note that the two list types cannot be mixed within an If header.
- This is not a functional restriction because the No-tag-list syntax
- is just a shorthand notation for a Tagged-list production with a
- Resource-Tag referring to the Request-URI.
-
- Each List consists of one or more Conditions. Each Condition is
- defined in terms of an entity-tag or state-token, potentially negated
- by the prefix "Not".
-
- Note that the If header syntax does not allow multiple instances of
- If headers in a single request. However, the HTTP header syntax
- allows extending single header values across multiple lines, by
- inserting a line break followed by whitespace (see [RFC2616], Section
- 4.2).
-
-10.4.3. List Evaluation
-
- A Condition that consists of a single entity-tag or state-token
- evaluates to true if the resource matches the described state (where
- the individual matching functions are defined below in
- Section 10.4.4). Prefixing it with "Not" reverses the result of the
- evaluation (thus, the "Not" applies only to the subsequent entity-tag
- or state-token).
-
- Each List production describes a series of conditions. The whole
- list evaluates to true if and only if each condition evaluates to
- true (that is, the list represents a logical conjunction of
- Conditions).
-
- Each No-tag-list and Tagged-list production may contain one or more
- Lists. They evaluate to true if and only if any of the contained
- lists evaluates to true (that is, if there's more than one List, that
- List sequence represents a logical disjunction of the Lists).
-
-
-
-
-Dusseault Standards Track [Page 73]
-\f
-RFC 4918 WebDAV June 2007
-
-
- Finally, the whole If header evaluates to true if and only if at
- least one of the No-tag-list or Tagged-list productions evaluates to
- true. If the header evaluates to false, the server MUST reject the
- request with a 412 (Precondition Failed) status. Otherwise,
- execution of the request can proceed as if the header wasn't present.
-
-10.4.4. Matching State Tokens and ETags
-
- When performing If header processing, the definition of a matching
- state token or entity tag is as follows:
-
- Identifying a resource: The resource is identified by the URI along
- with the token, in tagged list production, or by the Request-URI in
- untagged list production.
-
- Matching entity tag: Where the entity tag matches an entity tag
- associated with the identified resource. Servers MUST use either the
- weak or the strong comparison function defined in Section 13.3.3 of
- [RFC2616].
-
- Matching state token: Where there is an exact match between the state
- token in the If header and any state token on the identified
- resource. A lock state token is considered to match if the resource
- is anywhere in the scope of the lock.
-
- Handling unmapped URLs: For both ETags and state tokens, treat as if
- the URL identified a resource that exists but does not have the
- specified state.
-
-10.4.5. If Header and Non-DAV-Aware Proxies
-
- Non-DAV-aware proxies will not honor the If header, since they will
- not understand the If header, and HTTP requires non-understood
- headers to be ignored. When communicating with HTTP/1.1 proxies, the
- client MUST use the "Cache-Control: no-cache" request header so as to
- prevent the proxy from improperly trying to service the request from
- its cache. When dealing with HTTP/1.0 proxies, the "Pragma: no-
- cache" request header MUST be used for the same reason.
-
- Because in general clients may not be able to reliably detect non-
- DAV-aware intermediates, they are advised to always prevent caching
- using the request directives mentioned above.
-
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 74]
-\f
-RFC 4918 WebDAV June 2007
-
-
-10.4.6. Example - No-tag Production
-
- If: (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
- ["I am an ETag"])
- (["I am another ETag"])
-
- The previous header would require that the resource identified in the
- Request-URI be locked with the specified lock token and be in the
- state identified by the "I am an ETag" ETag or in the state
- identified by the second ETag "I am another ETag".
-
- To put the matter more plainly one can think of the previous If
- header as expressing the condition below:
-
- (
- is-locked-with(urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2) AND
- matches-etag("I am an ETag")
- )
- OR
- (
- matches-etag("I am another ETag")
- )
-
-10.4.7. Example - Using "Not" with No-tag Production
-
- If: (Not <urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
- <urn:uuid:58f202ac-22cf-11d1-b12d-002035b29092>)
-
- This If header requires that the resource must not be locked with a
- lock having the lock token
- urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 and must be locked by a
- lock with the lock token
- urn:uuid:58f202ac-22cf-11d1-b12d-002035b29092.
-
-10.4.8. Example - Causing a Condition to Always Evaluate to True
-
- There may be cases where a client wishes to submit state tokens, but
- doesn't want the request to fail just because the state token isn't
- current anymore. One simple way to do this is to include a Condition
- that is known to always evaluate to true, such as in:
-
- If: (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>)
- (Not <DAV:no-lock>)
-
- "DAV:no-lock" is known to never represent a current lock token. Lock
- tokens are assigned by the server, following the uniqueness
- requirements described in Section 6.5, therefore cannot use the
- "DAV:" scheme. Thus, by applying "Not" to a state token that is
-
-
-
-Dusseault Standards Track [Page 75]
-\f
-RFC 4918 WebDAV June 2007
-
-
- known not to be current, the Condition always evaluates to true.
- Consequently, the whole If header will always evaluate to true, and
- the lock token urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 will be
- submitted in any case.
-
-10.4.9. Example - Tagged List If Header in COPY
-
- >>Request
-
- COPY /resource1 HTTP/1.1
- Host: www.example.com
- Destination: /resource2
- If: </resource1>
- (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
- [W/"A weak ETag"]) (["strong ETag"])
-
- In this example, http://www.example.com/resource1 is being copied to
- http://www.example.com/resource2. When the method is first applied
- to http://www.example.com/resource1, resource1 must be in the state
- specified by "(<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2> [W/"A
- weak ETag"]) (["strong ETag"])". That is, either it must be locked
- with a lock token of "urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2"
- and have a weak entity tag W/"A weak ETag" or it must have a strong
- entity tag "strong ETag".
-
-10.4.10. Example - Matching Lock Tokens with Collection Locks
-
- DELETE /specs/rfc2518.txt HTTP/1.1
- Host: www.example.com
- If: <http://www.example.com/specs/>
- (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>)
-
- For this example, the lock token must be compared to the identified
- resource, which is the 'specs' collection identified by the URL in
- the tagged list production. If the 'specs' collection is not locked
- by a lock with the specified lock token, the request MUST fail.
- Otherwise, this request could succeed, because the If header
- evaluates to true, and because the lock token for the lock affecting
- the affected resource has been submitted.
-
-10.4.11. Example - Matching ETags on Unmapped URLs
-
- Consider a collection "/specs" that does not contain the member
- "/specs/rfc2518.doc". In this case, the If header
-
- If: </specs/rfc2518.doc> (["4217"])
-
-
-
-
-
-Dusseault Standards Track [Page 76]
-\f
-RFC 4918 WebDAV June 2007
-
-
- will evaluate to false (the URI isn't mapped, thus the resource
- identified by the URI doesn't have an entity matching the ETag
- "4217").
-
- On the other hand, an If header of
-
- If: </specs/rfc2518.doc> (Not ["4217"])
-
- will consequently evaluate to true.
-
- Note that, as defined above in Section 10.4.4, the same
- considerations apply to matching state tokens.
-
-10.5. Lock-Token Header
-
- Lock-Token = "Lock-Token" ":" Coded-URL
-
- The Lock-Token request header is used with the UNLOCK method to
- identify the lock to be removed. The lock token in the Lock-Token
- request header MUST identify a lock that contains the resource
- identified by Request-URI as a member.
-
- The Lock-Token response header is used with the LOCK method to
- indicate the lock token created as a result of a successful LOCK
- request to create a new lock.
-
-10.6. Overwrite Header
-
- Overwrite = "Overwrite" ":" ("T" | "F")
-
- The Overwrite request header specifies whether the server should
- overwrite a resource mapped to the destination URL during a COPY or
- MOVE. A value of "F" states that the server must not perform the
- COPY or MOVE operation if the destination URL does map to a resource.
- If the overwrite header is not included in a COPY or MOVE request,
- then the resource MUST treat the request as if it has an overwrite
- header of value "T". While the Overwrite header appears to duplicate
- the functionality of using an "If-Match: *" header (see [RFC2616]),
- If-Match applies only to the Request-URI, and not to the Destination
- of a COPY or MOVE.
-
- If a COPY or MOVE is not performed due to the value of the Overwrite
- header, the method MUST fail with a 412 (Precondition Failed) status
- code. The server MUST do authorization checks before checking this
- or any conditional header.
-
- All DAV-compliant resources MUST support the Overwrite header.
-
-
-
-
-Dusseault Standards Track [Page 77]
-\f
-RFC 4918 WebDAV June 2007
-
-
-10.7. Timeout Request Header
-
- TimeOut = "Timeout" ":" 1#TimeType
- TimeType = ("Second-" DAVTimeOutVal | "Infinite")
- ; No LWS allowed within TimeType
- DAVTimeOutVal = 1*DIGIT
-
- Clients MAY include Timeout request headers in their LOCK requests.
- However, the server is not required to honor or even consider these
- requests. Clients MUST NOT submit a Timeout request header with any
- method other than a LOCK method.
-
- The "Second" TimeType specifies the number of seconds that will
- elapse between granting of the lock at the server, and the automatic
- removal of the lock. The timeout value for TimeType "Second" MUST
- NOT be greater than 2^32-1.
-
- See Section 6.6 for a description of lock timeout behavior.
-
-11. Status Code Extensions to HTTP/1.1
-
- The following status codes are added to those defined in HTTP/1.1
- [RFC2616].
-
-11.1. 207 Multi-Status
-
- The 207 (Multi-Status) status code provides status for multiple
- independent operations (see Section 13 for more information).
-
-11.2. 422 Unprocessable Entity
-
- The 422 (Unprocessable Entity) status code means the server
- understands the content type of the request entity (hence a
- 415(Unsupported Media Type) status code is inappropriate), and the
- syntax of the request entity is correct (thus a 400 (Bad Request)
- status code is inappropriate) but was unable to process the contained
- instructions. For example, this error condition may occur if an XML
- request body contains well-formed (i.e., syntactically correct), but
- semantically erroneous, XML instructions.
-
-11.3. 423 Locked
-
- The 423 (Locked) status code means the source or destination resource
- of a method is locked. This response SHOULD contain an appropriate
- precondition or postcondition code, such as 'lock-token-submitted' or
- 'no-conflicting-lock'.
-
-
-
-
-
-Dusseault Standards Track [Page 78]
-\f
-RFC 4918 WebDAV June 2007
-
-
-11.4. 424 Failed Dependency
-
- The 424 (Failed Dependency) status code means that the method could
- not be performed on the resource because the requested action
- depended on another action and that action failed. For example, if a
- command in a PROPPATCH method fails, then, at minimum, the rest of
- the commands will also fail with 424 (Failed Dependency).
-
-11.5. 507 Insufficient Storage
-
- The 507 (Insufficient Storage) status code means the method could not
- be performed on the resource because the server is unable to store
- the representation needed to successfully complete the request. This
- condition is considered to be temporary. If the request that
- received this status code was the result of a user action, the
- request MUST NOT be repeated until it is requested by a separate user
- action.
-
-12. Use of HTTP Status Codes
-
- These HTTP codes are not redefined, but their use is somewhat
- extended by WebDAV methods and requirements. In general, many HTTP
- status codes can be used in response to any request, not just in
- cases described in this document. Note also that WebDAV servers are
- known to use 300-level redirect responses (and early interoperability
- tests found clients unprepared to see those responses). A 300-level
- response MUST NOT be used when the server has created a new resource
- in response to the request.
-
-12.1. 412 Precondition Failed
-
- Any request can contain a conditional header defined in HTTP (If-
- Match, If-Modified-Since, etc.) or the "If" or "Overwrite"
- conditional headers defined in this specification. If the server
- evaluates a conditional header, and if that condition fails to hold,
- then this error code MUST be returned. On the other hand, if the
- client did not include a conditional header in the request, then the
- server MUST NOT use this status code.
-
-12.2. 414 Request-URI Too Long
-
- This status code is used in HTTP 1.1 only for Request-URIs, not URIs
- in other locations.
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 79]
-\f
-RFC 4918 WebDAV June 2007
-
-
-13. Multi-Status Response
-
- A Multi-Status response conveys information about multiple resources
- in situations where multiple status codes might be appropriate. The
- default Multi-Status response body is a text/xml or application/xml
- HTTP entity with a 'multistatus' root element. Further elements
- contain 200, 300, 400, and 500 series status codes generated during
- the method invocation. 100 series status codes SHOULD NOT be recorded
- in a 'response' XML element.
-
- Although '207' is used as the overall response status code, the
- recipient needs to consult the contents of the multistatus response
- body for further information about the success or failure of the
- method execution. The response MAY be used in success, partial
- success and also in failure situations.
-
- The 'multistatus' root element holds zero or more 'response' elements
- in any order, each with information about an individual resource.
- Each 'response' element MUST have an 'href' element to identify the
- resource.
-
- A Multi-Status response uses one out of two distinct formats for
- representing the status:
-
- 1. A 'status' element as child of the 'response' element indicates
- the status of the message execution for the identified resource
- as a whole (for instance, see Section 9.6.2). Some method
- definitions provide information about specific status codes
- clients should be prepared to see in a response. However,
- clients MUST be able to handle other status codes, using the
- generic rules defined in Section 10 of [RFC2616].
-
- 2. For PROPFIND and PROPPATCH, the format has been extended using
- the 'propstat' element instead of 'status', providing information
- about individual properties of a resource. This format is
- specific to PROPFIND and PROPPATCH, and is described in detail in
- Sections 9.1 and 9.2.
-
-13.1. Response Headers
-
- HTTP defines the Location header to indicate a preferred URL for the
- resource that was addressed in the Request-URI (e.g., in response to
- successful PUT requests or in redirect responses). However, use of
- this header creates ambiguity when there are URLs in the body of the
- response, as with Multi-Status. Thus, use of the Location header
- with the Multi-Status response is intentionally undefined.
-
-
-
-
-
-Dusseault Standards Track [Page 80]
-\f
-RFC 4918 WebDAV June 2007
-
-
-13.2. Handling Redirected Child Resources
-
- Redirect responses (300-303, 305, and 307) defined in HTTP 1.1
- normally take a Location header to indicate the new URI for the
- single resource redirected from the Request-URI. Multi-Status
- responses contain many resource addresses, but the original
- definition in [RFC2518] did not have any place for the server to
- provide the new URI for redirected resources. This specification
- does define a 'location' element for this information (see
- Section 14.9). Servers MUST use this new element with redirect
- responses in Multi-Status.
-
- Clients encountering redirected resources in Multi-Status MUST NOT
- rely on the 'location' element being present with a new URI. If the
- element is not present, the client MAY reissue the request to the
- individual redirected resource, because the response to that request
- can be redirected with a Location header containing the new URI.
-
-13.3. Internal Status Codes
-
- Sections 9.2.1, 9.1.2, 9.6.1, 9.8.3, and 9.9.2 define various status
- codes used in Multi-Status responses. This specification does not
- define the meaning of other status codes that could appear in these
- responses.
-
-14. XML Element Definitions
-
- In this section, the final line of each section gives the element
- type declaration using the format defined in [REC-XML]. The "Value"
- field, where present, specifies further restrictions on the allowable
- contents of the XML element using BNF (i.e., to further restrict the
- values of a PCDATA element). Note that all of the elements defined
- here may be extended according to the rules defined in Section 17.
- All elements defined here are in the "DAV:" namespace.
-
-14.1. activelock XML Element
-
- Name: activelock
-
- Purpose: Describes a lock on a resource.
-
-
- <!ELEMENT activelock (lockscope, locktype, depth, owner?, timeout?,
- locktoken?, lockroot)>
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 81]
-\f
-RFC 4918 WebDAV June 2007
-
-
-14.2. allprop XML Element
-
- Name: allprop
-
- Purpose: Specifies that all names and values of dead properties and
- the live properties defined by this document existing on the
- resource are to be returned.
-
- <!ELEMENT allprop EMPTY >
-
-14.3. collection XML Element
-
- Name: collection
-
- Purpose: Identifies the associated resource as a collection. The
- DAV:resourcetype property of a collection resource MUST contain
- this element. It is normally empty but extensions may add sub-
- elements.
-
- <!ELEMENT collection EMPTY >
-
-14.4. depth XML Element
-
- Name: depth
-
- Purpose: Used for representing depth values in XML content (e.g.,
- in lock information).
-
- Value: "0" | "1" | "infinity"
-
- <!ELEMENT depth (#PCDATA) >
-
-14.5. error XML Element
-
- Name: error
-
- Purpose: Error responses, particularly 403 Forbidden and 409
- Conflict, sometimes need more information to indicate what went
- wrong. In these cases, servers MAY return an XML response body
- with a document element of 'error', containing child elements
- identifying particular condition codes.
-
- Description: Contains at least one XML element, and MUST NOT
- contain text or mixed content. Any element that is a child of the
- 'error' element is considered to be a precondition or
- postcondition code. Unrecognized elements MUST be ignored.
-
- <!ELEMENT error ANY >
-
-
-
-Dusseault Standards Track [Page 82]
-\f
-RFC 4918 WebDAV June 2007
-
-
-14.6. exclusive XML Element
-
- Name: exclusive
-
- Purpose: Specifies an exclusive lock.
-
-
- <!ELEMENT exclusive EMPTY >
-
-
-14.7. href XML Element
-
- Name: href
-
- Purpose: MUST contain a URI or a relative reference.
-
- Description: There may be limits on the value of 'href' depending
- on the context of its use. Refer to the specification text where
- 'href' is used to see what limitations apply in each case.
-
- Value: Simple-ref
-
-
- <!ELEMENT href (#PCDATA)>
-
-14.8. include XML Element
-
- Name: include
-
- Purpose: Any child element represents the name of a property to be
- included in the PROPFIND response. All elements inside an
- 'include' XML element MUST define properties related to the
- resource, although possible property names are in no way limited
- to those property names defined in this document or other
- standards. This element MUST NOT contain text or mixed content.
-
- <!ELEMENT include ANY >
-
-14.9. location XML Element
-
- Name: location
-
- Purpose: HTTP defines the "Location" header (see [RFC2616], Section
- 14.30) for use with some status codes (such as 201 and the 300
- series codes). When these codes are used inside a 'multistatus'
- element, the 'location' element can be used to provide the
- accompanying Location header value.
-
-
-
-
-Dusseault Standards Track [Page 83]
-\f
-RFC 4918 WebDAV June 2007
-
-
- Description: Contains a single href element with the same value
- that would be used in a Location header.
-
-
- <!ELEMENT location (href)>
-
-14.10. lockentry XML Element
-
- Name: lockentry
-
- Purpose: Defines the types of locks that can be used with the
- resource.
-
- <!ELEMENT lockentry (lockscope, locktype) >
-
-14.11. lockinfo XML Element
-
- Name: lockinfo
-
- Purpose: The 'lockinfo' XML element is used with a LOCK method to
- specify the type of lock the client wishes to have created.
-
-
- <!ELEMENT lockinfo (lockscope, locktype, owner?) >
-
-14.12. lockroot XML Element
-
- Name: lockroot
-
- Purpose: Contains the root URL of the lock, which is the URL
- through which the resource was addressed in the LOCK request.
-
- Description: The href element contains the root of the lock. The
- server SHOULD include this in all DAV:lockdiscovery property
- values and the response to LOCK requests.
-
- <!ELEMENT lockroot (href) >
-
-14.13. lockscope XML Element
-
- Name: lockscope
-
- Purpose: Specifies whether a lock is an exclusive lock, or a shared
- lock.
-
-
- <!ELEMENT lockscope (exclusive | shared) >
-
-
-
-
-Dusseault Standards Track [Page 84]
-\f
-RFC 4918 WebDAV June 2007
-
-
-14.14. locktoken XML Element
-
- Name: locktoken
-
- Purpose: The lock token associated with a lock.
-
- Description: The href contains a single lock token URI, which
- refers to the lock.
-
- <!ELEMENT locktoken (href) >
-
-14.15. locktype XML Element
-
- Name: locktype
-
- Purpose: Specifies the access type of a lock. At present, this
- specification only defines one lock type, the write lock.
-
-
- <!ELEMENT locktype (write) >
-
-
-14.16. multistatus XML Element
-
- Name: multistatus
-
- Purpose: Contains multiple response messages.
-
- Description: The 'responsedescription' element at the top level is
- used to provide a general message describing the overarching
- nature of the response. If this value is available, an
- application may use it instead of presenting the individual
- response descriptions contained within the responses.
-
-
- <!ELEMENT multistatus (response*, responsedescription?) >
-
-
-14.17. owner XML Element
-
- Name: owner
-
- Purpose: Holds client-supplied information about the creator of a
- lock.
-
- Description: Allows a client to provide information sufficient for
- either directly contacting a principal (such as a telephone number
- or Email URI), or for discovering the principal (such as the URL
-
-
-
-Dusseault Standards Track [Page 85]
-\f
-RFC 4918 WebDAV June 2007
-
-
- of a homepage) who created a lock. The value provided MUST be
- treated as a dead property in terms of XML Information Item
- preservation. The server MUST NOT alter the value unless the
- owner value provided by the client is empty. For a certain amount
- of interoperability between different client implementations, if
- clients have URI-formatted contact information for the lock
- creator suitable for user display, then clients SHOULD put those
- URIs in 'href' child elements of the 'owner' element.
-
- Extensibility: MAY be extended with child elements, mixed content,
- text content or attributes.
-
- <!ELEMENT owner ANY >
-
-14.18. prop XML Element
-
- Name: prop
-
- Purpose: Contains properties related to a resource.
-
- Description: A generic container for properties defined on
- resources. All elements inside a 'prop' XML element MUST define
- properties related to the resource, although possible property
- names are in no way limited to those property names defined in
- this document or other standards. This element MUST NOT contain
- text or mixed content.
-
- <!ELEMENT prop ANY >
-
-14.19. propertyupdate XML Element
-
- Name: propertyupdate
-
- Purpose: Contains a request to alter the properties on a resource.
-
- Description: This XML element is a container for the information
- required to modify the properties on the resource.
-
- <!ELEMENT propertyupdate (remove | set)+ >
-
-14.20. propfind XML Element
-
- Name: propfind
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 86]
-\f
-RFC 4918 WebDAV June 2007
-
-
- Purpose: Specifies the properties to be returned from a PROPFIND
- method. Four special elements are specified for use with
- 'propfind': 'prop', 'allprop', 'include', and 'propname'. If
- 'prop' is used inside 'propfind', it MUST NOT contain property
- values.
-
- <!ELEMENT propfind ( propname | (allprop, include?) | prop ) >
-
-14.21. propname XML Element
-
- Name: propname
-
- Purpose: Specifies that only a list of property names on the
- resource is to be returned.
-
- <!ELEMENT propname EMPTY >
-
-14.22. propstat XML Element
-
- Name: propstat
-
- Purpose: Groups together a prop and status element that is
- associated with a particular 'href' element.
-
- Description: The propstat XML element MUST contain one prop XML
- element and one status XML element. The contents of the prop XML
- element MUST only list the names of properties to which the result
- in the status element applies. The optional precondition/
- postcondition element and 'responsedescription' text also apply to
- the properties named in 'prop'.
-
- <!ELEMENT propstat (prop, status, error?, responsedescription?) >
-
-14.23. remove XML Element
-
- Name: remove
-
- Purpose: Lists the properties to be removed from a resource.
-
- Description: Remove instructs that the properties specified in prop
- should be removed. Specifying the removal of a property that does
- not exist is not an error. All the XML elements in a 'prop' XML
- element inside of a 'remove' XML element MUST be empty, as only
- the names of properties to be removed are required.
-
- <!ELEMENT remove (prop) >
-
-
-
-
-
-Dusseault Standards Track [Page 87]
-\f
-RFC 4918 WebDAV June 2007
-
-
-14.24. response XML Element
-
- Name: response
-
- Purpose: Holds a single response describing the effect of a method
- on resource and/or its properties.
-
- Description: The 'href' element contains an HTTP URL pointing to a
- WebDAV resource when used in the 'response' container. A
- particular 'href' value MUST NOT appear more than once as the
- child of a 'response' XML element under a 'multistatus' XML
- element. This requirement is necessary in order to keep
- processing costs for a response to linear time. Essentially, this
- prevents having to search in order to group together all the
- responses by 'href'. There are, however, no requirements
- regarding ordering based on 'href' values. The optional
- precondition/postcondition element and 'responsedescription' text
- can provide additional information about this resource relative to
- the request or result.
-
-
- <!ELEMENT response (href, ((href*, status)|(propstat+)),
- error?, responsedescription? , location?) >
-
-14.25. responsedescription XML Element
-
- Name: responsedescription
-
- Purpose: Contains information about a status response within a
- Multi-Status.
-
- Description: Provides information suitable to be presented to a
- user.
-
- <!ELEMENT responsedescription (#PCDATA) >
-
-14.26. set XML Element
-
- Name: set
-
- Purpose: Lists the property values to be set for a resource.
-
- Description: The 'set' element MUST contain only a 'prop' element.
- The elements contained by the 'prop' element inside the 'set'
- element MUST specify the name and value of properties that are set
- on the resource identified by Request-URI. If a property already
- exists, then its value is replaced. Language tagging information
- appearing in the scope of the 'prop' element (in the "xml:lang"
-
-
-
-Dusseault Standards Track [Page 88]
-\f
-RFC 4918 WebDAV June 2007
-
-
- attribute, if present) MUST be persistently stored along with the
- property, and MUST be subsequently retrievable using PROPFIND.
-
- <!ELEMENT set (prop) >
-
-14.27. shared XML Element
-
- Name: shared
-
- Purpose: Specifies a shared lock.
-
-
- <!ELEMENT shared EMPTY >
-
-
-14.28. status XML Element
-
- Name: status
-
- Purpose: Holds a single HTTP status-line.
-
- Value: status-line (defined in Section 6.1 of [RFC2616])
-
- <!ELEMENT status (#PCDATA) >
-
-14.29. timeout XML Element
-
- Name: timeout
-
- Purpose: The number of seconds remaining before a lock expires.
-
- Value: TimeType (defined in Section 10.7)
-
-
- <!ELEMENT timeout (#PCDATA) >
-
-14.30. write XML Element
-
- Name: write
-
- Purpose: Specifies a write lock.
-
-
- <!ELEMENT write EMPTY >
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 89]
-\f
-RFC 4918 WebDAV June 2007
-
-
-15. DAV Properties
-
- For DAV properties, the name of the property is also the same as the
- name of the XML element that contains its value. In the section
- below, the final line of each section gives the element type
- declaration using the format defined in [REC-XML]. The "Value"
- field, where present, specifies further restrictions on the allowable
- contents of the XML element using BNF (i.e., to further restrict the
- values of a PCDATA element).
-
- A protected property is one that cannot be changed with a PROPPATCH
- request. There may be other requests that would result in a change
- to a protected property (as when a LOCK request affects the value of
- DAV:lockdiscovery). Note that a given property could be protected on
- one type of resource, but not protected on another type of resource.
-
- A computed property is one with a value defined in terms of a
- computation (based on the content and other properties of that
- resource, or even of some other resource). A computed property is
- always a protected property.
-
- COPY and MOVE behavior refers to local COPY and MOVE operations.
-
- For properties defined based on HTTP GET response headers (DAV:get*),
- the header value could include LWS as defined in [RFC2616], Section
- 4.2. Server implementors SHOULD strip LWS from these values before
- using as WebDAV property values.
-
-15.1. creationdate Property
-
- Name: creationdate
-
- Purpose: Records the time and date the resource was created.
-
- Value: date-time (defined in [RFC3339], see the ABNF in Section
- 5.6.)
-
- Protected: MAY be protected. Some servers allow DAV:creationdate
- to be changed to reflect the time the document was created if that
- is more meaningful to the user (rather than the time it was
- uploaded). Thus, clients SHOULD NOT use this property in
- synchronization logic (use DAV:getetag instead).
-
- COPY/MOVE behavior: This property value SHOULD be kept during a
- MOVE operation, but is normally re-initialized when a resource is
- created with a COPY. It should not be set in a COPY.
-
-
-
-
-
-Dusseault Standards Track [Page 90]
-\f
-RFC 4918 WebDAV June 2007
-
-
- Description: The DAV:creationdate property SHOULD be defined on all
- DAV compliant resources. If present, it contains a timestamp of
- the moment when the resource was created. Servers that are
- incapable of persistently recording the creation date SHOULD
- instead leave it undefined (i.e. report "Not Found").
-
- <!ELEMENT creationdate (#PCDATA) >
-
-15.2. displayname Property
-
- Name: displayname
-
- Purpose: Provides a name for the resource that is suitable for
- presentation to a user.
-
- Value: Any text.
-
- Protected: SHOULD NOT be protected. Note that servers implementing
- [RFC2518] might have made this a protected property as this is a
- new requirement.
-
- COPY/MOVE behavior: This property value SHOULD be preserved in COPY
- and MOVE operations.
-
- Description: Contains a description of the resource that is
- suitable for presentation to a user. This property is defined on
- the resource, and hence SHOULD have the same value independent of
- the Request-URI used to retrieve it (thus, computing this property
- based on the Request-URI is deprecated). While generic clients
- might display the property value to end users, client UI designers
- must understand that the method for identifying resources is still
- the URL. Changes to DAV:displayname do not issue moves or copies
- to the server, but simply change a piece of meta-data on the
- individual resource. Two resources can have the same DAV:
- displayname value even within the same collection.
-
- <!ELEMENT displayname (#PCDATA) >
-
-15.3. getcontentlanguage Property
-
- Name: getcontentlanguage
-
- Purpose: Contains the Content-Language header value (from Section
- 14.12 of [RFC2616]) as it would be returned by a GET without
- accept headers.
-
- Value: language-tag (language-tag is defined in Section 3.10 of
- [RFC2616])
-
-
-
-Dusseault Standards Track [Page 91]
-\f
-RFC 4918 WebDAV June 2007
-
-
- Protected: SHOULD NOT be protected, so that clients can reset the
- language. Note that servers implementing [RFC2518] might have
- made this a protected property as this is a new requirement.
-
- COPY/MOVE behavior: This property value SHOULD be preserved in COPY
- and MOVE operations.
-
- Description: The DAV:getcontentlanguage property MUST be defined on
- any DAV-compliant resource that returns the Content-Language
- header on a GET.
-
- <!ELEMENT getcontentlanguage (#PCDATA) >
-
-15.4. getcontentlength Property
-
- Name: getcontentlength
-
- Purpose: Contains the Content-Length header returned by a GET
- without accept headers.
-
- Value: See Section 14.13 of [RFC2616].
-
- Protected: This property is computed, therefore protected.
-
- Description: The DAV:getcontentlength property MUST be defined on
- any DAV-compliant resource that returns the Content-Length header
- in response to a GET.
-
- COPY/MOVE behavior: This property value is dependent on the size of
- the destination resource, not the value of the property on the
- source resource.
-
- <!ELEMENT getcontentlength (#PCDATA) >
-
-15.5. getcontenttype Property
-
- Name: getcontenttype
-
- Purpose: Contains the Content-Type header value (from Section 14.17
- of [RFC2616]) as it would be returned by a GET without accept
- headers.
-
- Value: media-type (defined in Section 3.7 of [RFC2616])
-
- Protected: Potentially protected if the server prefers to assign
- content types on its own (see also discussion in Section 9.7.1).
-
-
-
-
-
-Dusseault Standards Track [Page 92]
-\f
-RFC 4918 WebDAV June 2007
-
-
- COPY/MOVE behavior: This property value SHOULD be preserved in COPY
- and MOVE operations.
-
- Description: This property MUST be defined on any DAV-compliant
- resource that returns the Content-Type header in response to a
- GET.
-
- <!ELEMENT getcontenttype (#PCDATA) >
-
-15.6. getetag Property
-
- Name: getetag
-
- Purpose: Contains the ETag header value (from Section 14.19 of
- [RFC2616]) as it would be returned by a GET without accept
- headers.
-
- Value: entity-tag (defined in Section 3.11 of [RFC2616])
-
- Protected: MUST be protected because this value is created and
- controlled by the server.
-
- COPY/MOVE behavior: This property value is dependent on the final
- state of the destination resource, not the value of the property
- on the source resource. Also note the considerations in
- Section 8.8.
-
- Description: The getetag property MUST be defined on any DAV-
- compliant resource that returns the Etag header. Refer to Section
- 3.11 of RFC 2616 for a complete definition of the semantics of an
- ETag, and to Section 8.6 for a discussion of ETags in WebDAV.
-
- <!ELEMENT getetag (#PCDATA) >
-
-15.7. getlastmodified Property
-
- Name: getlastmodified
-
- Purpose: Contains the Last-Modified header value (from Section
- 14.29 of [RFC2616]) as it would be returned by a GET method
- without accept headers.
-
- Value: rfc1123-date (defined in Section 3.3.1 of [RFC2616])
-
- Protected: SHOULD be protected because some clients may rely on the
- value for appropriate caching behavior, or on the value of the
- Last-Modified header to which this property is linked.
-
-
-
-
-Dusseault Standards Track [Page 93]
-\f
-RFC 4918 WebDAV June 2007
-
-
- COPY/MOVE behavior: This property value is dependent on the last
- modified date of the destination resource, not the value of the
- property on the source resource. Note that some server
- implementations use the file system date modified value for the
- DAV:getlastmodified value, and this can be preserved in a MOVE
- even when the HTTP Last-Modified value SHOULD change. Note that
- since [RFC2616] requires clients to use ETags where provided, a
- server implementing ETags can count on clients using a much better
- mechanism than modification dates for offline synchronization or
- cache control. Also note the considerations in Section 8.8.
-
- Description: The last-modified date on a resource SHOULD only
- reflect changes in the body (the GET responses) of the resource.
- A change in a property only SHOULD NOT cause the last-modified
- date to change, because clients MAY rely on the last-modified date
- to know when to overwrite the existing body. The DAV:
- getlastmodified property MUST be defined on any DAV-compliant
- resource that returns the Last-Modified header in response to a
- GET.
-
- <!ELEMENT getlastmodified (#PCDATA) >
-
-15.8. lockdiscovery Property
-
- Name: lockdiscovery
-
- Purpose: Describes the active locks on a resource
-
- Protected: MUST be protected. Clients change the list of locks
- through LOCK and UNLOCK, not through PROPPATCH.
-
- COPY/MOVE behavior: The value of this property depends on the lock
- state of the destination, not on the locks of the source resource.
- Recall that locks are not moved in a MOVE operation.
-
- Description: Returns a listing of who has a lock, what type of lock
- he has, the timeout type and the time remaining on the timeout,
- and the associated lock token. Owner information MAY be omitted
- if it is considered sensitive. If there are no locks, but the
- server supports locks, the property will be present but contain
- zero 'activelock' elements. If there are one or more locks, an
- 'activelock' element appears for each lock on the resource. This
- property is NOT lockable with respect to write locks (Section 7).
-
- <!ELEMENT lockdiscovery (activelock)* >
-
-
-
-
-
-
-Dusseault Standards Track [Page 94]
-\f
-RFC 4918 WebDAV June 2007
-
-
-15.8.1. Example - Retrieving DAV:lockdiscovery
-
- >>Request
-
- PROPFIND /container/ HTTP/1.1
- Host: www.example.com
- Content-Length: xxxx
- Content-Type: application/xml; charset="utf-8"
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D='DAV:'>
- <D:prop><D:lockdiscovery/></D:prop>
- </D:propfind>
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D='DAV:'>
- <D:response>
- <D:href>http://www.example.com/container/</D:href>
- <D:propstat>
- <D:prop>
- <D:lockdiscovery>
- <D:activelock>
- <D:locktype><D:write/></D:locktype>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:depth>0</D:depth>
- <D:owner>Jane Smith</D:owner>
- <D:timeout>Infinite</D:timeout>
- <D:locktoken>
- <D:href
- >urn:uuid:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76</D:href>
- </D:locktoken>
- <D:lockroot>
- <D:href>http://www.example.com/container/</D:href>
- </D:lockroot>
- </D:activelock>
- </D:lockdiscovery>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-
-
-
-Dusseault Standards Track [Page 95]
-\f
-RFC 4918 WebDAV June 2007
-
-
- This resource has a single exclusive write lock on it, with an
- infinite timeout.
-
-15.9. resourcetype Property
-
- Name: resourcetype
-
- Purpose: Specifies the nature of the resource.
-
- Protected: SHOULD be protected. Resource type is generally decided
- through the operation creating the resource (MKCOL vs PUT), not by
- PROPPATCH.
-
- COPY/MOVE behavior: Generally a COPY/MOVE of a resource results in
- the same type of resource at the destination.
-
- Description: MUST be defined on all DAV-compliant resources. Each
- child element identifies a specific type the resource belongs to,
- such as 'collection', which is the only resource type defined by
- this specification (see Section 14.3). If the element contains
- the 'collection' child element plus additional unrecognized
- elements, it should generally be treated as a collection. If the
- element contains no recognized child elements, it should be
- treated as a non-collection resource. The default value is empty.
- This element MUST NOT contain text or mixed content. Any custom
- child element is considered to be an identifier for a resource
- type.
-
- Example: (fictional example to show extensibility)
-
- <x:resourcetype xmlns:x="DAV:">
- <x:collection/>
- <f:search-results xmlns:f="http://www.example.com/ns"/>
- </x:resourcetype>
-
-15.10. supportedlock Property
-
- Name: supportedlock
-
- Purpose: To provide a listing of the lock capabilities supported by
- the resource.
-
- Protected: MUST be protected. Servers, not clients, determine what
- lock mechanisms are supported.
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 96]
-\f
-RFC 4918 WebDAV June 2007
-
-
- COPY/MOVE behavior: This property value is dependent on the kind of
- locks supported at the destination, not on the value of the
- property at the source resource. Servers attempting to COPY to a
- destination should not attempt to set this property at the
- destination.
-
- Description: Returns a listing of the combinations of scope and
- access types that may be specified in a lock request on the
- resource. Note that the actual contents are themselves controlled
- by access controls, so a server is not required to provide
- information the client is not authorized to see. This property is
- NOT lockable with respect to write locks (Section 7).
-
- <!ELEMENT supportedlock (lockentry)* >
-
-15.10.1. Example - Retrieving DAV:supportedlock
-
- >>Request
-
- PROPFIND /container/ HTTP/1.1
- Host: www.example.com
- Content-Length: xxxx
- Content-Type: application/xml; charset="utf-8"
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:prop><D:supportedlock/></D:prop>
- </D:propfind>
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.example.com/container/</D:href>
- <D:propstat>
- <D:prop>
- <D:supportedlock>
- <D:lockentry>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- <D:lockentry>
- <D:lockscope><D:shared/></D:lockscope>
-
-
-
-Dusseault Standards Track [Page 97]
-\f
-RFC 4918 WebDAV June 2007
-
-
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- </D:supportedlock>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-16. Precondition/Postcondition XML Elements
-
- As introduced in Section 8.7, extra information on error conditions
- can be included in the body of many status responses. This section
- makes requirements on the use of the error body mechanism and
- introduces a number of precondition and postcondition codes.
-
- A "precondition" of a method describes the state of the server that
- must be true for that method to be performed. A "postcondition" of a
- method describes the state of the server that must be true after that
- method has been completed.
-
- Each precondition and postcondition has a unique XML element
- associated with it. In a 207 Multi-Status response, the XML element
- MUST appear inside an 'error' element in the appropriate 'propstat or
- 'response' element depending on whether the condition applies to one
- or more properties or to the resource as a whole. In all other error
- responses where this specification's 'error' body is used, the
- precondition/postcondition XML element MUST be returned as the child
- of a top-level 'error' element in the response body, unless otherwise
- negotiated by the request, along with an appropriate response status.
- The most common response status codes are 403 (Forbidden) if the
- request should not be repeated because it will always fail, and 409
- (Conflict) if it is expected that the user might be able to resolve
- the conflict and resubmit the request. The 'error' element MAY
- contain child elements with specific error information and MAY be
- extended with any custom child elements.
-
- This mechanism does not take the place of using a correct numeric
- status code as defined here or in HTTP, because the client must
- always be able to take a reasonable course of action based only on
- the numeric code. However, it does remove the need to define new
- numeric codes. The new machine-readable codes used for this purpose
- are XML elements classified as preconditions and postconditions, so
- naturally, any group defining a new condition code can use their own
- namespace. As always, the "DAV:" namespace is reserved for use by
- IETF-chartered WebDAV working groups.
-
-
-
-
-
-Dusseault Standards Track [Page 98]
-\f
-RFC 4918 WebDAV June 2007
-
-
- A server supporting this specification SHOULD use the XML error
- whenever a precondition or postcondition defined in this document is
- violated. For error conditions not specified in this document, the
- server MAY simply choose an appropriate numeric status and leave the
- response body blank. However, a server MAY instead use a custom
- condition code and other supporting text, because even when clients
- do not automatically recognize condition codes, they can be quite
- useful in interoperability testing and debugging.
-
- Example - Response with precondition code
-
- >>Response
-
- HTTP/1.1 423 Locked
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:error xmlns:D="DAV:">
- <D:lock-token-submitted>
- <D:href>/workspace/webdav/</D:href>
- </D:lock-token-submitted>
- </D:error>
-
- In this example, a client unaware of a depth-infinity lock on the
- parent collection "/workspace/webdav/" attempted to modify the
- collection member "/workspace/webdav/proposal.doc".
-
- Some other useful preconditions and postconditions have been defined
- in other specifications extending WebDAV, such as [RFC3744] (see
- particularly Section 7.1.1), [RFC3253], and [RFC3648].
-
- All these elements are in the "DAV:" namespace. If not specified
- otherwise, the content for each condition's XML element is defined to
- be empty.
-
-
- Name: lock-token-matches-request-uri
-
- Use with: 409 Conflict
-
- Purpose: (precondition) -- A request may include a Lock-Token header
- to identify a lock for the UNLOCK method. However, if the
- Request-URI does not fall within the scope of the lock identified
- by the token, the server SHOULD use this error. The lock may have
- a scope that does not include the Request-URI, or the lock could
- have disappeared, or the token may be invalid.
-
-
-
-
-Dusseault Standards Track [Page 99]
-\f
-RFC 4918 WebDAV June 2007
-
-
- Name: lock-token-submitted (precondition)
-
- Use with: 423 Locked
-
- Purpose: The request could not succeed because a lock token should
- have been submitted. This element, if present, MUST contain at
- least one URL of a locked resource that prevented the request. In
- cases of MOVE, COPY, and DELETE where collection locks are
- involved, it can be difficult for the client to find out which
- locked resource made the request fail -- but the server is only
- responsible for returning one such locked resource. The server
- MAY return every locked resource that prevented the request from
- succeeding if it knows them all.
-
- <!ELEMENT lock-token-submitted (href+) >
-
-
- Name: no-conflicting-lock (precondition)
-
- Use with: Typically 423 Locked
-
- Purpose: A LOCK request failed due the presence of an already
- existing conflicting lock. Note that a lock can be in conflict
- although the resource to which the request was directed is only
- indirectly locked. In this case, the precondition code can be
- used to inform the client about the resource that is the root of
- the conflicting lock, avoiding a separate lookup of the
- "lockdiscovery" property.
-
- <!ELEMENT no-conflicting-lock (href)* >
-
-
- Name: no-external-entities
-
- Use with: 403 Forbidden
-
- Purpose: (precondition) -- If the server rejects a client request
- because the request body contains an external entity, the server
- SHOULD use this error.
-
-
- Name: preserved-live-properties
-
- Use with: 409 Conflict
-
- Purpose: (postcondition) -- The server received an otherwise-valid
- MOVE or COPY request, but cannot maintain the live properties with
- the same behavior at the destination. It may be that the server
-
-
-
-Dusseault Standards Track [Page 100]
-\f
-RFC 4918 WebDAV June 2007
-
-
- only supports some live properties in some parts of the
- repository, or simply has an internal error.
-
-
- Name: propfind-finite-depth
-
- Use with: 403 Forbidden
-
- Purpose: (precondition) -- This server does not allow infinite-depth
- PROPFIND requests on collections.
-
-
- Name: cannot-modify-protected-property
-
- Use with: 403 Forbidden
-
- Purpose: (precondition) -- The client attempted to set a protected
- property in a PROPPATCH (such as DAV:getetag). See also
- [RFC3253], Section 3.12.
-
-17. XML Extensibility in DAV
-
- The XML namespace extension ([REC-XML-NAMES]) is used in this
- specification in order to allow for new XML elements to be added
- without fear of colliding with other element names. Although WebDAV
- request and response bodies can be extended by arbitrary XML
- elements, which can be ignored by the message recipient, an XML
- element in the "DAV:" namespace SHOULD NOT be used in the request or
- response body unless that XML element is explicitly defined in an
- IETF RFC reviewed by a WebDAV working group.
-
- For WebDAV to be both extensible and backwards-compatible, both
- clients and servers need to know how to behave when unexpected or
- unrecognized command extensions are received. For XML processing,
- this means that clients and servers MUST process received XML
- documents as if unexpected elements and attributes (and all children
- of unrecognized elements) were not there. An unexpected element or
- attribute includes one that may be used in another context but is not
- expected here. Ignoring such items for purposes of processing can of
- course be consistent with logging all information or presenting for
- debugging.
-
- This restriction also applies to the processing, by clients, of DAV
- property values where unexpected XML elements SHOULD be ignored
- unless the property's schema declares otherwise.
-
- This restriction does not apply to setting dead DAV properties on the
- server where the server MUST record all XML elements.
-
-
-
-Dusseault Standards Track [Page 101]
-\f
-RFC 4918 WebDAV June 2007
-
-
- Additionally, this restriction does not apply to the use of XML where
- XML happens to be the content type of the entity body, for example,
- when used as the body of a PUT.
-
- Processing instructions in XML SHOULD be ignored by recipients.
- Thus, specifications extending WebDAV SHOULD NOT use processing
- instructions to define normative behavior.
-
- XML DTD fragments are included for all the XML elements defined in
- this specification. However, correct XML will not be valid according
- to any DTD due to namespace usage and extension rules. In
- particular:
-
- o Elements (from this specification) are in the "DAV:" namespace,
-
- o Element ordering is irrelevant unless otherwise stated,
-
- o Extension attributes MAY be added,
-
- o For element type definitions of "ANY", the normative text
- definition for that element defines what can be in it and what
- that means.
-
- o For element type definitions of "#PCDATA", extension elements MUST
- NOT be added.
-
- o For other element type definitions, including "EMPTY", extension
- elements MAY be added.
-
- Note that this means that elements containing elements cannot be
- extended to contain text, and vice versa.
-
- With DTD validation relaxed by the rules above, the constraints
- described by the DTD fragments are normative (see for example
- Appendix A). A recipient of a WebDAV message with an XML body MUST
- NOT validate the XML document according to any hard-coded or
- dynamically-declared DTD.
-
- Note that this section describes backwards-compatible extensibility
- rules. There might also be times when an extension is designed not
- to be backwards-compatible, for example, defining an extension that
- reuses an XML element defined in this document but omitting one of
- the child elements required by the DTDs in this specification.
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 102]
-\f
-RFC 4918 WebDAV June 2007
-
-
-18. DAV Compliance Classes
-
- A DAV-compliant resource can advertise several classes of compliance.
- A client can discover the compliance classes of a resource by
- executing OPTIONS on the resource and examining the "DAV" header
- which is returned. Note particularly that resources, rather than
- servers, are spoken of as being compliant. That is because
- theoretically some resources on a server could support different
- feature sets. For example, a server could have a sub-repository
- where an advanced feature like versioning was supported, even if that
- feature was not supported on all sub-repositories.
-
- Since this document describes extensions to the HTTP/1.1 protocol,
- minimally all DAV-compliant resources, clients, and proxies MUST be
- compliant with [RFC2616].
-
- A resource that is class 2 or class 3 compliant must also be class 1
- compliant.
-
-18.1. Class 1
-
- A class 1 compliant resource MUST meet all "MUST" requirements in all
- sections of this document.
-
- Class 1 compliant resources MUST return, at minimum, the value "1" in
- the DAV header on all responses to the OPTIONS method.
-
-18.2. Class 2
-
- A class 2 compliant resource MUST meet all class 1 requirements and
- support the LOCK method, the DAV:supportedlock property, the DAV:
- lockdiscovery property, the Time-Out response header and the Lock-
- Token request header. A class 2 compliant resource SHOULD also
- support the Timeout request header and the 'owner' XML element.
-
- Class 2 compliant resources MUST return, at minimum, the values "1"
- and "2" in the DAV header on all responses to the OPTIONS method.
-
-18.3. Class 3
-
- A resource can explicitly advertise its support for the revisions to
- [RFC2518] made in this document. Class 1 MUST be supported as well.
- Class 2 MAY be supported. Advertising class 3 support in addition to
- class 1 and 2 means that the server supports all the requirements in
- this specification. Advertising class 3 and class 1 support, but not
- class 2, means that the server supports all the requirements in this
- specification except possibly those that involve locking support.
-
-
-
-
-Dusseault Standards Track [Page 103]
-\f
-RFC 4918 WebDAV June 2007
-
-
- Example:
-
- DAV: 1, 3
-
-19. Internationalization Considerations
-
- In the realm of internationalization, this specification complies
- with the IETF Character Set Policy [RFC2277]. In this specification,
- human-readable fields can be found either in the value of a property,
- or in an error message returned in a response entity body. In both
- cases, the human-readable content is encoded using XML, which has
- explicit provisions for character set tagging and encoding, and
- requires that XML processors read XML elements encoded, at minimum,
- using the UTF-8 [RFC3629] and UTF-16 [RFC2781] encodings of the ISO
- 10646 multilingual plane. XML examples in this specification
- demonstrate use of the charset parameter of the Content-Type header
- (defined in [RFC3023]), as well as XML charset declarations.
-
- XML also provides a language tagging capability for specifying the
- language of the contents of a particular XML element. The "xml:lang"
- attribute appears on an XML element to identify the language of its
- content and attributes. See [REC-XML] for definitions of values and
- scoping.
-
- WebDAV applications MUST support the character set tagging, character
- set encoding, and the language tagging functionality of the XML
- specification. Implementors of WebDAV applications are strongly
- encouraged to read "XML Media Types" [RFC3023] for instruction on
- which MIME media type to use for XML transport, and on use of the
- charset parameter of the Content-Type header.
-
- Names used within this specification fall into four categories: names
- of protocol elements such as methods and headers, names of XML
- elements, names of properties, and names of conditions. Naming of
- protocol elements follows the precedent of HTTP, using English names
- encoded in US-ASCII for methods and headers. Since these protocol
- elements are not visible to users, and are simply long token
- identifiers, they do not need to support multiple languages.
- Similarly, the names of XML elements used in this specification are
- not visible to the user and hence do not need to support multiple
- languages.
-
- WebDAV property names are qualified XML names (pairs of XML namespace
- name and local name). Although some applications (e.g., a generic
- property viewer) will display property names directly to their users,
- it is expected that the typical application will use a fixed set of
- properties, and will provide a mapping from the property name and
- namespace to a human-readable field when displaying the property name
-
-
-
-Dusseault Standards Track [Page 104]
-\f
-RFC 4918 WebDAV June 2007
-
-
- to a user. It is only in the case where the set of properties is not
- known ahead of time that an application need display a property name
- to a user. We recommend that applications provide human-readable
- property names wherever feasible.
-
- For error reporting, we follow the convention of HTTP/1.1 status
- codes, including with each status code a short, English description
- of the code (e.g., 423 (Locked)). While the possibility exists that
- a poorly crafted user agent would display this message to a user,
- internationalized applications will ignore this message, and display
- an appropriate message in the user's language and character set.
-
- Since interoperation of clients and servers does not require locale
- information, this specification does not specify any mechanism for
- transmission of this information.
-
-20. Security Considerations
-
- This section is provided to detail issues concerning security
- implications of which WebDAV applications need to be aware.
-
- All of the security considerations of HTTP/1.1 (discussed in
- [RFC2616]) and XML (discussed in [RFC3023]) also apply to WebDAV. In
- addition, the security risks inherent in remote authoring require
- stronger authentication technology, introduce several new privacy
- concerns, and may increase the hazards from poor server design.
- These issues are detailed below.
-
-20.1. Authentication of Clients
-
- Due to their emphasis on authoring, WebDAV servers need to use
- authentication technology to protect not just access to a network
- resource, but the integrity of the resource as well. Furthermore,
- the introduction of locking functionality requires support for
- authentication.
-
- A password sent in the clear over an insecure channel is an
- inadequate means for protecting the accessibility and integrity of a
- resource as the password may be intercepted. Since Basic
- authentication for HTTP/1.1 performs essentially clear text
- transmission of a password, Basic authentication MUST NOT be used to
- authenticate a WebDAV client to a server unless the connection is
- secure. Furthermore, a WebDAV server MUST NOT send a Basic
- authentication challenge in a WWW-Authenticate header unless the
- connection is secure. An example of a secure connection would be a
- Transport Layer Security (TLS) connection employing a strong cipher
- suite and server authentication.
-
-
-
-
-Dusseault Standards Track [Page 105]
-\f
-RFC 4918 WebDAV June 2007
-
-
- WebDAV applications MUST support the Digest authentication scheme
- [RFC2617]. Since Digest authentication verifies that both parties to
- a communication know a shared secret, a password, without having to
- send that secret in the clear, Digest authentication avoids the
- security problems inherent in Basic authentication while providing a
- level of authentication that is useful in a wide range of scenarios.
-
-20.2. Denial of Service
-
- Denial-of-service attacks are of special concern to WebDAV servers.
- WebDAV plus HTTP enables denial-of-service attacks on every part of a
- system's resources.
-
- o The underlying storage can be attacked by PUTting extremely large
- files.
-
- o Asking for recursive operations on large collections can attack
- processing time.
-
- o Making multiple pipelined requests on multiple connections can
- attack network connections.
-
- WebDAV servers need to be aware of the possibility of a denial-of-
- service attack at all levels. The proper response to such an attack
- MAY be to simply drop the connection. Or, if the server is able to
- make a response, the server MAY use a 400-level status request such
- as 400 (Bad Request) and indicate why the request was refused (a 500-
- level status response would indicate that the problem is with the
- server, whereas unintentional DoS attacks are something the client is
- capable of remedying).
-
-20.3. Security through Obscurity
-
- WebDAV provides, through the PROPFIND method, a mechanism for listing
- the member resources of a collection. This greatly diminishes the
- effectiveness of security or privacy techniques that rely only on the
- difficulty of discovering the names of network resources. Users of
- WebDAV servers are encouraged to use access control techniques to
- prevent unwanted access to resources, rather than depending on the
- relative obscurity of their resource names.
-
-20.4. Privacy Issues Connected to Locks
-
- When submitting a lock request, a user agent may also submit an
- 'owner' XML field giving contact information for the person taking
- out the lock (for those cases where a person, rather than a robot, is
- taking out the lock). This contact information is stored in a DAV:
- lockdiscovery property on the resource, and can be used by other
-
-
-
-Dusseault Standards Track [Page 106]
-\f
-RFC 4918 WebDAV June 2007
-
-
- collaborators to begin negotiation over access to the resource.
- However, in many cases, this contact information can be very private,
- and should not be widely disseminated. Servers SHOULD limit read
- access to the DAV:lockdiscovery property as appropriate.
- Furthermore, user agents SHOULD provide control over whether contact
- information is sent at all, and if contact information is sent,
- control over exactly what information is sent.
-
-20.5. Privacy Issues Connected to Properties
-
- Since property values are typically used to hold information such as
- the author of a document, there is the possibility that privacy
- concerns could arise stemming from widespread access to a resource's
- property data. To reduce the risk of inadvertent release of private
- information via properties, servers are encouraged to develop access
- control mechanisms that separate read access to the resource body and
- read access to the resource's properties. This allows a user to
- control the dissemination of their property data without overly
- restricting access to the resource's contents.
-
-20.6. Implications of XML Entities
-
- XML supports a facility known as "external entities", defined in
- Section 4.2.2 of [REC-XML], which instructs an XML processor to
- retrieve and include additional XML. An external XML entity can be
- used to append or modify the document type declaration (DTD)
- associated with an XML document. An external XML entity can also be
- used to include XML within the content of an XML document. For non-
- validating XML, such as the XML used in this specification, including
- an external XML entity is not required by XML. However, XML does
- state that an XML processor may, at its discretion, include the
- external XML entity.
-
- External XML entities have no inherent trustworthiness and are
- subject to all the attacks that are endemic to any HTTP GET request.
- Furthermore, it is possible for an external XML entity to modify the
- DTD, and hence affect the final form of an XML document, in the worst
- case, significantly modifying its semantics or exposing the XML
- processor to the security risks discussed in [RFC3023]. Therefore,
- implementers must be aware that external XML entities should be
- treated as untrustworthy. If a server chooses not to handle external
- XML entities, it SHOULD respond to requests containing external
- entities with the 'no-external-entities' condition code.
-
- There is also the scalability risk that would accompany a widely
- deployed application that made use of external XML entities. In this
- situation, it is possible that there would be significant numbers of
- requests for one external XML entity, potentially overloading any
-
-
-
-Dusseault Standards Track [Page 107]
-\f
-RFC 4918 WebDAV June 2007
-
-
- server that fields requests for the resource containing the external
- XML entity.
-
- Furthermore, there's also a risk based on the evaluation of "internal
- entities" as defined in Section 4.2.2 of [REC-XML]. A small,
- carefully crafted request using nested internal entities may require
- enormous amounts of memory and/or processing time to process. Server
- implementers should be aware of this risk and configure their XML
- parsers so that requests like these can be detected and rejected as
- early as possible.
-
-20.7. Risks Connected with Lock Tokens
-
- This specification encourages the use of "A Universally Unique
- Identifier (UUID) URN Namespace" ([RFC4122]) for lock tokens
- (Section 6.5), in order to guarantee their uniqueness across space
- and time. Version 1 UUIDs (defined in Section 4) MAY contain a
- "node" field that "consists of an IEEE 802 MAC address, usually the
- host address. For systems with multiple IEEE addresses, any
- available one can be used". Since a WebDAV server will issue many
- locks over its lifetime, the implication is that it may also be
- publicly exposing its IEEE 802 address.
-
- There are several risks associated with exposure of IEEE 802
- addresses. Using the IEEE 802 address:
-
- o It is possible to track the movement of hardware from subnet to
- subnet.
-
- o It may be possible to identify the manufacturer of the hardware
- running a WebDAV server.
-
- o It may be possible to determine the number of each type of
- computer running WebDAV.
-
- This risk only applies to host-address-based UUID versions. Section
- 4 of [RFC4122] describes several other mechanisms for generating
- UUIDs that do not involve the host address and therefore do not
- suffer from this risk.
-
-20.8. Hosting Malicious Content
-
- HTTP has the ability to host programs that are executed on client
- machines. These programs can take many forms including Web scripts,
- executables, plug-in modules, and macros in documents. WebDAV does
- not change any of the security concerns around these programs, yet
- often WebDAV is used in contexts where a wide range of users can
- publish documents on a server. The server might not have a close
-
-
-
-Dusseault Standards Track [Page 108]
-\f
-RFC 4918 WebDAV June 2007
-
-
- trust relationship with the author that is publishing the document.
- Servers that allow clients to publish arbitrary content can usefully
- implement precautions to check that content published to the server
- is not harmful to other clients. Servers could do this by techniques
- such as restricting the types of content that is allowed to be
- published and running virus and malware detection software on
- published content. Servers can also mitigate the risk by having
- appropriate access restriction and authentication of users that are
- allowed to publish content to the server.
-
-21. IANA Considerations
-
-21.1. New URI Schemes
-
- This specification defines two URI schemes:
-
- 1. the "opaquelocktoken" scheme defined in Appendix C, and
-
- 2. the "DAV" URI scheme, which historically was used in [RFC2518] to
- disambiguate WebDAV property and XML element names and which
- continues to be used for that purpose in this specification and
- others extending WebDAV. Creation of identifiers in the "DAV:"
- namespace is controlled by the IETF.
-
- Note that defining new URI schemes for XML namespaces is now
- discouraged. "DAV:" was defined before standard best practices
- emerged.
-
-21.2. XML Namespaces
-
- XML namespaces disambiguate WebDAV property names and XML elements.
- Any WebDAV user or application can define a new namespace in order to
- create custom properties or extend WebDAV XML syntax. IANA does not
- need to manage such namespaces, property names, or element names.
-
-21.3. Message Header Fields
-
- The message header fields below should be added to the permanent
- registry (see [RFC3864]).
-
-21.3.1. DAV
-
- Header field name: DAV
-
- Applicable protocol: http
-
- Status: standard
-
-
-
-
-Dusseault Standards Track [Page 109]
-\f
-RFC 4918 WebDAV June 2007
-
-
- Author/Change controller: IETF
-
- Specification document: this specification (Section 10.1)
-
-21.3.2. Depth
-
- Header field name: Depth
-
- Applicable protocol: http
-
- Status: standard
-
- Author/Change controller: IETF
-
- Specification document: this specification (Section 10.2)
-
-21.3.3. Destination
-
- Header field name: Destination
-
- Applicable protocol: http
-
- Status: standard
-
- Author/Change controller: IETF
-
- Specification document: this specification (Section 10.3)
-
-21.3.4. If
-
- Header field name: If
-
- Applicable protocol: http
-
- Status: standard
-
- Author/Change controller: IETF
-
- Specification document: this specification (Section 10.4)
-
-21.3.5. Lock-Token
-
- Header field name: Lock-Token
-
- Applicable protocol: http
-
- Status: standard
-
-
-
-
-Dusseault Standards Track [Page 110]
-\f
-RFC 4918 WebDAV June 2007
-
-
- Author/Change controller: IETF
-
- Specification document: this specification (Section 10.5)
-
-21.3.6. Overwrite
-
- Header field name: Overwrite
-
- Applicable protocol: http
-
- Status: standard
-
- Author/Change controller: IETF
-
- Specification document: this specification (Section 10.6)
-
-21.3.7. Timeout
-
- Header field name: Timeout
-
- Applicable protocol: http
-
- Status: standard
-
- Author/Change controller: IETF
-
- Specification document: this specification (Section 10.7)
-
-21.4. HTTP Status Codes
-
- This specification defines the HTTP status codes
-
- o 207 Multi-Status (Section 11.1)
-
- o 422 Unprocessable Entity (Section 11.2),
-
- o 423 Locked (Section 11.3),
-
- o 424 Failed Dependency (Section 11.4) and
-
- o 507 Insufficient Storage (Section 11.5),
-
- to be updated in the registry at
- <http://www.iana.org/assignments/http-status-codes>.
-
- Note: the HTTP status code 102 (Processing) has been removed in this
- specification; its IANA registration should continue to reference RFC
- 2518.
-
-
-
-Dusseault Standards Track [Page 111]
-\f
-RFC 4918 WebDAV June 2007
-
-
-22. Acknowledgements
-
- A specification such as this thrives on piercing critical review and
- withers from apathetic neglect. The authors gratefully acknowledge
- the contributions of the following people, whose insights were so
- valuable at every stage of our work.
-
- Contributors to RFC 2518
-
- Terry Allen, Harald Alvestrand, Jim Amsden, Becky Anderson, Alan
- Babich, Sanford Barr, Dylan Barrell, Bernard Chester, Tim Berners-
- Lee, Dan Connolly, Jim Cunningham, Ron Daniel, Jr., Jim Davis, Keith
- Dawson, Mark Day, Brian Deen, Martin Duerst, David Durand, Lee
- Farrell, Chuck Fay, Wesley Felter, Roy Fielding, Mark Fisher, Alan
- Freier, George Florentine, Jim Gettys, Phill Hallam-Baker, Dennis
- Hamilton, Steve Henning, Mead Himelstein, Alex Hopmann, Andre van der
- Hoek, Ben Laurie, Paul Leach, Ora Lassila, Karen MacArthur, Steven
- Martin, Larry Masinter, Michael Mealling, Keith Moore, Thomas Narten,
- Henrik Nielsen, Kenji Ota, Bob Parker, Glenn Peterson, Jon Radoff,
- Saveen Reddy, Henry Sanders, Christopher Seiwald, Judith Slein, Mike
- Spreitzer, Einar Stefferud, Greg Stein, Ralph Swick, Kenji Takahashi,
- Richard N. Taylor, Robert Thau, John Turner, Sankar Virdhagriswaran,
- Fabio Vitali, Gregory Woodhouse, and Lauren Wood.
-
- Two from this list deserve special mention. The contributions by
- Larry Masinter have been invaluable; he both helped the formation of
- the working group and patiently coached the authors along the way.
- In so many ways he has set high standards that we have toiled to
- meet. The contributions of Judith Slein were also invaluable; by
- clarifying the requirements and in patiently reviewing version after
- version, she both improved this specification and expanded our minds
- on document management.
-
- We would also like to thank John Turner for developing the XML DTD.
-
- The authors of RFC 2518 were Yaron Goland, Jim Whitehead, A. Faizi,
- Steve Carter, and D. Jensen. Although their names had to be removed
- due to IETF author count restrictions, they can take credit for the
- majority of the design of WebDAV.
-
- Additional Acknowledgements for This Specification
-
- Significant contributors of text for this specification are listed as
- contributors in the section below. We must also gratefully
- acknowledge Geoff Clemm, Joel Soderberg, and Dan Brotsky for hashing
- out specific text on the list or in meetings. Joe Hildebrand and
- Cullen Jennings helped close many issues. Barry Lind described an
- additional security consideration and Cullen Jennings provided text
-
-
-
-Dusseault Standards Track [Page 112]
-\f
-RFC 4918 WebDAV June 2007
-
-
- for that consideration. Jason Crawford tracked issue status for this
- document for a period of years, followed by Elias Sinderson.
-
-23. Contributors to This Specification
-
- Julian Reschke
- <green/>bytes GmbH
- Hafenweg 16, 48155 Muenster, Germany
- EMail: julian.reschke@greenbytes.de
-
-
- Elias Sinderson
- University of California, Santa Cruz
- 1156 High Street, Santa Cruz, CA 95064
- EMail: elias@cse.ucsc.edu
-
-
- Jim Whitehead
- University of California, Santa Cruz
- 1156 High Street, Santa Cruz, CA 95064
- EMail: ejw@soe.ucsc.edu
-
-24. Authors of RFC 2518
-
- Y. Y. Goland
- Microsoft Corporation
- One Microsoft Way
- Redmond, WA 98052-6399
- EMail: yarong@microsoft.com
-
-
- E. J. Whitehead, Jr.
- Dept. Of Information and Computer Science
- University of California, Irvine
- Irvine, CA 92697-3425
- EMail: ejw@ics.uci.edu
-
-
- A. Faizi
- Netscape
- 685 East Middlefield Road
- Mountain View, CA 94043
- EMail: asad@netscape.com
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 113]
-\f
-RFC 4918 WebDAV June 2007
-
-
- S. R. Carter
- Novell
- 1555 N. Technology Way
- M/S ORM F111
- Orem, UT 84097-2399
- EMail: srcarter@novell.com
-
-
- D. Jensen
- Novell
- 1555 N. Technology Way
- M/S ORM F111
- Orem, UT 84097-2399
- EMail: dcjensen@novell.com
-
-25. References
-
-25.1. Normative References
-
- [REC-XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler,
- E., and F. Yergeau, "Extensible Markup Language
- (XML) 1.0 (Fourth Edition)", W3C REC-xml-20060816,
- August 2006,
- <http://www.w3.org/TR/2006/REC-xml-20060816/>.
-
- [REC-XML-INFOSET] Cowan, J. and R. Tobin, "XML Information Set
- (Second Edition)", W3C REC-xml-infoset-20040204,
- February 2004, <http://www.w3.org/TR/2004/
- REC-xml-infoset-20040204/>.
-
- [REC-XML-NAMES] Bray, T., Hollander, D., Layman, A., and R. Tobin,
- "Namespaces in XML 1.0 (Second Edition)", W3C REC-
- xml-names-20060816, August 2006, <http://
- www.w3.org/TR/2006/REC-xml-names-20060816/>.
-
- [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.
-
- [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.
-
-
-
-
-
-Dusseault Standards Track [Page 114]
-\f
-RFC 4918 WebDAV June 2007
-
-
- [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.
-
- [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on
- the Internet: Timestamps", RFC 3339, July 2002.
-
- [RFC3629] Yergeau, F., "UTF-8, a transformation format of
- ISO 10646", STD 63, RFC 3629, November 2003.
-
- [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter,
- "Uniform Resource Identifier (URI): Generic
- Syntax", STD 66, RFC 3986, January 2005.
-
- [RFC4122] Leach, P., Mealling, M., and R. Salz, "A
- Universally Unique IDentifier (UUID) URN
- Namespace", RFC 4122, July 2005.
-
-25.2. Informative References
-
- [RFC2291] Slein, J., Vitali, F., Whitehead, E., and D.
- Durand, "Requirements for a Distributed Authoring
- and Versioning Protocol for the World Wide Web",
- RFC 2291, February 1998.
-
- [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S.,
- and D. Jensen, "HTTP Extensions for Distributed
- Authoring -- WEBDAV", RFC 2518, February 1999.
-
- [RFC2781] Hoffman, P. and F. Yergeau, "UTF-16, an encoding
- of ISO 10646", RFC 2781, February 2000.
-
- [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML
- Media Types", RFC 3023, January 2001.
-
- [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and
- J. Whitehead, "Versioning Extensions to WebDAV
- (Web Distributed Authoring and Versioning)",
- RFC 3253, March 2002.
-
- [RFC3648] Whitehead, J. and J. Reschke, Ed., "Web
- Distributed Authoring and Versioning (WebDAV)
- Ordered Collections Protocol", RFC 3648,
- December 2003.
-
-
-
-
-
-
-Dusseault Standards Track [Page 115]
-\f
-RFC 4918 WebDAV June 2007
-
-
- [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J.
- Whitehead, "Web Distributed Authoring and
- Versioning (WebDAV) Access Control Protocol",
- RFC 3744, May 2004.
-
- [RFC3864] Klyne, G., Nottingham, M., and J. Mogul,
- "Registration Procedures for Message Header
- Fields", BCP 90, RFC 3864, September 2004.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 116]
-\f
-RFC 4918 WebDAV June 2007
-
-
-Appendix A. Notes on Processing XML Elements
-
-A.1. Notes on Empty XML Elements
-
- XML supports two mechanisms for indicating that an XML element does
- not have any content. The first is to declare an XML element of the
- form <A></A>. The second is to declare an XML element of the form
- <A/>. The two XML elements are semantically identical.
-
-A.2. Notes on Illegal XML Processing
-
- XML is a flexible data format that makes it easy to submit data that
- appears legal but in fact is not. The philosophy of "Be flexible in
- what you accept and strict in what you send" still applies, but it
- must not be applied inappropriately. XML is extremely flexible in
- dealing with issues of whitespace, element ordering, inserting new
- elements, etc. This flexibility does not require extension,
- especially not in the area of the meaning of elements.
-
- There is no kindness in accepting illegal combinations of XML
- elements. At best, it will cause an unwanted result and at worst it
- can cause real damage.
-
-A.3. Example - XML Syntax Error
-
- The following request body for a PROPFIND method is illegal.
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:allprop/>
- <D:propname/>
- </D:propfind>
-
- The definition of the propfind element only allows for the allprop or
- the propname element, not both. Thus, the above is an error and must
- be responded to with a 400 (Bad Request).
-
- Imagine, however, that a server wanted to be "kind" and decided to
- pick the allprop element as the true element and respond to it. A
- client running over a bandwidth limited line who intended to execute
- a propname would be in for a big surprise if the server treated the
- command as an allprop.
-
- Additionally, if a server were lenient and decided to reply to this
- request, the results would vary randomly from server to server, with
- some servers executing the allprop directive, and others executing
- the propname directive. This reduces interoperability rather than
- increasing it.
-
-
-
-Dusseault Standards Track [Page 117]
-\f
-RFC 4918 WebDAV June 2007
-
-
-A.4. Example - Unexpected XML Element
-
- The previous example was illegal because it contained two elements
- that were explicitly banned from appearing together in the propfind
- element. However, XML is an extensible language, so one can imagine
- new elements being defined for use with propfind. Below is the
- request body of a PROPFIND and, like the previous example, must be
- rejected with a 400 (Bad Request) by a server that does not
- understand the expired-props element.
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:"
- xmlns:E="http://www.example.com/standards/props/">
- <E:expired-props/>
- </D:propfind>
-
- To understand why a 400 (Bad Request) is returned, let us look at the
- request body as the server unfamiliar with expired-props sees it.
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:"
- xmlns:E="http://www.example.com/standards/props/">
- </D:propfind>
-
- As the server does not understand the 'expired-props' element,
- according to the WebDAV-specific XML processing rules specified in
- Section 17, it must process the request as if the element were not
- there. Thus, the server sees an empty propfind, which by the
- definition of the propfind element is illegal.
-
- Please note that had the extension been additive, it would not
- necessarily have resulted in a 400 (Bad Request). For example,
- imagine the following request body for a PROPFIND:
-
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:"
- xmlns:E="http://www.example.com/standards/props/">
- <D:propname/>
- <E:leave-out>*boss*</E:leave-out>
- </D:propfind>
-
- The previous example contains the fictitious element leave-out. Its
- purpose is to prevent the return of any property whose name matches
- the submitted pattern. If the previous example were submitted to a
- server unfamiliar with 'leave-out', the only result would be that the
- 'leave-out' element would be ignored and a propname would be
- executed.
-
-
-
-Dusseault Standards Track [Page 118]
-\f
-RFC 4918 WebDAV June 2007
-
-
-Appendix B. Notes on HTTP Client Compatibility
-
- WebDAV was designed to be, and has been found to be, backward-
- compatible with HTTP 1.1. The PUT and DELETE methods are defined in
- HTTP and thus may be used by HTTP clients as well as WebDAV-aware
- clients, but the responses to PUT and DELETE have been extended in
- this specification in ways that only a WebDAV client would be
- entirely prepared for. Some theoretical concerns were raised about
- whether those responses would cause interoperability problems with
- HTTP-only clients, and this section addresses those concerns.
-
- Since any HTTP client ought to handle unrecognized 400-level and 500-
- level status codes as errors, the following new status codes should
- not present any issues: 422, 423, and 507 (424 is also a new status
- code but it appears only in the body of a Multistatus response.) So,
- for example, if an HTTP client attempted to PUT or DELETE a locked
- resource, the 423 Locked response ought to result in a generic error
- presented to the user.
-
- The 207 Multistatus response is interesting because an HTTP client
- issuing a DELETE request to a collection might interpret a 207
- response as a success, even though it does not realize the resource
- is a collection and cannot understand that the DELETE operation might
- have been a complete or partial failure. That interpretation isn't
- entirely justified, because a 200-level response indicates that the
- server "received, understood, and accepted" the request, not that the
- request resulted in complete success.
-
- One option is that a server could treat a DELETE of a collection as
- an atomic operation, and use either 204 No Content in case of
- success, or some appropriate error response (400 or 500 level) for an
- error. This approach would indeed maximize backward compatibility.
- However, since interoperability tests and working group discussions
- have not turned up any instances of HTTP clients issuing a DELETE
- request against a WebDAV collection, this concern is more theoretical
- than practical. Thus, servers are likely to be completely successful
- at interoperating with HTTP clients even if they treat any collection
- DELETE request as a WebDAV request and send a 207 Multi-Status
- response.
-
- In general, server implementations are encouraged to use the detailed
- responses and other mechanisms defined in this document rather than
- make changes for theoretical interoperability concerns.
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 119]
-\f
-RFC 4918 WebDAV June 2007
-
-
-Appendix C. The 'opaquelocktoken' Scheme and URIs
-
- The 'opaquelocktoken' URI scheme was defined in [RFC2518] (and
- registered by IANA) in order to create syntactically correct and
- easy-to-generate URIs out of UUIDs, intended to be used as lock
- tokens and to be unique across all resources for all time.
-
- An opaquelocktoken URI is constructed by concatenating the
- 'opaquelocktoken' scheme with a UUID, along with an optional
- extension. Servers can create new UUIDs for each new lock token. If
- a server wishes to reuse UUIDs, the server MUST add an extension, and
- the algorithm generating the extension MUST guarantee that the same
- extension will never be used twice with the associated UUID.
-
- OpaqueLockToken-URI = "opaquelocktoken:" UUID [Extension]
- ; UUID is defined in Section 3 of [RFC4122]. Note that LWS
- ; is not allowed between elements of
- ; this production.
-
- Extension = path
- ; path is defined in Section 3.3 of [RFC3986]
-
-
-Appendix D. Lock-null Resources
-
- The original WebDAV model for locking unmapped URLs created "lock-
- null resources". This model was over-complicated and some
- interoperability and implementation problems were discovered. The
- new WebDAV model for locking unmapped URLs (see Section 7.3) creates
- "locked empty resources". Lock-null resources are deprecated. This
- section discusses the original model briefly because clients MUST be
- able to handle either model.
-
- In the original "lock-null resource" model, which is no longer
- recommended for implementation:
-
- o A lock-null resource sometimes appeared as "Not Found". The
- server responds with a 404 or 405 to any method except for PUT,
- MKCOL, OPTIONS, PROPFIND, LOCK, UNLOCK.
-
- o A lock-null resource does however show up as a member of its
- parent collection.
-
- o The server removes the lock-null resource entirely (its URI
- becomes unmapped) if its lock goes away before it is converted to
- a regular resource. Recall that locks go away not only when they
- expire or are unlocked, but are also removed if a resource is
- renamed or moved, or if any parent collection is renamed or moved.
-
-
-
-Dusseault Standards Track [Page 120]
-\f
-RFC 4918 WebDAV June 2007
-
-
- o The server converts the lock-null resource into a regular resource
- if a PUT request to the URL is successful.
-
- o The server converts the lock-null resource into a collection if a
- MKCOL request to the URL is successful (though interoperability
- experience showed that not all servers followed this requirement).
-
- o Property values were defined for DAV:lockdiscovery and DAV:
- supportedlock properties but not necessarily for other properties
- like DAV:getcontenttype.
-
- Clients can easily interoperate both with servers that support the
- old model "lock-null resources" and the recommended model of "locked
- empty resources" by only attempting PUT after a LOCK to an unmapped
- URL, not MKCOL or GET.
-
-D.1. Guidance for Clients Using LOCK to Create Resources
-
- A WebDAV client implemented to this specification might find servers
- that create lock-null resources (implemented before this
- specification using [RFC2518]) as well as servers that create locked
- empty resources. The response to the LOCK request will not indicate
- what kind of resource was created. There are a few techniques that
- help the client deal with either type.
-
- If the client wishes to avoid accidentally creating either lock-
- null or empty locked resources, an "If-Match: *" header can be
- included with LOCK requests to prevent the server from creating a
- new resource.
-
- If a LOCK request creates a resource and the client subsequently
- wants to overwrite that resource using a COPY or MOVE request, the
- client should include an "Overwrite: T" header.
-
- If a LOCK request creates a resource and the client then decides
- to get rid of that resource, a DELETE request is supposed to fail
- on a lock-null resource and UNLOCK should be used instead. But
- with a locked empty resource, UNLOCK doesn't make the resource
- disappear. Therefore, the client might have to try both requests
- and ignore an error in one of the two requests.
-
-Appendix E. Guidance for Clients Desiring to Authenticate
-
- Many WebDAV clients that have already been implemented have account
- settings (similar to the way email clients store IMAP account
- settings). Thus, the WebDAV client would be able to authenticate
- with its first couple requests to the server, provided it had a way
- to get the authentication challenge from the server with realm name,
-
-
-
-Dusseault Standards Track [Page 121]
-\f
-RFC 4918 WebDAV June 2007
-
-
- nonce, and other challenge information. Note that the results of
- some requests might vary according to whether or not the client is
- authenticated -- a PROPFIND might return more visible resources if
- the client is authenticated, yet not fail if the client is anonymous.
-
- There are a number of ways the client might be able to trigger the
- server to provide an authentication challenge. This appendix
- describes a couple approaches that seem particularly likely to work.
-
- The first approach is to perform a request that ought to require
- authentication. However, it's possible that a server might handle
- any request even without authentication, so to be entirely safe, the
- client could add a conditional header to ensure that even if the
- request passes permissions checks, it's not actually handled by the
- server. An example of following this approach would be to use a PUT
- request with an "If-Match" header with a made-up ETag value. This
- approach might fail to result in an authentication challenge if the
- server does not test authorization before testing conditionals as is
- required (see Section 8.5), or if the server does not need to test
- authorization.
-
- Example - forcing auth challenge with write request
-
- >>Request
-
- PUT /forceauth.txt HTTP/1.1
- Host: www.example.com
- If-Match: "xxx"
- Content-Type: text/plain
- Content-Length: 0
-
-
- The second approach is to use an Authorization header (defined in
- [RFC2617]), which is likely to be rejected by the server but which
- will then prompt a proper authentication challenge. For example, the
- client could start with a PROPFIND request containing an
- Authorization header containing a made-up Basic userid:password
- string or with actual plausible credentials. This approach relies on
- the server responding with a "401 Unauthorized" along with a
- challenge if it receives an Authorization header with an unrecognized
- username, invalid password, or if it doesn't even handle Basic
- authentication. This seems likely to work because of the
- requirements of RFC 2617:
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 122]
-\f
-RFC 4918 WebDAV June 2007
-
-
- "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."
-
- There's a slight problem with implementing that recommendation in
- some cases, because some servers do not even have challenge
- information for certain resources. Thus, when there's no way to
- authenticate to a resource or the resource is entirely publicly
- available over all accepted methods, the server MAY ignore the
- Authorization header, and the client will presumably try again later.
-
- Example - forcing auth challenge with Authorization header
-
- >>Request
-
- PROPFIND /docs/ HTTP/1.1
- Host: www.example.com
- Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
- Content-type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- [body omitted]
-
-
-Appendix F. Summary of Changes from RFC 2518
-
- This section lists major changes between this document and RFC 2518,
- starting with those that are likely to result in implementation
- changes. Servers will advertise support for all changes in this
- specification by returning the compliance class "3" in the DAV
- response header (see Sections 10.1 and 18.3).
-
-F.1. Changes for Both Client and Server Implementations
-
- Collections and Namespace Operations
-
- o The semantics of PROPFIND 'allprop' (Section 9.1) have been
- relaxed so that servers return results including, at a minimum,
- the live properties defined in this specification, but not
- necessarily return other live properties. The 'allprop' directive
- therefore means something more like "return all properties that
- are supposed to be returned when 'allprop' is requested" -- a set
- of properties that may include custom properties and properties
- defined in other specifications if those other specifications so
- require. Related to this, 'allprop' requests can now be extended
- with the 'include' syntax to include specific named properties,
-
-
-
-Dusseault Standards Track [Page 123]
-\f
-RFC 4918 WebDAV June 2007
-
-
- thereby avoiding additional requests due to changed 'allprop'
- semantics.
-
- o Servers are now allowed to reject PROPFIND requests with Depth:
- Infinity. Clients that used this will need to be able to do a
- series of Depth:1 requests instead.
-
- o Multi-Status response bodies now can transport the value of HTTP's
- Location response header in the new 'location' element. Clients
- may use this to avoid additional roundtrips to the server when
- there is a 'response' element with a 3xx status (see
- Section 14.24).
-
- o The definition of COPY has been relaxed so that it doesn't require
- servers to first delete the target resources anymore (this was a
- known incompatibility with [RFC3253]). See Section 9.8.
-
- Headers and Marshalling
-
- o The Destination and If request headers now allow absolute paths in
- addition to full URIs (see Section 8.3). This may be useful for
- clients operating through a reverse proxy that does rewrite the
- Host request header, but not WebDAV-specific headers.
-
- o This specification adopts the error marshalling extensions and the
- "precondition/postcondition" terminology defined in [RFC3253] (see
- Section 16). Related to that, it adds the "error" XML element
- inside multistatus response bodies (see Section 14.5, however note
- that it uses a format different from the one recommended in RFC
- 3253).
-
- o Senders and recipients are now required to support the UTF-16
- character encoding in XML message bodies (see Section 19).
-
- o Clients are now required to send the Depth header on PROPFIND
- requests, although servers are still encouraged to support clients
- that don't.
-
- Locking
-
- o RFC 2518's concept of "lock-null resources" (LNRs) has been
- replaced by a simplified approach, the "locked empty resources"
- (see Section 7.3). There are some aspects of lock-null resources
- clients cannot rely on anymore, namely, the ability to use them to
- create a locked collection or the fact that they disappear upon
- UNLOCK when no PUT or MKCOL request was issued. Note that servers
- are still allowed to implement LNRs as per RFC 2518.
-
-
-
-
-Dusseault Standards Track [Page 124]
-\f
-RFC 4918 WebDAV June 2007
-
-
- o There is no implicit refresh of locks anymore. Locks are only
- refreshed upon explicit request (see Section 9.10.2).
-
- o Clarified that the DAV:owner value supplied in the LOCK request
- must be preserved by the server just like a dead property
- (Section 14.17). Also added the DAV:lockroot element
- (Section 14.12), which allows clients to discover the root of
- lock.
-
-F.2. Changes for Server Implementations
-
- Collections and Namespace Operations
-
- o Due to interoperability problems, allowable formats for contents
- of 'href' elements in multistatus responses have been limited (see
- Section 8.3).
-
- o Due to lack of implementation, support for the 'propertybehavior'
- request body for COPY and MOVE has been removed. Instead,
- requirements for property preservation have been clarified (see
- Sections 9.8 and 9.9).
-
- Properties
-
- o Strengthened server requirements for storage of property values,
- in particular persistence of language information (xml:lang),
- whitespace, and XML namespace information (see Section 4.3).
-
- o Clarified requirements on which properties should be writable by
- the client; in particular, setting "DAV:displayname" should be
- supported by servers (see Section 15).
-
- o Only 'rfc1123-date' productions are legal as values for DAV:
- getlastmodified (see Section 15.7).
-
- Headers and Marshalling
-
- o Servers are now required to do authorization checks before
- processing conditional headers (see Section 8.5).
-
- Locking
-
- o Strengthened requirement to check identity of lock creator when
- accessing locked resources (see Section 6.4). Clients should be
- aware that lock tokens returned to other principals can only be
- used to break a lock, if at all.
-
-
-
-
-
-Dusseault Standards Track [Page 125]
-\f
-RFC 4918 WebDAV June 2007
-
-
- o Section 8.10.4 of [RFC2518] incorrectly required servers to return
- a 409 status where a 207 status was really appropriate. This has
- been corrected (Section 9.10).
-
-F.3. Other Changes
-
- The definition of collection state has been fixed so it doesn't vary
- anymore depending on the Request-URI (see Section 5.2).
-
- The DAV:source property introduced in Section 4.6 of [RFC2518] was
- removed due to lack of implementation experience.
-
- The DAV header now allows non-IETF extensions through URIs in
- addition to compliance class tokens. It also can now be used in
- requests, although this specification does not define any associated
- semantics for the compliance classes defined in here (see
- Section 10.1).
-
- In RFC 2518, the definition of the Depth header (Section 9.2)
- required that, by default, request headers would be applied to each
- resource in scope. Based on implementation experience, the default
- has now been reversed (see Section 10.2).
-
- The definitions of HTTP status code 102 ([RFC2518], Section 10.1) and
- the Status-URI response header (Section 9.7) have been removed due to
- lack of implementation.
-
- The TimeType format used in the Timeout request header and the
- "timeout" XML element used to be extensible. Now, only the two
- formats defined by this specification are allowed (see Section 10.7).
-
-Author's Address
-
- Lisa Dusseault (editor)
- CommerceNet
- 2064 Edgewood Dr.
- Palo Alto, CA 94303
- US
-
- EMail: ldusseault@commerce.net
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 126]
-\f
-RFC 4918 WebDAV June 2007
-
-
-Full Copyright Statement
-
- Copyright (C) The IETF Trust (2007).
-
- 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, THE IETF TRUST 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.
-
-
-
-
-
-
-
-Dusseault Standards Track [Page 127]
-\f
+++ /dev/null
-
-
-
-
-
-
-Internet Engineering Task Force (IETF) M. Nottingham
-Request for Comments: 6585 Rackspace
-Updates: 2616 R. Fielding
-Category: Standards Track Adobe
-ISSN: 2070-1721 April 2012
-
-
- Additional HTTP Status Codes
-
-Abstract
-
- This document specifies additional HyperText Transfer Protocol (HTTP)
- status codes for a variety of common situations.
-
-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 5741.
-
- 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/rfc6585.
-
-Copyright Notice
-
- Copyright (c) 2012 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.
-
-
-
-
-
-
-
-
-
-Nottingham & Fielding Standards Track [Page 1]
-\f
-RFC 6585 Additional HTTP Status Codes April 2012
-
-
-Table of Contents
-
- 1. Introduction ....................................................2
- 2. Requirements ....................................................2
- 3. 428 Precondition Required .......................................2
- 4. 429 Too Many Requests ...........................................3
- 5. 431 Request Header Fields Too Large .............................4
- 6. 511 Network Authentication Required .............................4
- 7. Security Considerations .........................................6
- 8. IANA Considerations .............................................7
- 9. References ......................................................7
- Appendix A. Acknowledgements .......................................9
- Appendix B. Issues Raised by Captive Portals .......................9
-
-1. Introduction
-
- This document specifies additional HTTP [RFC2616] status codes for a
- variety of common situations, to improve interoperability and avoid
- confusion when other, less precise status codes are used.
-
- Note that these status codes are optional; servers cannot be required
- to support them. However, because clients will treat unknown status
- codes as a generic error of the same class (e.g., 499 is treated as
- 400 if it is not recognized), they can be safely deployed by existing
- servers (see [RFC2616] Section 6.1.1 for more information).
-
-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 [RFC2119].
-
-3. 428 Precondition Required
-
- The 428 status code indicates that the origin server requires the
- request to be conditional.
-
- Its typical use is to avoid the "lost update" problem, where a client
- GETs a resource's state, modifies it, and PUTs it back to the server,
- when meanwhile a third party has modified the state on the server,
- leading to a conflict. By requiring requests to be conditional, the
- server can assure that clients are working with the correct copies.
-
- Responses using this status code SHOULD explain how to resubmit the
- request successfully. For example:
-
- HTTP/1.1 428 Precondition Required
- Content-Type: text/html
-
-
-
-Nottingham & Fielding Standards Track [Page 2]
-\f
-RFC 6585 Additional HTTP Status Codes April 2012
-
-
- <html>
- <head>
- <title>Precondition Required</title>
- </head>
- <body>
- <h1>Precondition Required</h1>
- <p>This request is required to be conditional;
- try using "If-Match".</p>
- </body>
- </html>
-
- Responses with the 428 status code MUST NOT be stored by a cache.
-
-4. 429 Too Many Requests
-
- The 429 status code indicates that the user has sent too many
- requests in a given amount of time ("rate limiting").
-
- The response representations SHOULD include details explaining the
- condition, and MAY include a Retry-After header indicating how long
- to wait before making a new request.
-
- For example:
-
- HTTP/1.1 429 Too Many Requests
- Content-Type: text/html
- Retry-After: 3600
-
- <html>
- <head>
- <title>Too Many Requests</title>
- </head>
- <body>
- <h1>Too Many Requests</h1>
- <p>I only allow 50 requests per hour to this Web site per
- logged in user. Try again soon.</p>
- </body>
- </html>
-
- Note that this specification does not define how the origin server
- identifies the user, nor how it counts requests. For example, an
- origin server that is limiting request rates can do so based upon
- counts of requests on a per-resource basis, across the entire server,
- or even among a set of servers. Likewise, it might identify the user
- by its authentication credentials, or a stateful cookie.
-
- Responses with the 429 status code MUST NOT be stored by a cache.
-
-
-
-
-Nottingham & Fielding Standards Track [Page 3]
-\f
-RFC 6585 Additional HTTP Status Codes April 2012
-
-
-5. 431 Request Header Fields Too Large
-
- The 431 status code indicates that the server is unwilling to process
- the request because its header fields are too large. The request MAY
- be resubmitted after reducing the size of the request header fields.
-
- It can be used both when the set of request header fields in total is
- too large, and when a single header field is at fault. In the latter
- case, the response representation SHOULD specify which header field
- was too large.
-
- For example:
-
- HTTP/1.1 431 Request Header Fields Too Large
- Content-Type: text/html
-
- <html>
- <head>
- <title>Request Header Fields Too Large</title>
- </head>
- <body>
- <h1>Request Header Fields Too Large</h1>
- <p>The "Example" header was too large.</p>
- </body>
- </html>
-
- Responses with the 431 status code MUST NOT be stored by a cache.
-
-6. 511 Network Authentication Required
-
- The 511 status code indicates that the client needs to authenticate
- to gain network access.
-
- The response representation SHOULD contain a link to a resource that
- allows the user to submit credentials (e.g., with an HTML form).
-
- Note that the 511 response SHOULD NOT contain a challenge or the
- login interface itself, because browsers would show the login
- interface as being associated with the originally requested URL,
- which may cause confusion.
-
- The 511 status SHOULD NOT be generated by origin servers; it is
- intended for use by intercepting proxies that are interposed as a
- means of controlling access to the network.
-
- Responses with the 511 status code MUST NOT be stored by a cache.
-
-
-
-
-
-Nottingham & Fielding Standards Track [Page 4]
-\f
-RFC 6585 Additional HTTP Status Codes April 2012
-
-
-6.1. The 511 Status Code and Captive Portals
-
- The 511 status code is designed to mitigate problems caused by
- "captive portals" to software (especially non-browser agents) that is
- expecting a response from the server that a request was made to, not
- the intervening network infrastructure. It is not intended to
- encourage deployment of captive portals -- only to limit the damage
- caused by them.
-
- A network operator wishing to require some authentication, acceptance
- of terms, or other user interaction before granting access usually
- does so by identifying clients who have not done so ("unknown
- clients") using their Media Access Control (MAC) addresses.
-
- Unknown clients then have all traffic blocked, except for that on TCP
- port 80, which is sent to an HTTP server (the "login server")
- dedicated to "logging in" unknown clients, and of course traffic to
- the login server itself.
-
- For example, a user agent might connect to a network and make the
- following HTTP request on TCP port 80:
-
- GET /index.htm HTTP/1.1
- Host: www.example.com
-
- Upon receiving such a request, the login server would generate a 511
- response:
-
- HTTP/1.1 511 Network Authentication Required
- Content-Type: text/html
-
- <html>
- <head>
- <title>Network Authentication Required</title>
- <meta http-equiv="refresh"
- content="0; url=https://login.example.net/">
- </head>
- <body>
- <p>You need to <a href="https://login.example.net/">
- authenticate with the local network</a> in order to gain
- access.</p>
- </body>
- </html>
-
- Here, the 511 status code assures that non-browser clients will not
- interpret the response as being from the origin server, and the META
- HTML element redirects the user agent to the login server.
-
-
-
-
-Nottingham & Fielding Standards Track [Page 5]
-\f
-RFC 6585 Additional HTTP Status Codes April 2012
-
-
-7. Security Considerations
-
-7.1. 428 Precondition Required
-
- The 428 status code is optional; clients cannot rely upon its use to
- prevent "lost update" conflicts.
-
-7.2. 429 Too Many Requests
-
- When a server is under attack or just receiving a very large number
- of requests from a single party, responding to each with a 429 status
- code will consume resources.
-
- Therefore, servers are not required to use the 429 status code; when
- limiting resource usage, it may be more appropriate to just drop
- connections, or take other steps.
-
-7.3. 431 Request Header Fields Too Large
-
- Servers are not required to use the 431 status code; when under
- attack, it may be more appropriate to just drop connections, or take
- other steps.
-
-7.4. 511 Network Authentication Required
-
- In common use, a response carrying the 511 status code will not come
- from the origin server indicated in the request's URL. This presents
- many security issues; e.g., an attacking intermediary may be
- inserting cookies into the original domain's name space, may be
- observing cookies or HTTP authentication credentials sent from the
- user agent, and so on.
-
- However, these risks are not unique to the 511 status code; in other
- words, a captive portal that is not using this status code introduces
- the same issues.
-
- Also, note that captive portals using this status code on a Secure
- Socket Layer (SSL) or Transport Layer Security (TLS) connection
- (commonly, port 443) will generate a certificate error on the client.
-
-
-
-
-
-
-
-
-
-
-
-
-Nottingham & Fielding Standards Track [Page 6]
-\f
-RFC 6585 Additional HTTP Status Codes April 2012
-
-
-8. IANA Considerations
-
- The HTTP Status Codes registry has been updated with the following
- entries:
-
- Value: 428
- Description: Precondition Required
- Reference: [RFC6585]
-
- Value: 429
- Description: Too Many Requests
- Reference: [RFC6585]
-
- Value: 431
- Description: Request Header Fields Too Large
- Reference: [RFC6585]
-
- Value: 511
- Description: Network Authentication Required
- Reference: [RFC6585]
-
-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.
-
- [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.
-
-9.2. Informative References
-
- [CORS] van Kesteren, A., Ed., "Cross-Origin Resource Sharing",
- W3C Working Draft WD-cors-20100727, July 2010,
- <http://www.w3.org/TR/cors/>.
-
- [Favicon] Wikipedia, "Favicon", March 2012,
- <http://en.wikipedia.org/w/
- index.php?title=Favicon&oldid=484627550>.
-
- [OAuth2.0] Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, "The
- OAuth 2.0 Authorization Protocol", Work in Progress,
- March 2012.
-
-
-
-
-
-
-Nottingham & Fielding Standards Track [Page 7]
-\f
-RFC 6585 Additional HTTP Status Codes April 2012
-
-
- [P3P] Marchiori, M., Ed., "The Platform for Privacy Preferences
- 1.0 (P3P1.0) Specification", W3C Recommendation
- REC-P3P-20020416, April 2002,
- <http://www.w3.org/TR/P3P/>.
-
- [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
- "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
- March 2007.
-
- [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed
- Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
-
- [WIDGETS] Caceres, M., Ed., "Widget Packaging and XML
- Configuration", W3C Recommendation REC-widgets-20110927,
- September 2011, <http://www.w3.org/TR/widgets/>.
-
- [WebFinger] WebFinger Project, "WebFingerProtocol (Draft)",
- January 2010, <http://code.google.com/p/webfinger/wiki/
- WebFingerProtocol>.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Nottingham & Fielding Standards Track [Page 8]
-\f
-RFC 6585 Additional HTTP Status Codes April 2012
-
-
-Appendix A. Acknowledgements
-
- Thanks to Jan Algermissen and Julian Reschke for their suggestions
- and feedback.
-
-Appendix B. Issues Raised by Captive Portals
-
- Since clients cannot differentiate between a portal's response and
- that of the HTTP server that they intended to communicate with, a
- number of issues arise. The 511 status code is intended to help
- mitigate some of them.
-
- One example is the "favicon.ico" [Favicon] commonly used by browsers
- to identify the site being accessed. If the favicon for a given site
- is fetched from a captive portal instead of the intended site (e.g.,
- because the user is unauthenticated), it will often "stick" in the
- browser's cache (most implementations cache favicons aggressively)
- beyond the portal session, so that it seems as if the portal's
- favicon has "taken over" the legitimate site.
-
- Another browser-based issue comes about when the Platform for Privacy
- Preferences [P3P] is supported. Depending on how it is implemented,
- it's possible a browser might interpret a portal's response for the
- p3p.xml file as the server's, resulting in the privacy policy (or
- lack thereof) advertised by the portal being interpreted as applying
- to the intended site. Other Web-based protocols such as WebFinger
- [WebFinger], Cross-Origin Resource Sharing [CORS], and Open
- Authorization [OAuth2.0] may also be vulnerable to such issues.
-
- Although HTTP is most widely used with Web browsers, a growing number
- of non-browsing applications use it as a substrate protocol. For
- example, Web Distributed Authoring and Versioning (WebDAV) [RFC4918]
- and Calendaring Extensions to WebDAV (CalDAV) [RFC4791] both use HTTP
- as the basis (for remote authoring and calendaring, respectively).
- Using these applications from behind a captive portal can result in
- spurious errors being presented to the user, and might result in
- content corruption, in extreme cases.
-
- Similarly, other non-browser applications using HTTP can be affected
- as well, e.g., widgets [WIDGETS], software updates, and other
- specialized software such as Twitter clients and the iTunes Music
- Store.
-
- It should be noted that it's sometimes believed that using HTTP
- redirection to direct traffic to the portal addresses these issues.
- However, since many of these uses "follow" redirects, this is not a
- good solution.
-
-
-
-
-Nottingham & Fielding Standards Track [Page 9]
-\f
-RFC 6585 Additional HTTP Status Codes April 2012
-
-
-Authors' Addresses
-
- Mark Nottingham
- Rackspace
-
- EMail: mnot@mnot.net
- URI: http://www.mnot.net/
-
-
- Roy T. Fielding
- Adobe Systems Incorporated
- 345 Park Ave.
- San Jose, CA 95110
- USA
-
- EMail: fielding@gbiv.com
- URI: http://roy.gbiv.com/
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Nottingham & Fielding Standards Track [Page 10]
-\f
+++ /dev/null
-
-
-
-
-
-
-Internet Engineering Task Force (IETF) S. Cheshire
-Request for Comments: 6762 M. Krochmal
-Category: Standards Track Apple Inc.
-ISSN: 2070-1721 February 2013
-
-
- Multicast DNS
-
-Abstract
-
- As networked devices become smaller, more portable, and more
- ubiquitous, the ability to operate with less configured
- infrastructure is increasingly important. In particular, the ability
- to look up DNS resource record data types (including, but not limited
- to, host names) in the absence of a conventional managed DNS server
- is useful.
-
- Multicast DNS (mDNS) provides the ability to perform DNS-like
- operations on the local link in the absence of any conventional
- Unicast DNS server. In addition, Multicast DNS designates a portion
- of the DNS namespace to be free for local use, without the need to
- pay any annual fee, and without the need to set up delegations or
- otherwise configure a conventional DNS server to answer for those
- names.
-
- The primary benefits of Multicast DNS names are that (i) they require
- little or no administration or configuration to set them up, (ii)
- they work when no infrastructure is present, and (iii) they work
- during infrastructure failures.
-
-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 5741.
-
- 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/rfc6762.
-
-
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 1]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
-Copyright Notice
-
- Copyright (c) 2013 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.
-
- This document may contain material from IETF Documents or IETF
- Contributions published or made publicly available before November
- 10, 2008. The person(s) controlling the copyright in some of this
- material may not have granted the IETF Trust the right to allow
- modifications of such material outside the IETF Standards Process.
- Without obtaining an adequate license from the person(s) controlling
- the copyright in such materials, this document may not be modified
- outside the IETF Standards Process, and derivative works of it may
- not be created outside the IETF Standards Process, except to format
- it for publication as an RFC or to translate it into languages other
- than English.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 2]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
-Table of Contents
-
- 1. Introduction ....................................................4
- 2. Conventions and Terminology Used in This Document ...............4
- 3. Multicast DNS Names .............................................5
- 4. Reverse Address Mapping .........................................7
- 5. Querying ........................................................8
- 6. Responding .....................................................13
- 7. Traffic Reduction ..............................................22
- 8. Probing and Announcing on Startup ..............................25
- 9. Conflict Resolution ............................................31
- 10. Resource Record TTL Values and Cache Coherency ................33
- 11. Source Address Check ..........................................38
- 12. Special Characteristics of Multicast DNS Domains ..............40
- 13. Enabling and Disabling Multicast DNS ..........................41
- 14. Considerations for Multiple Interfaces ........................42
- 15. Considerations for Multiple Responders on the Same Machine ....43
- 16. Multicast DNS Character Set ...................................45
- 17. Multicast DNS Message Size ....................................46
- 18. Multicast DNS Message Format ..................................47
- 19. Summary of Differences between Multicast DNS and Unicast DNS ..51
- 20. IPv6 Considerations ...........................................52
- 21. Security Considerations .......................................52
- 22. IANA Considerations ...........................................53
- 23. Acknowledgments ...............................................56
- 24. References ....................................................56
- Appendix A. Design Rationale for Choice of UDP Port Number ........60
- Appendix B. Design Rationale for Not Using Hashed Multicast
- Addresses .............................................61
- Appendix C. Design Rationale for Maximum Multicast DNS Name
- Length ................................................62
- Appendix D. Benefits of Multicast Responses .......................64
- Appendix E. Design Rationale for Encoding Negative Responses ......65
- Appendix F. Use of UTF-8 ..........................................66
- Appendix G. Private DNS Namespaces ................................67
- Appendix H. Deployment History ....................................67
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 3]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
-1. Introduction
-
- Multicast DNS and its companion technology DNS-Based Service
- Discovery [RFC6763] were created to provide IP networking with the
- ease-of-use and autoconfiguration for which AppleTalk was well-known
- [RFC6760]. When reading this document, familiarity with the concepts
- of Zero Configuration Networking [Zeroconf] and automatic link-local
- addressing [RFC3927] [RFC4862] is helpful.
-
- Multicast DNS borrows heavily from the existing DNS protocol
- [RFC1034] [RFC1035] [RFC6195], using the existing DNS message
- structure, name syntax, and resource record types. This document
- specifies no new operation codes or response codes. This document
- describes how clients send DNS-like queries via IP multicast, and how
- a collection of hosts cooperate to collectively answer those queries
- in a useful manner.
-
-2. Conventions and Terminology Used in This Document
-
- 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 "Key words for use in
- RFCs to Indicate Requirement Levels" [RFC2119].
-
- When this document uses the term "Multicast DNS", it should be taken
- to mean: "Clients performing DNS-like queries for DNS-like resource
- records by sending DNS-like UDP query and response messages over IP
- Multicast to UDP port 5353". The design rationale for selecting UDP
- port 5353 is discussed in Appendix A.
-
- This document uses the term "host name" in the strict sense to mean a
- fully qualified domain name that has an IPv4 or IPv6 address record.
- It does not use the term "host name" in the commonly used but
- incorrect sense to mean just the first DNS label of a host's fully
- qualified domain name.
-
- A DNS (or mDNS) packet contains an IP Time to Live (TTL) in the IP
- header, which is effectively a hop-count limit for the packet, to
- guard against routing loops. Each resource record also contains a
- TTL, which is the number of seconds for which the resource record may
- be cached. This document uses the term "IP TTL" to refer to the IP
- header TTL (hop limit), and the term "RR TTL" or just "TTL" to refer
- to the resource record TTL (cache lifetime).
-
- DNS-format messages contain a header, a Question Section, then
- Answer, Authority, and Additional Record Sections. The Answer,
- Authority, and Additional Record Sections all hold resource records
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 4]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- in the same format. Where this document describes issues that apply
- equally to all three sections, it uses the term "Resource Record
- Sections" to refer collectively to these three sections.
-
- This document uses the terms "shared" and "unique" when referring to
- resource record sets [RFC1034]:
-
- A "shared" resource record set is one where several Multicast DNS
- responders may have records with the same name, rrtype, and
- rrclass, and several responders may respond to a particular query.
-
- A "unique" resource record set is one where all the records with
- that name, rrtype, and rrclass are conceptually under the control
- or ownership of a single responder, and it is expected that at
- most one responder should respond to a query for that name,
- rrtype, and rrclass. Before claiming ownership of a unique
- resource record set, a responder MUST probe to verify that no
- other responder already claims ownership of that set, as described
- in Section 8.1, "Probing". (For fault-tolerance and other
- reasons, sometimes it is permissible to have more than one
- responder answering for a particular "unique" resource record set,
- but such cooperating responders MUST give answers containing
- identical rdata for these records. If they do not give answers
- containing identical rdata, then the probing step will reject the
- data as being inconsistent with what is already being advertised
- on the network for those names.)
-
- Strictly speaking, the terms "shared" and "unique" apply to resource
- record sets, not to individual resource records. However, it is
- sometimes convenient to talk of "shared resource records" and "unique
- resource records". When used this way, the terms should be
- understood to mean a record that is a member of a "shared" or
- "unique" resource record set, respectively.
-
-3. Multicast DNS Names
-
- A host that belongs to an organization or individual who has control
- over some portion of the DNS namespace can be assigned a globally
- unique name within that portion of the DNS namespace, such as,
- "cheshire.example.com.". For those of us who have this luxury, this
- works very well. However, the majority of home computer users do not
- have easy access to any portion of the global DNS namespace within
- which they have the authority to create names. This leaves the
- majority of home computers effectively anonymous for practical
- purposes.
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 5]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- To remedy this problem, this document allows any computer user to
- elect to give their computers link-local Multicast DNS host names of
- the form: "single-dns-label.local.". For example, a laptop computer
- may answer to the name "MyComputer.local.". Any computer user is
- granted the authority to name their computer this way, provided that
- the chosen host name is not already in use on that link. Having
- named their computer this way, the user has the authority to continue
- utilizing that name until such time as a name conflict occurs on the
- link that is not resolved in the user's favor. If this happens, the
- computer (or its human user) MUST cease using the name, and SHOULD
- attempt to allocate a new unique name for use on that link. These
- conflicts are expected to be relatively rare for people who choose
- reasonably imaginative names, but it is still important to have a
- mechanism in place to handle them when they happen.
-
- This document specifies that the DNS top-level domain ".local." is a
- special domain with special semantics, namely that any fully
- qualified name ending in ".local." is link-local, and names within
- this domain are meaningful only on the link where they originate.
- This is analogous to IPv4 addresses in the 169.254/16 prefix or IPv6
- addresses in the FE80::/10 prefix, which are link-local and
- meaningful only on the link where they originate.
-
- Any DNS query for a name ending with ".local." MUST be sent to the
- mDNS IPv4 link-local multicast address 224.0.0.251 (or its IPv6
- equivalent FF02::FB). The design rationale for using a fixed
- multicast address instead of selecting from a range of multicast
- addresses using a hash function is discussed in Appendix B.
- Implementers MAY choose to look up such names concurrently via other
- mechanisms (e.g., Unicast DNS) and coalesce the results in some
- fashion. Implementers choosing to do this should be aware of the
- potential for user confusion when a given name can produce different
- results depending on external network conditions (such as, but not
- limited to, which name lookup mechanism responds faster).
-
- It is unimportant whether a name ending with ".local." occurred
- because the user explicitly typed in a fully qualified domain name
- ending in ".local.", or because the user entered an unqualified
- domain name and the host software appended the suffix ".local."
- because that suffix appears in the user's search list. The ".local."
- suffix could appear in the search list because the user manually
- configured it, or because it was received via DHCP [RFC2132] or via
- any other mechanism for configuring the DNS search list. In this
- respect the ".local." suffix is treated no differently from any other
- search domain that might appear in the DNS search list.
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 6]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- DNS queries for names that do not end with ".local." MAY be sent to
- the mDNS multicast address, if no other conventional DNS server is
- available. This can allow hosts on the same link to continue
- communicating using each other's globally unique DNS names during
- network outages that disrupt communication with the greater Internet.
- When resolving global names via local multicast, it is even more
- important to use DNS Security Extensions (DNSSEC) [RFC4033] or other
- security mechanisms to ensure that the response is trustworthy.
- Resolving global names via local multicast is a contentious issue,
- and this document does not discuss it further, instead concentrating
- on the issue of resolving local names using DNS messages sent to a
- multicast address.
-
- This document recommends a single flat namespace for dot-local host
- names, (i.e., the names of DNS "A" and "AAAA" records, which map
- names to IPv4 and IPv6 addresses), but other DNS record types (such
- as those used by DNS-Based Service Discovery [RFC6763]) may contain
- as many labels as appropriate for the desired usage, up to a maximum
- of 255 bytes, plus a terminating zero byte at the end. Name length
- issues are discussed further in Appendix C.
-
- Enforcing uniqueness of host names is probably desirable in the
- common case, but this document does not mandate that. It is
- permissible for a collection of coordinated hosts to agree to
- maintain multiple DNS address records with the same name, possibly
- for load-balancing or fault-tolerance reasons. This document does
- not take a position on whether that is sensible. It is important
- that both modes of operation be supported. The Multicast DNS
- protocol allows hosts to verify and maintain unique names for
- resource records where that behavior is desired, and it also allows
- hosts to maintain multiple resource records with a single shared name
- where that behavior is desired. This consideration applies to all
- resource records, not just address records (host names). In summary:
- It is required that the protocol have the ability to detect and
- handle name conflicts, but it is not required that this ability be
- used for every record.
-
-4. Reverse Address Mapping
-
- Like ".local.", the IPv4 and IPv6 reverse mapping domains are also
- defined to be link-local:
-
- Any DNS query for a name ending with "254.169.in-addr.arpa." MUST
- be sent to the mDNS IPv4 link-local multicast address 224.0.0.251
- or the mDNS IPv6 multicast address FF02::FB. Since names under
- this domain correspond to IPv4 link-local addresses, it is logical
- that the local link is the best place to find information
- pertaining to those names.
-
-
-
-Cheshire & Krochmal Standards Track [Page 7]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- Likewise, any DNS query for a name within the reverse mapping
- domains for IPv6 link-local addresses ("8.e.f.ip6.arpa.",
- "9.e.f.ip6.arpa.", "a.e.f.ip6.arpa.", and "b.e.f.ip6.arpa.") MUST
- be sent to the mDNS IPv6 link-local multicast address FF02::FB or
- the mDNS IPv4 link-local multicast address 224.0.0.251.
-
-5. Querying
-
- There are two kinds of Multicast DNS queries: one-shot queries of the
- kind made by legacy DNS resolvers, and continuous, ongoing Multicast
- DNS queries made by fully compliant Multicast DNS queriers, which
- support asynchronous operations including DNS-Based Service Discovery
- [RFC6763].
-
- Except in the rare case of a Multicast DNS responder that is
- advertising only shared resource records and no unique records, a
- Multicast DNS responder MUST also implement a Multicast DNS querier
- so that it can first verify the uniqueness of those records before it
- begins answering queries for them.
-
-5.1. One-Shot Multicast DNS Queries
-
- The most basic kind of Multicast DNS client may simply send standard
- DNS queries blindly to 224.0.0.251:5353, without necessarily even
- being aware of what a multicast address is. This change can
- typically be implemented with just a few lines of code in an existing
- DNS resolver library. If a name being queried falls within one of
- the reserved Multicast DNS domains (see Sections 3 and 4), then,
- rather than using the configured Unicast DNS server address, the
- query is instead sent to 224.0.0.251:5353 (or its IPv6 equivalent
- [FF02::FB]:5353). Typically, the timeout would also be shortened to
- two or three seconds. It's possible to make a minimal Multicast DNS
- resolver with only these simple changes. These queries are typically
- done using a high-numbered ephemeral UDP source port, but regardless
- of whether they are sent from a dynamic port or from a fixed port,
- these queries MUST NOT be sent using UDP source port 5353, since
- using UDP source port 5353 signals the presence of a fully compliant
- Multicast DNS querier, as described below.
-
- A simple DNS resolver like this will typically just take the first
- response it receives. It will not listen for additional UDP
- responses, but in many instances this may not be a serious problem.
- If a user types "http://MyPrinter.local." into their web browser, and
- their simple DNS resolver just takes the first response it receives,
- and the user gets to see the status and configuration web page for
- their printer, then the protocol has met the user's needs in this
- case.
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 8]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- While a basic DNS resolver like this may be adequate for simple host
- name lookup, it may not get ideal behavior in other cases.
- Additional refinements to create a fully compliant Multicast DNS
- querier are described below.
-
-5.2. Continuous Multicast DNS Querying
-
- In one-shot queries, the underlying assumption is that the
- transaction begins when the application issues a query, and ends when
- the first response is received. There is another type of query
- operation that is more asynchronous, in which having received one
- response is not necessarily an indication that there will be no more
- relevant responses, and the querying operation continues until no
- further responses are required. Determining when no further
- responses are required depends on the type of operation being
- performed. If the operation is looking up the IPv4 and IPv6
- addresses of another host, then no further responses are required
- once a successful connection has been made to one of those IPv4 or
- IPv6 addresses. If the operation is browsing to present the user
- with a list of DNS-SD services found on the network [RFC6763], then
- no further responses are required once the user indicates this to the
- user-interface software, e.g., by closing the network browsing window
- that was displaying the list of discovered services.
-
- Imagine some hypothetical software that allows users to discover
- network printers. The user wishes to discover all printers on the
- local network, not only the printer that is quickest to respond.
- When the user is actively looking for a network printer to use, they
- open a network browsing window that displays the list of discovered
- printers. It would be convenient for the user if they could rely on
- this list of network printers to stay up to date as network printers
- come and go, rather than displaying out-of-date stale information,
- and requiring the user explicitly to click a "refresh" button any
- time they want to see accurate information (which, from the moment it
- is displayed, is itself already beginning to become out-of-date and
- stale). If we are to display a continuously updated live list like
- this, we need to be able to do it efficiently, without naive constant
- polling, which would be an unreasonable burden on the network. It is
- not expected that all users will be browsing to discover new printers
- all the time, but when a user is browsing to discover service
- instances for an extended period, we want to be able to support that
- operation efficiently.
-
- Therefore, when retransmitting Multicast DNS queries to implement
- this kind of continuous monitoring, the interval between the first
- two queries MUST be at least one second, the intervals between
- successive queries MUST increase by at least a factor of two, and the
- querier MUST implement Known-Answer Suppression, as described below
-
-
-
-Cheshire & Krochmal Standards Track [Page 9]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- in Section 7.1. The Known-Answer Suppression mechanism tells
- responders which answers are already known to the querier, thereby
- allowing responders to avoid wasting network capacity with pointless
- repeated transmission of those answers. A querier retransmits its
- question because it wishes to receive answers it may have missed the
- first time, not because it wants additional duplicate copies of
- answers it already received. Failure to implement Known-Answer
- Suppression can result in unacceptable levels of network traffic.
- When the interval between queries reaches or exceeds 60 minutes, a
- querier MAY cap the interval to a maximum of 60 minutes, and perform
- subsequent queries at a steady-state rate of one query per hour. To
- avoid accidental synchronization when, for some reason, multiple
- clients begin querying at exactly the same moment (e.g., because of
- some common external trigger event), a Multicast DNS querier SHOULD
- also delay the first query of the series by a randomly chosen amount
- in the range 20-120 ms.
-
- When a Multicast DNS querier receives an answer, the answer contains
- a TTL value that indicates for how many seconds this answer is valid.
- After this interval has passed, the answer will no longer be valid
- and SHOULD be deleted from the cache. Before the record expiry time
- is reached, a Multicast DNS querier that has local clients with an
- active interest in the state of that record (e.g., a network browsing
- window displaying a list of discovered services to the user) SHOULD
- reissue its query to determine whether the record is still valid.
-
- To perform this cache maintenance, a Multicast DNS querier should
- plan to retransmit its query after at least 50% of the record
- lifetime has elapsed. This document recommends the following
- specific strategy.
-
- The querier should plan to issue a query at 80% of the record
- lifetime, and then if no answer is received, at 85%, 90%, and 95%.
- If an answer is received, then the remaining TTL is reset to the
- value given in the answer, and this process repeats for as long as
- the Multicast DNS querier has an ongoing interest in the record. If
- no answer is received after four queries, the record is deleted when
- it reaches 100% of its lifetime. A Multicast DNS querier MUST NOT
- perform this cache maintenance for records for which it has no local
- clients with an active interest. If the expiry of a particular
- record from the cache would result in no net effect to any client
- software running on the querier device, and no visible effect to the
- human user, then there is no reason for the Multicast DNS querier to
- waste network capacity checking whether the record remains valid.
-
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 10]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- To avoid the case where multiple Multicast DNS queriers on a network
- all issue their queries simultaneously, a random variation of 2% of
- the record TTL should be added, so that queries are scheduled to be
- performed at 80-82%, 85-87%, 90-92%, and then 95-97% of the TTL.
-
- An additional efficiency optimization SHOULD be performed when a
- Multicast DNS response is received containing a unique answer (as
- indicated by the cache-flush bit being set, described in Section
- 10.2, "Announcements to Flush Outdated Cache Entries"). In this
- case, there is no need for the querier to continue issuing a stream
- of queries with exponentially increasing intervals, since the receipt
- of a unique answer is a good indication that no other answers will be
- forthcoming. In this case, the Multicast DNS querier SHOULD plan to
- issue its next query for this record at 80-82% of the record's TTL,
- as described above.
-
- A compliant Multicast DNS querier, which implements the rules
- specified in this document, MUST send its Multicast DNS queries from
- UDP source port 5353 (the well-known port assigned to mDNS), and MUST
- listen for Multicast DNS replies sent to UDP destination port 5353 at
- the mDNS link-local multicast address (224.0.0.251 and/or its IPv6
- equivalent FF02::FB).
-
-5.3. Multiple Questions per Query
-
- Multicast DNS allows a querier to place multiple questions in the
- Question Section of a single Multicast DNS query message.
-
- The semantics of a Multicast DNS query message containing multiple
- questions is identical to a series of individual DNS query messages
- containing one question each. Combining multiple questions into a
- single message is purely an efficiency optimization and has no other
- semantic significance.
-
-5.4. Questions Requesting Unicast Responses
-
- Sending Multicast DNS responses via multicast has the benefit that
- all the other hosts on the network get to see those responses,
- enabling them to keep their caches up to date and detect conflicting
- responses.
-
- However, there are situations where all the other hosts on the
- network don't need to see every response. Some examples are a laptop
- computer waking from sleep, the Ethernet cable being connected to a
- running machine, or a previously inactive interface being activated
- through a configuration change. At the instant of wake-up or link
- activation, the machine is a brand new participant on a new network.
- Its Multicast DNS cache for that interface is empty, and it has no
-
-
-
-Cheshire & Krochmal Standards Track [Page 11]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- knowledge of its peers on that link. It may have a significant
- number of questions that it wants answered right away, to discover
- information about its new surroundings and present that information
- to the user. As a new participant on the network, it has no idea
- whether the exact same questions may have been asked and answered
- just seconds ago. In this case, triggering a large sudden flood of
- multicast responses may impose an unreasonable burden on the network.
-
- To avoid large floods of potentially unnecessary responses in these
- cases, Multicast DNS defines the top bit in the class field of a DNS
- question as the unicast-response bit. When this bit is set in a
- question, it indicates that the querier is willing to accept unicast
- replies in response to this specific query, as well as the usual
- multicast responses. These questions requesting unicast responses
- are referred to as "QU" questions, to distinguish them from the more
- usual questions requesting multicast responses ("QM" questions). A
- Multicast DNS querier sending its initial batch of questions
- immediately on wake from sleep or interface activation SHOULD set the
- unicast-response bit in those questions.
-
- When a question is retransmitted (as described in Section 5.2), the
- unicast-response bit SHOULD NOT be set in subsequent retransmissions
- of that question. Subsequent retransmissions SHOULD be usual "QM"
- questions. After the first question has received its responses, the
- querier should have a large Known-Answer list (Section 7.1) so that
- subsequent queries should elicit few, if any, further responses.
- Reverting to multicast responses as soon as possible is important
- because of the benefits that multicast responses provide (see
- Appendix D). In addition, the unicast-response bit SHOULD be set
- only for questions that are active and ready to be sent the moment of
- wake from sleep or interface activation. New questions created by
- local clients afterwards should be treated as normal "QM" questions
- and SHOULD NOT have the unicast-response bit set on the first
- question of the series.
-
- When receiving a question with the unicast-response bit set, a
- responder SHOULD usually respond with a unicast packet directed back
- to the querier. However, if the responder has not multicast that
- record recently (within one quarter of its TTL), then the responder
- SHOULD instead multicast the response so as to keep all the peer
- caches up to date, and to permit passive conflict detection. In the
- case of answering a probe question (Section 8.1) with the unicast-
- response bit set, the responder should always generate the requested
- unicast response, but it may also send a multicast announcement if
- the time since the last multicast announcement of that record is more
- than a quarter of its TTL.
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 12]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- Unicast replies are subject to all the same packet generation rules
- as multicast replies, including the cache-flush bit (Section 10.2)
- and (except when defending a unique name against a probe from another
- host) randomized delays to reduce network collisions (Section 6).
-
-5.5. Direct Unicast Queries to Port 5353
-
- In specialized applications there may be rare situations where it
- makes sense for a Multicast DNS querier to send its query via unicast
- to a specific machine. When a Multicast DNS responder receives a
- query via direct unicast, it SHOULD respond as it would for "QU"
- questions, as described above in Section 5.4. Since it is possible
- for a unicast query to be received from a machine outside the local
- link, responders SHOULD check that the source address in the query
- packet matches the local subnet for that link (or, in the case of
- IPv6, the source address has an on-link prefix) and silently ignore
- the packet if not.
-
- There may be specialized situations, outside the scope of this
- document, where it is intended and desirable to create a responder
- that does answer queries originating outside the local link. Such a
- responder would need to ensure that these non-local queries are
- always answered via unicast back to the querier, since an answer sent
- via link-local multicast would not reach a querier outside the local
- link.
-
-6. Responding
-
- When a Multicast DNS responder constructs and sends a Multicast DNS
- response message, the Resource Record Sections of that message must
- contain only records for which that responder is explicitly
- authoritative. These answers may be generated because the record
- answers a question received in a Multicast DNS query message, or at
- certain other times that the responder determines than an unsolicited
- announcement is warranted. A Multicast DNS responder MUST NOT place
- records from its cache, which have been learned from other responders
- on the network, in the Resource Record Sections of outgoing response
- messages. Only an authoritative source for a given record is allowed
- to issue responses containing that record.
-
- The determination of whether a given record answers a given question
- is made using the standard DNS rules: the record name must match the
- question name, the record rrtype must match the question qtype unless
- the qtype is "ANY" (255) or the rrtype is "CNAME" (5), and the record
- rrclass must match the question qclass unless the qclass is "ANY"
- (255). As with Unicast DNS, generally only DNS class 1 ("Internet")
- is used, but should client software use classes other than 1, the
- matching rules described above MUST be used.
-
-
-
-Cheshire & Krochmal Standards Track [Page 13]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- A Multicast DNS responder MUST only respond when it has a positive,
- non-null response to send, or it authoritatively knows that a
- particular record does not exist. For unique records, where the host
- has already established sole ownership of the name, it MUST return
- negative answers to queries for records that it knows not to exist.
- For example, a host with no IPv6 address, that has claimed sole
- ownership of the name "host.local." for all rrtypes, MUST respond to
- AAAA queries for "host.local." by sending a negative answer
- indicating that no AAAA records exist for that name. See Section
- 6.1, "Negative Responses". For shared records, which are owned by no
- single host, the nonexistence of a given record is ascertained by the
- failure of any machine to respond to the Multicast DNS query, not by
- any explicit negative response. For shared records, NXDOMAIN and
- other error responses MUST NOT be sent.
-
- Multicast DNS responses MUST NOT contain any questions in the
- Question Section. Any questions in the Question Section of a
- received Multicast DNS response MUST be silently ignored. Multicast
- DNS queriers receiving Multicast DNS responses do not care what
- question elicited the response; they care only that the information
- in the response is true and accurate.
-
- A Multicast DNS responder on Ethernet [IEEE.802.3] and similar shared
- multiple access networks SHOULD have the capability of delaying its
- responses by up to 500 ms, as described below.
-
- If a large number of Multicast DNS responders were all to respond
- immediately to a particular query, a collision would be virtually
- guaranteed. By imposing a small random delay, the number of
- collisions is dramatically reduced. On a full-sized Ethernet using
- the maximum cable lengths allowed and the maximum number of repeaters
- allowed, an Ethernet frame is vulnerable to collisions during the
- transmission of its first 256 bits. On 10 Mb/s Ethernet, this
- equates to a vulnerable time window of 25.6 microseconds. On higher-
- speed variants of Ethernet, the vulnerable time window is shorter.
-
- In the case where a Multicast DNS responder has good reason to
- believe that it will be the only responder on the link that will send
- a response (i.e., because it is able to answer every question in the
- query message, and for all of those answer records it has previously
- verified that the name, rrtype, and rrclass are unique on the link),
- it SHOULD NOT impose any random delay before responding, and SHOULD
- normally generate its response within at most 10 ms. In particular,
- this applies to responding to probe queries with the unicast-response
- bit set. Since receiving a probe query gives a clear indication that
- some other responder is planning to start using this name in the very
- near future, answering such probe queries to defend a unique record
- is a high priority and needs to be done without delay. A probe query
-
-
-
-Cheshire & Krochmal Standards Track [Page 14]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- can be distinguished from a normal query by the fact that a probe
- query contains a proposed record in the Authority Section that
- answers the question in the Question Section (for more details, see
- Section 8.2, "Simultaneous Probe Tiebreaking").
-
- Responding without delay is appropriate for records like the address
- record for a particular host name, when the host name has been
- previously verified unique. Responding without delay is *not*
- appropriate for things like looking up PTR records used for DNS-Based
- Service Discovery [RFC6763], where a large number of responses may be
- anticipated.
-
- In any case where there may be multiple responses, such as queries
- where the answer is a member of a shared resource record set, each
- responder SHOULD delay its response by a random amount of time
- selected with uniform random distribution in the range 20-120 ms.
- The reason for requiring that the delay be at least 20 ms is to
- accommodate the situation where two or more query packets are sent
- back-to-back, because in that case we want a responder with answers
- to more than one of those queries to have the opportunity to
- aggregate all of its answers into a single response message.
-
- In the case where the query has the TC (truncated) bit set,
- indicating that subsequent Known-Answer packets will follow,
- responders SHOULD delay their responses by a random amount of time
- selected with uniform random distribution in the range 400-500 ms, to
- allow enough time for all the Known-Answer packets to arrive, as
- described in Section 7.2, "Multipacket Known-Answer Suppression".
-
- The source UDP port in all Multicast DNS responses MUST be 5353 (the
- well-known port assigned to mDNS). Multicast DNS implementations
- MUST silently ignore any Multicast DNS responses they receive where
- the source UDP port is not 5353.
-
- The destination UDP port in all Multicast DNS responses MUST be 5353,
- and the destination address MUST be the mDNS IPv4 link-local
- multicast address 224.0.0.251 or its IPv6 equivalent FF02::FB, except
- when generating a reply to a query that explicitly requested a
- unicast response:
-
- * via the unicast-response bit,
- * by virtue of being a legacy query (Section 6.7), or
- * by virtue of being a direct unicast query.
-
- Except for these three specific cases, responses MUST NOT be sent via
- unicast, because then the "Passive Observation of Failures"
- mechanisms described in Section 10.5 would not work correctly. Other
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 15]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- benefits of sending responses via multicast are discussed in Appendix
- D. A Multicast DNS querier MUST only accept unicast responses if
- they answer a recently sent query (e.g., sent within the last two
- seconds) that explicitly requested unicast responses. A Multicast
- DNS querier MUST silently ignore all other unicast responses.
-
- To protect the network against excessive packet flooding due to
- software bugs or malicious attack, a Multicast DNS responder MUST NOT
- (except in the one special case of answering probe queries) multicast
- a record on a given interface until at least one second has elapsed
- since the last time that record was multicast on that particular
- interface. A legitimate querier on the network should have seen the
- previous transmission and cached it. A querier that did not receive
- and cache the previous transmission will retry its request and
- receive a subsequent response. In the special case of answering
- probe queries, because of the limited time before the probing host
- will make its decision about whether or not to use the name, a
- Multicast DNS responder MUST respond quickly. In this special case
- only, when responding via multicast to a probe, a Multicast DNS
- responder is only required to delay its transmission as necessary to
- ensure an interval of at least 250 ms since the last time the record
- was multicast on that interface.
-
-6.1. Negative Responses
-
- In the early design of Multicast DNS it was assumed that explicit
- negative responses would never be needed. A host can assert the
- existence of the set of records that it claims to exist, and the
- union of all such sets on a link is the set of Multicast DNS records
- that exist on that link. Asserting the nonexistence of every record
- in the complement of that set -- i.e., all possible Multicast DNS
- records that could exist on this link but do not at this moment --
- was felt to be impractical and unnecessary. The nonexistence of a
- record would be ascertained by a querier querying for it and failing
- to receive a response from any of the hosts currently attached to the
- link.
-
- However, operational experience showed that explicit negative
- responses can sometimes be valuable. One such example is when a
- querier is querying for a AAAA record, and the host name in question
- has no associated IPv6 addresses. In this case, the responding host
- knows it currently has exclusive ownership of that name, and it knows
- that it currently does not have any IPv6 addresses, so an explicit
- negative response is preferable to the querier having to retransmit
- its query multiple times, and eventually give up with a timeout,
- before it can conclude that a given AAAA record does not exist.
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 16]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- Any time a responder receives a query for a name for which it has
- verified exclusive ownership, for a type for which that name has no
- records, the responder MUST (except as allowed in (a) below) respond
- asserting the nonexistence of that record using a DNS NSEC record
- [RFC4034]. In the case of Multicast DNS the NSEC record is not being
- used for its usual DNSSEC [RFC4033] security properties, but simply
- as a way of expressing which records do or do not exist with a given
- name.
-
- On receipt of a question for a particular name, rrtype, and rrclass,
- for which a responder does have one or more unique answers, the
- responder MAY also include an NSEC record in the Additional Record
- Section indicating the nonexistence of other rrtypes for that name
- and rrclass.
-
- Implementers working with devices with sufficient memory and CPU
- resources MAY choose to implement code to handle the full generality
- of the DNS NSEC record [RFC4034], including bitmaps up to 65,536 bits
- long. To facilitate use by devices with limited memory and CPU
- resources, Multicast DNS queriers are only REQUIRED to be able to
- parse a restricted form of the DNS NSEC record. All compliant
- Multicast DNS implementations MUST at least correctly generate and
- parse the restricted DNS NSEC record format described below:
-
- o The 'Next Domain Name' field contains the record's own name.
- When used with name compression, this means that the 'Next
- Domain Name' field always takes exactly two bytes in the
- message.
-
- o The Type Bit Map block number is 0.
-
- o The Type Bit Map block length byte is a value in the range 1-32.
-
- o The Type Bit Map data is 1-32 bytes, as indicated by length
- byte.
-
- Because this restricted form of the DNS NSEC record is limited to
- Type Bit Map block number zero, it cannot express the existence of
- rrtypes above 255. Consequently, if a Multicast DNS responder were
- to have records with rrtypes above 255, it MUST NOT generate these
- restricted-form NSEC records for those names, since to do so would
- imply that the name has no records with rrtypes above 255, which
- would be false. In such cases a Multicast DNS responder MUST either
- (a) emit no NSEC record for that name, or (b) emit a full NSEC record
- containing the appropriate Type Bit Map block(s) with the correct
- bits set for all the record types that exist. In practice this is
- not a significant limitation, since rrtypes above 255 are not
- currently in widespread use.
-
-
-
-Cheshire & Krochmal Standards Track [Page 17]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- If a Multicast DNS implementation receives an NSEC record where the
- 'Next Domain Name' field is not the record's own name, then the
- implementation SHOULD ignore the 'Next Domain Name' field and process
- the remainder of the NSEC record as usual. In Multicast DNS the
- 'Next Domain Name' field is not currently used, but it could be used
- in a future version of this protocol, which is why a Multicast DNS
- implementation MUST NOT reject or ignore an NSEC record it receives
- just because it finds an unexpected value in the 'Next Domain Name'
- field.
-
- If a Multicast DNS implementation receives an NSEC record containing
- more than one Type Bit Map, or where the Type Bit Map block number is
- not zero, or where the block length is not in the range 1-32, then
- the Multicast DNS implementation MAY silently ignore the entire NSEC
- record. A Multicast DNS implementation MUST NOT ignore an entire
- message just because that message contains one or more NSEC record(s)
- that the Multicast DNS implementation cannot parse. This provision
- is to allow future enhancements to the protocol to be introduced in a
- backwards-compatible way that does not break compatibility with older
- Multicast DNS implementations.
-
- To help differentiate these synthesized NSEC records (generated
- programmatically on-the-fly) from conventional Unicast DNS NSEC
- records (which actually exist in a signed DNS zone), the synthesized
- Multicast DNS NSEC records MUST NOT have the NSEC bit set in the Type
- Bit Map, whereas conventional Unicast DNS NSEC records do have the
- NSEC bit set.
-
- The TTL of the NSEC record indicates the intended lifetime of the
- negative cache entry. In general, the TTL given for an NSEC record
- SHOULD be the same as the TTL that the record would have had, had it
- existed. For example, the TTL for address records in Multicast DNS
- is typically 120 seconds (see Section 10), so the negative cache
- lifetime for an address record that does not exist should also be 120
- seconds.
-
- A responder MUST only generate negative responses to queries for
- which it has legitimate ownership of the name, rrtype, and rrclass in
- question, and can legitimately assert that no record with that name,
- rrtype, and rrclass exists. A responder can assert that a specified
- rrtype does not exist for one of its names if it knows a priori that
- it has exclusive ownership of that name (e.g., names of reverse
- address mapping PTR records, which are derived from IP addresses,
- which should be unique on the local link) or if it previously claimed
- unique ownership of that name using probe queries for rrtype "ANY".
- (If it were to use probe queries for a specific rrtype, then it would
- only own the name for that rrtype, and could not assert that other
- rrtypes do not exist.)
-
-
-
-Cheshire & Krochmal Standards Track [Page 18]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- The design rationale for this mechanism for encoding negative
- responses is discussed further in Appendix E.
-
-6.2. Responding to Address Queries
-
- When a Multicast DNS responder sends a Multicast DNS response message
- containing its own address records, it MUST include all addresses
- that are valid on the interface on which it is sending the message,
- and MUST NOT include addresses that are not valid on that interface
- (such as addresses that may be configured on the host's other
- interfaces). For example, if an interface has both an IPv6 link-
- local and an IPv6 routable address, both should be included in the
- response message so that queriers receive both and can make their own
- choice about which to use. This allows a querier that only has an
- IPv6 link-local address to connect to the link-local address, and a
- different querier that has an IPv6 routable address to connect to the
- IPv6 routable address instead.
-
- When a Multicast DNS responder places an IPv4 or IPv6 address record
- (rrtype "A" or "AAAA") into a response message, it SHOULD also place
- any records of the other address type with the same name into the
- additional section, if there is space in the message. This is to
- provide fate sharing, so that all a device's addresses are delivered
- atomically in a single message, to reduce the risk that packet loss
- could cause a querier to receive only the IPv4 addresses and not the
- IPv6 addresses, or vice versa.
-
- In the event that a device has only IPv4 addresses but no IPv6
- addresses, or vice versa, then the appropriate NSEC record SHOULD be
- placed into the additional section, so that queriers can know with
- certainty that the device has no addresses of that kind.
-
- Some Multicast DNS responders treat a physical interface with both
- IPv4 and IPv6 address as a single interface with two addresses.
- Other Multicast DNS responders may treat this case as logically two
- interfaces (one with one or more IPv4 addresses, and the other with
- one or more IPv6 addresses), but responders that operate this way
- MUST NOT put the corresponding automatic NSEC records in replies they
- send (i.e., a negative IPv4 assertion in their IPv6 responses, and a
- negative IPv6 assertion in their IPv4 responses) because this would
- cause incorrect operation in responders on the network that work the
- former way.
-
-6.3. Responding to Multiquestion Queries
-
- Multicast DNS responders MUST correctly handle DNS query messages
- containing more than one question, by answering any or all of the
- questions to which they have answers. Unlike single-question
-
-
-
-Cheshire & Krochmal Standards Track [Page 19]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- queries, where responding without delay is allowed in appropriate
- cases, for query messages containing more than one question, all
- (non-defensive) answers SHOULD be randomly delayed in the range
- 20-120 ms, or 400-500 ms if the TC (truncated) bit is set. This is
- because when a query message contains more than one question, a
- Multicast DNS responder cannot generally be certain that other
- responders will not also be simultaneously generating answers to
- other questions in that query message. (Answers defending a name, in
- response to a probe for that name, are not subject to this delay rule
- and are still sent immediately.)
-
-6.4. Response Aggregation
-
- When possible, a responder SHOULD, for the sake of network
- efficiency, aggregate as many responses as possible into a single
- Multicast DNS response message. For example, when a responder has
- several responses it plans to send, each delayed by a different
- interval, then earlier responses SHOULD be delayed by up to an
- additional 500 ms if that will permit them to be aggregated with
- other responses scheduled to go out a little later.
-
-6.5. Wildcard Queries (qtype "ANY" and qclass "ANY")
-
- When responding to queries using qtype "ANY" (255) and/or qclass
- "ANY" (255), a Multicast DNS responder MUST respond with *ALL* of its
- records that match the query. This is subtly different from how
- qtype "ANY" and qclass "ANY" work in Unicast DNS.
-
- A common misconception is that a Unicast DNS query for qtype "ANY"
- will elicit a response containing all matching records. This is
- incorrect. If there are any records that match the query, the
- response is required only to contain at least one of them, not
- necessarily all of them.
-
- This somewhat surprising behavior is commonly seen with caching
- (i.e., "recursive") name servers. If a caching server receives a
- qtype "ANY" query for which it has at least one valid answer, it is
- allowed to return only those matching answers it happens to have
- already in its cache, and it is not required to reconsult the
- authoritative name server to check if there are any more records that
- also match the qtype "ANY" query.
-
- For example, one might imagine that a query for qtype "ANY" for name
- "host.example.com" would return both the IPv4 (A) and the IPv6 (AAAA)
- address records for that host. In reality, what happens is that it
- depends on the history of what queries have been previously received
- by intervening caching servers. If a caching server has no records
- for "host.example.com", then it will consult another server (usually
-
-
-
-Cheshire & Krochmal Standards Track [Page 20]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- the authoritative name server for the name in question), and, in that
- case, it will typically return all IPv4 and IPv6 address records.
- However, if some other host has recently done a query for qtype "A"
- for name "host.example.com", so that the caching server already has
- IPv4 address records for "host.example.com" in its cache but no IPv6
- address records, then it will return only the IPv4 address records it
- already has cached, and no IPv6 address records.
-
- Multicast DNS does not share this property that qtype "ANY" and
- qclass "ANY" queries return some undefined subset of the matching
- records. When responding to queries using qtype "ANY" (255) and/or
- qclass "ANY" (255), a Multicast DNS responder MUST respond with *ALL*
- of its records that match the query.
-
-6.6. Cooperating Multicast DNS Responders
-
- If a Multicast DNS responder ("A") observes some other Multicast DNS
- responder ("B") send a Multicast DNS response message containing a
- resource record with the same name, rrtype, and rrclass as one of A's
- resource records, but *different* rdata, then:
-
- o If A's resource record is intended to be a shared resource
- record, then this is no conflict, and no action is required.
-
- o If A's resource record is intended to be a member of a unique
- resource record set owned solely by that responder, then this is
- a conflict and MUST be handled as described in Section 9,
- "Conflict Resolution".
-
- If a Multicast DNS responder ("A") observes some other Multicast DNS
- responder ("B") send a Multicast DNS response message containing a
- resource record with the same name, rrtype, and rrclass as one of A's
- resource records, and *identical* rdata, then:
-
- o If the TTL of B's resource record given in the message is at
- least half the true TTL from A's point of view, then no action
- is required.
-
- o If the TTL of B's resource record given in the message is less
- than half the true TTL from A's point of view, then A MUST mark
- its record to be announced via multicast. Queriers receiving
- the record from B would use the TTL given by B and, hence, may
- delete the record sooner than A expects. By sending its own
- multicast response correcting the TTL, A ensures that the record
- will be retained for the desired time.
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 21]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- These rules allow multiple Multicast DNS responders to offer the same
- data on the network (perhaps for fault-tolerance reasons) without
- conflicting with each other.
-
-6.7. Legacy Unicast Responses
-
- If the source UDP port in a received Multicast DNS query is not port
- 5353, this indicates that the querier originating the query is a
- simple resolver such as described in Section 5.1, "One-Shot Multicast
- DNS Queries", which does not fully implement all of Multicast DNS.
- In this case, the Multicast DNS responder MUST send a UDP response
- directly back to the querier, via unicast, to the query packet's
- source IP address and port. This unicast response MUST be a
- conventional unicast response as would be generated by a conventional
- Unicast DNS server; for example, it MUST repeat the query ID and the
- question given in the query message. In addition, the cache-flush
- bit described in Section 10.2, "Announcements to Flush Outdated Cache
- Entries", MUST NOT be set in legacy unicast responses.
-
- The resource record TTL given in a legacy unicast response SHOULD NOT
- be greater than ten seconds, even if the true TTL of the Multicast
- DNS resource record is higher. This is because Multicast DNS
- responders that fully participate in the protocol use the cache
- coherency mechanisms described in Section 10, "Resource Record TTL
- Values and Cache Coherency", to update and invalidate stale data.
- Were unicast responses sent to legacy resolvers to use the same high
- TTLs, these legacy resolvers, which do not implement these cache
- coherency mechanisms, could retain stale cached resource record data
- long after it is no longer valid.
-
-7. Traffic Reduction
-
- A variety of techniques are used to reduce the amount of traffic on
- the network.
-
-7.1. Known-Answer Suppression
-
- When a Multicast DNS querier sends a query to which it already knows
- some answers, it populates the Answer Section of the DNS query
- message with those answers.
-
- Generally, this applies only to Shared records, not Unique records,
- since if a Multicast DNS querier already has at least one Unique
- record in its cache then it should not be expecting further different
- answers to this question, since the Unique record(s) it already has
- comprise the complete answer, so it has no reason to be sending the
- query at all. In contrast, having some Shared records in its cache
- does not necessarily imply that a Multicast DNS querier will not
-
-
-
-Cheshire & Krochmal Standards Track [Page 22]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- receive further answers to this query, and it is in this case that it
- is beneficial to use the Known-Answer list to suppress repeated
- sending of redundant answers that the querier already knows.
-
- A Multicast DNS responder MUST NOT answer a Multicast DNS query if
- the answer it would give is already included in the Answer Section
- with an RR TTL at least half the correct value. If the RR TTL of the
- answer as given in the Answer Section is less than half of the true
- RR TTL as known by the Multicast DNS responder, the responder MUST
- send an answer so as to update the querier's cache before the record
- becomes in danger of expiration.
-
- Because a Multicast DNS responder will respond if the remaining TTL
- given in the Known-Answer list is less than half the true TTL, it is
- superfluous for the querier to include such records in the Known-
- Answer list. Therefore, a Multicast DNS querier SHOULD NOT include
- records in the Known-Answer list whose remaining TTL is less than
- half of their original TTL. Doing so would simply consume space in
- the message without achieving the goal of suppressing responses and
- would, therefore, be a pointless waste of network capacity.
-
- A Multicast DNS querier MUST NOT cache resource records observed in
- the Known-Answer Section of other Multicast DNS queries. The Answer
- Section of Multicast DNS queries is not authoritative. By placing
- information in the Answer Section of a Multicast DNS query, the
- querier is stating that it *believes* the information to be true. It
- is not asserting that the information *is* true. Some of those
- records may have come from other hosts that are no longer on the
- network. Propagating that stale information to other Multicast DNS
- queriers on the network would not be helpful.
-
-7.2. Multipacket Known-Answer Suppression
-
- Sometimes a Multicast DNS querier will already have too many answers
- to fit in the Known-Answer Section of its query packets. In this
- case, it should issue a Multicast DNS query containing a question and
- as many Known-Answer records as will fit. It MUST then set the TC
- (Truncated) bit in the header before sending the query. It MUST
- immediately follow the packet with another query packet containing no
- questions and as many more Known-Answer records as will fit. If
- there are still too many records remaining to fit in the packet, it
- again sets the TC bit and continues until all the Known-Answer
- records have been sent.
-
- A Multicast DNS responder seeing a Multicast DNS query with the TC
- bit set defers its response for a time period randomly selected in
- the interval 400-500 ms. This gives the Multicast DNS querier time
- to send additional Known-Answer packets before the responder
-
-
-
-Cheshire & Krochmal Standards Track [Page 23]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- responds. If the responder sees any of its answers listed in the
- Known-Answer lists of subsequent packets from the querying host, it
- MUST delete that answer from the list of answers it is planning to
- give (provided that no other host on the network has also issued a
- query for that record and is waiting to receive an answer).
-
- If the responder receives additional Known-Answer packets with the TC
- bit set, it SHOULD extend the delay as necessary to ensure a pause of
- 400-500 ms after the last such packet before it sends its answer.
- This opens the potential risk that a continuous stream of Known-
- Answer packets could, theoretically, prevent a responder from
- answering indefinitely. In practice, answers are never actually
- delayed significantly, and should a situation arise where significant
- delays did happen, that would be a scenario where the network is so
- overloaded that it would be desirable to err on the side of caution.
- The consequence of delaying an answer may be that it takes a user
- longer than usual to discover all the services on the local network;
- in contrast, the consequence of incorrectly answering before all the
- Known-Answer packets have been received would be wasted capacity
- sending unnecessary answers on an already overloaded network. In
- this (rare) situation, sacrificing speed to preserve reliable network
- operation is the right trade-off.
-
-7.3. Duplicate Question Suppression
-
- If a host is planning to transmit (or retransmit) a query, and it
- sees another host on the network send a query containing the same
- "QM" question, and the Known-Answer Section of that query does not
- contain any records that this host would not also put in its own
- Known-Answer Section, then this host SHOULD treat its own query as
- having been sent. When multiple queriers on the network are querying
- for the same resource records, there is no need for them to all be
- repeatedly asking the same question.
-
-7.4. Duplicate Answer Suppression
-
- If a host is planning to send an answer, and it sees another host on
- the network send a response message containing the same answer
- record, and the TTL in that record is not less than the TTL this host
- would have given, then this host SHOULD treat its own answer as
- having been sent, and not also send an identical answer itself. When
- multiple responders on the network have the same data, there is no
- need for all of them to respond.
-
-
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 24]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- The opportunity for duplicate answer suppression occurs when a host
- has received a query, and is delaying its response for some pseudo-
- random interval up to 500 ms, as described elsewhere in this
- document, and then, before the host sends its response, it sees some
- other host on the network send a response message containing the same
- answer record.
-
- This feature is particularly useful when Multicast DNS Proxy Servers
- are in use, where there could be more than one proxy on the network
- giving Multicast DNS answers on behalf of some other host (e.g.,
- because that other host is currently asleep and is not itself
- responding to queries).
-
-8. Probing and Announcing on Startup
-
- Typically a Multicast DNS responder should have, at the very least,
- address records for all of its active interfaces. Creating and
- advertising an HINFO record on each interface as well can be useful
- to network administrators.
-
- Whenever a Multicast DNS responder starts up, wakes up from sleep,
- receives an indication of a network interface "Link Change" event, or
- has any other reason to believe that its network connectivity may
- have changed in some relevant way, it MUST perform the two startup
- steps below: Probing (Section 8.1) and Announcing (Section 8.3).
-
-8.1. Probing
-
- The first startup step is that, for all those resource records that a
- Multicast DNS responder desires to be unique on the local link, it
- MUST send a Multicast DNS query asking for those resource records, to
- see if any of them are already in use. The primary example of this
- is a host's address records, which map its unique host name to its
- unique IPv4 and/or IPv6 addresses. All probe queries SHOULD be done
- using the desired resource record name and class (usually class 1,
- "Internet"), and query type "ANY" (255), to elicit answers for all
- types of records with that name. This allows a single question to be
- used in place of several questions, which is more efficient on the
- network. It also allows a host to verify exclusive ownership of a
- name for all rrtypes, which is desirable in most cases. It would be
- confusing, for example, if one host owned the "A" record for
- "myhost.local.", but a different host owned the "AAAA" record for
- that name.
-
-
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 25]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- The ability to place more than one question in a Multicast DNS query
- is useful here, because it can allow a host to use a single message
- to probe for all of its resource records instead of needing a
- separate message for each. For example, a host can simultaneously
- probe for uniqueness of its "A" record and all its SRV records
- [RFC6763] in the same query message.
-
- When ready to send its Multicast DNS probe packet(s) the host should
- first wait for a short random delay time, uniformly distributed in
- the range 0-250 ms. This random delay is to guard against the case
- where several devices are powered on simultaneously, or several
- devices are connected to an Ethernet hub, which is then powered on,
- or some other external event happens that might cause a group of
- hosts to all send synchronized probes.
-
- 250 ms after the first query, the host should send a second; then,
- 250 ms after that, a third. If, by 250 ms after the third probe, no
- conflicting Multicast DNS responses have been received, the host may
- move to the next step, announcing. (Note that probing is the one
- exception from the normal rule that there should be at least one
- second between repetitions of the same question, and the interval
- between subsequent repetitions should at least double.)
-
- When sending probe queries, a host MUST NOT consult its cache for
- potential answers. Only conflicting Multicast DNS responses received
- "live" from the network are considered valid for the purposes of
- determining whether probing has succeeded or failed.
-
- In order to allow services to announce their presence without
- unreasonable delay, the time window for probing is intentionally set
- quite short. As a result of this, from the time the first probe
- packet is sent, another device on the network using that name has
- just 750 ms to respond to defend its name. On networks that are
- slow, or busy, or both, it is possible for round-trip latency to
- account for a few hundred milliseconds, and software delays in slow
- devices can add additional delay. Hence, it is important that when a
- device receives a probe query for a name that it is currently using,
- it SHOULD generate its response to defend that name immediately and
- send it as quickly as possible. The usual rules about random delays
- before responding, to avoid sudden bursts of simultaneous answers
- from different hosts, do not apply here since normally at most one
- host should ever respond to a given probe question. Even when a
- single DNS query message contains multiple probe questions, it would
- be unusual for that message to elicit a defensive response from more
- than one other host. Because of the mDNS multicast rate-limiting
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 26]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- rules, the probes SHOULD be sent as "QU" questions with the unicast-
- response bit set, to allow a defending host to respond immediately
- via unicast, instead of potentially having to wait before replying
- via multicast.
-
- During probing, from the time the first probe packet is sent until
- 250 ms after the third probe, if any conflicting Multicast DNS
- response is received, then the probing host MUST defer to the
- existing host, and SHOULD choose new names for some or all of its
- resource records as appropriate. Apparently conflicting Multicast
- DNS responses received *before* the first probe packet is sent MUST
- be silently ignored (see discussion of stale probe packets in Section
- 8.2, "Simultaneous Probe Tiebreaking", below). In the case of a host
- probing using query type "ANY" as recommended above, any answer
- containing a record with that name, of any type, MUST be considered a
- conflicting response and handled accordingly.
-
- If fifteen conflicts occur within any ten-second period, then the
- host MUST wait at least five seconds before each successive
- additional probe attempt. This is to help ensure that, in the event
- of software bugs or other unanticipated problems, errant hosts do not
- flood the network with a continuous stream of multicast traffic. For
- very simple devices, a valid way to comply with this requirement is
- to always wait five seconds after any failed probe attempt before
- trying again.
-
- If a responder knows by other means that its unique resource record
- set name, rrtype, and rrclass cannot already be in use by any other
- responder on the network, then it SHOULD skip the probing step for
- that resource record set. For example, when creating the reverse
- address mapping PTR records, the host can reasonably assume that no
- other host will be trying to create those same PTR records, since
- that would imply that the two hosts were trying to use the same IP
- address, and if that were the case, the two hosts would be suffering
- communication problems beyond the scope of what Multicast DNS is
- designed to solve. Similarly, if a responder is acting as a proxy,
- taking over from another Multicast DNS responder that has already
- verified the uniqueness of the record, then the proxy SHOULD NOT
- repeat the probing step for those records.
-
-8.2. Simultaneous Probe Tiebreaking
-
- The astute reader will observe that there is a race condition
- inherent in the previous description. If two hosts are probing for
- the same name simultaneously, neither will receive any response to
- the probe, and the hosts could incorrectly conclude that they may
- both proceed to use the name. To break this symmetry, each host
- populates the query message's Authority Section with the record or
-
-
-
-Cheshire & Krochmal Standards Track [Page 27]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- records with the rdata that it would be proposing to use, should its
- probing be successful. The Authority Section is being used here in a
- way analogous to the way it is used as the "Update Section" in a DNS
- Update message [RFC2136] [RFC3007].
-
- When a host is probing for a group of related records with the same
- name (e.g., the SRV and TXT record describing a DNS-SD service), only
- a single question need be placed in the Question Section, since query
- type "ANY" (255) is used, which will elicit answers for all records
- with that name. However, for tiebreaking to work correctly in all
- cases, the Authority Section must contain *all* the records and
- proposed rdata being probed for uniqueness.
-
- When a host that is probing for a record sees another host issue a
- query for the same record, it consults the Authority Section of that
- query. If it finds any resource record(s) there which answers the
- query, then it compares the data of that (those) resource record(s)
- with its own tentative data. We consider first the simple case of a
- host probing for a single record, receiving a simultaneous probe from
- another host also probing for a single record. The two records are
- compared and the lexicographically later data wins. This means that
- if the host finds that its own data is lexicographically later, it
- simply ignores the other host's probe. If the host finds that its
- own data is lexicographically earlier, then it defers to the winning
- host by waiting one second, and then begins probing for this record
- again. The logic for waiting one second and then trying again is to
- guard against stale probe packets on the network (possibly even stale
- probe packets sent moments ago by this host itself, before some
- configuration change, which may be echoed back after a short delay by
- some Ethernet switches and some 802.11 base stations). If the
- winning simultaneous probe was from a real other host on the network,
- then after one second it will have completed its probing, and will
- answer subsequent probes. If the apparently winning simultaneous
- probe was in fact just an old stale packet on the network (maybe from
- the host itself), then when it retries its probing in one second, its
- probes will go unanswered, and it will successfully claim the name.
-
- The determination of "lexicographically later" is performed by first
- comparing the record class (excluding the cache-flush bit described
- in Section 10.2), then the record type, then raw comparison of the
- binary content of the rdata without regard for meaning or structure.
- If the record classes differ, then the numerically greater class is
- considered "lexicographically later". Otherwise, if the record types
- differ, then the numerically greater type is considered
- "lexicographically later". If the rrtype and rrclass both match,
- then the rdata is compared.
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 28]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- In the case of resource records containing rdata that is subject to
- name compression [RFC1035], the names MUST be uncompressed before
- comparison. (The details of how a particular name is compressed is
- an artifact of how and where the record is written into the DNS
- message; it is not an intrinsic property of the resource record
- itself.)
-
- The bytes of the raw uncompressed rdata are compared in turn,
- interpreting the bytes as eight-bit UNSIGNED values, until a byte is
- found whose value is greater than that of its counterpart (in which
- case, the rdata whose byte has the greater value is deemed
- lexicographically later) or one of the resource records runs out of
- rdata (in which case, the resource record which still has remaining
- data first is deemed lexicographically later). The following is an
- example of a conflict:
-
- MyPrinter.local. A 169.254.99.200
- MyPrinter.local. A 169.254.200.50
-
- In this case, 169.254.200.50 is lexicographically later (the third
- byte, with value 200, is greater than its counterpart with value 99),
- so it is deemed the winner.
-
- Note that it is vital that the bytes are interpreted as UNSIGNED
- values in the range 0-255, or the wrong outcome may result. In the
- example above, if the byte with value 200 had been incorrectly
- interpreted as a signed eight-bit value, then it would be interpreted
- as value -56, and the wrong address record would be deemed the
- winner.
-
-8.2.1. Simultaneous Probe Tiebreaking for Multiple Records
-
- When a host is probing for a set of records with the same name, or a
- message is received containing multiple tiebreaker records answering
- a given probe question in the Question Section, the host's records
- and the tiebreaker records from the message are each sorted into
- order, and then compared pairwise, using the same comparison
- technique described above, until a difference is found.
-
- The records are sorted using the same lexicographical order as
- described above, that is, if the record classes differ, the record
- with the lower class number comes first. If the classes are the same
- but the rrtypes differ, the record with the lower rrtype number comes
- first. If the class and rrtype match, then the rdata is compared
- bytewise until a difference is found. For example, in the common
- case of advertising DNS-SD services with a TXT record and an SRV
- record, the TXT record comes first (the rrtype value for TXT is 16)
- and the SRV record comes second (the rrtype value for SRV is 33).
-
-
-
-Cheshire & Krochmal Standards Track [Page 29]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- When comparing the records, if the first records match perfectly,
- then the second records are compared, and so on. If either list of
- records runs out of records before any difference is found, then the
- list with records remaining is deemed to have won the tiebreak. If
- both lists run out of records at the same time without any difference
- being found, then this indicates that two devices are advertising
- identical sets of records, as is sometimes done for fault tolerance,
- and there is, in fact, no conflict.
-
-8.3. Announcing
-
- The second startup step is that the Multicast DNS responder MUST send
- an unsolicited Multicast DNS response containing, in the Answer
- Section, all of its newly registered resource records (both shared
- records, and unique records that have completed the probing step).
- If there are too many resource records to fit in a single packet,
- multiple packets should be used.
-
- In the case of shared records (e.g., the PTR records used by DNS-
- Based Service Discovery [RFC6763]), the records are simply placed as
- is into the Answer Section of the DNS response.
-
- In the case of records that have been verified to be unique in the
- previous step, they are placed into the Answer Section of the DNS
- response with the most significant bit of the rrclass set to one.
- The most significant bit of the rrclass for a record in the Answer
- Section of a response message is the Multicast DNS cache-flush bit
- and is discussed in more detail below in Section 10.2, "Announcements
- to Flush Outdated Cache Entries".
-
- The Multicast DNS responder MUST send at least two unsolicited
- responses, one second apart. To provide increased robustness against
- packet loss, a responder MAY send up to eight unsolicited responses,
- provided that the interval between unsolicited responses increases by
- at least a factor of two with every response sent.
-
- A Multicast DNS responder MUST NOT send announcements in the absence
- of information that its network connectivity may have changed in some
- relevant way. In particular, a Multicast DNS responder MUST NOT send
- regular periodic announcements as a matter of course.
-
- Whenever a Multicast DNS responder receives any Multicast DNS
- response (solicited or otherwise) containing a conflicting resource
- record, the conflict MUST be resolved as described in Section 9,
- "Conflict Resolution".
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 30]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
-8.4. Updating
-
- At any time, if the rdata of any of a host's Multicast DNS records
- changes, the host MUST repeat the Announcing step described above to
- update neighboring caches. For example, if any of a host's IP
- addresses change, it MUST re-announce those address records. The
- host does not need to repeat the Probing step because it has already
- established unique ownership of that name.
-
- In the case of shared records, a host MUST send a "goodbye"
- announcement with RR TTL zero (see Section 10.1, "Goodbye Packets")
- for the old rdata, to cause it to be deleted from peer caches, before
- announcing the new rdata. In the case of unique records, a host
- SHOULD omit the "goodbye" announcement, since the cache-flush bit on
- the newly announced records will cause old rdata to be flushed from
- peer caches anyway.
-
- A host may update the contents of any of its records at any time,
- though a host SHOULD NOT update records more frequently than ten
- times per minute. Frequent rapid updates impose a burden on the
- network. If a host has information to disseminate which changes more
- frequently than ten times per minute, then it may be more appropriate
- to design a protocol for that specific purpose.
-
-9. Conflict Resolution
-
- A conflict occurs when a Multicast DNS responder has a unique record
- for which it is currently authoritative, and it receives a Multicast
- DNS response message containing a record with the same name, rrtype
- and rrclass, but inconsistent rdata. What may be considered
- inconsistent is context sensitive, except that resource records with
- identical rdata are never considered inconsistent, even if they
- originate from different hosts. This is to permit use of proxies and
- other fault-tolerance mechanisms that may cause more than one
- responder to be capable of issuing identical answers on the network.
-
- A common example of a resource record type that is intended to be
- unique, not shared between hosts, is the address record that maps a
- host's name to its IP address. Should a host witness another host
- announce an address record with the same name but a different IP
- address, then that is considered inconsistent, and that address
- record is considered to be in conflict.
-
- Whenever a Multicast DNS responder receives any Multicast DNS
- response (solicited or otherwise) containing a conflicting resource
- record in any of the Resource Record Sections, the Multicast DNS
- responder MUST immediately reset its conflicted unique record to
- probing state, and go through the startup steps described above in
-
-
-
-Cheshire & Krochmal Standards Track [Page 31]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- Section 8, "Probing and Announcing on Startup". The protocol used in
- the Probing phase will determine a winner and a loser, and the loser
- MUST cease using the name, and reconfigure.
-
- It is very important that any host receiving a resource record that
- conflicts with one of its own MUST take action as described above.
- In the case of two hosts using the same host name, where one has been
- configured to require a unique host name and the other has not, the
- one that has not been configured to require a unique host name will
- not perceive any conflict, and will not take any action. By
- reverting to Probing state, the host that desires a unique host name
- will go through the necessary steps to ensure that a unique host name
- is obtained.
-
- The recommended course of action after probing and failing is as
- follows:
-
- 1. Programmatically change the resource record name in an attempt
- to find a new name that is unique. This could be done by
- adding some further identifying information (e.g., the model
- name of the hardware) if it is not already present in the name,
- or appending the digit "2" to the name, or incrementing a
- number at the end of the name if one is already present.
-
- 2. Probe again, and repeat as necessary until a unique name is
- found.
-
- 3. Once an available unique name has been determined, by probing
- without receiving any conflicting response, record this newly
- chosen name in persistent storage so that the device will use
- the same name the next time it is power-cycled.
-
- 4. Display a message to the user or operator informing them of the
- name change. For example:
-
- The name "Bob's Music" is in use by another music server on
- the network. Your music collection has been renamed to
- "Bob's Music (2)". If you want to change this name, use
- [describe appropriate menu item or preference dialog here].
-
- The details of how the user or operator is informed of the new
- name depends on context. A desktop computer with a screen
- might put up a dialog box. A headless server in the closet may
- write a message to a log file, or use whatever mechanism
- (email, SNMP trap, etc.) it uses to inform the administrator of
- error conditions. On the other hand, a headless server in the
- closet may not inform the user at all -- if the user cares,
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 32]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- they will notice the name has changed, and connect to the
- server in the usual way (e.g., via web browser) to configure a
- new name.
-
- 5. After one minute of probing, if the Multicast DNS responder has
- been unable to find any unused name, it should log an error
- message to inform the user or operator of this fact. This
- situation should never occur in normal operation. The only
- situations that would cause this to happen would be either a
- deliberate denial-of-service attack, or some kind of very
- obscure hardware or software bug that acts like a deliberate
- denial-of-service attack.
-
- These considerations apply to address records (i.e., host names) and
- to all resource records where uniqueness (or maintenance of some
- other defined constraint) is desired.
-
-10. Resource Record TTL Values and Cache Coherency
-
- As a general rule, the recommended TTL value for Multicast DNS
- resource records with a host name as the resource record's name
- (e.g., A, AAAA, HINFO) or a host name contained within the resource
- record's rdata (e.g., SRV, reverse mapping PTR record) SHOULD be 120
- seconds.
-
- The recommended TTL value for other Multicast DNS resource records is
- 75 minutes.
-
- A querier with an active outstanding query will issue a query message
- when one or more of the resource records in its cache are 80% of the
- way to expiry. If the TTL on those records is 75 minutes, this
- ongoing cache maintenance process yields a steady-state query rate of
- one query every 60 minutes.
-
- Any distributed cache needs a cache coherency protocol. If Multicast
- DNS resource records follow the recommendation and have a TTL of 75
- minutes, that means that stale data could persist in the system for a
- little over an hour. Making the default RR TTL significantly lower
- would reduce the lifetime of stale data, but would produce too much
- extra traffic on the network. Various techniques are available to
- minimize the impact of such stale data, outlined in the five
- subsections below.
-
-10.1. Goodbye Packets
-
- In the case where a host knows that certain resource record data is
- about to become invalid (for example, when the host is undergoing a
- clean shutdown), the host SHOULD send an unsolicited Multicast DNS
-
-
-
-Cheshire & Krochmal Standards Track [Page 33]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- response packet, giving the same resource record name, rrtype,
- rrclass, and rdata, but an RR TTL of zero. This has the effect of
- updating the TTL stored in neighboring hosts' cache entries to zero,
- causing that cache entry to be promptly deleted.
-
- Queriers receiving a Multicast DNS response with a TTL of zero SHOULD
- NOT immediately delete the record from the cache, but instead record
- a TTL of 1 and then delete the record one second later. In the case
- of multiple Multicast DNS responders on the network described in
- Section 6.6 above, if one of the responders shuts down and
- incorrectly sends goodbye packets for its records, it gives the other
- cooperating responders one second to send out their own response to
- "rescue" the records before they expire and are deleted.
-
-10.2. Announcements to Flush Outdated Cache Entries
-
- Whenever a host has a resource record with new data, or with what
- might potentially be new data (e.g., after rebooting, waking from
- sleep, connecting to a new network link, or changing IP address), the
- host needs to inform peers of that new data. In cases where the host
- has not been continuously connected and participating on the network
- link, it MUST first probe to re-verify uniqueness of its unique
- records, as described above in Section 8.1, "Probing".
-
- Having completed the Probing step, if necessary, the host MUST then
- send a series of unsolicited announcements to update cache entries in
- its neighbor hosts. In these unsolicited announcements, if the
- record is one that has been verified unique, the host sets the most
- significant bit of the rrclass field of the resource record. This
- bit, the cache-flush bit, tells neighboring hosts that this is not a
- shared record type. Instead of merging this new record additively
- into the cache in addition to any previous records with the same
- name, rrtype, and rrclass, all old records with that name, rrtype,
- and rrclass that were received more than one second ago are declared
- invalid, and marked to expire from the cache in one second.
-
- The semantics of the cache-flush bit are as follows: normally when a
- resource record appears in a Resource Record Section of the DNS
- response it means, "This is an assertion that this information is
- true". When a resource record appears in a Resource Record Section
- of the DNS response with the cache-flush bit set, it means, "This is
- an assertion that this information is the truth and the whole truth,
- and anything you may have heard more than a second ago regarding
- records of this name/rrtype/rrclass is no longer true".
-
- To accommodate the case where the set of records from one host
- constituting a single unique RRSet is too large to fit in a single
- packet, only cache records that are more than one second old are
-
-
-
-Cheshire & Krochmal Standards Track [Page 34]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- flushed. This allows the announcing host to generate a quick burst
- of packets back-to-back on the wire containing all the members of the
- RRSet. When receiving records with the cache-flush bit set, all
- records older than one second are marked to be deleted one second in
- the future. One second after the end of the little packet burst, any
- records not represented within that packet burst will then be expired
- from all peer caches.
-
- Any time a host sends a response packet containing some members of a
- unique RRSet, it MUST send the entire RRSet, preferably in a single
- packet, or if the entire RRSet will not fit in a single packet, in a
- quick burst of packets sent as close together as possible. The host
- MUST set the cache-flush bit on all members of the unique RRSet.
-
- Another reason for waiting one second before deleting stale records
- from the cache is to accommodate bridged networks. For example, a
- host's address record announcement on a wireless interface may be
- bridged onto a wired Ethernet and may cause that same host's Ethernet
- address records to be flushed from peer caches. The one-second delay
- gives the host the chance to see its own announcement arrive on the
- wired Ethernet, and immediately re-announce its Ethernet interface's
- address records so that both sets remain valid and live in peer
- caches.
-
- These rules, about when to set the cache-flush bit and about sending
- the entire rrset, apply regardless of *why* the response message is
- being generated. They apply to startup announcements as described in
- Section 8.3, "Announcing", and to responses generated as a result of
- receiving query messages.
-
- The cache-flush bit is only set in records in the Resource Record
- Sections of Multicast DNS responses sent to UDP port 5353.
-
- The cache-flush bit MUST NOT be set in any resource records in a
- response message sent in legacy unicast responses to UDP ports other
- than 5353.
-
- The cache-flush bit MUST NOT be set in any resource records in the
- Known-Answer list of any query message.
-
- The cache-flush bit MUST NOT ever be set in any shared resource
- record. To do so would cause all the other shared versions of this
- resource record with different rdata from different responders to be
- immediately deleted from all the caches on the network.
-
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 35]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- The cache-flush bit does *not* apply to questions listed in the
- Question Section of a Multicast DNS message. The top bit of the
- rrclass field in questions is used for an entirely different purpose
- (see Section 5.4, "Questions Requesting Unicast Responses").
-
- Note that the cache-flush bit is NOT part of the resource record
- class. The cache-flush bit is the most significant bit of the second
- 16-bit word of a resource record in a Resource Record Section of a
- Multicast DNS message (the field conventionally referred to as the
- rrclass field), and the actual resource record class is the least
- significant fifteen bits of this field. There is no Multicast DNS
- resource record class 0x8001. The value 0x8001 in the rrclass field
- of a resource record in a Multicast DNS response message indicates a
- resource record with class 1, with the cache-flush bit set. When
- receiving a resource record with the cache-flush bit set,
- implementations should take care to mask off that bit before storing
- the resource record in memory, or otherwise ensure that it is given
- the correct semantic interpretation.
-
- The reuse of the top bit of the rrclass field only applies to
- conventional resource record types that are subject to caching, not
- to pseudo-RRs like OPT [RFC2671], TSIG [RFC2845], TKEY [RFC2930],
- SIG0 [RFC2931], etc., that pertain only to a particular transport
- level message and not to any actual DNS data. Since pseudo-RRs
- should never go into the Multicast DNS cache, the concept of a cache-
- flush bit for these types is not applicable. In particular, the
- rrclass field of an OPT record encodes the sender's UDP payload size,
- and should be interpreted as a sixteen-bit length value in the range
- 0-65535, not a one-bit flag and a fifteen-bit length.
-
-10.3. Cache Flush on Topology change
-
- If the hardware on a given host is able to indicate physical changes
- of connectivity, then when the hardware indicates such a change, the
- host should take this information into account in its Multicast DNS
- cache management strategy. For example, a host may choose to
- immediately flush all cache records received on a particular
- interface when that cable is disconnected. Alternatively, a host may
- choose to adjust the remaining TTL on all those records to a few
- seconds so that if the cable is not reconnected quickly, those
- records will expire from the cache.
-
- Likewise, when a host reboots, wakes from sleep, or undergoes some
- other similar discontinuous state change, the cache management
- strategy should take that information into account.
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 36]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
-10.4. Cache Flush on Failure Indication
-
- Sometimes a cache record can be determined to be stale when a client
- attempts to use the rdata it contains, and the client finds that
- rdata to be incorrect.
-
- For example, the rdata in an address record can be determined to be
- incorrect if attempts to contact that host fail, either because (for
- an IPv4 address on a local subnet) ARP requests for that address go
- unanswered, because (for an IPv6 address with an on-link prefix) ND
- requests for that address go unanswered, or because (for an address
- on a remote network) a router returns an ICMP "Host Unreachable"
- error.
-
- The rdata in an SRV record can be determined to be incorrect if
- attempts to communicate with the indicated service at the host and
- port number indicated are not successful.
-
- The rdata in a DNS-SD PTR record can be determined to be incorrect if
- attempts to look up the SRV record it references are not successful.
-
- The software implementing the Multicast DNS resource record cache
- should provide a mechanism so that clients detecting stale rdata can
- inform the cache.
-
- When the cache receives this hint that it should reconfirm some
- record, it MUST issue two or more queries for the resource record in
- dispute. If no response is received within ten seconds, then, even
- though its TTL may indicate that it is not yet due to expire, that
- record SHOULD be promptly flushed from the cache.
-
- The end result of this is that if a printer suffers a sudden power
- failure or other abrupt disconnection from the network, its name may
- continue to appear in DNS-SD browser lists displayed on users'
- screens. Eventually, that entry will expire from the cache
- naturally, but if a user tries to access the printer before that
- happens, the failure to successfully contact the printer will trigger
- the more hasty demise of its cache entries. This is a sensible
- trade-off between good user experience and good network efficiency.
- If we were to insist that printers should disappear from the printer
- list within 30 seconds of becoming unavailable, for all failure
- modes, the only way to achieve this would be for the client to poll
- the printer at least every 30 seconds, or for the printer to announce
- its presence at least every 30 seconds, both of which would be an
- unreasonable burden on most networks.
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 37]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
-10.5. Passive Observation Of Failures (POOF)
-
- A host observes the multicast queries issued by the other hosts on
- the network. One of the major benefits of also sending responses
- using multicast is that it allows all hosts to see the responses (or
- lack thereof) to those queries.
-
- If a host sees queries, for which a record in its cache would be
- expected to be given as an answer in a multicast response, but no
- such answer is seen, then the host may take this as an indication
- that the record may no longer be valid.
-
- After seeing two or more of these queries, and seeing no multicast
- response containing the expected answer within ten seconds, then even
- though its TTL may indicate that it is not yet due to expire, that
- record SHOULD be flushed from the cache. The host SHOULD NOT perform
- its own queries to reconfirm that the record is truly gone. If every
- host on a large network were to do this, it would cause a lot of
- unnecessary multicast traffic. If host A sends multicast queries
- that remain unanswered, then there is no reason to suppose that host
- B or any other host is likely to be any more successful.
-
- The previous section, "Cache Flush on Failure Indication", describes
- a situation where a user trying to print discovers that the printer
- is no longer available. By implementing the passive observation
- described here, when one user fails to contact the printer, all hosts
- on the network observe that failure and update their caches
- accordingly.
-
-11. Source Address Check
-
- All Multicast DNS responses (including responses sent via unicast)
- SHOULD be sent with IP TTL set to 255. This is recommended to
- provide backwards-compatibility with older Multicast DNS queriers
- (implementing a draft version of this document, posted in February
- 2004) that check the IP TTL on reception to determine whether the
- packet originated on the local link. These older queriers discard
- all packets with TTLs other than 255.
-
- A host sending Multicast DNS queries to a link-local destination
- address (including the 224.0.0.251 and FF02::FB link-local multicast
- addresses) MUST only accept responses to that query that originate
- from the local link, and silently discard any other response packets.
- Without this check, it could be possible for remote rogue hosts to
- send spoof answer packets (perhaps unicast to the victim host), which
- the receiving machine could misinterpret as having originated on the
- local link.
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 38]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- The test for whether a response originated on the local link is done
- in two ways:
-
- * All responses received with a destination address in the IP
- header that is the mDNS IPv4 link-local multicast address
- 224.0.0.251 or the mDNS IPv6 link-local multicast address
- FF02::FB are necessarily deemed to have originated on the local
- link, regardless of source IP address. This is essential to
- allow devices to work correctly and reliably in unusual
- configurations, such as multiple logical IP subnets overlayed on
- a single link, or in cases of severe misconfiguration, where
- devices are physically connected to the same link, but are
- currently misconfigured with completely unrelated IP addresses
- and subnet masks.
-
- * For responses received with a unicast destination address in the
- IP header, the source IP address in the packet is checked to see
- if it is an address on a local subnet. An IPv4 source address
- is determined to be on a local subnet if, for (one of) the
- address(es) configured on the interface receiving the packet, (I
- & M) == (P & M), where I and M are the interface address and
- subnet mask respectively, P is the source IP address from the
- packet, '&' represents the bitwise logical 'and' operation, and
- '==' represents a bitwise equality test. An IPv6 source address
- is determined to be on the local link if, for any of the on-link
- IPv6 prefixes on the interface receiving the packet (learned via
- IPv6 router advertisements or otherwise configured on the host),
- the first 'n' bits of the IPv6 source address match the first
- 'n' bits of the prefix address, where 'n' is the length of the
- prefix being considered.
-
- Since queriers will ignore responses apparently originating outside
- the local subnet, a responder SHOULD avoid generating responses that
- it can reasonably predict will be ignored. This applies particularly
- in the case of overlayed subnets. If a responder receives a query
- addressed to the mDNS IPv4 link-local multicast address 224.0.0.251,
- from a source address not apparently on the same subnet as the
- responder (or, in the case of IPv6, from a source IPv6 address for
- which the responder does not have any address with the same prefix on
- that interface), then even if the query indicates that a unicast
- response is preferred (see Section 5.4, "Questions Requesting Unicast
- Responses"), the responder SHOULD elect to respond by multicast
- anyway, since it can reasonably predict that a unicast response with
- an apparently non-local source address will probably be ignored.
-
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 39]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
-12. Special Characteristics of Multicast DNS Domains
-
- Unlike conventional DNS names, names that end in ".local." have only
- local significance. The same is true of names within the IPv4 link-
- local reverse mapping domain "254.169.in-addr.arpa." and the IPv6
- link-local reverse mapping domains "8.e.f.ip6.arpa.",
- "9.e.f.ip6.arpa.", "a.e.f.ip6.arpa.", and "b.e.f.ip6.arpa.".
-
- These names function primarily as protocol identifiers, rather than
- as user-visible identifiers. Even though they may occasionally be
- visible to end users, that is not their primary purpose. As such,
- these names should be treated as opaque identifiers. In particular,
- the string "local" should not be translated or localized into
- different languages, much as the name "localhost" is not translated
- or localized into different languages.
-
- Conventional Unicast DNS seeks to provide a single unified namespace,
- where a given DNS query yields the same answer no matter where on the
- planet it is performed or to which recursive DNS server the query is
- sent. In contrast, each IP link has its own private ".local.",
- "254.169.in-addr.arpa." and IPv6 link-local reverse mapping
- namespaces, and the answer to any query for a name within those
- domains depends on where that query is asked. (This characteristic
- is not unique to Multicast DNS. Although the original concept of DNS
- was a single global namespace, in recent years, split views,
- firewalls, intranets, DNS geolocation, and the like have increasingly
- meant that the answer to a given DNS query has become dependent on
- the location of the querier.)
-
- The IPv4 name server address for a Multicast DNS domain is
- 224.0.0.251. The IPv6 name server address for a Multicast DNS domain
- is FF02::FB. These are multicast addresses; therefore, they identify
- not a single host but a collection of hosts, working in cooperation
- to maintain some reasonable facsimile of a competently managed DNS
- zone. Conceptually, a Multicast DNS domain is a single DNS zone;
- however, its server is implemented as a distributed process running
- on a cluster of loosely cooperating CPUs rather than as a single
- process running on a single CPU.
-
- Multicast DNS domains are not delegated from their parent domain via
- use of NS (Name Server) records, and there is also no concept of
- delegation of subdomains within a Multicast DNS domain. Just because
- a particular host on the network may answer queries for a particular
- record type with the name "example.local." does not imply anything
- about whether that host will answer for the name
- "child.example.local.", or indeed for other record types with the
- name "example.local.".
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 40]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- There are no NS records anywhere in Multicast DNS domains. Instead,
- the Multicast DNS domains are reserved by IANA, and there is
- effectively an implicit delegation of all Multicast DNS domains to
- the 224.0.0.251:5353 and [FF02::FB]:5353 multicast groups, by virtue
- of client software implementing the protocol rules specified in this
- document.
-
- Multicast DNS zones have no SOA (Start of Authority) record. A
- conventional DNS zone's SOA record contains information such as the
- email address of the zone administrator and the monotonically
- increasing serial number of the last zone modification. There is no
- single human administrator for any given Multicast DNS zone, so there
- is no email address. Because the hosts managing any given Multicast
- DNS zone are only loosely coordinated, there is no readily available
- monotonically increasing serial number to determine whether or not
- the zone contents have changed. A host holding part of the shared
- zone could crash or be disconnected from the network at any time
- without informing the other hosts. There is no reliable way to
- provide a zone serial number that would, whenever such a crash or
- disconnection occurred, immediately change to indicate that the
- contents of the shared zone had changed.
-
- Zone transfers are not possible for any Multicast DNS zone.
-
-13. Enabling and Disabling Multicast DNS
-
- The option to fail-over to Multicast DNS for names not ending in
- ".local." SHOULD be a user-configured option, and SHOULD be disabled
- by default because of the possible security issues related to
- unintended local resolution of apparently global names. Enabling
- Multicast DNS for names not ending in ".local." may be appropriate on
- a secure isolated network, or on some future network were machines
- exclusively use DNSSEC for all DNS queries, and have Multicast DNS
- responders capable of generating the appropriate cryptographic DNSSEC
- signatures, thereby guarding against spoofing.
-
- The option to look up unqualified (relative) names by appending
- ".local." (or not) is controlled by whether ".local." appears (or
- not) in the client's DNS search list.
-
- No special control is needed for enabling and disabling Multicast DNS
- for names explicitly ending with ".local." as entered by the user.
- The user doesn't need a way to disable Multicast DNS for names ending
- with ".local.", because if the user doesn't want to use Multicast
- DNS, they can achieve this by simply not using those names. If a
- user *does* enter a name ending in ".local.", then we can safely
- assume the user's intention was probably that it should work. Having
- user configuration options that can be (intentionally or
-
-
-
-Cheshire & Krochmal Standards Track [Page 41]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- unintentionally) set so that local names don't work is just one more
- way of frustrating the user's ability to perform the tasks they want,
- perpetuating the view that, "IP networking is too complicated to
- configure and too hard to use".
-
-14. Considerations for Multiple Interfaces
-
- A host SHOULD defend its dot-local host name on all active interfaces
- on which it is answering Multicast DNS queries.
-
- In the event of a name conflict on *any* interface, a host should
- configure a new host name, if it wishes to maintain uniqueness of its
- host name.
-
- A host may choose to use the same name (or set of names) for all of
- its address records on all interfaces, or it may choose to manage its
- Multicast DNS interfaces independently, potentially answering to a
- different name (or set of names) on different interfaces.
-
- Except in the case of proxying and other similar specialized uses,
- addresses in IPv4 or IPv6 address records in Multicast DNS responses
- MUST be valid for use on the interface on which the response is being
- sent.
-
- Just as the same link-local IP address may validly be in use
- simultaneously on different links by different hosts, the same link-
- local host name may validly be in use simultaneously on different
- links, and this is not an error. A multihomed host with connections
- to two different links may be able to communicate with two different
- hosts that are validly using the same name. While this kind of name
- duplication should be rare, it means that a host that wants to fully
- support this case needs network programming APIs that allow
- applications to specify on what interface to perform a link-local
- Multicast DNS query, and to discover on what interface a Multicast
- DNS response was received.
-
- There is one other special precaution that multihomed hosts need to
- take. It's common with today's laptop computers to have an Ethernet
- connection and an 802.11 [IEEE.802.11] wireless connection active at
- the same time. What the software on the laptop computer can't easily
- tell is whether the wireless connection is in fact bridged onto the
- same network segment as its Ethernet connection. If the two networks
- are bridged together, then packets the host sends on one interface
- will arrive on the other interface a few milliseconds later, and care
- must be taken to ensure that this bridging does not cause problems:
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 42]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- When the host announces its host name (i.e., its address records) on
- its wireless interface, those announcement records are sent with the
- cache-flush bit set, so when they arrive on the Ethernet segment,
- they will cause all the peers on the Ethernet to flush the host's
- Ethernet address records from their caches. The Multicast DNS
- protocol has a safeguard to protect against this situation: when
- records are received with the cache-flush bit set, other records are
- not deleted from peer caches immediately, but are marked for deletion
- in one second. When the host sees its own wireless address records
- arrive on its Ethernet interface, with the cache-flush bit set, this
- one-second grace period gives the host time to respond and re-
- announce its Ethernet address records, to reinstate those records in
- peer caches before they are deleted.
-
- As described, this solves one problem, but creates another, because
- when those Ethernet announcement records arrive back on the wireless
- interface, the host would again respond defensively to reinstate its
- wireless records, and this process would continue forever,
- continuously flooding the network with traffic. The Multicast DNS
- protocol has a second safeguard, to solve this problem: the cache-
- flush bit does not apply to records received very recently, within
- the last second. This means that when the host sees its own Ethernet
- address records arrive on its wireless interface, with the cache-
- flush bit set, it knows there's no need to re-announce its wireless
- address records again because it already sent them less than a second
- ago, and this makes them immune from deletion from peer caches. (See
- Section 10.2.)
-
-15. Considerations for Multiple Responders on the Same Machine
-
- It is possible to have more than one Multicast DNS responder and/or
- querier implementation coexist on the same machine, but there are
- some known issues.
-
-15.1. Receiving Unicast Responses
-
- In most operating systems, incoming *multicast* packets can be
- delivered to *all* open sockets bound to the right port number,
- provided that the clients take the appropriate steps to allow this.
- For this reason, all Multicast DNS implementations SHOULD use the
- SO_REUSEPORT and/or SO_REUSEADDR options (or equivalent as
- appropriate for the operating system in question) so they will all be
- able to bind to UDP port 5353 and receive incoming multicast packets
- addressed to that port. However, unlike multicast packets, incoming
- unicast UDP packets are typically delivered only to the first socket
- to bind to that port. This means that "QU" responses and other
- packets sent via unicast will be received only by the first Multicast
- DNS responder and/or querier on a system. This limitation can be
-
-
-
-Cheshire & Krochmal Standards Track [Page 43]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- partially mitigated if Multicast DNS implementations detect when they
- are not the first to bind to port 5353, and in that case they do not
- request "QU" responses. One way to detect if there is another
- Multicast DNS implementation already running is to attempt binding to
- port 5353 without using SO_REUSEPORT and/or SO_REUSEADDR, and if that
- fails it indicates that some other socket is already bound to this
- port.
-
-15.2. Multipacket Known-Answer lists
-
- When a Multicast DNS querier issues a query with too many Known
- Answers to fit into a single packet, it divides the Known-Answer list
- into two or more packets. Multicast DNS responders associate the
- initial truncated query with its continuation packets by examining
- the source IP address in each packet. Since two independent
- Multicast DNS queriers running on the same machine will be sending
- packets with the same source IP address, from an outside perspective
- they appear to be a single entity. If both queriers happened to send
- the same multipacket query at the same time, with different Known-
- Answer lists, then they could each end up suppressing answers that
- the other needs.
-
-15.3. Efficiency
-
- If different clients on a machine were each to have their own
- independent Multicast DNS implementation, they would lose certain
- efficiency benefits. Apart from the unnecessary code duplication,
- memory usage, and CPU load, the clients wouldn't get the benefit of a
- shared system-wide cache, and they would not be able to aggregate
- separate queries into single packets to reduce network traffic.
-
-15.4. Recommendation
-
- Because of these issues, this document encourages implementers to
- design systems with a single Multicast DNS implementation that
- provides Multicast DNS services shared by all clients on that
- machine, much as most operating systems today have a single TCP
- implementation, which is shared between all clients on that machine.
- Due to engineering constraints, there may be situations where
- embedding a "user-level" Multicast DNS implementation in the client
- application software is the most expedient solution, and while this
- will usually work in practice, implementers should be aware of the
- issues outlined in this section.
-
-
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 44]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
-16. Multicast DNS Character Set
-
- Historically, Unicast DNS has been used with a very restricted set of
- characters. Indeed, conventional DNS is usually limited to just
- twenty-six letters, ten digits and the hyphen character, not even
- allowing spaces or other punctuation. Attempts to remedy this for
- Unicast DNS have been badly constrained by the perceived need to
- accommodate old buggy legacy DNS implementations. In reality, the
- DNS specification itself actually imposes no limits on what
- characters may be used in names, and good DNS implementations handle
- any arbitrary eight-bit data without trouble. "Clarifications to the
- DNS Specification" [RFC2181] directly discusses the subject of
- allowable character set in Section 11 ("Name syntax"), and explicitly
- states that DNS names may contain arbitrary eight-bit data. However,
- the old rules for ARPANET host names back in the 1980s required host
- names to be just letters, digits, and hyphens [RFC1034], and since
- the predominant use of DNS is to store host address records, many
- have assumed that the DNS protocol itself suffers from the same
- limitation. It might be accurate to say that there could be
- hypothetical bad implementations that do not handle eight-bit data
- correctly, but it would not be accurate to say that the protocol
- doesn't allow names containing eight-bit data.
-
- Multicast DNS is a new protocol and doesn't (yet) have old buggy
- legacy implementations to constrain the design choices. Accordingly,
- it adopts the simple obvious elegant solution: all names in Multicast
- DNS MUST be encoded as precomposed UTF-8 [RFC3629] "Net-Unicode"
- [RFC5198] text.
-
- Some users of 16-bit Unicode have taken to stuffing a "zero-width
- nonbreaking space" character (U+FEFF) at the start of each UTF-16
- file, as a hint to identify whether the data is big-endian or little-
- endian, and calling it a "Byte Order Mark" (BOM). Since there is
- only one possible byte order for UTF-8 data, a BOM is neither
- necessary nor permitted. Multicast DNS names MUST NOT contain a
- "Byte Order Mark". Any occurrence of the Unicode character U+FEFF at
- the start or anywhere else in a Multicast DNS name MUST be
- interpreted as being an actual intended part of the name,
- representing (just as for any other legal unicode value) an actual
- literal instance of that character (in this case a zero-width non-
- breaking space character).
-
- For names that are restricted to US-ASCII [RFC0020] letters, digits,
- and hyphens, the UTF-8 encoding is identical to the US-ASCII
- encoding, so this is entirely compatible with existing host names.
- For characters outside the US-ASCII range, UTF-8 encoding is used.
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 45]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- Multicast DNS implementations MUST NOT use any other encodings apart
- from precomposed UTF-8 (US-ASCII being considered a compatible subset
- of UTF-8). The reasons for selecting UTF-8 instead of Punycode
- [RFC3492] are discussed further in Appendix F.
-
- The simple rules for case-insensitivity in Unicast DNS [RFC1034]
- [RFC1035] also apply in Multicast DNS; that is to say, in name
- comparisons, the lowercase letters "a" to "z" (0x61 to 0x7A) match
- their uppercase equivalents "A" to "Z" (0x41 to 0x5A). Hence, if a
- querier issues a query for an address record with the name
- "myprinter.local.", then a responder having an address record with
- the name "MyPrinter.local." should issue a response. No other
- automatic equivalences should be assumed. In particular, all UTF-8
- multibyte characters (codes 0x80 and higher) are compared by simple
- binary comparison of the raw byte values. Accented characters are
- *not* defined to be automatically equivalent to their unaccented
- counterparts. Where automatic equivalences are desired, this may be
- achieved through the use of programmatically generated CNAME records.
- For example, if a responder has an address record for an accented
- name Y, and a querier issues a query for a name X, where X is the
- same as Y with all the accents removed, then the responder may issue
- a response containing two resource records: a CNAME record "X CNAME
- Y", asserting that the requested name X (unaccented) is an alias for
- the true (accented) name Y, followed by the address record for Y.
-
-17. Multicast DNS Message Size
-
- The 1987 DNS specification [RFC1035] restricts DNS messages carried
- by UDP to no more than 512 bytes (not counting the IP or UDP
- headers). For UDP packets carried over the wide-area Internet in
- 1987, this was appropriate. For link-local multicast packets on
- today's networks, there is no reason to retain this restriction.
- Given that the packets are by definition link-local, there are no
- Path MTU issues to consider.
-
- Multicast DNS messages carried by UDP may be up to the IP MTU of the
- physical interface, less the space required for the IP header (20
- bytes for IPv4; 40 bytes for IPv6) and the UDP header (8 bytes).
-
- In the case of a single Multicast DNS resource record that is too
- large to fit in a single MTU-sized multicast response packet, a
- Multicast DNS responder SHOULD send the resource record alone, in a
- single IP datagram, using multiple IP fragments. Resource records
- this large SHOULD be avoided, except in the very rare cases where
- they really are the appropriate solution to the problem at hand.
- Implementers should be aware that many simple devices do not
- reassemble fragmented IP datagrams, so large resource records SHOULD
- NOT be used except in specialized cases where the implementer knows
-
-
-
-Cheshire & Krochmal Standards Track [Page 46]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- that all receivers implement reassembly, or where the large resource
- record contains optional data which is not essential for correct
- operation of the client.
-
- A Multicast DNS packet larger than the interface MTU, which is sent
- using fragments, MUST NOT contain more than one resource record.
-
- Even when fragmentation is used, a Multicast DNS packet, including IP
- and UDP headers, MUST NOT exceed 9000 bytes.
-
- Note that 9000 bytes is also the maximum payload size of an Ethernet
- "Jumbo" packet [Jumbo]. However, in practice Ethernet "Jumbo"
- packets are not widely used, so it is advantageous to keep packets
- under 1500 bytes whenever possible. Even on hosts that normally
- handle Ethernet "Jumbo" packets and IP fragment reassembly, it is
- becoming more common for these hosts to implement power-saving modes
- where the main CPU goes to sleep and hands off packet reception tasks
- to a more limited processor in the network interface hardware, which
- may not support Ethernet "Jumbo" packets or IP fragment reassembly.
-
-18. Multicast DNS Message Format
-
- This section describes specific rules pertaining to the allowable
- values for the header fields of a Multicast DNS message, and other
- message format considerations.
-
-18.1. ID (Query Identifier)
-
- Multicast DNS implementations SHOULD listen for unsolicited responses
- issued by hosts booting up (or waking up from sleep or otherwise
- joining the network). Since these unsolicited responses may contain
- a useful answer to a question for which the querier is currently
- awaiting an answer, Multicast DNS implementations SHOULD examine all
- received Multicast DNS response messages for useful answers, without
- regard to the contents of the ID field or the Question Section. In
- Multicast DNS, knowing which particular query message (if any) is
- responsible for eliciting a particular response message is less
- interesting than knowing whether the response message contains useful
- information.
-
- Multicast DNS implementations MAY cache data from any or all
- Multicast DNS response messages they receive, for possible future
- use, provided of course that normal TTL aging is performed on these
- cached resource records.
-
- In multicast query messages, the Query Identifier SHOULD be set to
- zero on transmission.
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 47]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- In multicast responses, including unsolicited multicast responses,
- the Query Identifier MUST be set to zero on transmission, and MUST be
- ignored on reception.
-
- In legacy unicast response messages generated specifically in
- response to a particular (unicast or multicast) query, the Query
- Identifier MUST match the ID from the query message.
-
-18.2. QR (Query/Response) Bit
-
- In query messages the QR bit MUST be zero.
- In response messages the QR bit MUST be one.
-
-18.3. OPCODE
-
- In both multicast query and multicast response messages, the OPCODE
- MUST be zero on transmission (only standard queries are currently
- supported over multicast). Multicast DNS messages received with an
- OPCODE other than zero MUST be silently ignored.
-
-18.4. AA (Authoritative Answer) Bit
-
- In query messages, the Authoritative Answer bit MUST be zero on
- transmission, and MUST be ignored on reception.
-
- In response messages for Multicast domains, the Authoritative Answer
- bit MUST be set to one (not setting this bit would imply there's some
- other place where "better" information may be found) and MUST be
- ignored on reception.
-
-18.5. TC (Truncated) Bit
-
- In query messages, if the TC bit is set, it means that additional
- Known-Answer records may be following shortly. A responder SHOULD
- record this fact, and wait for those additional Known-Answer records,
- before deciding whether to respond. If the TC bit is clear, it means
- that the querying host has no additional Known Answers.
-
- In multicast response messages, the TC bit MUST be zero on
- transmission, and MUST be ignored on reception.
-
- In legacy unicast response messages, the TC bit has the same meaning
- as in conventional Unicast DNS: it means that the response was too
- large to fit in a single packet, so the querier SHOULD reissue its
- query using TCP in order to receive the larger response.
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 48]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
-18.6. RD (Recursion Desired) Bit
-
- In both multicast query and multicast response messages, the
- Recursion Desired bit SHOULD be zero on transmission, and MUST be
- ignored on reception.
-
-18.7. RA (Recursion Available) Bit
-
- In both multicast query and multicast response messages, the
- Recursion Available bit MUST be zero on transmission, and MUST be
- ignored on reception.
-
-18.8. Z (Zero) Bit
-
- In both query and response messages, the Zero bit MUST be zero on
- transmission, and MUST be ignored on reception.
-
-18.9. AD (Authentic Data) Bit
-
- In both multicast query and multicast response messages, the
- Authentic Data bit [RFC2535] MUST be zero on transmission, and MUST
- be ignored on reception.
-
-18.10. CD (Checking Disabled) Bit
-
- In both multicast query and multicast response messages, the Checking
- Disabled bit [RFC2535] MUST be zero on transmission, and MUST be
- ignored on reception.
-
-18.11. RCODE (Response Code)
-
- In both multicast query and multicast response messages, the Response
- Code MUST be zero on transmission. Multicast DNS messages received
- with non-zero Response Codes MUST be silently ignored.
-
-18.12. Repurposing of Top Bit of qclass in Question Section
-
- In the Question Section of a Multicast DNS query, the top bit of the
- qclass field is used to indicate that unicast responses are preferred
- for this particular question. (See Section 5.4.)
-
-18.13. Repurposing of Top Bit of rrclass in Resource Record Sections
-
- In the Resource Record Sections of a Multicast DNS response, the top
- bit of the rrclass field is used to indicate that the record is a
- member of a unique RRSet, and the entire RRSet has been sent together
- (in the same packet, or in consecutive packets if there are too many
- records to fit in a single packet). (See Section 10.2.)
-
-
-
-Cheshire & Krochmal Standards Track [Page 49]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
-18.14. Name Compression
-
- When generating Multicast DNS messages, implementations SHOULD use
- name compression wherever possible to compress the names of resource
- records, by replacing some or all of the resource record name with a
- compact two-byte reference to an appearance of that data somewhere
- earlier in the message [RFC1035].
-
- This applies not only to Multicast DNS responses, but also to
- queries. When a query contains more than one question, successive
- questions in the same message often contain similar names, and
- consequently name compression SHOULD be used, to save bytes. In
- addition, queries may also contain Known Answers in the Answer
- Section, or probe tiebreaking data in the Authority Section, and
- these names SHOULD similarly be compressed for network efficiency.
-
- In addition to compressing the *names* of resource records, names
- that appear within the *rdata* of the following rrtypes SHOULD also
- be compressed in all Multicast DNS messages:
-
- NS, CNAME, PTR, DNAME, SOA, MX, AFSDB, RT, KX, RP, PX, SRV, NSEC
-
- Until future IETF Standards Action [RFC5226] specifying that names in
- the rdata of other types should be compressed, names that appear
- within the rdata of any type not listed above MUST NOT be compressed.
-
- Implementations receiving Multicast DNS messages MUST correctly
- decode compressed names appearing in the Question Section, and
- compressed names of resource records appearing in other sections.
-
- In addition, implementations MUST correctly decode compressed names
- appearing within the *rdata* of the rrtypes listed above. Where
- possible, implementations SHOULD also correctly decode compressed
- names appearing within the *rdata* of other rrtypes known to the
- implementers at the time of implementation, because such forward-
- thinking planning helps facilitate the deployment of future
- implementations that may have reason to compress those rrtypes. It
- is possible that no future IETF Standards Action [RFC5226] will be
- created that mandates or permits the compression of rdata in new
- types, but having implementations designed such that they are capable
- of decompressing all known types helps keep future options open.
-
- One specific difference between Unicast DNS and Multicast DNS is that
- Unicast DNS does not allow name compression for the target host in an
- SRV record, because Unicast DNS implementations before the first SRV
- specification in 1996 [RFC2052] may not decode these compressed
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 50]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- records properly. Since all Multicast DNS implementations were
- created after 1996, all Multicast DNS implementations are REQUIRED to
- decode compressed SRV records correctly.
-
- In legacy unicast responses generated to answer legacy queries, name
- compression MUST NOT be performed on SRV records.
-
-19. Summary of Differences between Multicast DNS and Unicast DNS
-
- Multicast DNS shares, as much as possible, the familiar APIs, naming
- syntax, resource record types, etc., of Unicast DNS. There are, of
- course, necessary differences by virtue of it using multicast, and by
- virtue of it operating in a community of cooperating peers, rather
- than a precisely defined hierarchy controlled by a strict chain of
- formal delegations from the root. These differences are summarized
- below:
-
- Multicast DNS...
- * uses multicast
- * uses UDP port 5353 instead of port 53
- * operates in well-defined parts of the DNS namespace
- * has no SOA (Start of Authority) records
- * uses UTF-8, and only UTF-8, to encode resource record names
- * allows names up to 255 bytes plus a terminating zero byte
- * allows name compression in rdata for SRV and other record types
- * allows larger UDP packets
- * allows more than one question in a query message
- * defines consistent results for qtype "ANY" and qclass "ANY" queries
- * uses the Answer Section of a query to list Known Answers
- * uses the TC bit in a query to indicate additional Known Answers
- * uses the Authority Section of a query for probe tiebreaking
- * ignores the Query ID field (except for generating legacy responses)
- * doesn't require the question to be repeated in the response message
- * uses unsolicited responses to announce new records
- * uses NSEC records to signal nonexistence of records
- * defines a unicast-response bit in the rrclass of query questions
- * defines a cache-flush bit in the rrclass of response records
- * uses DNS RR TTL 0 to indicate that a record has been deleted
- * recommends AAAA records in the additional section when responding
- to rrtype "A" queries, and vice versa
- * monitors queries to perform Duplicate Question Suppression
- * monitors responses to perform Duplicate Answer Suppression...
- * ... and Ongoing Conflict Detection
- * ... and Opportunistic Caching
-
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 51]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
-20. IPv6 Considerations
-
- An IPv4-only host and an IPv6-only host behave as "ships that pass in
- the night". Even if they are on the same Ethernet, neither is aware
- of the other's traffic. For this reason, each physical link may have
- *two* unrelated ".local." zones, one for IPv4 and one for IPv6.
- Since for practical purposes, a group of IPv4-only hosts and a group
- of IPv6-only hosts on the same Ethernet act as if they were on two
- entirely separate Ethernet segments, it is unsurprising that their
- use of the ".local." zone should occur exactly as it would if they
- really were on two entirely separate Ethernet segments.
-
- A dual-stack (v4/v6) host can participate in both ".local." zones,
- and should register its name(s) and perform its lookups both using
- IPv4 and IPv6. This enables it to reach, and be reached by, both
- IPv4-only and IPv6-only hosts. In effect, this acts like a
- multihomed host, with one connection to the logical "IPv4 Ethernet
- segment", and a connection to the logical "IPv6 Ethernet segment".
- When such a host generates NSEC records, if it is using the same host
- name for its IPv4 addresses and its IPv6 addresses on that network
- interface, its NSEC records should indicate that the host name has
- both A and AAAA records.
-
-21. Security Considerations
-
- The algorithm for detecting and resolving name conflicts is, by its
- very nature, an algorithm that assumes cooperating participants. Its
- purpose is to allow a group of hosts to arrive at a mutually disjoint
- set of host names and other DNS resource record names, in the absence
- of any central authority to coordinate this or mediate disputes. In
- the absence of any higher authority to resolve disputes, the only
- alternative is that the participants must work together cooperatively
- to arrive at a resolution.
-
- In an environment where the participants are mutually antagonistic
- and unwilling to cooperate, other mechanisms are appropriate, like
- manually configured DNS.
-
- In an environment where there is a group of cooperating participants,
- but clients cannot be sure that there are no antagonistic hosts on
- the same physical link, the cooperating participants need to use
- IPsec signatures and/or DNSSEC [RFC4033] signatures so that they can
- distinguish Multicast DNS messages from trusted participants (which
- they process as usual) from Multicast DNS messages from untrusted
- participants (which they silently discard).
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 52]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- If DNS queries for *global* DNS names are sent to the mDNS multicast
- address (during network outages which disrupt communication with the
- greater Internet) it is *especially* important to use DNSSEC, because
- the user may have the impression that he or she is communicating with
- some authentic host, when in fact he or she is really communicating
- with some local host that is merely masquerading as that name. This
- is less critical for names ending with ".local.", because the user
- should be aware that those names have only local significance and no
- global authority is implied.
-
- Most computer users neglect to type the trailing dot at the end of a
- fully qualified domain name, making it a relative domain name (e.g.,
- "www.example.com"). In the event of network outage, attempts to
- positively resolve the name as entered will fail, resulting in
- application of the search list, including ".local.", if present. A
- malicious host could masquerade as "www.example.com." by answering
- the resulting Multicast DNS query for "www.example.com.local.". To
- avoid this, a host MUST NOT append the search suffix ".local.", if
- present, to any relative (partially qualified) host name containing
- two or more labels. Appending ".local." to single-label relative
- host names is acceptable, since the user should have no expectation
- that a single-label host name will resolve as is. However, users who
- have both "example.com" and "local" in their search lists should be
- aware that if they type "www" into their web browser, it may not be
- immediately clear to them whether the page that appears is
- "www.example.com" or "www.local".
-
- Multicast DNS uses UDP port 5353. On operating systems where only
- privileged processes are allowed to use ports below 1024, no such
- privilege is required to use port 5353.
-
-22. IANA Considerations
-
- IANA has allocated the UDP port 5353 for the Multicast DNS protocol
- described in this document [SN].
-
- IANA has allocated the IPv4 link-local multicast address 224.0.0.251
- for the use described in this document [MC4].
-
- IANA has allocated the IPv6 multicast address set FF0X::FB (where "X"
- indicates any hexadecimal digit from '1' to 'F') for the use
- described in this document [MC6]. Only address FF02::FB (link-local
- scope) is currently in use by deployed software, but it is possible
- that in the future implementers may experiment with Multicast DNS
- using larger-scoped addresses, such as FF05::FB (site-local scope)
- [RFC4291].
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 53]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- IANA has implemented the following DNS records:
-
- MDNS.MCAST.NET. IN A 224.0.0.251
- 251.0.0.224.IN-ADDR.ARPA. IN PTR MDNS.MCAST.NET.
-
- Entries for the AAAA and corresponding PTR records have not been made
- as there is not yet an RFC providing direction for the management of
- the IP6.ARPA domain relating to the IPv6 multicast address space.
-
- The reuse of the top bit of the rrclass field in the Question and
- Resource Record Sections means that Multicast DNS can only carry DNS
- records with classes in the range 0-32767. Classes in the range
- 32768 to 65535 are incompatible with Multicast DNS. IANA has noted
- this fact, and if IANA receives a request to allocate a DNS class
- value above 32767, IANA will make sure the requester is aware of this
- implication before proceeding. This does not mean that allocations
- of DNS class values above 32767 should be denied, only that they
- should not be allowed until the requester has indicated that they are
- aware of how this allocation will interact with Multicast DNS.
- However, to date, only three DNS classes have been assigned by IANA
- (1, 3, and 4), and only one (1, "Internet") is actually in widespread
- use, so this issue is likely to remain a purely theoretical one.
-
- IANA has recorded the list of domains below as being Special-Use
- Domain Names [RFC6761]:
-
- .local.
- .254.169.in-addr.arpa.
- .8.e.f.ip6.arpa.
- .9.e.f.ip6.arpa.
- .a.e.f.ip6.arpa.
- .b.e.f.ip6.arpa.
-
-22.1. Domain Name Reservation Considerations
-
- The six domains listed above, and any names falling within those
- domains (e.g., "MyPrinter.local.", "34.12.254.169.in-addr.arpa.",
- "Ink-Jet._pdl-datastream._tcp.local.") are special [RFC6761] in the
- following ways:
-
- 1. Users may use these names as they would other DNS names,
- entering them anywhere that they would otherwise enter a
- conventional DNS name, or a dotted decimal IPv4 address, or a
- literal IPv6 address.
-
- Since there is no central authority responsible for assigning
- dot-local names, and all devices on the local network are
- equally entitled to claim any dot-local name, users SHOULD be
-
-
-
-Cheshire & Krochmal Standards Track [Page 54]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- aware of this and SHOULD exercise appropriate caution. In an
- untrusted or unfamiliar network environment, users SHOULD be
- aware that using a name like "www.local" may not actually
- connect them to the web site they expected, and could easily
- connect them to a different web page, or even a fake or spoof
- of their intended web site, designed to trick them into
- revealing confidential information. As always with networking,
- end-to-end cryptographic security can be a useful tool. For
- example, when connecting with ssh, the ssh host key
- verification process will inform the user if it detects that
- the identity of the entity they are communicating with has
- changed since the last time they connected to that name.
-
- 2. Application software may use these names as they would other
- similar DNS names, and is not required to recognize the names
- and treat them specially. Due to the relative ease of spoofing
- dot-local names, end-to-end cryptographic security remains
- important when communicating across a local network, just as it
- is when communicating across the global Internet.
-
- 3. Name resolution APIs and libraries SHOULD recognize these names
- as special and SHOULD NOT send queries for these names to their
- configured (unicast) caching DNS server(s). This is to avoid
- unnecessary load on the root name servers and other name
- servers, caused by queries for which those name servers do not
- have useful non-negative answers to give, and will not ever
- have useful non-negative answers to give.
-
- 4. Caching DNS servers SHOULD recognize these names as special and
- SHOULD NOT attempt to look up NS records for them, or otherwise
- query authoritative DNS servers in an attempt to resolve these
- names. Instead, caching DNS servers SHOULD generate immediate
- NXDOMAIN responses for all such queries they may receive (from
- misbehaving name resolver libraries). This is to avoid
- unnecessary load on the root name servers and other name
- servers.
-
- 5. Authoritative DNS servers SHOULD NOT by default be configurable
- to answer queries for these names, and, like caching DNS
- servers, SHOULD generate immediate NXDOMAIN responses for all
- such queries they may receive. DNS server software MAY provide
- a configuration option to override this default, for testing
- purposes or other specialized uses.
-
- 6. DNS server operators SHOULD NOT attempt to configure
- authoritative DNS servers to act as authoritative for any of
- these names. Configuring an authoritative DNS server to act as
- authoritative for any of these names may not, in many cases,
-
-
-
-Cheshire & Krochmal Standards Track [Page 55]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- yield the expected result. Since name resolver libraries and
- caching DNS servers SHOULD NOT send queries for those names
- (see 3 and 4 above), such queries SHOULD be suppressed before
- they even reach the authoritative DNS server in question, and
- consequently it will not even get an opportunity to answer
- them.
-
- 7. DNS Registrars MUST NOT allow any of these names to be
- registered in the normal way to any person or entity. These
- names are reserved protocol identifiers with special meaning
- and fall outside the set of names available for allocation by
- registrars. Attempting to allocate one of these names as if it
- were a normal domain name will probably not work as desired,
- for reasons 3, 4, and 6 above.
-
-23. Acknowledgments
-
- The concepts described in this document have been explored,
- developed, and implemented with help from Ran Atkinson, Richard
- Brown, Freek Dijkstra, Erik Guttman, Kyle McKay, Pasi Sarolahti,
- Pekka Savola, Robby Simpson, Mark Townsley, Paul Vixie, Bill
- Woodcock, and others. Special thanks go to Bob Bradley, Josh
- Graessley, Scott Herscher, Rory McGuire, Roger Pantos, and Kiren
- Sekar for their significant contributions. Special thanks also to
- Kerry Lynn for converting the document to xml2rfc form in May 2010,
- and to Area Director Ralph Droms for shepherding the document through
- its final steps.
-
-24. References
-
-24.1. Normative References
-
- [MC4] IANA, "IPv4 Multicast Address Space Registry",
- <http://www.iana.org/assignments/multicast-addresses/>.
-
- [MC6] IANA, "IPv6 Multicast Address Space Registry",
- <http://www.iana.org/assignments/
- ipv6-multicast-addresses/>.
-
- [RFC0020] Cerf, V., "ASCII format for network interchange", RFC 20,
- October 1969.
-
- [RFC1034] Mockapetris, P., "Domain names - concepts and facilities",
- STD 13, RFC 1034, November 1987.
-
- [RFC1035] Mockapetris, P., "Domain names - implementation and
- specification", STD 13, RFC 1035, November 1987.
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 56]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
- 10646", STD 63, RFC 3629, November 2003.
-
- [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S.
- Rose, "Resource Records for the DNS Security Extensions",
- RFC 4034, March 2005.
-
- [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network
- Interchange", RFC 5198, March 2008.
-
- [RFC6195] Eastlake 3rd, D., "Domain Name System (DNS) IANA
- Considerations", BCP 42, RFC 6195, March 2011.
-
- [RFC6761] Cheshire, S. and M. Krochmal, "Special-Use Domain Names",
- RFC 6761, February 2013.
-
- [SN] IANA, "Service Name and Transport Protocol Port Number
- Registry", <http://www.iana.org/assignments/
- service-names-port-numbers/>.
-
-24.2. Informative References
-
- [B4W] "Bonjour for Windows",
- <http://en.wikipedia.org/wiki/Bonjour_(software)>.
-
- [BJ] Apple Bonjour Open Source Software,
- <http://developer.apple.com/bonjour/>.
-
- [IEEE.802.3]
- "Information technology - Telecommunications and
- information exchange between systems - Local and
- metropolitan area networks - Specific requirements - Part
- 3: Carrier Sense Multiple Access with Collision Detection
- (CMSA/CD) Access Method and Physical Layer
- Specifications", IEEE Std 802.3-2008, December 2008,
- <http://standards.ieee.org/getieee802/802.3.html>.
-
- [IEEE.802.11]
- "Information technology - Telecommunications and
- information exchange between systems - Local and
- metropolitan area networks - Specific requirements - Part
- 11: Wireless LAN Medium Access Control (MAC) and Physical
- Layer (PHY) Specifications", IEEE Std 802.11-2007, June
- 2007, <http://standards.ieee.org/getieee802/802.11.html>.
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 57]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- [Jumbo] "Ethernet Jumbo Frames", November 2009,
- <http://www.ethernetalliance.org/library/whitepaper/
- ethernet-jumbo-frames/>.
-
- [NIAS] Cheshire, S. "Discovering Named Instances of Abstract
- Services using DNS", Work in Progress, July 2001.
-
- [NSD] "NsdManager | Android Developer", June 2012,
- <http://developer.android.com/reference/
- android/net/nsd/NsdManager.html>.
-
- [RFC2052] Gulbrandsen, A. and P. Vixie, "A DNS RR for specifying the
- location of services (DNS SRV)", RFC 2052, October 1996.
-
- [RFC2132] Alexander, S. and R. Droms, "DHCP Options and BOOTP Vendor
- Extensions", RFC 2132, March 1997.
-
- [RFC2136] Vixie, P., Ed., Thomson, S., Rekhter, Y., and J. Bound,
- "Dynamic Updates in the Domain Name System (DNS UPDATE)",
- RFC 2136, April 1997.
-
- [RFC2181] Elz, R. and R. Bush, "Clarifications to the DNS
- Specification", RFC 2181, July 1997.
-
- [RFC2535] Eastlake 3rd, D., "Domain Name System Security
- Extensions", RFC 2535, March 1999.
-
- [RFC2671] Vixie, P., "Extension Mechanisms for DNS (EDNS0)", RFC
- 2671, August 1999.
-
- [RFC2845] Vixie, P., Gudmundsson, O., Eastlake 3rd, D., and B.
- Wellington, "Secret Key Transaction Authentication for DNS
- (TSIG)", RFC 2845, May 2000.
-
- [RFC2930] Eastlake 3rd, D., "Secret Key Establishment for DNS (TKEY
- RR)", RFC 2930, September 2000.
-
- [RFC2931] Eastlake 3rd, D., "DNS Request and Transaction Signatures
- ( SIG(0)s )", RFC 2931, September 2000.
-
- [RFC3007] Wellington, B., "Secure Domain Name System (DNS) Dynamic
- Update", RFC 3007, November 2000.
-
- [RFC3492] Costello, A., "Punycode: A Bootstring encoding of Unicode
- for Internationalized Domain Names in Applications
- (IDNA)", RFC 3492, March 2003.
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 58]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- [RFC3927] Cheshire, S., Aboba, B., and E. Guttman, "Dynamic
- Configuration of IPv4 Link-Local Addresses", RFC 3927, May
- 2005.
-
- [RFC4033] Arends, R., Austein, R., Larson, M., Massey, D., and S.
- Rose, "DNS Security Introduction and Requirements", RFC
- 4033, March 2005.
-
- [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing
- Architecture", RFC 4291, February 2006.
-
- [RFC4795] Aboba, B., Thaler, D., and L. Esibov, "Link-local
- Multicast Name Resolution (LLMNR)", RFC 4795, January
- 2007.
-
- [RFC4861] Narten, T., Nordmark, E., Simpson, W., and H. Soliman,
- "Neighbor Discovery for IP version 6 (IPv6)", RFC 4861,
- September 2007.
-
- [RFC4862] Thomson, S., Narten, T., and T. Jinmei, "IPv6 Stateless
- Address Autoconfiguration", RFC 4862, September 2007.
-
- [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
- IANA Considerations Section in RFCs", BCP 26, RFC 5226,
- May 2008.
-
- [RFC5890] Klensin, J., "Internationalized Domain Names for
- Applications (IDNA): Definitions and Document Framework",
- RFC 5890, August 2010.
-
- [RFC6281] Cheshire, S., Zhu, Z., Wakikawa, R., and L. Zhang,
- "Understanding Apple's Back to My Mac (BTMM) Service", RFC
- 6281, June 2011.
-
- [RFC6760] Cheshire, S. and M. Krochmal, "Requirements for a Protocol
- to Replace the AppleTalk Name Binding Protocol (NBP)", RFC
- 6760, February 2013.
-
- [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service
- Discovery", RFC 6763, February 2013.
-
- [Zeroconf] Cheshire, S. and D. Steinberg, "Zero Configuration
- Networking: The Definitive Guide", O'Reilly Media, Inc.,
- ISBN 0-596-10100-7, December 2005.
-
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 59]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
-Appendix A. Design Rationale for Choice of UDP Port Number
-
- Arguments were made for and against using UDP port 53, the standard
- Unicast DNS port. Some of the arguments are given below. The
- arguments for using a different port were greater in number and more
- compelling, so that option was ultimately selected. The UDP port
- "5353" was selected for its mnemonic similarity to "53".
-
- Arguments for using UDP port 53:
-
- * This is "just DNS", so it should be the same port.
-
- * There is less work to be done updating old resolver libraries to do
- simple Multicast DNS queries. Only the destination address need be
- changed. In some cases, this can be achieved without any code
- changes, just by adding the address 224.0.0.251 to a configuration
- file.
-
- Arguments for using a different port (UDP port 5353):
-
- * This is not "just DNS". This is a DNS-like protocol, but
- different.
-
- * Changing resolver library code to use a different port number is
- not hard. In some cases, this can be achieved without any code
- changes, just by adding the address 224.0.0.251:5353 to a
- configuration file.
-
- * Using the same port number makes it hard to run a Multicast DNS
- responder and a conventional Unicast DNS server on the same
- machine. If a conventional Unicast DNS server wishes to implement
- Multicast DNS as well, it can still do that, by opening two
- sockets. Having two different port numbers allows this
- flexibility.
-
- * Some VPN software hijacks all outgoing traffic to port 53 and
- redirects it to a special DNS server set up to serve those VPN
- clients while they are connected to the corporate network. It is
- questionable whether this is the right thing to do, but it is
- common, and redirecting link-local multicast DNS packets to a
- remote server rarely produces any useful results. It does mean,
- for example, that a user of such VPN software becomes unable to
- access their local network printer sitting on their desk right next
- to their computer. Using a different UDP port helps avoid this
- particular problem.
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 60]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- * On many operating systems, unprivileged software may not send or
- receive packets on low-numbered ports. This means that any
- software sending or receiving Multicast DNS packets on port 53
- would have to run as "root", which is an undesirable security risk.
- Using a higher-numbered UDP port avoids this restriction.
-
-Appendix B. Design Rationale for Not Using Hashed Multicast Addresses
-
- Some discovery protocols use a range of multicast addresses, and
- determine the address to be used by a hash function of the name being
- sought. Queries are sent via multicast to the address as indicated
- by the hash function, and responses are returned to the querier via
- unicast. Particularly in IPv6, where multicast addresses are
- extremely plentiful, this approach is frequently advocated. For
- example, IPv6 Neighbor Discovery [RFC4861] sends Neighbor
- Solicitation messages to the "solicited-node multicast address",
- which is computed as a function of the solicited IPv6 address.
-
- There are some disadvantages to using hashed multicast addresses like
- this in a service discovery protocol:
-
- * When a host has a large number of records with different names, the
- host may have to join a large number of multicast groups. Each
- time a host joins or leaves a multicast group, this results in
- Internet Group Management Protocol (IGMP) or Multicast Listener
- Discovery (MLD) traffic on the network announcing this fact.
- Joining a large number of multicast groups can place undue burden
- on the Ethernet hardware, which typically supports a limited number
- of multicast addresses efficiently. When this number is exceeded,
- the Ethernet hardware may have to resort to receiving all
- multicasts and passing them up to the host networking code for
- filtering in software, thereby defeating much of the point of using
- a multicast address range in the first place. Finally, many IPv6
- stacks have a fixed limit IPV6_MAX_MEMBERSHIPS, and the code simply
- fails with an error if a client attempts to exceed this limit.
- Common values for IPV6_MAX_MEMBERSHIPS are 20 or 31.
-
- * Multiple questions cannot be placed in one packet if they don't all
- hash to the same multicast address.
-
- * Duplicate Question Suppression doesn't work if queriers are not
- seeing each other's queries.
-
- * Duplicate Answer Suppression doesn't work if responders are not
- seeing each other's responses.
-
- * Opportunistic Caching doesn't work.
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 61]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- * Ongoing Conflict Detection doesn't work.
-
-Appendix C. Design Rationale for Maximum Multicast DNS Name Length
-
- Multicast DNS names may be up to 255 bytes long (in the on-the-wire
- message format), not counting the terminating zero byte at the end.
-
- "Domain Names - Implementation and Specification" [RFC1035] says:
-
- Various objects and parameters in the DNS have size limits. They
- are listed below. Some could be easily changed, others are more
- fundamental.
-
- labels 63 octets or less
-
- names 255 octets or less
-
- ...
-
- the total length of a domain name (i.e., label octets and label
- length octets) is restricted to 255 octets or less.
-
- This text does not state whether this 255-byte limit includes the
- terminating zero at the end of every name.
-
- Several factors lead us to conclude that the 255-byte limit does
- *not* include the terminating zero:
-
- o It is common in software engineering to have size limits that are a
- power of two, or a multiple of a power of two, for efficiency. For
- example, an integer on a modern processor is typically 2, 4, or 8
- bytes, not 3 or 5 bytes. The number 255 is not a power of two, nor
- is it to most people a particularly noteworthy number. It is
- noteworthy to computer scientists for only one reason -- because it
- is exactly one *less* than a power of two. When a size limit is
- exactly one less than a power of two, that suggests strongly that
- the one extra byte is being reserved for some specific reason -- in
- this case reserved, perhaps, to leave room for a terminating zero
- at the end.
-
- o In the case of DNS label lengths, the stated limit is 63 bytes. As
- with the total name length, this limit is exactly one less than a
- power of two. This label length limit also excludes the label
- length byte at the start of every label. Including that extra
- byte, a 63-byte label takes 64 bytes of space in memory or in a DNS
- message.
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 62]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- o It is common in software engineering for the semantic "length" of
- an object to be one less than the number of bytes it takes to store
- that object. For example, in C, strlen("foo") is 3, but
- sizeof("foo") (which includes the terminating zero byte at the end)
- is 4.
-
- o The text describing the total length of a domain name mentions
- explicitly that label length and data octets are included, but does
- not mention the terminating zero at the end. The zero byte at the
- end of a domain name is not a label length. Indeed, the value zero
- is chosen as the terminating marker precisely because it is not a
- legal length byte value -- DNS prohibits empty labels. For
- example, a name like "bad..name." is not a valid domain name
- because it contains a zero-length label in the middle, which cannot
- be expressed in a DNS message, because software parsing the message
- would misinterpret a zero label-length byte as being a zero "end of
- name" marker instead.
-
- Finally, "Clarifications to the DNS Specification" [RFC2181] offers
- additional confirmation that, in the context of DNS specifications,
- the stated "length" of a domain name does not include the terminating
- zero byte at the end. That document refers to the root name, which
- is typically written as "." and is represented in a DNS message by a
- single lone zero byte (i.e., zero bytes of data plus a terminating
- zero), as the "zero length full name":
-
- The zero length full name is defined as representing the root of
- the DNS tree, and is typically written and displayed as ".".
-
- This wording supports the interpretation that, in a DNS context, when
- talking about lengths of names, the terminating zero byte at the end
- is not counted. If the root name (".") is considered to be zero
- length, then to be consistent, the length (for example) of "org" has
- to be 4 and the length of "ietf.org" has to be 9, as shown below:
-
- ------
- | 0x00 | length = 0
- ------
-
- ------------------ ------
- | 0x03 | o | r | g | | 0x00 | length = 4
- ------------------ ------
-
- ----------------------------------------- ------
- | 0x04 | i | e | t | f | 0x03 | o | r | g | | 0x00 | length = 9
- ----------------------------------------- ------
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 63]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- This means that the maximum length of a domain name, as represented
- in a Multicast DNS message, up to but not including the final
- terminating zero, must not exceed 255 bytes.
-
- However, many Unicast DNS implementers have read these RFCs
- differently, and argue that the 255-byte limit does include the
- terminating zero, and that the "Clarifications to the DNS
- Specification" [RFC2181] statement that "." is the "zero length full
- name" was simply a mistake.
-
- Hence, implementers should be aware that other Unicast DNS
- implementations may limit the maximum domain name to 254 bytes plus a
- terminating zero, depending on how that implementer interpreted the
- DNS specifications.
-
- Compliant Multicast DNS implementations MUST support names up to 255
- bytes plus a terminating zero, i.e., 256 bytes total.
-
-Appendix D. Benefits of Multicast Responses
-
- Some people have argued that sending responses via multicast is
- inefficient on the network. In fact, using multicast responses can
- result in a net lowering of overall multicast traffic for a variety
- of reasons, and provides other benefits too:
-
- * Opportunistic Caching. One multicast response can update the
- caches on all machines on the network. If another machine later
- wants to issue the same query, and it already has the answer in its
- cache, it may not need to even transmit that multicast query on the
- network at all.
-
- * Duplicate Query Suppression. When more than one machine has the
- same ongoing long-lived query running, every machine does not have
- to transmit its own independent query. When one machine transmits
- a query, all the other hosts see the answers, so they can suppress
- their own queries.
-
- * Passive Observation Of Failures (POOF). When a host sees a
- multicast query, but does not see the corresponding multicast
- response, it can use this information to promptly delete stale data
- from its cache. To achieve the same level of user-interface
- quality and responsiveness without multicast responses would
- require lower cache lifetimes and more frequent network polling,
- resulting in a higher packet rate.
-
- * Passive Conflict Detection. Just because a name has been
- previously verified to be unique does not guarantee it will
- continue to be so indefinitely. By allowing all Multicast DNS
-
-
-
-Cheshire & Krochmal Standards Track [Page 64]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- responders to constantly monitor their peers' responses, conflicts
- arising out of network topology changes can be promptly detected
- and resolved. If responses were not sent via multicast, some other
- conflict detection mechanism would be needed, imposing its own
- additional burden on the network.
-
- * Use on devices with constrained memory resources: When using
- delayed responses to reduce network collisions, responders need to
- maintain a list recording to whom each answer should be sent. The
- option of multicast responses allows responders with limited
- storage, which cannot store an arbitrarily long list of response
- addresses, to choose to fail-over to a single multicast response in
- place of multiple unicast responses, when appropriate.
-
- * Overlayed Subnets. In the case of overlayed subnets, multicast
- responses allow a receiver to know with certainty that a response
- originated on the local link, even when its source address may
- apparently suggest otherwise.
-
- * Robustness in the face of misconfiguration: Link-local multicast
- transcends virtually every conceivable network misconfiguration.
- Even if you have a collection of devices where every device's IP
- address, subnet mask, default gateway, and DNS server address are
- all wrong, packets sent by any of those devices addressed to a
- link-local multicast destination address will still be delivered to
- all peers on the local link. This can be extremely helpful when
- diagnosing and rectifying network problems, since it facilitates a
- direct communication channel between client and server that works
- without reliance on ARP, IP routing tables, etc. Being able to
- discover what IP address a device has (or thinks it has) is
- frequently a very valuable first step in diagnosing why it is
- unable to communicate on the local network.
-
-Appendix E. Design Rationale for Encoding Negative Responses
-
- Alternative methods of asserting nonexistence were considered, such
- as using an NXDOMAIN response, or emitting a resource record with
- zero-length rdata.
-
- Using an NXDOMAIN response does not work well with Multicast DNS. A
- Unicast DNS NXDOMAIN response applies to the entire message, but for
- efficiency Multicast DNS allows (and encourages) multiple responses
- in a single message. If the error code in the header were NXDOMAIN,
- it would not be clear to which name(s) that error code applied.
-
- Asserting nonexistence by emitting a resource record with zero-length
- rdata would mean that there would be no way to differentiate between
- a record that doesn't exist, and a record that does exist, with zero-
-
-
-
-Cheshire & Krochmal Standards Track [Page 65]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- length rdata. By analogy, most file systems today allow empty files,
- so a file that exists with zero bytes of data is not considered
- equivalent to a filename that does not exist.
-
- A benefit of asserting nonexistence through NSEC records instead of
- through NXDOMAIN responses is that NSEC records can be added to the
- Additional Section of a DNS response to offer additional information
- beyond what the querier explicitly requested. For example, in
- response to an SRV query, a responder should include A record(s)
- giving its IPv4 addresses in the Additional Section, and an NSEC
- record indicating which other types it does or does not have for this
- name. If the responder is running on a host that does not support
- IPv6 (or does support IPv6 but currently has no IPv6 address on that
- interface) then this NSEC record in the Additional Section will
- indicate this absence of AAAA records. In effect, the responder is
- saying, "Here's my SRV record, and here are my IPv4 addresses, and
- no, I don't have any IPv6 addresses, so don't waste your time
- asking". Without this information in the Additional Section, it
- would take the querier an additional round-trip to perform an
- additional query to ascertain that the target host has no AAAA
- records. (Arguably Unicast DNS could also benefit from this ability
- to express nonexistence in the Additional Section, but that is
- outside the scope of this document.)
-
-Appendix F. Use of UTF-8
-
- After many years of debate, as a result of the perceived need to
- accommodate certain DNS implementations that apparently couldn't
- handle any character that's not a letter, digit, or hyphen (and
- apparently never would be updated to remedy this limitation), the
- Unicast DNS community settled on an extremely baroque encoding called
- "Punycode" [RFC3492]. Punycode is a remarkably ingenious encoding
- solution, but it is complicated, hard to understand, and hard to
- implement, using sophisticated techniques including insertion unsort
- coding, generalized variable-length integers, and bias adaptation.
- The resulting encoding is remarkably compact given the constraints,
- but it's still not as good as simple straightforward UTF-8, and it's
- hard even to predict whether a given input string will encode to a
- Punycode string that fits within DNS's 63-byte limit, except by
- simply trying the encoding and seeing whether it fits. Indeed, the
- encoded size depends not only on the input characters, but on the
- order they appear, so the same set of characters may or may not
- encode to a legal Punycode string that fits within DNS's 63-byte
- limit, depending on the order the characters appear. This is
- extremely hard to present in a user interface that explains to users
- why one name is allowed, but another name containing the exact same
- characters is not. Neither Punycode nor any other of the "ASCII-
- Compatible Encodings" [RFC5890] proposed for Unicast DNS may be used
-
-
-
-Cheshire & Krochmal Standards Track [Page 66]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- in Multicast DNS messages. Any text being represented internally in
- some other representation must be converted to canonical precomposed
- UTF-8 before being placed in any Multicast DNS message.
-
-Appendix G. Private DNS Namespaces
-
- The special treatment of names ending in ".local." has been
- implemented in Macintosh computers since the days of Mac OS 9, and
- continues today in Mac OS X and iOS. There are also implementations
- for Microsoft Windows [B4W], Linux, and other platforms.
-
- Some network operators setting up private internal networks
- ("intranets") have used unregistered top-level domains, and some may
- have used the ".local" top-level domain. Using ".local" as a private
- top-level domain conflicts with Multicast DNS and may cause problems
- for users. Clients can be configured to send both Multicast and
- Unicast DNS queries in parallel for these names, and this does allow
- names to be looked up both ways, but this results in additional
- network traffic and additional delays in name resolution, as well as
- potentially creating user confusion when it is not clear whether any
- given result was received via link-local multicast from a peer on the
- same link, or from the configured unicast name server. Because of
- this, we recommend against using ".local" as a private Unicast DNS
- top-level domain. We do not recommend use of unregistered top-level
- domains at all, but should network operators decide to do this, the
- following top-level domains have been used on private internal
- networks without the problems caused by trying to reuse ".local." for
- this purpose:
-
- .intranet.
- .internal.
- .private.
- .corp.
- .home.
- .lan.
-
-Appendix H. Deployment History
-
- In July 1997, in an email to the net-thinkers@thumper.vmeng.com
- mailing list, Stuart Cheshire first proposed the idea of running the
- AppleTalk Name Binding Protocol [RFC6760] over IP. As a result of
- this and related IETF discussions, the IETF Zeroconf working group
- was chartered September 1999. After various working group
- discussions and other informal IETF discussions, several Internet-
- Drafts were written that were loosely related to the general themes
- of DNS and multicast, but did not address the service discovery
- aspect of NBP.
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 67]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- In April 2000, Stuart Cheshire registered IPv4 multicast address
- 224.0.0.251 with IANA [MC4] and began writing code to test and
- develop the idea of performing NBP-like service discovery using
- Multicast DNS, which was documented in a group of three Internet-
- Drafts:
-
- o "Requirements for a Protocol to Replace the AppleTalk Name Binding
- Protocol (NBP)" [RFC6760] is an overview explaining the AppleTalk
- Name Binding Protocol, because many in the IETF community had
- little first-hand experience using AppleTalk, and confusion in the
- IETF community about what AppleTalk NBP did was causing confusion
- about what would be required in an IP-based replacement.
-
- o "Discovering Named Instances of Abstract Services using DNS" [NIAS]
- proposed a way to perform NBP-like service discovery using DNS-
- compatible names and record types.
-
- o "Multicast DNS" (this document) specifies a way to transport those
- DNS-compatible queries and responses using IP multicast, for zero-
- configuration environments where no conventional Unicast DNS server
- was available.
-
- In 2001, an update to Mac OS 9 added resolver library support for
- host name lookup using Multicast DNS. If the user typed a name such
- as "MyPrinter.local." into any piece of networking software that used
- the standard Mac OS 9 name lookup APIs, then those name lookup APIs
- would recognize the name as a dot-local name and query for it by
- sending simple one-shot Multicast DNS queries to 224.0.0.251:5353.
- This enabled the user to, for example, enter the name
- "MyPrinter.local." into their web browser in order to view a
- printer's status and configuration web page, or enter the name
- "MyPrinter.local." into the printer setup utility to create a print
- queue for printing documents on that printer.
-
- Multicast DNS responder software, with full service discovery, first
- began shipping to end users in volume with the launch of Mac OS X
- 10.2 "Jaguar" in August 2002, and network printer makers (who had
- historically supported AppleTalk in their network printers and were
- receptive to IP-based technologies that could offer them similar
- ease-of-use) started adopting Multicast DNS shortly thereafter.
-
- In September 2002, Apple released the source code for the
- mDNSResponder daemon as Open Source under Apple's standard Apple
- Public Source License (APSL).
-
- Multicast DNS responder software became available for Microsoft
- Windows users in June 2004 with the launch of Apple's "Rendezvous for
- Windows" (now "Bonjour for Windows"), both in executable form (a
-
-
-
-Cheshire & Krochmal Standards Track [Page 68]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
- downloadable installer for end users) and as Open Source (one of the
- supported platforms within Apple's body of cross-platform code in the
- publicly accessible mDNSResponder CVS source code repository) [BJ].
-
- In August 2006, Apple re-licensed the cross-platform mDNSResponder
- source code under the Apache License, Version 2.0.
-
- In addition to desktop and laptop computers running Mac OS X and
- Microsoft Windows, Multicast DNS is now implemented in a wide range
- of hardware devices, such as Apple's "AirPort" wireless base
- stations, iPhone and iPad, and in home gateways from other vendors,
- network printers, network cameras, TiVo DVRs, etc.
-
- The Open Source community has produced many independent
- implementations of Multicast DNS, some in C like Apple's
- mDNSResponder daemon, and others in a variety of different languages
- including Java, Python, Perl, and C#/Mono.
-
- In January 2007, the IETF published the Informational RFC "Link-Local
- Multicast Name Resolution (LLMNR)" [RFC4795], which is substantially
- similar to Multicast DNS, but incompatible in some small but
- important ways. In particular, the LLMNR design explicitly excluded
- support for service discovery, which made it an unsuitable candidate
- for a protocol to replace AppleTalk NBP [RFC6760].
-
- While the original focus of Multicast DNS and DNS-Based Service
- Discovery was for zero-configuration environments without a
- conventional Unicast DNS server, DNS-Based Service Discovery also
- works using Unicast DNS servers, using DNS Update [RFC2136] [RFC3007]
- to create service discovery records and standard DNS queries to query
- for them. Apple's Back to My Mac service, launched with Mac OS X
- 10.5 "Leopard" in October 2007, uses DNS-Based Service Discovery over
- Unicast DNS [RFC6281].
-
- In June 2012, Google's Android operating system added native support
- for DNS-SD and Multicast DNS with the android.net.nsd.NsdManager
- class in Android 4.1 "Jelly Bean" (API Level 16) [NSD].
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 69]
-\f
-RFC 6762 Multicast DNS February 2013
-
-
-Authors' Addresses
-
- Stuart Cheshire
- Apple Inc.
- 1 Infinite Loop
- Cupertino, CA 95014
- USA
-
- Phone: +1 408 974 3207
- EMail: cheshire@apple.com
-
-
- Marc Krochmal
- Apple Inc.
- 1 Infinite Loop
- Cupertino, CA 95014
- USA
-
- Phone: +1 408 974 4368
- EMail: marc@apple.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Cheshire & Krochmal Standards Track [Page 70]
-\f
+++ /dev/null
-
-
-
-
-
-
-Internet Engineering Task Force (IETF) R. Fielding, Ed.
-Request for Comments: 7230 Adobe
-Obsoletes: 2145, 2616 J. Reschke, Ed.
-Updates: 2817, 2818 greenbytes
-Category: Standards Track June 2014
-ISSN: 2070-1721
-
-
- Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing
-
-Abstract
-
- The Hypertext Transfer Protocol (HTTP) is a stateless application-
- level protocol for distributed, collaborative, hypertext information
- systems. This document provides an overview of HTTP architecture and
- its associated terminology, defines the "http" and "https" Uniform
- Resource Identifier (URI) schemes, defines the HTTP/1.1 message
- syntax and parsing requirements, and describes related security
- concerns for implementations.
-
-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 5741.
-
- 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/rfc7230.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 1]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-Copyright Notice
-
- Copyright (c) 2014 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.
-
- This document may contain material from IETF Documents or IETF
- Contributions published or made publicly available before November
- 10, 2008. The person(s) controlling the copyright in some of this
- material may not have granted the IETF Trust the right to allow
- modifications of such material outside the IETF Standards Process.
- Without obtaining an adequate license from the person(s) controlling
- the copyright in such materials, this document may not be modified
- outside the IETF Standards Process, and derivative works of it may
- not be created outside the IETF Standards Process, except to format
- it for publication as an RFC or to translate it into languages other
- than English.
-
-Table of Contents
-
- 1. Introduction ....................................................5
- 1.1. Requirements Notation ......................................6
- 1.2. Syntax Notation ............................................6
- 2. Architecture ....................................................6
- 2.1. Client/Server Messaging ....................................7
- 2.2. Implementation Diversity ...................................8
- 2.3. Intermediaries .............................................9
- 2.4. Caches ....................................................11
- 2.5. Conformance and Error Handling ............................12
- 2.6. Protocol Versioning .......................................13
- 2.7. Uniform Resource Identifiers ..............................16
- 2.7.1. http URI Scheme ....................................17
- 2.7.2. https URI Scheme ...................................18
- 2.7.3. http and https URI Normalization and Comparison ....19
- 3. Message Format .................................................19
- 3.1. Start Line ................................................20
- 3.1.1. Request Line .......................................21
- 3.1.2. Status Line ........................................22
- 3.2. Header Fields .............................................22
-
-
-
-Fielding & Reschke Standards Track [Page 2]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- 3.2.1. Field Extensibility ................................23
- 3.2.2. Field Order ........................................23
- 3.2.3. Whitespace .........................................24
- 3.2.4. Field Parsing ......................................25
- 3.2.5. Field Limits .......................................26
- 3.2.6. Field Value Components .............................27
- 3.3. Message Body ..............................................28
- 3.3.1. Transfer-Encoding ..................................28
- 3.3.2. Content-Length .....................................30
- 3.3.3. Message Body Length ................................32
- 3.4. Handling Incomplete Messages ..............................34
- 3.5. Message Parsing Robustness ................................34
- 4. Transfer Codings ...............................................35
- 4.1. Chunked Transfer Coding ...................................36
- 4.1.1. Chunk Extensions ...................................36
- 4.1.2. Chunked Trailer Part ...............................37
- 4.1.3. Decoding Chunked ...................................38
- 4.2. Compression Codings .......................................38
- 4.2.1. Compress Coding ....................................38
- 4.2.2. Deflate Coding .....................................38
- 4.2.3. Gzip Coding ........................................39
- 4.3. TE ........................................................39
- 4.4. Trailer ...................................................40
- 5. Message Routing ................................................40
- 5.1. Identifying a Target Resource .............................40
- 5.2. Connecting Inbound ........................................41
- 5.3. Request Target ............................................41
- 5.3.1. origin-form ........................................42
- 5.3.2. absolute-form ......................................42
- 5.3.3. authority-form .....................................43
- 5.3.4. asterisk-form ......................................43
- 5.4. Host ......................................................44
- 5.5. Effective Request URI .....................................45
- 5.6. Associating a Response to a Request .......................46
- 5.7. Message Forwarding ........................................47
- 5.7.1. Via ................................................47
- 5.7.2. Transformations ....................................49
- 6. Connection Management ..........................................50
- 6.1. Connection ................................................51
- 6.2. Establishment .............................................52
- 6.3. Persistence ...............................................52
- 6.3.1. Retrying Requests ..................................53
- 6.3.2. Pipelining .........................................54
- 6.4. Concurrency ...............................................55
- 6.5. Failures and Timeouts .....................................55
- 6.6. Tear-down .................................................56
- 6.7. Upgrade ...................................................57
- 7. ABNF List Extension: #rule .....................................59
-
-
-
-Fielding & Reschke Standards Track [Page 3]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- 8. IANA Considerations ............................................61
- 8.1. Header Field Registration .................................61
- 8.2. URI Scheme Registration ...................................62
- 8.3. Internet Media Type Registration ..........................62
- 8.3.1. Internet Media Type message/http ...................62
- 8.3.2. Internet Media Type application/http ...............63
- 8.4. Transfer Coding Registry ..................................64
- 8.4.1. Procedure ..........................................65
- 8.4.2. Registration .......................................65
- 8.5. Content Coding Registration ...............................66
- 8.6. Upgrade Token Registry ....................................66
- 8.6.1. Procedure ..........................................66
- 8.6.2. Upgrade Token Registration .........................67
- 9. Security Considerations ........................................67
- 9.1. Establishing Authority ....................................67
- 9.2. Risks of Intermediaries ...................................68
- 9.3. Attacks via Protocol Element Length .......................69
- 9.4. Response Splitting ........................................69
- 9.5. Request Smuggling .........................................70
- 9.6. Message Integrity .........................................70
- 9.7. Message Confidentiality ...................................71
- 9.8. Privacy of Server Log Information .........................71
- 10. Acknowledgments ...............................................72
- 11. References ....................................................74
- 11.1. Normative References .....................................74
- 11.2. Informative References ...................................75
- Appendix A. HTTP Version History ..................................78
- A.1. Changes from HTTP/1.0 ....................................78
- A.1.1. Multihomed Web Servers ............................78
- A.1.2. Keep-Alive Connections ............................79
- A.1.3. Introduction of Transfer-Encoding .................79
- A.2. Changes from RFC 2616 ....................................80
- Appendix B. Collected ABNF ........................................82
- Index .............................................................85
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 4]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-1. Introduction
-
- The Hypertext Transfer Protocol (HTTP) is a stateless application-
- level request/response protocol that uses extensible semantics and
- self-descriptive message payloads for flexible interaction with
- network-based hypertext information systems. This document is the
- first in a series of documents that collectively form the HTTP/1.1
- specification:
-
- 1. "Message Syntax and Routing" (this document)
-
- 2. "Semantics and Content" [RFC7231]
-
- 3. "Conditional Requests" [RFC7232]
-
- 4. "Range Requests" [RFC7233]
-
- 5. "Caching" [RFC7234]
-
- 6. "Authentication" [RFC7235]
-
- This HTTP/1.1 specification obsoletes RFC 2616 and RFC 2145 (on HTTP
- versioning). This specification also updates the use of CONNECT to
- establish a tunnel, previously defined in RFC 2817, and defines the
- "https" URI scheme that was described informally in RFC 2818.
-
- HTTP is a generic interface protocol for information systems. It is
- designed to hide the details of how a service is implemented by
- presenting a uniform interface to clients that is independent of the
- types of resources provided. Likewise, servers do not need to be
- aware of each client's purpose: an HTTP request can be considered in
- isolation rather than being associated with a specific type of client
- or a predetermined sequence of application steps. The result is a
- protocol that can be used effectively in many different contexts and
- for which implementations can evolve independently over time.
-
- HTTP is also designed for use as an intermediation protocol for
- translating communication to and from non-HTTP information systems.
- HTTP proxies and gateways can provide access to alternative
- information services by translating their diverse protocols into a
- hypertext format that can be viewed and manipulated by clients in the
- same way as HTTP services.
-
- One consequence of this flexibility is that the protocol cannot be
- defined in terms of what occurs behind the interface. Instead, we
- are limited to defining the syntax of communication, the intent of
- received communication, and the expected behavior of recipients. If
- the communication is considered in isolation, then successful actions
-
-
-
-Fielding & Reschke Standards Track [Page 5]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- ought to be reflected in corresponding changes to the observable
- interface provided by servers. However, since multiple clients might
- act in parallel and perhaps at cross-purposes, we cannot require that
- such changes be observable beyond the scope of a single response.
-
- This document describes the architectural elements that are used or
- referred to in HTTP, defines the "http" and "https" URI schemes,
- describes overall network operation and connection management, and
- defines HTTP message framing and forwarding requirements. Our goal
- is to define all of the mechanisms necessary for HTTP message
- handling that are independent of message semantics, thereby defining
- the complete set of requirements for message parsers and message-
- forwarding intermediaries.
-
-1.1. Requirements Notation
-
- 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].
-
- Conformance criteria and considerations regarding error handling are
- defined in Section 2.5.
-
-1.2. Syntax Notation
-
- This specification uses the Augmented Backus-Naur Form (ABNF)
- notation of [RFC5234] with a list extension, defined in Section 7,
- that allows for compact definition of comma-separated lists using a
- '#' operator (similar to how the '*' operator indicates repetition).
- Appendix B shows the collected grammar with all list operators
- expanded to standard ABNF notation.
-
- The following core rules are included by reference, as defined in
- [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF
- (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote),
- HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF (line
- feed), OCTET (any 8-bit sequence of data), SP (space), and VCHAR (any
- visible [USASCII] character).
-
- As a convention, ABNF rule names prefixed with "obs-" denote
- "obsolete" grammar rules that appear for historical reasons.
-
-2. Architecture
-
- HTTP was created for the World Wide Web (WWW) architecture and has
- evolved over time to support the scalability needs of a worldwide
- hypertext system. Much of that architecture is reflected in the
- terminology and syntax productions used to define HTTP.
-
-
-
-Fielding & Reschke Standards Track [Page 6]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-2.1. Client/Server Messaging
-
- HTTP is a stateless request/response protocol that operates by
- exchanging messages (Section 3) across a reliable transport- or
- session-layer "connection" (Section 6). An HTTP "client" is a
- program that establishes a connection to a server for the purpose of
- sending one or more HTTP requests. An HTTP "server" is a program
- that accepts connections in order to service HTTP requests by sending
- HTTP responses.
-
- The terms "client" and "server" refer only to the roles that these
- programs perform for a particular connection. The same program might
- act as a client on some connections and a server on others. The term
- "user agent" refers to any of the various client programs that
- initiate a request, including (but not limited to) browsers, spiders
- (web-based robots), command-line tools, custom applications, and
- mobile apps. The term "origin server" refers to the program that can
- originate authoritative responses for a given target resource. The
- terms "sender" and "recipient" refer to any implementation that sends
- or receives a given message, respectively.
-
- HTTP relies upon the Uniform Resource Identifier (URI) standard
- [RFC3986] to indicate the target resource (Section 5.1) and
- relationships between resources. Messages are passed in a format
- similar to that used by Internet mail [RFC5322] and the Multipurpose
- Internet Mail Extensions (MIME) [RFC2045] (see Appendix A of
- [RFC7231] for the differences between HTTP and MIME messages).
-
- Most HTTP communication consists of a retrieval request (GET) for a
- representation of some resource identified by a URI. In the simplest
- case, this might be accomplished via a single bidirectional
- connection (===) between the user agent (UA) and the origin
- server (O).
-
- request >
- UA ======================================= O
- < response
-
- A client sends an HTTP request to a server in the form of a request
- message, beginning with a request-line that includes a method, URI,
- and protocol version (Section 3.1.1), followed by header fields
- containing request modifiers, client information, and representation
- metadata (Section 3.2), an empty line to indicate the end of the
- header section, and finally a message body containing the payload
- body (if any, Section 3.3).
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 7]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- A server responds to a client's request by sending one or more HTTP
- response messages, each beginning with a status line that includes
- the protocol version, a success or error code, and textual reason
- phrase (Section 3.1.2), possibly followed by header fields containing
- server information, resource metadata, and representation metadata
- (Section 3.2), an empty line to indicate the end of the header
- section, and finally a message body containing the payload body (if
- any, Section 3.3).
-
- A connection might be used for multiple request/response exchanges,
- as defined in Section 6.3.
-
- The following example illustrates a typical message exchange for a
- GET request (Section 4.3.1 of [RFC7231]) on the URI
- "http://www.example.com/hello.txt":
-
- Client request:
-
- GET /hello.txt HTTP/1.1
- User-Agent: curl/7.16.3 libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3
- Host: www.example.com
- Accept-Language: en, mi
-
-
- Server response:
-
- HTTP/1.1 200 OK
- Date: Mon, 27 Jul 2009 12:28:53 GMT
- Server: Apache
- Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT
- ETag: "34aa387-d-1568eb00"
- Accept-Ranges: bytes
- Content-Length: 51
- Vary: Accept-Encoding
- Content-Type: text/plain
-
- Hello World! My payload includes a trailing CRLF.
-
-2.2. Implementation Diversity
-
- When considering the design of HTTP, it is easy to fall into a trap
- of thinking that all user agents are general-purpose browsers and all
- origin servers are large public websites. That is not the case in
- practice. Common HTTP user agents include household appliances,
- stereos, scales, firmware update scripts, command-line programs,
- mobile apps, and communication devices in a multitude of shapes and
- sizes. Likewise, common HTTP origin servers include home automation
-
-
-
-
-Fielding & Reschke Standards Track [Page 8]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- units, configurable networking components, office machines,
- autonomous robots, news feeds, traffic cameras, ad selectors, and
- video-delivery platforms.
-
- The term "user agent" does not imply that there is a human user
- directly interacting with the software agent at the time of a
- request. In many cases, a user agent is installed or configured to
- run in the background and save its results for later inspection (or
- save only a subset of those results that might be interesting or
- erroneous). Spiders, for example, are typically given a start URI
- and configured to follow certain behavior while crawling the Web as a
- hypertext graph.
-
- The implementation diversity of HTTP means that not all user agents
- can make interactive suggestions to their user or provide adequate
- warning for security or privacy concerns. In the few cases where
- this specification requires reporting of errors to the user, it is
- acceptable for such reporting to only be observable in an error
- console or log file. Likewise, requirements that an automated action
- be confirmed by the user before proceeding might be met via advance
- configuration choices, run-time options, or simple avoidance of the
- unsafe action; confirmation does not imply any specific user
- interface or interruption of normal processing if the user has
- already made that choice.
-
-2.3. Intermediaries
-
- HTTP enables the use of intermediaries to satisfy requests through a
- chain of connections. There are three common forms of HTTP
- intermediary: proxy, gateway, and tunnel. In some cases, a single
- intermediary might act as an origin server, proxy, gateway, or
- tunnel, switching behavior based on the nature of each request.
-
- > > > >
- UA =========== A =========== B =========== C =========== O
- < < < <
-
- 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.
- Some HTTP communication options might apply only to the connection
- with the nearest, non-tunnel neighbor, only to the endpoints of the
- chain, or to all connections along the chain. Although the diagram
- is linear, each participant might be engaged in multiple,
- simultaneous communications. For example, B might 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
-
-
-
-
-Fielding & Reschke Standards Track [Page 9]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- request. Likewise, later requests might be sent through a different
- path of connections, often based on dynamic configuration for load
- balancing.
-
- The terms "upstream" and "downstream" are used to describe
- directional requirements in relation to the message flow: all
- messages flow from upstream to downstream. The terms "inbound" and
- "outbound" are used to describe directional requirements in relation
- to the request route: "inbound" means toward the origin server and
- "outbound" means toward the user agent.
-
- A "proxy" is a message-forwarding agent that is selected by the
- client, usually via local configuration rules, to receive requests
- for some type(s) of absolute URI and attempt to satisfy those
- requests via translation through the HTTP interface. Some
- translations are minimal, such as for proxy requests for "http" URIs,
- whereas other requests might require translation to and from entirely
- different application-level protocols. Proxies are often used to
- group an organization's HTTP requests through a common intermediary
- for the sake of security, annotation services, or shared caching.
- Some proxies are designed to apply transformations to selected
- messages or payloads while they are being forwarded, as described in
- Section 5.7.2.
-
- A "gateway" (a.k.a. "reverse proxy") is an intermediary that acts as
- an origin server for the outbound connection but translates received
- requests and forwards them inbound to another server or servers.
- Gateways are often used to encapsulate legacy or untrusted
- information services, to improve server performance through
- "accelerator" caching, and to enable partitioning or load balancing
- of HTTP services across multiple machines.
-
- All HTTP requirements applicable to an origin server also apply to
- the outbound communication of a gateway. A gateway communicates with
- inbound servers using any protocol that it desires, including private
- extensions to HTTP that are outside the scope of this specification.
- However, an HTTP-to-HTTP gateway that wishes to interoperate with
- third-party HTTP servers ought to conform to user agent requirements
- on the gateway's inbound connection.
-
- A "tunnel" acts as a blind relay between two connections without
- changing the messages. Once active, a tunnel is not considered a
- party to the HTTP communication, though the tunnel might have been
- initiated by an HTTP request. A tunnel ceases to exist when both
- ends of the relayed connection are closed. Tunnels are used to
- extend a virtual connection through an intermediary, such as when
- Transport Layer Security (TLS, [RFC5246]) is used to establish
- confidential communication through a shared firewall proxy.
-
-
-
-Fielding & Reschke Standards Track [Page 10]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- The above categories for intermediary only consider those acting as
- participants in the HTTP communication. There are also
- intermediaries that can act on lower layers of the network protocol
- stack, filtering or redirecting HTTP traffic without the knowledge or
- permission of message senders. Network intermediaries are
- indistinguishable (at a protocol level) from a man-in-the-middle
- attack, often introducing security flaws or interoperability problems
- due to mistakenly violating HTTP semantics.
-
- For example, an "interception proxy" [RFC3040] (also commonly known
- as a "transparent proxy" [RFC1919] or "captive portal") differs from
- an HTTP proxy because it is not selected by the client. Instead, an
- interception proxy filters or redirects outgoing TCP port 80 packets
- (and occasionally other common port traffic). Interception proxies
- are commonly found on public network access points, as a means of
- enforcing account subscription prior to allowing use of non-local
- Internet services, and within corporate firewalls to enforce network
- usage policies.
-
- HTTP is defined as a stateless protocol, meaning that each request
- message can be understood in isolation. Many implementations depend
- on HTTP's stateless design in order to reuse proxied connections or
- dynamically load balance requests across multiple servers. Hence, a
- server MUST NOT assume that two requests on the same connection are
- from the same user agent unless the connection is secured and
- specific to that agent. Some non-standard HTTP extensions (e.g.,
- [RFC4559]) have been known to violate this requirement, resulting in
- security and interoperability problems.
-
-2.4. Caches
-
- A "cache" is a local store of previous 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 employ a cache, though a cache
- cannot be used by a server while it is acting as a tunnel.
-
- 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 that has not been cached by UA or A.
-
- > >
- UA =========== A =========== B - - - - - - C - - - - - - O
- < <
-
-
-
-
-Fielding & Reschke Standards Track [Page 11]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- A response is "cacheable" if a cache is allowed to store a copy of
- the response message for use in answering subsequent requests. Even
- when a response is cacheable, there might be additional constraints
- placed by the client or by the origin server on when that cached
- response can be used for a particular request. HTTP requirements for
- cache behavior and cacheable responses are defined in Section 2 of
- [RFC7234].
-
- There is a wide variety of architectures and configurations of caches
- deployed across the World Wide Web and inside large organizations.
- These include national hierarchies of proxy caches to save
- transoceanic bandwidth, collaborative systems that broadcast or
- multicast cache entries, archives of pre-fetched cache entries for
- use in off-line or high-latency environments, and so on.
-
-2.5. Conformance and Error Handling
-
- This specification targets conformance criteria according to the role
- of a participant in HTTP communication. Hence, HTTP requirements are
- placed on senders, recipients, clients, servers, user agents,
- intermediaries, origin servers, proxies, gateways, or caches,
- depending on what behavior is being constrained by the requirement.
- Additional (social) requirements are placed on implementations,
- resource owners, and protocol element registrations when they apply
- beyond the scope of a single communication.
-
- The verb "generate" is used instead of "send" where a requirement
- differentiates between creating a protocol element and merely
- forwarding a received element downstream.
-
- An implementation is considered conformant if it complies with all of
- the requirements associated with the roles it partakes in HTTP.
-
- Conformance includes both the syntax and semantics of protocol
- elements. A sender MUST NOT generate protocol elements that convey a
- meaning that is known by that sender to be false. A sender MUST NOT
- generate protocol elements that do not match the grammar defined by
- the corresponding ABNF rules. Within a given message, a sender MUST
- NOT generate protocol elements or syntax alternatives that are only
- allowed to be generated by participants in other roles (i.e., a role
- that the sender does not have for that message).
-
- When a received protocol element is parsed, the recipient MUST be
- able to parse any value of reasonable length that is applicable to
- the recipient's role and that matches the grammar defined by the
- corresponding ABNF rules. Note, however, that some received protocol
- elements might not be parsed. For example, an intermediary
-
-
-
-
-Fielding & Reschke Standards Track [Page 12]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- forwarding a message might parse a header-field into generic
- field-name and field-value components, but then forward the header
- field without further parsing inside the field-value.
-
- HTTP does not have specific length limitations for many of its
- protocol elements because the lengths that might be appropriate will
- vary widely, depending on the deployment context and purpose of the
- implementation. Hence, interoperability between senders and
- recipients depends on shared expectations regarding what is a
- reasonable length for each protocol element. Furthermore, what is
- commonly understood to be a reasonable length for some protocol
- elements has changed over the course of the past two decades of HTTP
- use and is expected to continue changing in the future.
-
- At a minimum, a recipient MUST be able to parse and process protocol
- element lengths that are at least as long as the values that it
- generates for those same protocol elements in other messages. For
- example, an origin server that publishes very long URI references to
- its own resources needs to be able to parse and process those same
- references when received as a request target.
-
- A recipient MUST interpret a received protocol element according to
- the semantics defined for it by this specification, including
- extensions to this specification, unless the recipient has determined
- (through experience or configuration) that the sender incorrectly
- implements what is implied by those semantics. For example, an
- origin server might disregard the contents of a received
- Accept-Encoding header field if inspection of the User-Agent header
- field indicates a specific implementation version that is known to
- fail on receipt of certain content codings.
-
- Unless noted otherwise, a recipient MAY attempt to recover a usable
- protocol element from an invalid construct. HTTP does not define
- specific error handling mechanisms except when they have a direct
- impact on security, since different applications of the protocol
- require different error handling strategies. For example, a Web
- browser might wish to transparently recover from a response where the
- Location header field doesn't parse according to the ABNF, whereas a
- systems control client might consider any form of error recovery to
- be dangerous.
-
-2.6. Protocol Versioning
-
- HTTP uses a "<major>.<minor>" numbering scheme to indicate versions
- of the protocol. This specification defines version "1.1". The
- protocol version as a whole indicates the sender's conformance with
- the set of requirements laid out in that version's corresponding
- specification of HTTP.
-
-
-
-Fielding & Reschke Standards Track [Page 13]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- The version of an HTTP message is indicated by an HTTP-version field
- in the first line of the message. HTTP-version is case-sensitive.
-
- HTTP-version = HTTP-name "/" DIGIT "." DIGIT
- HTTP-name = %x48.54.54.50 ; "HTTP", case-sensitive
-
- The HTTP version number consists of two decimal digits separated by a
- "." (period or decimal point). The first digit ("major version")
- indicates the HTTP messaging syntax, whereas the second digit ("minor
- version") indicates the highest minor version within that major
- version to which the sender is conformant and able to understand for
- future communication. The minor version advertises the sender's
- communication capabilities even when the sender is only using a
- backwards-compatible subset of the protocol, thereby letting the
- recipient know that more advanced features can be used in response
- (by servers) or in future requests (by clients).
-
- When an HTTP/1.1 message is sent to an HTTP/1.0 recipient [RFC1945]
- or a recipient whose version is unknown, the HTTP/1.1 message is
- constructed such that it can be interpreted as a valid HTTP/1.0
- message if all of the newer features are ignored. This specification
- places recipient-version requirements on some new features so that a
- conformant sender will only use compatible features until it has
- determined, through configuration or the receipt of a message, that
- the recipient supports HTTP/1.1.
-
- The interpretation of a header field does not change between minor
- versions of the same major HTTP version, though the default behavior
- of a recipient in the absence of such a field can change. Unless
- specified otherwise, header fields defined in HTTP/1.1 are defined
- for all versions of HTTP/1.x. In particular, the Host and Connection
- header fields ought to be implemented by all HTTP/1.x implementations
- whether or not they advertise conformance with HTTP/1.1.
-
- New header fields can be introduced without changing the protocol
- version if their defined semantics allow them to be safely ignored by
- recipients that do not recognize them. Header field extensibility is
- discussed in Section 3.2.1.
-
- Intermediaries that process HTTP messages (i.e., all intermediaries
- other than those acting as tunnels) MUST send their own HTTP-version
- in forwarded messages. In other words, they are not allowed to
- blindly forward the first line of an HTTP message without ensuring
- that the protocol version in that message matches a version to which
- that intermediary is conformant for both the receiving and sending of
- messages. Forwarding an HTTP message without rewriting the
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 14]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- HTTP-version might result in communication errors when downstream
- recipients use the message sender's version to determine what
- features are safe to use for later communication with that sender.
-
- A client SHOULD send a request version equal to the highest version
- to which the client is conformant and whose major version is no
- higher than the highest version supported by the server, if this is
- known. A client MUST NOT send a version to which it is not
- conformant.
-
- A client MAY send a lower request version if it is known that the
- server incorrectly implements the HTTP specification, but only after
- the client has attempted at least one normal request and determined
- from the response status code or header fields (e.g., Server) that
- the server improperly handles higher request versions.
-
- A server SHOULD send a response version equal to the highest version
- to which the server is conformant that has a major version less than
- or equal to the one received in the request. A server MUST NOT send
- a version to which it is not conformant. A server can send a 505
- (HTTP Version Not Supported) response if it wishes, for any reason,
- to refuse service of the client's major protocol version.
-
- A server MAY send an HTTP/1.0 response to a request if it is known or
- suspected that the client incorrectly implements the HTTP
- specification and is incapable of correctly processing later version
- responses, such as when a client fails to parse the version number
- correctly or when an intermediary is known to blindly forward the
- HTTP-version even when it doesn't conform to the given minor version
- of the protocol. Such protocol downgrades SHOULD NOT be performed
- unless triggered by specific client attributes, such as when one or
- more of the request header fields (e.g., User-Agent) uniquely match
- the values sent by a client known to be in error.
-
- The intention of HTTP's versioning design is that the major number
- will only be incremented if an incompatible message syntax is
- introduced, and that the minor number will only be incremented when
- changes made to the protocol have the effect of adding to the message
- semantics or implying additional capabilities of the sender.
- However, the minor version was not incremented for the changes
- introduced between [RFC2068] and [RFC2616], and this revision has
- specifically avoided any such changes to the protocol.
-
- When an HTTP message is received with a major version number that the
- recipient implements, but a higher minor version number than what the
- recipient implements, the recipient SHOULD process the message as if
- it were in the highest minor version within that major version to
- which the recipient is conformant. A recipient can assume that a
-
-
-
-Fielding & Reschke Standards Track [Page 15]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- message with a higher minor version, when sent to a recipient that
- has not yet indicated support for that higher version, is
- sufficiently backwards-compatible to be safely processed by any
- implementation of the same major version.
-
-2.7. Uniform Resource Identifiers
-
- Uniform Resource Identifiers (URIs) [RFC3986] are used throughout
- HTTP as the means for identifying resources (Section 2 of [RFC7231]).
- URI references are used to target requests, indicate redirects, and
- define relationships.
-
- The definitions of "URI-reference", "absolute-URI", "relative-part",
- "scheme", "authority", "port", "host", "path-abempty", "segment",
- "query", and "fragment" are adopted from the URI generic syntax. An
- "absolute-path" rule is defined for protocol elements that can
- contain a non-empty path component. (This rule differs slightly from
- the path-abempty rule of RFC 3986, which allows for an empty path to
- be used in references, and path-absolute rule, which does not allow
- paths that begin with "//".) A "partial-URI" rule is defined for
- protocol elements that can contain a relative URI but not a fragment
- component.
-
- URI-reference = <URI-reference, see [RFC3986], Section 4.1>
- absolute-URI = <absolute-URI, see [RFC3986], Section 4.3>
- relative-part = <relative-part, see [RFC3986], Section 4.2>
- scheme = <scheme, see [RFC3986], Section 3.1>
- authority = <authority, see [RFC3986], Section 3.2>
- uri-host = <host, see [RFC3986], Section 3.2.2>
- port = <port, see [RFC3986], Section 3.2.3>
- path-abempty = <path-abempty, see [RFC3986], Section 3.3>
- segment = <segment, see [RFC3986], Section 3.3>
- query = <query, see [RFC3986], Section 3.4>
- fragment = <fragment, see [RFC3986], Section 3.5>
-
- absolute-path = 1*( "/" segment )
- partial-URI = relative-part [ "?" query ]
-
- Each protocol element in HTTP that allows a URI reference will
- indicate in its ABNF production whether the element allows any form
- of reference (URI-reference), only a URI in absolute form
- (absolute-URI), only the path and optional query components, or some
- combination of the above. Unless otherwise indicated, URI references
- are parsed relative to the effective request URI (Section 5.5).
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 16]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-2.7.1. http URI Scheme
-
- The "http" URI scheme is hereby defined for the purpose of minting
- identifiers according to their association with the hierarchical
- namespace governed by a potential HTTP origin server listening for
- TCP ([RFC0793]) connections on a given port.
-
- http-URI = "http:" "//" authority path-abempty [ "?" query ]
- [ "#" fragment ]
-
- The origin server for an "http" URI is identified by the authority
- component, which includes a host identifier and optional TCP port
- ([RFC3986], Section 3.2.2). The hierarchical path component and
- optional query component serve as an identifier for a potential
- target resource within that origin server's name space. The optional
- fragment component allows for indirect identification of a secondary
- resource, independent of the URI scheme, as defined in Section 3.5 of
- [RFC3986].
-
- A sender MUST NOT generate an "http" URI with an empty host
- identifier. A recipient that processes such a URI reference MUST
- reject it as invalid.
-
- If the host identifier is provided as an IP address, the origin
- server is the listener (if any) on the indicated TCP port at that IP
- address. If host is a registered name, the registered name is an
- indirect identifier for use with a name resolution service, such as
- DNS, to find an address for that origin server. If the port
- subcomponent is empty or not given, TCP port 80 (the reserved port
- for WWW services) is the default.
-
- Note that the presence of a URI with a given authority component does
- not imply that there is always an HTTP server listening for
- connections on that host and port. Anyone can mint a URI. What the
- authority component determines is who has the right to respond
- authoritatively to requests that target the identified resource. The
- delegated nature of registered names and IP addresses creates a
- federated namespace, based on control over the indicated host and
- port, whether or not an HTTP server is present. See Section 9.1 for
- security considerations related to establishing authority.
-
- When an "http" URI is used within a context that calls for access to
- the indicated resource, a client MAY attempt access by resolving the
- host to an IP address, establishing a TCP connection to that address
- on the indicated port, and sending an HTTP request message
- (Section 3) containing the URI's identifying data (Section 5) to the
- server. If the server responds to that request with a non-interim
-
-
-
-
-Fielding & Reschke Standards Track [Page 17]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- HTTP response message, as described in Section 6 of [RFC7231], then
- that response is considered an authoritative answer to the client's
- request.
-
- Although HTTP is independent of the transport protocol, the "http"
- scheme is specific to TCP-based services because the name delegation
- process depends on TCP for establishing authority. An HTTP service
- based on some other underlying connection protocol would presumably
- be identified using a different URI scheme, just as the "https"
- scheme (below) is used for resources that require an end-to-end
- secured connection. Other protocols might also be used to provide
- access to "http" identified resources -- it is only the authoritative
- interface that is specific to TCP.
-
- The URI generic syntax for authority also includes a deprecated
- userinfo subcomponent ([RFC3986], Section 3.2.1) for including user
- authentication information in the URI. Some implementations make use
- of the userinfo component for internal configuration of
- authentication information, such as within command invocation
- options, configuration files, or bookmark lists, even though such
- usage might expose a user identifier or password. A sender MUST NOT
- generate the userinfo subcomponent (and its "@" delimiter) when an
- "http" URI reference is generated within a message as a request
- target or header field value. Before making use of an "http" URI
- reference received from an untrusted source, a recipient SHOULD parse
- for userinfo and treat its presence as an error; it is likely being
- used to obscure the authority for the sake of phishing attacks.
-
-2.7.2. https URI Scheme
-
- The "https" URI scheme is hereby defined for the purpose of minting
- identifiers according to their association with the hierarchical
- namespace governed by a potential HTTP origin server listening to a
- given TCP port for TLS-secured connections ([RFC5246]).
-
- All of the requirements listed above for the "http" scheme are also
- requirements for the "https" scheme, except that TCP port 443 is the
- default if the port subcomponent is empty or not given, and the user
- agent MUST ensure that its connection to the origin server is secured
- through the use of strong encryption, end-to-end, prior to sending
- the first HTTP request.
-
- https-URI = "https:" "//" authority path-abempty [ "?" query ]
- [ "#" fragment ]
-
- Note that the "https" URI scheme depends on both TLS and TCP for
- establishing authority. Resources made available via the "https"
- scheme have no shared identity with the "http" scheme even if their
-
-
-
-Fielding & Reschke Standards Track [Page 18]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- resource identifiers indicate the same authority (the same host
- listening to the same TCP port). They are distinct namespaces and
- are considered to be distinct origin servers. However, an extension
- to HTTP that is defined to apply to entire host domains, such as the
- Cookie protocol [RFC6265], can allow information set by one service
- to impact communication with other services within a matching group
- of host domains.
-
- The process for authoritative access to an "https" identified
- resource is defined in [RFC2818].
-
-2.7.3. http and https URI Normalization and Comparison
-
- Since the "http" and "https" schemes conform to the URI generic
- syntax, such URIs are normalized and compared according to the
- algorithm defined in Section 6 of [RFC3986], using the defaults
- described above for each scheme.
-
- If the port is equal to the default port for a scheme, the normal
- form is to omit the port subcomponent. When not being used in
- absolute form as the request target of an OPTIONS request, an empty
- path component is equivalent to an absolute path of "/", so the
- normal form is to provide a path of "/" instead. The scheme and host
- are case-insensitive and normally provided in lowercase; all other
- components are compared in a case-sensitive manner. Characters other
- than those in the "reserved" set are equivalent to their
- percent-encoded octets: the normal form is to not encode them (see
- Sections 2.1 and 2.2 of [RFC3986]).
-
- For example, the following three URIs are equivalent:
-
- http://example.com:80/~smith/home.html
- http://EXAMPLE.com/%7Esmith/home.html
- http://EXAMPLE.com:/%7esmith/home.html
-
-3. Message Format
-
- All HTTP/1.1 messages consist of a start-line followed by a sequence
- of octets in a format similar to the Internet Message Format
- [RFC5322]: zero or more header fields (collectively referred to as
- the "headers" or the "header section"), an empty line indicating the
- end of the header section, and an optional message body.
-
- HTTP-message = start-line
- *( header-field CRLF )
- CRLF
- [ message-body ]
-
-
-
-
-Fielding & Reschke Standards Track [Page 19]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- The normal procedure for parsing an HTTP message is to read the
- start-line into a structure, read each header field into a hash table
- by field name until the empty line, and then use the parsed data to
- determine if a message body is expected. If a message body has been
- indicated, then it is read as a stream until an amount of octets
- equal to the message body length is read or the connection is closed.
-
- A recipient MUST parse an HTTP message as a sequence of octets in an
- encoding that is a superset of US-ASCII [USASCII]. Parsing an HTTP
- message as a stream of Unicode characters, without regard for the
- specific encoding, creates security vulnerabilities due to the
- varying ways that string processing libraries handle invalid
- multibyte character sequences that contain the octet LF (%x0A).
- String-based parsers can only be safely used within protocol elements
- after the element has been extracted from the message, such as within
- a header field-value after message parsing has delineated the
- individual fields.
-
- An HTTP message can be parsed as a stream for incremental processing
- or forwarding downstream. However, recipients cannot rely on
- incremental delivery of partial messages, since some implementations
- will buffer or delay message forwarding for the sake of network
- efficiency, security checks, or payload transformations.
-
- A sender MUST NOT send whitespace between the start-line and the
- first header field. A recipient that receives whitespace between the
- start-line and the first header field MUST either reject the message
- as invalid or consume each whitespace-preceded line without further
- processing of it (i.e., ignore the entire line, along with any
- subsequent lines preceded by whitespace, until a properly formed
- header field is received or the header section is terminated).
-
- The presence of such whitespace in a request might be an attempt to
- trick a server into ignoring that field or processing the line after
- it as a new request, either of which might result in a security
- vulnerability if other implementations within the request chain
- interpret the same message differently. Likewise, the presence of
- such whitespace in a response might be ignored by some clients or
- cause others to cease parsing.
-
-3.1. Start Line
-
- An HTTP message can be either a request from client to server or a
- response from server to client. Syntactically, the two types of
- message differ only in the start-line, which is either a request-line
- (for requests) or a status-line (for responses), and in the algorithm
- for determining the length of the message body (Section 3.3).
-
-
-
-
-Fielding & Reschke Standards Track [Page 20]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- In theory, a client could receive requests and a server could receive
- responses, distinguishing them by their different start-line formats,
- but, in practice, servers are implemented to only expect a request (a
- response is interpreted as an unknown or invalid request method) and
- clients are implemented to only expect a response.
-
- start-line = request-line / status-line
-
-3.1.1. Request Line
-
- A request-line begins with a method token, followed by a single space
- (SP), the request-target, another single space (SP), the protocol
- version, and ends with CRLF.
-
- request-line = method SP request-target SP HTTP-version CRLF
-
- The method token indicates the request method to be performed on the
- target resource. The request method is case-sensitive.
-
- method = token
-
- The request methods defined by this specification can be found in
- Section 4 of [RFC7231], along with information regarding the HTTP
- method registry and considerations for defining new methods.
-
- The request-target identifies the target resource upon which to apply
- the request, as defined in Section 5.3.
-
- Recipients typically parse the request-line into its component parts
- by splitting on whitespace (see Section 3.5), since no whitespace is
- allowed in the three components. Unfortunately, some user agents
- fail to properly encode or exclude whitespace found in hypertext
- references, resulting in those disallowed characters being sent in a
- request-target.
-
- Recipients of an invalid request-line SHOULD respond with either a
- 400 (Bad Request) error or a 301 (Moved Permanently) redirect with
- the request-target properly encoded. A recipient SHOULD NOT attempt
- to autocorrect and then process the request without a redirect, since
- the invalid request-line might be deliberately crafted to bypass
- security filters along the request chain.
-
- HTTP does not place a predefined limit on the length of a
- request-line, as described in Section 2.5. A server that receives a
- method longer than any that it implements SHOULD respond with a 501
- (Not Implemented) status code. A server that receives a
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 21]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- request-target longer than any URI it wishes to parse MUST respond
- with a 414 (URI Too Long) status code (see Section 6.5.12 of
- [RFC7231]).
-
- Various ad hoc limitations on request-line length are found in
- practice. It is RECOMMENDED that all HTTP senders and recipients
- support, at a minimum, request-line lengths of 8000 octets.
-
-3.1.2. Status Line
-
- The first line of a response message is the status-line, consisting
- of the protocol version, a space (SP), the status code, another
- space, a possibly empty textual phrase describing the status code,
- and ending with CRLF.
-
- status-line = HTTP-version SP status-code SP reason-phrase CRLF
-
- The status-code element is a 3-digit integer code describing the
- result of the server's attempt to understand and satisfy the client's
- corresponding request. The rest of the response message is to be
- interpreted in light of the semantics defined for that status code.
- See Section 6 of [RFC7231] for information about the semantics of
- status codes, including the classes of status code (indicated by the
- first digit), the status codes defined by this specification,
- considerations for the definition of new status codes, and the IANA
- registry.
-
- status-code = 3DIGIT
-
- The reason-phrase element exists for the sole purpose of providing a
- textual description associated with the numeric status code, mostly
- out of deference to earlier Internet application protocols that were
- more frequently used with interactive text clients. A client SHOULD
- ignore the reason-phrase content.
-
- reason-phrase = *( HTAB / SP / VCHAR / obs-text )
-
-3.2. Header Fields
-
- Each header field consists of a case-insensitive field name followed
- by a colon (":"), optional leading whitespace, the field value, and
- optional trailing whitespace.
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 22]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- header-field = field-name ":" OWS field-value OWS
-
- field-name = token
- field-value = *( field-content / obs-fold )
- field-content = field-vchar [ 1*( SP / HTAB ) field-vchar ]
- field-vchar = VCHAR / obs-text
-
- obs-fold = CRLF 1*( SP / HTAB )
- ; obsolete line folding
- ; see Section 3.2.4
-
- The field-name token labels the corresponding field-value as having
- the semantics defined by that header field. For example, the Date
- header field is defined in Section 7.1.1.2 of [RFC7231] as containing
- the origination timestamp for the message in which it appears.
-
-3.2.1. Field Extensibility
-
- Header fields are fully extensible: there is no limit on the
- introduction of new field names, each presumably defining new
- semantics, nor on the number of header fields used in a given
- message. Existing fields are defined in each part of this
- specification and in many other specifications outside this document
- set.
-
- New header fields can be defined such that, when they are understood
- by a recipient, they might override or enhance the interpretation of
- previously defined header fields, define preconditions on request
- evaluation, or refine the meaning of responses.
-
- A proxy MUST forward unrecognized header fields unless the field-name
- is listed in the Connection header field (Section 6.1) or the proxy
- is specifically configured to block, or otherwise transform, such
- fields. Other recipients SHOULD ignore unrecognized header fields.
- These requirements allow HTTP's functionality to be enhanced without
- requiring prior update of deployed intermediaries.
-
- All defined header fields ought to be registered with IANA in the
- "Message Headers" registry, as described in Section 8.3 of [RFC7231].
-
-3.2.2. Field Order
-
- The order in which header fields with differing field names are
- received is not significant. However, it is good practice to send
- header fields that contain control data first, such as Host on
- requests and Date on responses, so that implementations can decide
- when not to handle a message as early as possible. A server MUST NOT
- apply a request to the target resource until the entire request
-
-
-
-Fielding & Reschke Standards Track [Page 23]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- header section is received, since later header fields might include
- conditionals, authentication credentials, or deliberately misleading
- duplicate header fields that would impact request processing.
-
- A sender MUST NOT generate multiple header fields with the same field
- name in a message unless either the entire field value for that
- header field is defined as a comma-separated list [i.e., #(values)]
- or the header field is a well-known exception (as noted below).
-
- A recipient MAY combine multiple header fields with the same field
- name into one "field-name: field-value" pair, without changing the
- semantics of the message, by appending each subsequent field value to
- the combined field value in order, 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; a proxy MUST NOT change the order of these field values when
- forwarding a message.
-
- Note: In practice, the "Set-Cookie" header field ([RFC6265]) often
- appears multiple times in a response message and does not use the
- list syntax, violating the above requirements on multiple header
- fields with the same name. Since it cannot be combined into a
- single field-value, recipients ought to handle "Set-Cookie" as a
- special case while processing header fields. (See Appendix A.2.3
- of [Kri2001] for details.)
-
-3.2.3. Whitespace
-
- This specification uses three rules to denote the use of linear
- whitespace: OWS (optional whitespace), RWS (required whitespace), and
- BWS ("bad" whitespace).
-
- The OWS rule is used where zero or more linear whitespace octets
- might appear. For protocol elements where optional whitespace is
- preferred to improve readability, a sender SHOULD generate the
- optional whitespace as a single SP; otherwise, a sender SHOULD NOT
- generate optional whitespace except as needed to white out invalid or
- unwanted protocol elements during in-place message filtering.
-
- The RWS rule is used when at least one linear whitespace octet is
- required to separate field tokens. A sender SHOULD generate RWS as a
- single SP.
-
- The BWS rule is used where the grammar allows optional whitespace
- only for historical reasons. A sender MUST NOT generate BWS in
- messages. A recipient MUST parse for such bad whitespace and remove
- it before interpreting the protocol element.
-
-
-
-
-Fielding & Reschke Standards Track [Page 24]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- OWS = *( SP / HTAB )
- ; optional whitespace
- RWS = 1*( SP / HTAB )
- ; required whitespace
- BWS = OWS
- ; "bad" whitespace
-
-3.2.4. Field Parsing
-
- Messages are parsed using a generic algorithm, independent of the
- individual header field names. The contents within a given field
- value are not parsed until a later stage of message interpretation
- (usually after the message's entire header section has been
- processed). Consequently, this specification does not use ABNF rules
- to define each "Field-Name: Field Value" pair, as was done in
- previous editions. Instead, this specification uses ABNF rules that
- are named according to each registered field name, wherein the rule
- defines the valid grammar for that field's corresponding field values
- (i.e., after the field-value has been extracted from the header
- section by a generic field parser).
-
- No whitespace is allowed between the header field-name and colon. In
- the past, differences in the handling of such whitespace have led to
- security vulnerabilities in request routing and response handling. A
- server MUST reject any received request message that contains
- whitespace between a header field-name and colon with a response code
- of 400 (Bad Request). A proxy MUST remove any such whitespace from a
- response message before forwarding the message downstream.
-
- A field value might be preceded and/or followed by optional
- whitespace (OWS); a single SP preceding the field-value is preferred
- for consistent readability by humans. The field value does not
- include any leading or trailing whitespace: OWS occurring before the
- first non-whitespace octet of the field value or after the last
- non-whitespace octet of the field value ought to be excluded by
- parsers when extracting the field value from a header field.
-
- Historically, HTTP header field values could be extended over
- multiple lines by preceding each extra line with at least one space
- or horizontal tab (obs-fold). This specification deprecates such
- line folding except within the message/http media type
- (Section 8.3.1). A sender MUST NOT generate a message that includes
- line folding (i.e., that has any field-value that contains a match to
- the obs-fold rule) unless the message is intended for packaging
- within the message/http media type.
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 25]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- A server that receives an obs-fold in a request message that is not
- within a message/http container MUST either reject the message by
- sending a 400 (Bad Request), preferably with a representation
- explaining that obsolete line folding is unacceptable, or replace
- each received obs-fold with one or more SP octets prior to
- interpreting the field value or forwarding the message downstream.
-
- A proxy or gateway that receives an obs-fold in a response message
- that is not within a message/http container MUST either discard the
- message and replace it with a 502 (Bad Gateway) response, preferably
- with a representation explaining that unacceptable line folding was
- received, or replace each received obs-fold with one or more SP
- octets prior to interpreting the field value or forwarding the
- message downstream.
-
- A user agent that receives an obs-fold in a response message that is
- not within a message/http container MUST replace each received
- obs-fold with one or more SP octets prior to interpreting the field
- value.
-
- Historically, HTTP has allowed field content with text in the
- ISO-8859-1 charset [ISO-8859-1], supporting other charsets only
- through use of [RFC2047] encoding. In practice, most HTTP header
- field values use only a subset of the US-ASCII charset [USASCII].
- Newly defined header fields SHOULD limit their field values to
- US-ASCII octets. A recipient SHOULD treat other octets in field
- content (obs-text) as opaque data.
-
-3.2.5. Field Limits
-
- HTTP does not place a predefined limit on the length of each header
- field or on the length of the header section as a whole, as described
- in Section 2.5. Various ad hoc limitations on individual header
- field length are found in practice, often depending on the specific
- field semantics.
-
- A server that receives a request header field, or set of fields,
- larger than it wishes to process MUST respond with an appropriate 4xx
- (Client Error) status code. Ignoring such header fields would
- increase the server's vulnerability to request smuggling attacks
- (Section 9.5).
-
- A client MAY discard or truncate received header fields that are
- larger than the client wishes to process if the field semantics are
- such that the dropped value(s) can be safely ignored without changing
- the message framing or response semantics.
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 26]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-3.2.6. Field Value Components
-
- Most HTTP header field values are defined using common syntax
- components (token, quoted-string, and comment) separated by
- whitespace or specific delimiting characters. Delimiters are chosen
- from the set of US-ASCII visual characters not allowed in a token
- (DQUOTE and "(),/:;<=>?@[\]{}").
-
- token = 1*tchar
-
- tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*"
- / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~"
- / DIGIT / ALPHA
- ; any VCHAR, except delimiters
-
- A string of text is parsed as a single value if it is quoted using
- double-quote marks.
-
- quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE
- qdtext = HTAB / SP /%x21 / %x23-5B / %x5D-7E / obs-text
- obs-text = %x80-FF
-
- 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.
-
- comment = "(" *( ctext / quoted-pair / comment ) ")"
- ctext = HTAB / SP / %x21-27 / %x2A-5B / %x5D-7E / obs-text
-
- The backslash octet ("\") can be used as a single-octet quoting
- mechanism within quoted-string and comment constructs. Recipients
- that process the value of a quoted-string MUST handle a quoted-pair
- as if it were replaced by the octet following the backslash.
-
- quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text )
-
- A sender SHOULD NOT generate a quoted-pair in a quoted-string except
- where necessary to quote DQUOTE and backslash octets occurring within
- that string. A sender SHOULD NOT generate a quoted-pair in a comment
- except where necessary to quote parentheses ["(" and ")"] and
- backslash octets occurring within that comment.
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 27]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-3.3. Message Body
-
- The message body (if any) of an HTTP message is used to carry the
- payload body of that request or response. The message body is
- identical to the payload body unless a transfer coding has been
- applied, as described in Section 3.3.1.
-
- message-body = *OCTET
-
- 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 a
- Content-Length or Transfer-Encoding header field. Request message
- framing is independent of method semantics, even if the method does
- not define any use for a message body.
-
- The presence of a message body in a response depends on both the
- request method to which it is responding and the response status code
- (Section 3.1.2). Responses to the HEAD request method (Section 4.3.2
- of [RFC7231]) never include a message body because the associated
- response header fields (e.g., Transfer-Encoding, Content-Length,
- etc.), if present, indicate only what their values would have been if
- the request method had been GET (Section 4.3.1 of [RFC7231]). 2xx
- (Successful) responses to a CONNECT request method (Section 4.3.6 of
- [RFC7231]) switch to tunnel mode instead of having a message body.
- All 1xx (Informational), 204 (No Content), and 304 (Not Modified)
- responses do not include a message body. All other responses do
- include a message body, although the body might be of zero length.
-
-3.3.1. Transfer-Encoding
-
- The Transfer-Encoding header field lists the transfer coding names
- corresponding to the sequence of transfer codings that have been (or
- will be) applied to the payload body in order to form the message
- body. Transfer codings are defined in Section 4.
-
- Transfer-Encoding = 1#transfer-coding
-
- Transfer-Encoding is analogous to the Content-Transfer-Encoding field
- of MIME, which was designed to enable safe transport of binary data
- over a 7-bit transport service ([RFC2045], Section 6). However, safe
- transport has a different focus for an 8bit-clean transfer protocol.
- In HTTP's case, Transfer-Encoding is primarily intended to accurately
- delimit a dynamically generated payload and to distinguish payload
- encodings that are only applied for transport efficiency or security
- from those that are characteristics of the selected resource.
-
-
-
-
-Fielding & Reschke Standards Track [Page 28]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- A recipient MUST be able to parse the chunked transfer coding
- (Section 4.1) because it plays a crucial role in framing messages
- when the payload body size is not known in advance. A sender MUST
- NOT apply chunked more than once to a message body (i.e., chunking an
- already chunked message is not allowed). If any transfer coding
- other than chunked is applied to a request payload body, the sender
- MUST apply chunked as the final transfer coding to ensure that the
- message is properly framed. If any transfer coding other than
- chunked is applied to a response payload body, the sender MUST either
- apply chunked as the final transfer coding or terminate the message
- by closing the connection.
-
- For example,
-
- Transfer-Encoding: gzip, chunked
-
- indicates that the payload body has been compressed using the gzip
- coding and then chunked using the chunked coding while forming the
- message body.
-
- Unlike Content-Encoding (Section 3.1.2.1 of [RFC7231]),
- Transfer-Encoding is a property of the message, not of the
- representation, and any recipient along the request/response chain
- MAY decode the received transfer coding(s) or apply additional
- transfer coding(s) to the message body, assuming that corresponding
- changes are made to the Transfer-Encoding field-value. Additional
- information about the encoding parameters can be provided by other
- header fields not defined by this specification.
-
- Transfer-Encoding MAY be sent in a response to a HEAD request or in a
- 304 (Not Modified) response (Section 4.1 of [RFC7232]) to a GET
- request, neither of which includes a message body, to indicate that
- the origin server would have applied a transfer coding to the message
- body if the request had been an unconditional GET. This indication
- is not required, however, because any recipient on the response chain
- (including the origin server) can remove transfer codings when they
- are not needed.
-
- A server MUST NOT send a Transfer-Encoding header field in any
- response with a status code of 1xx (Informational) or 204 (No
- Content). A server MUST NOT send a Transfer-Encoding header field in
- any 2xx (Successful) response to a CONNECT request (Section 4.3.6 of
- [RFC7231]).
-
- Transfer-Encoding was added in HTTP/1.1. It is generally assumed
- that implementations advertising only HTTP/1.0 support will not
- understand how to process a transfer-encoded payload. A client MUST
- NOT send a request containing Transfer-Encoding unless it knows the
-
-
-
-Fielding & Reschke Standards Track [Page 29]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- server will handle HTTP/1.1 (or later) requests; such knowledge might
- be in the form of specific user configuration or by remembering the
- version of a prior received response. A server MUST NOT send a
- response containing Transfer-Encoding unless the corresponding
- request indicates HTTP/1.1 (or later).
-
- A server that receives a request message with a transfer coding it
- does not understand SHOULD respond with 501 (Not Implemented).
-
-3.3.2. Content-Length
-
- When a message does not have a Transfer-Encoding header field, a
- Content-Length header field can provide the anticipated size, as a
- decimal number of octets, for a potential payload body. For messages
- that do include a payload body, the Content-Length field-value
- provides the framing information necessary for determining where the
- body (and message) ends. For messages that do not include a payload
- body, the Content-Length indicates the size of the selected
- representation (Section 3 of [RFC7231]).
-
- Content-Length = 1*DIGIT
-
- An example is
-
- Content-Length: 3495
-
- A sender MUST NOT send a Content-Length header field in any message
- that contains a Transfer-Encoding header field.
-
- A user agent SHOULD send a Content-Length in a request message when
- no Transfer-Encoding is sent and the request method defines a meaning
- for an enclosed payload body. For example, a Content-Length header
- field is normally sent in a POST request even when the value is 0
- (indicating an empty payload body). A user agent SHOULD NOT send a
- Content-Length header field when the request message does not contain
- a payload body and the method semantics do not anticipate such a
- body.
-
- A server MAY send a Content-Length header field in a response to a
- HEAD request (Section 4.3.2 of [RFC7231]); a server MUST NOT send
- Content-Length in such a response unless its field-value equals the
- decimal number of octets that would have been sent in the payload
- body of a response if the same request had used the GET method.
-
- A server MAY send a Content-Length header field in a 304 (Not
- Modified) response to a conditional GET request (Section 4.1 of
- [RFC7232]); a server MUST NOT send Content-Length in such a response
-
-
-
-
-Fielding & Reschke Standards Track [Page 30]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- unless its field-value equals the decimal number of octets that would
- have been sent in the payload body of a 200 (OK) response to the same
- request.
-
- A server MUST NOT send a Content-Length header field in any response
- with a status code of 1xx (Informational) or 204 (No Content). A
- server MUST NOT send a Content-Length header field in any 2xx
- (Successful) response to a CONNECT request (Section 4.3.6 of
- [RFC7231]).
-
- Aside from the cases defined above, in the absence of
- Transfer-Encoding, an origin server SHOULD send a Content-Length
- header field when the payload body size is known prior to sending the
- complete header section. This will allow downstream recipients to
- measure transfer progress, know when a received message is complete,
- and potentially reuse the connection for additional requests.
-
- Any Content-Length field value greater than or equal to zero is
- valid. Since there is no predefined limit to the length of a
- payload, a recipient MUST anticipate potentially large decimal
- numerals and prevent parsing errors due to integer conversion
- overflows (Section 9.3).
-
- If a message is received that has multiple Content-Length header
- fields with field-values consisting of the same decimal value, or a
- single Content-Length header field with a field value containing a
- list of identical decimal values (e.g., "Content-Length: 42, 42"),
- indicating that duplicate Content-Length header fields have been
- generated or combined by an upstream message processor, then the
- recipient MUST either reject the message as invalid or replace the
- duplicated field-values with a single valid Content-Length field
- containing that decimal value prior to determining the message body
- length or forwarding the message.
-
- Note: HTTP's use of Content-Length for message framing differs
- significantly from the same field's use in MIME, where it is an
- optional field used only within the "message/external-body"
- media-type.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 31]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-3.3.3. Message Body Length
-
- The length of a message body is determined by one of the following
- (in order of precedence):
-
- 1. Any response to a HEAD request and any response with a 1xx
- (Informational), 204 (No Content), or 304 (Not Modified) status
- code is always terminated by the first empty line after the
- header fields, regardless of the header fields present in the
- message, and thus cannot contain a message body.
-
- 2. Any 2xx (Successful) response to a CONNECT request implies that
- the connection will become a tunnel immediately after the empty
- line that concludes the header fields. A client MUST ignore any
- Content-Length or Transfer-Encoding header fields received in
- such a message.
-
- 3. If a Transfer-Encoding header field is present and the chunked
- transfer coding (Section 4.1) is the final encoding, the message
- body length is determined by reading and decoding the chunked
- data until the transfer coding indicates the data is complete.
-
- If a Transfer-Encoding header field is present in a response and
- the chunked transfer coding is not the final encoding, the
- message body length is determined by reading the connection until
- it is closed by the server. If a Transfer-Encoding header field
- is present in a request and the chunked transfer coding is not
- the final encoding, the message body length cannot be determined
- reliably; the server MUST respond with the 400 (Bad Request)
- status code and then close the connection.
-
- If a message is received with both a Transfer-Encoding and a
- Content-Length header field, the Transfer-Encoding overrides the
- Content-Length. Such a message might indicate an attempt to
- perform request smuggling (Section 9.5) or response splitting
- (Section 9.4) and ought to be handled as an error. A sender MUST
- remove the received Content-Length field prior to forwarding such
- a message downstream.
-
- 4. If a message is received without Transfer-Encoding and with
- either multiple Content-Length header fields having differing
- field-values or a single Content-Length header field having an
- invalid value, then the message framing is invalid and the
- recipient MUST treat it as an unrecoverable error. If this is a
- request message, the server MUST respond with a 400 (Bad Request)
- status code and then close the connection. If this is a response
- message received by a proxy, the proxy MUST close the connection
- to the server, discard the received response, and send a 502 (Bad
-
-
-
-Fielding & Reschke Standards Track [Page 32]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- Gateway) response to the client. If this is a response message
- received by a user agent, the user agent MUST close the
- connection to the server and discard the received response.
-
- 5. If a valid Content-Length header field is present without
- Transfer-Encoding, its decimal value defines the expected message
- body length in octets. If the sender closes the connection or
- the recipient times out before the indicated number of octets are
- received, the recipient MUST consider the message to be
- incomplete and close the connection.
-
- 6. If this is a request message and none of the above are true, then
- the message body length is zero (no message body is present).
-
- 7. Otherwise, this is a response message without a declared message
- body length, so the message body length is determined by the
- number of octets received prior to the server closing the
- connection.
-
- Since there is no way to distinguish a successfully completed,
- close-delimited message from a partially received message interrupted
- by network failure, a server SHOULD generate encoding or
- length-delimited messages whenever possible. The close-delimiting
- feature exists primarily for backwards compatibility with HTTP/1.0.
-
- A server MAY reject a request that contains a message body but not a
- Content-Length by responding with 411 (Length Required).
-
- Unless a transfer coding other than chunked has been applied, a
- client that sends a request containing a message body SHOULD use a
- valid Content-Length header field if the message body length is known
- in advance, rather than the chunked transfer coding, since some
- existing services respond to chunked with a 411 (Length Required)
- status code even though they understand the chunked transfer coding.
- This is typically because such services are implemented via a gateway
- that requires a content-length in advance of being called and the
- server is unable or unwilling to buffer the entire request before
- processing.
-
- A user agent that sends a request containing a message body MUST send
- a valid Content-Length header field if it does not know the server
- will handle HTTP/1.1 (or later) requests; such knowledge can be in
- the form of specific user configuration or by remembering the version
- of a prior received response.
-
- If the final response to the last request on a connection has been
- completely received and there remains additional data to read, a user
- agent MAY discard the remaining data or attempt to determine if that
-
-
-
-Fielding & Reschke Standards Track [Page 33]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- data belongs as part of the prior response body, which might be the
- case if the prior message's Content-Length value is incorrect. A
- client MUST NOT process, cache, or forward such extra data as a
- separate response, since such behavior would be vulnerable to cache
- poisoning.
-
-3.4. Handling Incomplete Messages
-
- A server that receives an incomplete request message, usually due to
- a canceled request or a triggered timeout exception, MAY send an
- error response prior to closing the connection.
-
- A client that receives an incomplete response message, which can
- occur when a connection is closed prematurely or when decoding a
- supposedly chunked transfer coding fails, MUST record the message as
- incomplete. Cache requirements for incomplete responses are defined
- in Section 3 of [RFC7234].
-
- If a response terminates in the middle of the header section (before
- the empty line is received) and the status code might rely on header
- fields to convey the full meaning of the response, then the client
- cannot assume that meaning has been conveyed; the client might need
- to repeat the request in order to determine what action to take next.
-
- A message body that uses the chunked transfer coding is incomplete if
- the zero-sized chunk that terminates the encoding has not been
- received. A message that uses a valid Content-Length is incomplete
- if the size of the message body received (in octets) is less than the
- value given by Content-Length. A response that has neither chunked
- transfer coding nor Content-Length is terminated by closure of the
- connection and, thus, is considered complete regardless of the number
- of message body octets received, provided that the header section was
- received intact.
-
-3.5. Message Parsing Robustness
-
- Older HTTP/1.0 user agent implementations might send an extra CRLF
- after a POST request as a workaround for some early server
- applications that failed to read message body content that was not
- terminated by a line-ending. An HTTP/1.1 user agent MUST NOT preface
- or follow a request with an extra CRLF. If terminating the request
- message body with a line-ending is desired, then the user agent MUST
- count the terminating CRLF octets as part of the message body length.
-
- In the interest of robustness, a server that is expecting to receive
- and parse a request-line SHOULD ignore at least one empty line (CRLF)
- received prior to the request-line.
-
-
-
-
-Fielding & Reschke Standards Track [Page 34]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- Although the line terminator for the start-line and header fields is
- the sequence CRLF, a recipient MAY recognize a single LF as a line
- terminator and ignore any preceding CR.
-
- Although the request-line and status-line grammar rules require that
- each of the component elements be separated by a single SP octet,
- recipients MAY instead parse on whitespace-delimited word boundaries
- and, aside from the CRLF terminator, treat any form of whitespace as
- the SP separator while ignoring preceding or trailing whitespace;
- such whitespace includes one or more of the following octets: SP,
- HTAB, VT (%x0B), FF (%x0C), or bare CR. However, lenient parsing can
- result in security vulnerabilities if there are multiple recipients
- of the message and each has its own unique interpretation of
- robustness (see Section 9.5).
-
- When a server listening only for HTTP request messages, or processing
- what appears from the start-line to be an HTTP request message,
- receives a sequence of octets that does not match the HTTP-message
- grammar aside from the robustness exceptions listed above, the server
- SHOULD respond with a 400 (Bad Request) response.
-
-4. Transfer Codings
-
- Transfer coding names are used to indicate an encoding transformation
- that has been, can be, or might need to be applied to a payload 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 rather than a property of the representation
- that is being transferred.
-
- transfer-coding = "chunked" ; Section 4.1
- / "compress" ; Section 4.2.1
- / "deflate" ; Section 4.2.2
- / "gzip" ; Section 4.2.3
- / transfer-extension
- transfer-extension = token *( OWS ";" OWS transfer-parameter )
-
- Parameters are in the form of a name or name=value pair.
-
- transfer-parameter = token BWS "=" BWS ( token / quoted-string )
-
- All transfer-coding names are case-insensitive and ought to be
- registered within the HTTP Transfer Coding registry, as defined in
- Section 8.4. They are used in the TE (Section 4.3) and
- Transfer-Encoding (Section 3.3.1) header fields.
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 35]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-4.1. Chunked Transfer Coding
-
- The chunked transfer coding wraps the payload body in order to
- transfer it as a series of chunks, each with its own size indicator,
- followed by an OPTIONAL trailer containing header fields. Chunked
- enables content streams of unknown size to be transferred as a
- sequence of length-delimited buffers, which enables the sender to
- retain connection persistence and the recipient to know when it has
- received the entire message.
-
- chunked-body = *chunk
- last-chunk
- trailer-part
- CRLF
-
- chunk = chunk-size [ chunk-ext ] CRLF
- chunk-data CRLF
- chunk-size = 1*HEXDIG
- last-chunk = 1*("0") [ chunk-ext ] CRLF
-
- chunk-data = 1*OCTET ; a sequence of chunk-size octets
-
- The chunk-size field is a string of hex digits indicating the size of
- the chunk-data in octets. The chunked transfer coding is complete
- when a chunk with a chunk-size of zero is received, possibly followed
- by a trailer, and finally terminated by an empty line.
-
- A recipient MUST be able to parse and decode the chunked transfer
- coding.
-
-4.1.1. Chunk Extensions
-
- The chunked encoding allows each chunk to include zero or more chunk
- extensions, immediately following the chunk-size, for the sake of
- supplying per-chunk metadata (such as a signature or hash),
- mid-message control information, or randomization of message body
- size.
-
- chunk-ext = *( ";" chunk-ext-name [ "=" chunk-ext-val ] )
-
- chunk-ext-name = token
- chunk-ext-val = token / quoted-string
-
- The chunked encoding is specific to each connection and is likely to
- be removed or recoded by each recipient (including intermediaries)
- before any higher-level application would have a chance to inspect
- the extensions. Hence, use of chunk extensions is generally limited
-
-
-
-
-Fielding & Reschke Standards Track [Page 36]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- to specialized HTTP services such as "long polling" (where client and
- server can have shared expectations regarding the use of chunk
- extensions) or for padding within an end-to-end secured connection.
-
- A recipient MUST ignore unrecognized chunk extensions. A server
- ought to limit the total length of chunk extensions received in a
- request to an amount reasonable for the services provided, in the
- same way that it applies length limitations and timeouts for other
- parts of a message, and generate an appropriate 4xx (Client Error)
- response if that amount is exceeded.
-
-4.1.2. Chunked Trailer Part
-
- A trailer allows the sender to include additional fields at the end
- of a chunked message in order to supply metadata that might be
- dynamically generated while the message body is sent, such as a
- message integrity check, digital signature, or post-processing
- status. The trailer fields are identical to header fields, except
- they are sent in a chunked trailer instead of the message's header
- section.
-
- trailer-part = *( header-field CRLF )
-
- A sender MUST NOT generate a trailer that contains a field necessary
- for message framing (e.g., Transfer-Encoding and Content-Length),
- routing (e.g., Host), request modifiers (e.g., controls and
- conditionals in Section 5 of [RFC7231]), authentication (e.g., see
- [RFC7235] and [RFC6265]), response control data (e.g., see Section
- 7.1 of [RFC7231]), or determining how to process the payload (e.g.,
- Content-Encoding, Content-Type, Content-Range, and Trailer).
-
- When a chunked message containing a non-empty trailer is received,
- the recipient MAY process the fields (aside from those forbidden
- above) as if they were appended to the message's header section. A
- recipient MUST ignore (or consider as an error) any fields that are
- forbidden to be sent in a trailer, since processing them as if they
- were present in the header section might bypass external security
- filters.
-
- Unless the request includes a TE header field indicating "trailers"
- is acceptable, as described in Section 4.3, a server SHOULD NOT
- generate trailer fields that it believes are necessary for the user
- agent to receive. Without a TE containing "trailers", the server
- ought to assume that the trailer fields might be silently discarded
- along the path to the user agent. This requirement allows
- intermediaries to forward a de-chunked message to an HTTP/1.0
- recipient without buffering the entire response.
-
-
-
-
-Fielding & Reschke Standards Track [Page 37]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-4.1.3. Decoding Chunked
-
- A process for decoding the chunked transfer coding can be represented
- in pseudo-code as:
-
- length := 0
- read chunk-size, chunk-ext (if any), and CRLF
- while (chunk-size > 0) {
- read chunk-data and CRLF
- append chunk-data to decoded-body
- length := length + chunk-size
- read chunk-size, chunk-ext (if any), and CRLF
- }
- read trailer field
- while (trailer field is not empty) {
- if (trailer field is allowed to be sent in a trailer) {
- append trailer field to existing header fields
- }
- read trailer-field
- }
- Content-Length := length
- Remove "chunked" from Transfer-Encoding
- Remove Trailer from existing header fields
-
-4.2. Compression Codings
-
- The codings defined below can be used to compress the payload of a
- message.
-
-4.2.1. Compress Coding
-
- The "compress" coding is an adaptive Lempel-Ziv-Welch (LZW) coding
- [Welch] that is commonly produced by the UNIX file compression
- program "compress". A recipient SHOULD consider "x-compress" to be
- equivalent to "compress".
-
-4.2.2. Deflate Coding
-
- The "deflate" coding is a "zlib" data format [RFC1950] containing a
- "deflate" compressed data stream [RFC1951] that uses a combination of
- the Lempel-Ziv (LZ77) compression algorithm and Huffman coding.
-
- Note: Some non-conformant implementations send the "deflate"
- compressed data without the zlib wrapper.
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 38]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-4.2.3. Gzip Coding
-
- The "gzip" coding is an LZ77 coding with a 32-bit Cyclic Redundancy
- Check (CRC) that is commonly produced by the gzip file compression
- program [RFC1952]. A recipient SHOULD consider "x-gzip" to be
- equivalent to "gzip".
-
-4.3. TE
-
- The "TE" header field in a request indicates what transfer codings,
- besides chunked, the client is willing to accept in response, and
- whether or not the client is willing to accept trailer fields in a
- chunked transfer coding.
-
- The TE field-value consists of a comma-separated list of transfer
- coding names, each allowing for optional parameters (as described in
- Section 4), and/or the keyword "trailers". A client MUST NOT send
- the chunked transfer coding name in TE; chunked is always acceptable
- for HTTP/1.1 recipients.
-
- TE = #t-codings
- t-codings = "trailers" / ( transfer-coding [ t-ranking ] )
- t-ranking = OWS ";" OWS "q=" rank
- rank = ( "0" [ "." 0*3DIGIT ] )
- / ( "1" [ "." 0*3("0") ] )
-
- Three examples of TE use are below.
-
- TE: deflate
- TE:
- TE: trailers, deflate;q=0.5
-
- 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 4.1.2, on behalf of itself and any downstream
- clients. For requests from an intermediary, this implies that
- either: (a) all downstream clients are willing to accept trailer
- fields in the forwarded response; or, (b) the intermediary will
- attempt to buffer the response on behalf of downstream recipients.
- Note that HTTP/1.1 does not define any means to limit the size of a
- chunked response such that an intermediary can be assured of
- buffering the entire response.
-
- When multiple transfer codings are acceptable, the client MAY rank
- the codings by preference using a case-insensitive "q" parameter
- (similar to the qvalues used in content negotiation fields, Section
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 39]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- 5.3.1 of [RFC7231]). The rank value is a real number in the range 0
- through 1, where 0.001 is the least preferred and 1 is the most
- preferred; a value of 0 means "not acceptable".
-
- If the TE field-value is empty or if no TE field is present, the only
- acceptable transfer coding is chunked. A message with no transfer
- coding is always acceptable.
-
- Since the TE header field only applies to the immediate connection, a
- sender of TE MUST also send a "TE" connection option within the
- Connection header field (Section 6.1) in order to prevent the TE
- field from being forwarded by intermediaries that do not support its
- semantics.
-
-4.4. Trailer
-
- When a message includes a message body encoded with the chunked
- transfer coding and the sender desires to send metadata in the form
- of trailer fields at the end of the message, the sender SHOULD
- generate a Trailer header field before the message body to indicate
- which fields will be present in the trailers. This allows the
- recipient to prepare for receipt of that metadata before it starts
- processing the body, which is useful if the message is being streamed
- and the recipient wishes to confirm an integrity check on the fly.
-
- Trailer = 1#field-name
-
-5. Message Routing
-
- HTTP request message routing is determined by each client based on
- the target resource, the client's proxy configuration, and
- establishment or reuse of an inbound connection. The corresponding
- response routing follows the same connection chain back to the
- client.
-
-5.1. Identifying a Target Resource
-
- HTTP is used in a wide variety of applications, ranging from
- general-purpose computers to home appliances. In some cases,
- communication options are hard-coded in a client's configuration.
- However, most HTTP clients rely on the same resource identification
- mechanism and configuration techniques as general-purpose Web
- browsers.
-
- HTTP communication is initiated by a user agent for some purpose.
- The purpose is a combination of request semantics, which are defined
- in [RFC7231], and a target resource upon which to apply those
- semantics. A URI reference (Section 2.7) is typically used as an
-
-
-
-Fielding & Reschke Standards Track [Page 40]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- identifier for the "target resource", which a user agent would
- resolve to its absolute form in order to obtain the "target URI".
- The target URI excludes the reference's fragment component, if any,
- since fragment identifiers are reserved for client-side processing
- ([RFC3986], Section 3.5).
-
-5.2. Connecting Inbound
-
- Once the target URI is determined, a client needs to decide whether a
- network request is necessary to accomplish the desired semantics and,
- if so, where that request is to be directed.
-
- If the client has a cache [RFC7234] and the request can be satisfied
- by it, then the request is usually directed there first.
-
- If the request is not satisfied by a cache, then a typical client
- will check its configuration to determine whether a proxy is to be
- used to satisfy the request. Proxy configuration is implementation-
- dependent, but is often based on URI prefix matching, selective
- authority matching, or both, and the proxy itself is usually
- identified by an "http" or "https" URI. If a proxy is applicable,
- the client connects inbound by establishing (or reusing) a connection
- to that proxy.
-
- If no proxy is applicable, a typical client will invoke a handler
- routine, usually specific to the target URI's scheme, to connect
- directly to an authority for the target resource. How that is
- accomplished is dependent on the target URI scheme and defined by its
- associated specification, similar to how this specification defines
- origin server access for resolution of the "http" (Section 2.7.1) and
- "https" (Section 2.7.2) schemes.
-
- HTTP requirements regarding connection management are defined in
- Section 6.
-
-5.3. Request Target
-
- Once an inbound connection is obtained, the client sends an HTTP
- request message (Section 3) with a request-target derived from the
- target URI. There are four distinct formats for the request-target,
- depending on both the method being requested and whether the request
- is to a proxy.
-
- request-target = origin-form
- / absolute-form
- / authority-form
- / asterisk-form
-
-
-
-
-Fielding & Reschke Standards Track [Page 41]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-5.3.1. origin-form
-
- The most common form of request-target is the origin-form.
-
- origin-form = absolute-path [ "?" query ]
-
- When making a request directly to an origin server, other than a
- CONNECT or server-wide OPTIONS request (as detailed below), a client
- MUST send only the absolute path and query components of the target
- URI as the request-target. If the target URI's path component is
- empty, the client MUST send "/" as the path within the origin-form of
- request-target. A Host header field is also sent, as defined in
- Section 5.4.
-
- For example, a client wishing to retrieve a representation of the
- resource identified as
-
- http://www.example.org/where?q=now
-
- directly from the origin server would open (or reuse) a TCP
- connection to port 80 of the host "www.example.org" and send the
- lines:
-
- GET /where?q=now HTTP/1.1
- Host: www.example.org
-
- followed by the remainder of the request message.
-
-5.3.2. absolute-form
-
- When making a request to a proxy, other than a CONNECT or server-wide
- OPTIONS request (as detailed below), a client MUST send the target
- URI in absolute-form as the request-target.
-
- absolute-form = absolute-URI
-
- The proxy is requested to either service that request from a valid
- cache, if possible, or make the same request on the client's behalf
- to either the next inbound proxy server or directly to the origin
- server indicated by the request-target. Requirements on such
- "forwarding" of messages are defined in Section 5.7.
-
- An example absolute-form of request-line would be:
-
- GET http://www.example.org/pub/WWW/TheProject.html HTTP/1.1
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 42]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- To allow for transition to the absolute-form for all requests in some
- future version of HTTP, a server MUST accept the absolute-form in
- requests, even though HTTP/1.1 clients will only send them in
- requests to proxies.
-
-5.3.3. authority-form
-
- The authority-form of request-target is only used for CONNECT
- requests (Section 4.3.6 of [RFC7231]).
-
- authority-form = authority
-
- When making a CONNECT request to establish a tunnel through one or
- more proxies, a client MUST send only the target URI's authority
- component (excluding any userinfo and its "@" delimiter) as the
- request-target. For example,
-
- CONNECT www.example.com:80 HTTP/1.1
-
-5.3.4. asterisk-form
-
- The asterisk-form of request-target is only used for a server-wide
- OPTIONS request (Section 4.3.7 of [RFC7231]).
-
- asterisk-form = "*"
-
- When a client wishes to request OPTIONS for the server as a whole, as
- opposed to a specific named resource of that server, the client MUST
- send only "*" (%x2A) as the request-target. For example,
-
- OPTIONS * HTTP/1.1
-
- If a proxy receives an OPTIONS request with an absolute-form of
- request-target in which the URI has an empty path and no query
- component, then the last proxy on the request chain MUST send a
- request-target of "*" when it forwards the request to the indicated
- origin server.
-
- For example, the request
-
- OPTIONS http://www.example.org:8001 HTTP/1.1
-
- would be forwarded by the final proxy as
-
- OPTIONS * HTTP/1.1
- Host: www.example.org:8001
-
- after connecting to port 8001 of host "www.example.org".
-
-
-
-Fielding & Reschke Standards Track [Page 43]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-5.4. Host
-
- The "Host" header field in a request provides the host and port
- information from the target URI, enabling the origin server to
- distinguish among resources while servicing requests for multiple
- host names on a single IP address.
-
- Host = uri-host [ ":" port ] ; Section 2.7.1
-
- A client MUST send a Host header field in all HTTP/1.1 request
- messages. If the target URI includes an authority component, then a
- client MUST send a field-value for Host that is identical to that
- authority component, excluding any userinfo subcomponent and its "@"
- delimiter (Section 2.7.1). If the authority component is missing or
- undefined for the target URI, then a client MUST send a Host header
- field with an empty field-value.
-
- Since the Host field-value is critical information for handling a
- request, a user agent SHOULD generate Host as the first header field
- following the request-line.
-
- For example, a GET request to the origin server for
- <http://www.example.org/pub/WWW/> would begin with:
-
- GET /pub/WWW/ HTTP/1.1
- Host: www.example.org
-
- A client MUST send a Host header field in an HTTP/1.1 request even if
- the request-target is in the absolute-form, since this allows the
- Host information to be forwarded through ancient HTTP/1.0 proxies
- that might not have implemented Host.
-
- When a proxy receives a request with an absolute-form of
- request-target, the proxy MUST ignore the received Host header field
- (if any) and instead replace it with the host information of the
- request-target. A proxy that forwards such a request MUST generate a
- new Host field-value based on the received request-target rather than
- forward the received Host field-value.
-
- Since the Host header field acts as an application-level routing
- mechanism, it is a frequent target for malware seeking to poison a
- shared cache or redirect a request to an unintended server. An
- interception proxy is particularly vulnerable if it relies on the
- Host field-value for redirecting requests to internal servers, or for
- use as a cache key in a shared cache, without first verifying that
- the intercepted connection is targeting a valid IP address for that
- host.
-
-
-
-
-Fielding & Reschke Standards Track [Page 44]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- A server MUST respond with a 400 (Bad Request) status code to any
- HTTP/1.1 request message that lacks a Host header field and to any
- request message that contains more than one Host header field or a
- Host header field with an invalid field-value.
-
-5.5. Effective Request URI
-
- Since the request-target often contains only part of the user agent's
- target URI, a server reconstructs the intended target as an
- "effective request URI" to properly service the request. This
- reconstruction involves both the server's local configuration and
- information communicated in the request-target, Host header field,
- and connection context.
-
- For a user agent, the effective request URI is the target URI.
-
- If the request-target is in absolute-form, the effective request URI
- is the same as the request-target. Otherwise, the effective request
- URI is constructed as follows:
-
- If the server's configuration (or outbound gateway) provides a
- fixed URI scheme, that scheme is used for the effective request
- URI. Otherwise, if the request is received over a TLS-secured TCP
- connection, the effective request URI's scheme is "https"; if not,
- the scheme is "http".
-
- If the server's configuration (or outbound gateway) provides a
- fixed URI authority component, that authority is used for the
- effective request URI. If not, then if the request-target is in
- authority-form, the effective request URI's authority component is
- the same as the request-target. If not, then if a Host header
- field is supplied with a non-empty field-value, the authority
- component is the same as the Host field-value. Otherwise, the
- authority component is assigned the default name configured for
- the server and, if the connection's incoming TCP port number
- differs from the default port for the effective request URI's
- scheme, then a colon (":") and the incoming port number (in
- decimal form) are appended to the authority component.
-
- If the request-target is in authority-form or asterisk-form, the
- effective request URI's combined path and query component is
- empty. Otherwise, the combined path and query component is the
- same as the request-target.
-
- The components of the effective request URI, once determined as
- above, can be combined into absolute-URI form by concatenating the
- scheme, "://", authority, and combined path and query component.
-
-
-
-
-Fielding & Reschke Standards Track [Page 45]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- Example 1: the following message received over an insecure TCP
- connection
-
- GET /pub/WWW/TheProject.html HTTP/1.1
- Host: www.example.org:8080
-
- has an effective request URI of
-
- http://www.example.org:8080/pub/WWW/TheProject.html
-
- Example 2: the following message received over a TLS-secured TCP
- connection
-
- OPTIONS * HTTP/1.1
- Host: www.example.org
-
- has an effective request URI of
-
- https://www.example.org
-
- Recipients of an HTTP/1.0 request that lacks a Host header field
- might need to use heuristics (e.g., examination of the URI path for
- something unique to a particular host) in order to guess the
- effective request URI's authority component.
-
- Once the effective request URI has been constructed, an origin server
- needs to decide whether or not to provide service for that URI via
- the connection in which the request was received. For example, the
- request might have been misdirected, deliberately or accidentally,
- such that the information within a received request-target or Host
- header field differs from the host or port upon which the connection
- has been made. If the connection is from a trusted gateway, that
- inconsistency might be expected; otherwise, it might indicate an
- attempt to bypass security filters, trick the server into delivering
- non-public content, or poison a cache. See Section 9 for security
- considerations regarding message routing.
-
-5.6. Associating a Response to a Request
-
- HTTP does not include a request identifier for associating a given
- request message with its corresponding one or more response messages.
- Hence, it relies on the order of response arrival to correspond
- exactly to the order in which requests are made on the same
- connection. More than one response message per request only occurs
- when one or more informational responses (1xx, see Section 6.2 of
- [RFC7231]) precede a final response to the same request.
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 46]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- A client that has more than one outstanding request on a connection
- MUST maintain a list of outstanding requests in the order sent and
- MUST associate each received response message on that connection to
- the highest ordered request that has not yet received a final
- (non-1xx) response.
-
-5.7. Message Forwarding
-
- As described in Section 2.3, intermediaries can serve a variety of
- roles in the processing of HTTP requests and responses. Some
- intermediaries are used to improve performance or availability.
- Others are used for access control or to filter content. Since an
- HTTP stream has characteristics similar to a pipe-and-filter
- architecture, there are no inherent limits to the extent an
- intermediary can enhance (or interfere) with either direction of the
- stream.
-
- An intermediary not acting as a tunnel MUST implement the Connection
- header field, as specified in Section 6.1, and exclude fields from
- being forwarded that are only intended for the incoming connection.
-
- An intermediary MUST NOT forward a message to itself unless it is
- protected from an infinite request loop. In general, an intermediary
- ought to recognize its own server names, including any aliases, local
- variations, or literal IP addresses, and respond to such requests
- directly.
-
-5.7.1. Via
-
- The "Via" header field indicates the presence of intermediate
- protocols and recipients between the user agent and the server (on
- requests) or between the origin server and the client (on responses),
- similar to the "Received" header field in email (Section 3.6.7 of
- [RFC5322]). Via can be used for tracking message forwards, avoiding
- request loops, and identifying the protocol capabilities of senders
- along the request/response chain.
-
- Via = 1#( received-protocol RWS received-by [ RWS comment ] )
-
- received-protocol = [ protocol-name "/" ] protocol-version
- ; see Section 6.7
- received-by = ( uri-host [ ":" port ] ) / pseudonym
- pseudonym = token
-
- Multiple Via field values represent each proxy or gateway that has
- forwarded the message. Each intermediary appends its own information
- about how the message was received, such that the end result is
- ordered according to the sequence of forwarding recipients.
-
-
-
-Fielding & Reschke Standards Track [Page 47]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- A proxy MUST send an appropriate Via header field, as described
- below, in each message that it forwards. An HTTP-to-HTTP gateway
- MUST send an appropriate Via header field in each inbound request
- message and MAY send a Via header field in forwarded response
- messages.
-
- For each intermediary, the received-protocol indicates the protocol
- and protocol version used by the upstream sender of the message.
- Hence, the Via field value records the advertised protocol
- capabilities of the request/response chain such that they remain
- visible to downstream recipients; this can be useful for determining
- what backwards-incompatible features might be safe to use in
- response, or within a later request, as described in Section 2.6.
- For brevity, the protocol-name is omitted when the received protocol
- is HTTP.
-
- The received-by portion of the field value 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, a sender MAY replace it with
- a pseudonym. If a port is not provided, a recipient MAY interpret
- that as meaning it was received on the default TCP port, if any, for
- the received-protocol.
-
- A sender MAY generate comments in the Via header field to identify
- the software of each recipient, analogous to the User-Agent and
- Server header fields. However, all comments in the Via field are
- optional, and a recipient MAY remove them 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 p.example.net, which
- completes the request by forwarding it to the origin server at
- www.example.com. The request received by www.example.com would then
- have the following Via header field:
-
- Via: 1.0 fred, 1.1 p.example.net
-
- An intermediary used as a portal through a network firewall SHOULD
- NOT forward the names and ports of hosts within the firewall region
- unless it is explicitly enabled to do so. If not enabled, such an
- intermediary SHOULD replace each received-by host of any host behind
- the firewall by an appropriate pseudonym for that host.
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 48]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- An intermediary MAY combine an ordered subsequence of Via header
- field entries into a single such entry if the entries have identical
- received-protocol values. 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
-
- A sender SHOULD NOT combine multiple entries unless they are all
- under the same organizational control and the hosts have already been
- replaced by pseudonyms. A sender MUST NOT combine entries that have
- different received-protocol values.
-
-5.7.2. Transformations
-
- Some intermediaries include features for transforming messages and
- their payloads. A 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. However, operational problems might occur
- when these transformations are applied to payloads intended for
- critical applications, such as medical imaging or scientific data
- analysis, particularly when integrity checks or digital signatures
- are used to ensure that the payload received is identical to the
- original.
-
- An HTTP-to-HTTP proxy is called a "transforming proxy" if it is
- designed or configured to modify messages in a semantically
- meaningful way (i.e., modifications, beyond those required by normal
- HTTP processing, that change the message in a way that would be
- significant to the original sender or potentially significant to
- downstream recipients). For example, a transforming proxy might be
- acting as a shared annotation server (modifying responses to include
- references to a local annotation database), a malware filter, a
- format transcoder, or a privacy filter. Such transformations are
- presumed to be desired by whichever client (or client organization)
- selected the proxy.
-
- If a proxy receives a request-target with a host name that is not a
- fully qualified domain name, it MAY add its own domain to the host
- name it received when forwarding the request. A proxy MUST NOT
- change the host name if the request-target contains a fully qualified
- domain name.
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 49]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- A proxy MUST NOT modify the "absolute-path" and "query" parts of the
- received request-target when forwarding it to the next inbound
- server, except as noted above to replace an empty path with "/" or
- "*".
-
- A proxy MAY modify the message body through application or removal of
- a transfer coding (Section 4).
-
- A proxy MUST NOT transform the payload (Section 3.3 of [RFC7231]) of
- a message that contains a no-transform cache-control directive
- (Section 5.2 of [RFC7234]).
-
- A proxy MAY transform the payload of a message that does not contain
- a no-transform cache-control directive. A proxy that transforms a
- payload MUST add a Warning header field with the warn-code of 214
- ("Transformation Applied") if one is not already in the message (see
- Section 5.5 of [RFC7234]). A proxy that transforms the payload of a
- 200 (OK) response can further inform downstream recipients that a
- transformation has been applied by changing the response status code
- to 203 (Non-Authoritative Information) (Section 6.3.4 of [RFC7231]).
-
- A proxy SHOULD NOT modify header fields that provide information
- about the endpoints of the communication chain, the resource state,
- or the selected representation (other than the payload) unless the
- field's definition specifically allows such modification or the
- modification is deemed necessary for privacy or security.
-
-6. Connection Management
-
- HTTP messaging is independent of the underlying transport- or
- session-layer connection protocol(s). HTTP only presumes a reliable
- transport with in-order delivery of requests and the corresponding
- in-order delivery of responses. The mapping of HTTP request and
- response structures onto the data units of an underlying transport
- protocol is outside the scope of this specification.
-
- As described in Section 5.2, the specific connection protocols to be
- used for an HTTP interaction are determined by client configuration
- and the target URI. For example, the "http" URI scheme
- (Section 2.7.1) indicates a default connection of TCP over IP, with a
- default TCP port of 80, but the client might be configured to use a
- proxy via some other connection, port, or protocol.
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 50]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- HTTP implementations are expected to engage in connection management,
- which includes maintaining the state of current connections,
- establishing a new connection or reusing an existing connection,
- processing messages received on a connection, detecting connection
- failures, and closing each connection. Most clients maintain
- multiple connections in parallel, including more than one connection
- per server endpoint. Most servers are designed to maintain thousands
- of concurrent connections, while controlling request queues to enable
- fair use and detect denial-of-service attacks.
-
-6.1. Connection
-
- The "Connection" header field allows the sender to indicate desired
- control options for the current connection. In order to avoid
- confusing downstream recipients, a proxy or gateway MUST remove or
- replace any received connection options before forwarding the
- message.
-
- When a header field aside from Connection is used to supply control
- information for or about the current connection, the sender MUST list
- the corresponding field-name within the Connection header field. A
- proxy or gateway MUST parse a received Connection header field before
- a message is forwarded and, for each connection-option in this field,
- remove any header field(s) from the message with the same name as the
- connection-option, and then remove the Connection header field itself
- (or replace it with the intermediary's own connection options for the
- forwarded message).
-
- Hence, the Connection header field provides a declarative way of
- distinguishing header fields that are only intended for the immediate
- recipient ("hop-by-hop") from those fields that are intended for all
- recipients on the chain ("end-to-end"), enabling the message to be
- self-descriptive and allowing future connection-specific extensions
- to be deployed without fear that they will be blindly forwarded by
- older intermediaries.
-
- The Connection header field's value has the following grammar:
-
- Connection = 1#connection-option
- connection-option = token
-
- Connection options are case-insensitive.
-
- A sender MUST NOT send a connection option corresponding to a header
- field that is intended for all recipients of the payload. For
- example, Cache-Control is never appropriate as a connection option
- (Section 5.2 of [RFC7234]).
-
-
-
-
-Fielding & Reschke Standards Track [Page 51]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- The connection options do not always correspond to a header field
- present in the message, since a connection-specific header field
- might not be needed if there are no parameters associated with a
- connection option. In contrast, a connection-specific header field
- that is received without a corresponding connection option usually
- indicates that the field has been improperly forwarded by an
- intermediary and ought to be ignored by the recipient.
-
- When defining new connection options, specification authors ought to
- survey existing header field names and ensure that the new connection
- option does not share the same name as an already deployed header
- field. Defining a new connection option essentially reserves that
- potential field-name for carrying additional information related to
- the connection option, since it would be unwise for senders to use
- that field-name for anything else.
-
- The "close" connection option is defined for a sender to signal that
- this 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 sender is going to close the connection after the current
- request/response is complete (Section 6.6).
-
- A client that does not support persistent connections MUST send the
- "close" connection option in every request message.
-
- A server that does not support persistent connections MUST send the
- "close" connection option in every response message that does not
- have a 1xx (Informational) status code.
-
-6.2. Establishment
-
- It is beyond the scope of this specification to describe how
- connections are established via various transport- or session-layer
- protocols. Each connection applies to only one transport link.
-
-6.3. Persistence
-
- HTTP/1.1 defaults to the use of "persistent connections", allowing
- multiple requests and responses to be carried over a single
- connection. The "close" connection option is used to signal that a
- connection will not persist after the current request/response. HTTP
- implementations SHOULD support persistent connections.
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 52]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- A recipient determines whether a connection is persistent or not
- based on the most recently received message's protocol version and
- Connection header field (if any):
-
- o If the "close" connection option is present, the connection will
- not persist after the current response; else,
-
- o If the received protocol is HTTP/1.1 (or later), the connection
- will persist after the current response; else,
-
- o If the received protocol is HTTP/1.0, the "keep-alive" connection
- option is present, the recipient is not a proxy, and the recipient
- wishes to honor the HTTP/1.0 "keep-alive" mechanism, the
- connection will persist after the current response; otherwise,
-
- o The connection will close after the current response.
-
- A client MAY send additional requests on a persistent connection
- until it sends or receives a "close" connection option or receives an
- HTTP/1.0 response without a "keep-alive" connection option.
-
- In order to remain persistent, all messages on a connection need to
- have a self-defined message length (i.e., one not defined by closure
- of the connection), as described in Section 3.3. A server MUST read
- the entire request message body or close the connection after sending
- its response, since otherwise the remaining data on a persistent
- connection would be misinterpreted as the next request. Likewise, a
- client MUST read the entire response message body if it intends to
- reuse the same connection for a subsequent request.
-
- A proxy server MUST NOT maintain a persistent connection with an
- HTTP/1.0 client (see Section 19.7.1 of [RFC2068] for information and
- discussion of the problems with the Keep-Alive header field
- implemented by many HTTP/1.0 clients).
-
- See Appendix A.1.2 for more information on backwards compatibility
- with HTTP/1.0 clients.
-
-6.3.1. Retrying Requests
-
- Connections can be closed at any time, with or without intention.
- Implementations ought to anticipate the need to recover from
- asynchronous close events.
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 53]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- When an inbound connection is closed prematurely, a client MAY open a
- new connection and automatically retransmit an aborted sequence of
- requests if all of those requests have idempotent methods (Section
- 4.2.2 of [RFC7231]). A proxy MUST NOT automatically retry
- non-idempotent requests.
-
- A user agent MUST NOT automatically retry a request with a non-
- idempotent method unless it has some means to know that the request
- semantics are actually idempotent, regardless of the method, or some
- means to detect that the original request was never applied. For
- example, a user agent that knows (through design or configuration)
- that a POST request to a given resource is safe can repeat that
- request automatically. Likewise, a user agent designed specifically
- to operate on a version control repository might be able to recover
- from partial failure conditions by checking the target resource
- revision(s) after a failed connection, reverting or fixing any
- changes that were partially applied, and then automatically retrying
- the requests that failed.
-
- A client SHOULD NOT automatically retry a failed automatic retry.
-
-6.3.2. Pipelining
-
- A client that supports persistent connections MAY "pipeline" its
- requests (i.e., send multiple requests without waiting for each
- response). A server MAY process a sequence of pipelined requests in
- parallel if they all have safe methods (Section 4.2.1 of [RFC7231]),
- but it MUST send the corresponding responses in the same order that
- the requests were received.
-
- A client that pipelines requests SHOULD retry unanswered requests if
- the connection closes before it receives all of the corresponding
- responses. When retrying pipelined requests after a failed
- connection (a connection not explicitly closed by the server in its
- last complete response), a client MUST NOT pipeline immediately after
- connection establishment, since the first remaining request in the
- prior pipeline might have caused an error response that can be lost
- again if multiple requests are sent on a prematurely closed
- connection (see the TCP reset problem described in Section 6.6).
-
- Idempotent methods (Section 4.2.2 of [RFC7231]) are significant to
- pipelining because they can be automatically retried after a
- connection failure. A user agent SHOULD NOT pipeline requests after
- a non-idempotent method, until the final response status code for
- that method has been received, unless the user agent has a means to
- detect and recover from partial failure conditions involving the
- pipelined sequence.
-
-
-
-
-Fielding & Reschke Standards Track [Page 54]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- An intermediary that receives pipelined requests MAY pipeline those
- requests when forwarding them inbound, since it can rely on the
- outbound user agent(s) to determine what requests can be safely
- pipelined. If the inbound connection fails before receiving a
- response, the pipelining intermediary MAY attempt to retry a sequence
- of requests that have yet to receive a response if the requests all
- have idempotent methods; otherwise, the pipelining intermediary
- SHOULD forward any received responses and then close the
- corresponding outbound connection(s) so that the outbound user
- agent(s) can recover accordingly.
-
-6.4. Concurrency
-
- A client ought to limit the number of simultaneous open connections
- that it maintains to a given server.
-
- Previous revisions of HTTP gave a specific number of connections as a
- ceiling, but this was found to be impractical for many applications.
- As a result, this specification does not mandate a particular maximum
- number of connections but, instead, encourages clients to be
- conservative when opening multiple connections.
-
- Multiple connections are typically used to avoid the "head-of-line
- blocking" problem, wherein a request that takes significant
- server-side processing and/or has a large payload blocks subsequent
- requests on the same connection. However, each connection consumes
- server resources. Furthermore, using multiple connections can cause
- undesirable side effects in congested networks.
-
- Note that a server might reject traffic that it deems abusive or
- characteristic of a denial-of-service attack, such as an excessive
- number of open connections from a single client.
-
-6.5. Failures and Timeouts
-
- Servers will usually have some timeout 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 proxy server. The use of
- persistent connections places no requirements on the length (or
- existence) of this timeout for either the client or the server.
-
- A client or server that wishes to time out SHOULD issue a graceful
- close on the connection. Implementations SHOULD constantly monitor
- open connections for a received closure signal and respond to it as
- appropriate, since prompt closure of both sides of a connection
- enables allocated system resources to be reclaimed.
-
-
-
-
-Fielding & Reschke Standards Track [Page 55]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- 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.
-
- A server SHOULD sustain persistent connections, when possible, and
- allow the underlying transport's flow-control mechanisms to resolve
- temporary overloads, rather than terminate connections with the
- expectation that clients will retry. The latter technique can
- exacerbate network congestion.
-
- A client sending a message body SHOULD monitor the network connection
- for an error response while it is transmitting the request. If the
- client sees a response that indicates the server does not wish to
- receive the message body and is closing the connection, the client
- SHOULD immediately cease transmitting the body and close its side of
- the connection.
-
-6.6. Tear-down
-
- The Connection header field (Section 6.1) provides a "close"
- connection option that a sender SHOULD send when it wishes to close
- the connection after the current request/response pair.
-
- A client that sends a "close" connection option MUST NOT send further
- requests on that connection (after the one containing "close") and
- MUST close the connection after reading the final response message
- corresponding to this request.
-
- A server that receives a "close" connection option MUST initiate a
- close of the connection (see below) after it sends the final response
- to the request that contained "close". The server SHOULD send a
- "close" connection option in its final response on that connection.
- The server MUST NOT process any further requests received on that
- connection.
-
- A server that sends a "close" connection option MUST initiate a close
- of the connection (see below) after it sends the response containing
- "close". The server MUST NOT process any further requests received
- on that connection.
-
- A client that receives a "close" connection option MUST cease sending
- requests on that connection and close the connection after reading
- the response message containing the "close"; if additional pipelined
- requests had been sent on the connection, the client SHOULD NOT
- assume that they will be processed by the server.
-
-
-
-Fielding & Reschke Standards Track [Page 56]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- If a server performs an immediate close of a TCP connection, there is
- a significant risk that the client will not be able to read the last
- HTTP response. If the server receives additional data from the
- client on a fully closed connection, such as another request that was
- sent by the client before receiving the server's response, the
- server's TCP stack will send a reset packet to the client;
- unfortunately, the reset packet might erase the client's
- unacknowledged input buffers before they can be read and interpreted
- by the client's HTTP parser.
-
- To avoid the TCP reset problem, servers typically close a connection
- in stages. First, the server performs a half-close by closing only
- the write side of the read/write connection. The server then
- continues to read from the connection until it receives a
- corresponding close by the client, or until the server is reasonably
- certain that its own TCP stack has received the client's
- acknowledgement of the packet(s) containing the server's last
- response. Finally, the server fully closes the connection.
-
- It is unknown whether the reset problem is exclusive to TCP or might
- also be found in other transport connection protocols.
-
-6.7. Upgrade
-
- The "Upgrade" header field is intended to provide a simple mechanism
- for transitioning from HTTP/1.1 to some other protocol on the same
- connection. A client MAY send a list of protocols in the Upgrade
- header field of a request to invite the server to switch to one or
- more of those protocols, in order of descending preference, before
- sending the final response. A server MAY ignore a received Upgrade
- header field if it wishes to continue using the current protocol on
- that connection. Upgrade cannot be used to insist on a protocol
- change.
-
- Upgrade = 1#protocol
-
- protocol = protocol-name ["/" protocol-version]
- protocol-name = token
- protocol-version = token
-
- A server that sends a 101 (Switching Protocols) response MUST send an
- Upgrade header field to indicate the new protocol(s) to which the
- connection is being switched; if multiple protocol layers are being
- switched, the sender MUST list the protocols in layer-ascending
- order. A server MUST NOT switch to a protocol that was not indicated
- by the client in the corresponding request's Upgrade header field. A
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 57]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- server MAY choose to ignore the order of preference indicated by the
- client and select the new protocol(s) based on other factors, such as
- the nature of the request or the current load on the server.
-
- A server that sends a 426 (Upgrade Required) response MUST send an
- Upgrade header field to indicate the acceptable protocols, in order
- of descending preference.
-
- A server MAY send an Upgrade header field in any other response to
- advertise that it implements support for upgrading to the listed
- protocols, in order of descending preference, when appropriate for a
- future request.
-
- The following is a hypothetical example sent by a client:
-
- GET /hello.txt HTTP/1.1
- Host: www.example.com
- Connection: upgrade
- Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11
-
-
- The capabilities and nature of the application-level communication
- after the protocol change is entirely dependent upon the new
- protocol(s) chosen. However, immediately after sending the 101
- (Switching Protocols) response, the server is expected to continue
- responding to the original request as if it had received its
- equivalent within the new protocol (i.e., the server still has an
- outstanding request to satisfy after the protocol has been changed,
- and is expected to do so without requiring the request to be
- repeated).
-
- For example, if the Upgrade header field is received in a GET request
- and the server decides to switch protocols, it first responds with a
- 101 (Switching Protocols) message in HTTP/1.1 and then immediately
- follows that with the new protocol's equivalent of a response to a
- GET on the target resource. This allows a connection to be upgraded
- to protocols with the same semantics as HTTP without the latency cost
- of an additional round trip. A server MUST NOT switch protocols
- unless the received message semantics can be honored by the new
- protocol; an OPTIONS request can be honored by any protocol.
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 58]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- The following is an example response to the above hypothetical
- request:
-
- HTTP/1.1 101 Switching Protocols
- Connection: upgrade
- Upgrade: HTTP/2.0
-
- [... data stream switches to HTTP/2.0 with an appropriate response
- (as defined by new protocol) to the "GET /hello.txt" request ...]
-
- When Upgrade is sent, the sender MUST also send a Connection header
- field (Section 6.1) that contains an "upgrade" connection option, in
- order to prevent Upgrade from being accidentally forwarded by
- intermediaries that might not implement the listed protocols. A
- server MUST ignore an Upgrade header field that is received in an
- HTTP/1.0 request.
-
- A client cannot begin using an upgraded protocol on the connection
- until it has completely sent the request message (i.e., the client
- can't change the protocol it is sending in the middle of a message).
- If a server receives both an Upgrade and an Expect header field with
- the "100-continue" expectation (Section 5.1.1 of [RFC7231]), the
- server MUST send a 100 (Continue) response before sending a 101
- (Switching Protocols) response.
-
- The Upgrade header field only applies to switching protocols on top
- of the existing connection; it cannot be used to switch the
- underlying connection (transport) protocol, nor to switch the
- existing communication to a different connection. For those
- purposes, it is more appropriate to use a 3xx (Redirection) response
- (Section 6.4 of [RFC7231]).
-
- 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 2.6 and future updates to this
- specification. Additional tokens ought to be registered with IANA
- using the registration procedure defined in Section 8.6.
-
-7. ABNF List Extension: #rule
-
- A #rule extension to the ABNF rules of [RFC5234] is used to improve
- readability in the definitions of some header field values.
-
- A construct "#" is defined, similar to "*", for defining
- comma-delimited lists of elements. The full form is "<n>#<m>element"
- indicating at least <n> and at most <m> elements, each separated by a
- single comma (",") and optional whitespace (OWS).
-
-
-
-
-Fielding & Reschke Standards Track [Page 59]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- In any production that uses the list construct, a sender MUST NOT
- generate empty list elements. In other words, a sender MUST generate
- lists that satisfy the following syntax:
-
- 1#element => element *( OWS "," OWS element )
-
- and:
-
- #element => [ 1#element ]
-
- and for n >= 1 and m > 1:
-
- <n>#<m>element => element <n-1>*<m-1>( OWS "," OWS element )
-
- For compatibility with legacy list rules, a recipient MUST parse and
- ignore a reasonable number of empty list elements: enough to handle
- common mistakes by senders that merge values, but not so much that
- they could be used as a denial-of-service mechanism. In other words,
- a recipient MUST accept lists that satisfy the following syntax:
-
- #element => [ ( "," / element ) *( OWS "," [ OWS element ] ) ]
-
- 1#element => *( "," OWS ) element *( OWS "," [ OWS element ] )
-
- Empty elements do not contribute to the count of elements present.
- For example, given these ABNF productions:
-
- example-list = 1#example-list-elmt
- example-list-elmt = token ; see Section 3.2.6
-
- Then the following are valid values for example-list (not including
- the double quotes, which are present for delimitation only):
-
- "foo,bar"
- "foo ,bar,"
- "foo , ,bar,charlie "
-
- In contrast, the following values would be invalid, since at least
- one non-empty element is required by the example-list production:
-
- ""
- ","
- ", ,"
-
- Appendix B shows the collected ABNF for recipients after the list
- constructs have been expanded.
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 60]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-8. IANA Considerations
-
-8.1. Header Field Registration
-
- HTTP header fields are registered within the "Message Headers"
- registry maintained at
- <http://www.iana.org/assignments/message-headers/>.
-
- This document defines the following HTTP header fields, so the
- "Permanent Message Header Field Names" registry has been updated
- accordingly (see [BCP90]).
-
- +-------------------+----------+----------+---------------+
- | Header Field Name | Protocol | Status | Reference |
- +-------------------+----------+----------+---------------+
- | Connection | http | standard | Section 6.1 |
- | Content-Length | http | standard | Section 3.3.2 |
- | Host | http | standard | Section 5.4 |
- | TE | http | standard | Section 4.3 |
- | Trailer | http | standard | Section 4.4 |
- | Transfer-Encoding | http | standard | Section 3.3.1 |
- | Upgrade | http | standard | Section 6.7 |
- | Via | http | standard | Section 5.7.1 |
- +-------------------+----------+----------+---------------+
-
- Furthermore, the header field-name "Close" has been registered as
- "reserved", since using that name as an HTTP header field might
- conflict with the "close" connection option of the Connection header
- field (Section 6.1).
-
- +-------------------+----------+----------+-------------+
- | Header Field Name | Protocol | Status | Reference |
- +-------------------+----------+----------+-------------+
- | Close | http | reserved | Section 8.1 |
- +-------------------+----------+----------+-------------+
-
- The change controller is: "IETF (iesg@ietf.org) - Internet
- Engineering Task Force".
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 61]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-8.2. URI Scheme Registration
-
- IANA maintains the registry of URI Schemes [BCP115] at
- <http://www.iana.org/assignments/uri-schemes/>.
-
- This document defines the following URI schemes, so the "Permanent
- URI Schemes" registry has been updated accordingly.
-
- +------------+------------------------------------+---------------+
- | URI Scheme | Description | Reference |
- +------------+------------------------------------+---------------+
- | http | Hypertext Transfer Protocol | Section 2.7.1 |
- | https | Hypertext Transfer Protocol Secure | Section 2.7.2 |
- +------------+------------------------------------+---------------+
-
-8.3. Internet Media Type Registration
-
- IANA maintains the registry of Internet media types [BCP13] at
- <http://www.iana.org/assignments/media-types>.
-
- This document serves as the specification for the Internet media
- types "message/http" and "application/http". The following has been
- registered with IANA.
-
-8.3.1. Internet Media Type message/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.
-
- Type name: message
-
- Subtype name: http
-
- Required parameters: N/A
-
- 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
-
-
-
-Fielding & Reschke Standards Track [Page 62]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- Security considerations: see Section 9
-
- Interoperability considerations: N/A
-
- Published specification: This specification (see Section 8.3.1).
-
- Applications that use this media type: N/A
-
- Fragment identifier considerations: N/A
-
- Additional information:
-
- Magic number(s): N/A
-
- Deprecated alias names for this type: N/A
-
- File extension(s): N/A
-
- Macintosh file type code(s): N/A
-
- Person and email address to contact for further information:
- See Authors' Addresses section.
-
- Intended usage: COMMON
-
- Restrictions on usage: N/A
-
- Author: See Authors' Addresses section.
-
- Change controller: IESG
-
-8.3.2. Internet Media Type application/http
-
- The application/http type can be used to enclose a pipeline of one or
- more HTTP request or response messages (not intermixed).
-
- Type name: application
-
- Subtype name: http
-
- Required parameters: N/A
-
- 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.
-
-
-
-
-Fielding & Reschke Standards Track [Page 63]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- 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 email.
-
- Security considerations: see Section 9
-
- Interoperability considerations: N/A
-
- Published specification: This specification (see Section 8.3.2).
-
- Applications that use this media type: N/A
-
- Fragment identifier considerations: N/A
-
- Additional information:
-
- Deprecated alias names for this type: N/A
-
- Magic number(s): N/A
-
- File extension(s): N/A
-
- Macintosh file type code(s): N/A
-
- Person and email address to contact for further information:
- See Authors' Addresses section.
-
- Intended usage: COMMON
-
- Restrictions on usage: N/A
-
- Author: See Authors' Addresses section.
-
- Change controller: IESG
-
-8.4. Transfer Coding Registry
-
- The "HTTP Transfer Coding Registry" defines the namespace for
- transfer coding names. It is maintained at
- <http://www.iana.org/assignments/http-parameters>.
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 64]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-8.4.1. Procedure
-
- Registrations MUST include the following fields:
-
- o Name
-
- o Description
-
- o Pointer to specification text
-
- Names of transfer codings MUST NOT overlap with names of content
- codings (Section 3.1.2.1 of [RFC7231]) unless the encoding
- transformation is identical, as is the case for the compression
- codings defined in Section 4.2.
-
- Values to be added to this namespace require IETF Review (see Section
- 4.1 of [RFC5226]), and MUST conform to the purpose of transfer coding
- defined in this specification.
-
- Use of program names for the identification of encoding formats is
- not desirable and is discouraged for future encodings.
-
-8.4.2. Registration
-
- The "HTTP Transfer Coding Registry" has been updated with the
- registrations below:
-
- +------------+--------------------------------------+---------------+
- | Name | Description | Reference |
- +------------+--------------------------------------+---------------+
- | chunked | Transfer in a series of chunks | Section 4.1 |
- | compress | UNIX "compress" data format [Welch] | Section 4.2.1 |
- | deflate | "deflate" compressed data | Section 4.2.2 |
- | | ([RFC1951]) inside the "zlib" data | |
- | | format ([RFC1950]) | |
- | gzip | GZIP file format [RFC1952] | Section 4.2.3 |
- | x-compress | Deprecated (alias for compress) | Section 4.2.1 |
- | x-gzip | Deprecated (alias for gzip) | Section 4.2.3 |
- +------------+--------------------------------------+---------------+
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 65]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-8.5. Content Coding Registration
-
- IANA maintains the "HTTP Content Coding Registry" at
- <http://www.iana.org/assignments/http-parameters>.
-
- The "HTTP Content Coding Registry" has been updated with the
- registrations below:
-
- +------------+--------------------------------------+---------------+
- | Name | Description | Reference |
- +------------+--------------------------------------+---------------+
- | compress | UNIX "compress" data format [Welch] | Section 4.2.1 |
- | deflate | "deflate" compressed data | Section 4.2.2 |
- | | ([RFC1951]) inside the "zlib" data | |
- | | format ([RFC1950]) | |
- | gzip | GZIP file format [RFC1952] | Section 4.2.3 |
- | x-compress | Deprecated (alias for compress) | Section 4.2.1 |
- | x-gzip | Deprecated (alias for gzip) | Section 4.2.3 |
- +------------+--------------------------------------+---------------+
-
-8.6. Upgrade Token Registry
-
- The "Hypertext Transfer Protocol (HTTP) Upgrade Token Registry"
- defines the namespace for protocol-name tokens used to identify
- protocols in the Upgrade header field. The registry is maintained at
- <http://www.iana.org/assignments/http-upgrade-tokens>.
-
-8.6.1. Procedure
-
- Each registered protocol name is associated with contact information
- and an optional set of specifications that details how the connection
- will be processed after it has been upgraded.
-
- Registrations happen on a "First Come First Served" basis (see
- Section 4.1 of [RFC5226]) and are subject to the following rules:
-
- 1. A protocol-name 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 a set of specifications associated with
- that token. Such specifications need not be publicly available.
-
- 5. The registration SHOULD name a set of expected "protocol-version"
- tokens associated with that token at the time of registration.
-
-
-
-Fielding & Reschke Standards Track [Page 66]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- 6. 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.
-
- 7. The IESG MAY reassign responsibility for a protocol token. This
- will normally only be used in the case when a responsible party
- cannot be contacted.
-
- This registration procedure for HTTP Upgrade Tokens replaces that
- previously defined in Section 7.2 of [RFC2817].
-
-8.6.2. Upgrade Token Registration
-
- The "HTTP" entry in the upgrade token registry has been updated with
- the registration below:
-
- +-------+----------------------+----------------------+-------------+
- | Value | Description | Expected Version | Reference |
- | | | Tokens | |
- +-------+----------------------+----------------------+-------------+
- | HTTP | Hypertext Transfer | any DIGIT.DIGIT | Section 2.6 |
- | | Protocol | (e.g, "2.0") | |
- +-------+----------------------+----------------------+-------------+
-
- The responsible party is: "IETF (iesg@ietf.org) - Internet
- Engineering Task Force".
-
-9. Security Considerations
-
- This section is meant to inform developers, information providers,
- and users of known security considerations relevant to HTTP message
- syntax, parsing, and routing. Security considerations about HTTP
- semantics and payloads are addressed in [RFC7231].
-
-9.1. Establishing Authority
-
- HTTP relies on the notion of an authoritative response: a response
- that has been determined by (or at the direction of) the authority
- identified within the target URI to be the most appropriate response
- for that request given the state of the target resource at the time
- of response message origination. Providing a response from a
- non-authoritative source, such as a shared cache, is often useful to
- improve performance and availability, but only to the extent that the
- source can be trusted or the distrusted response can be safely used.
-
- Unfortunately, establishing authority can be difficult. For example,
- phishing is an attack on the user's perception of authority, where
- that perception can be misled by presenting similar branding in
-
-
-
-Fielding & Reschke Standards Track [Page 67]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- hypertext, possibly aided by userinfo obfuscating the authority
- component (see Section 2.7.1). User agents can reduce the impact of
- phishing attacks by enabling users to easily inspect a target URI
- prior to making an action, by prominently distinguishing (or
- rejecting) userinfo when present, and by not sending stored
- credentials and cookies when the referring document is from an
- unknown or untrusted source.
-
- When a registered name is used in the authority component, the "http"
- URI scheme (Section 2.7.1) relies on the user's local name resolution
- service to determine where it can find authoritative responses. This
- means that any attack on a user's network host table, cached names,
- or name resolution libraries becomes an avenue for attack on
- establishing authority. Likewise, the user's choice of server for
- Domain Name Service (DNS), and the hierarchy of servers from which it
- obtains resolution results, could impact the authenticity of address
- mappings; DNS Security Extensions (DNSSEC, [RFC4033]) are one way to
- improve authenticity.
-
- Furthermore, after an IP address is obtained, establishing authority
- for an "http" URI is vulnerable to attacks on Internet Protocol
- routing.
-
- The "https" scheme (Section 2.7.2) is intended to prevent (or at
- least reveal) many of these potential attacks on establishing
- authority, provided that the negotiated TLS connection is secured and
- the client properly verifies that the communicating server's identity
- matches the target URI's authority component (see [RFC2818]).
- Correctly implementing such verification can be difficult (see
- [Georgiev]).
-
-9.2. Risks of Intermediaries
-
- By their very nature, HTTP intermediaries are men-in-the-middle and,
- thus, represent an opportunity for man-in-the-middle attacks.
- Compromise of the systems on which the intermediaries run can result
- in serious security and privacy problems. Intermediaries might have
- access to security-related information, personal information about
- individual users and organizations, and proprietary information
- belonging to users and content providers. A compromised
- intermediary, or an intermediary implemented or configured without
- regard to security and privacy considerations, might be used in the
- commission of a wide range of potential attacks.
-
- Intermediaries that contain a shared cache are especially vulnerable
- to cache poisoning attacks, as described in Section 8 of [RFC7234].
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 68]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- Implementers need to consider the privacy and security implications
- of their design and coding decisions, and of the configuration
- options they provide to operators (especially the default
- configuration).
-
- Users need to be aware that intermediaries are no more trustworthy
- than the people who run them; HTTP itself cannot solve this problem.
-
-9.3. Attacks via Protocol Element Length
-
- Because HTTP uses mostly textual, character-delimited fields, parsers
- are often vulnerable to attacks based on sending very long (or very
- slow) streams of data, particularly where an implementation is
- expecting a protocol element with no predefined length.
-
- To promote interoperability, specific recommendations are made for
- minimum size limits on request-line (Section 3.1.1) and header fields
- (Section 3.2). These are minimum recommendations, chosen to be
- supportable even by implementations with limited resources; it is
- expected that most implementations will choose substantially higher
- limits.
-
- A server can reject a message that has a request-target that is too
- long (Section 6.5.12 of [RFC7231]) or a request payload that is too
- large (Section 6.5.11 of [RFC7231]). Additional status codes related
- to capacity limits have been defined by extensions to HTTP [RFC6585].
-
- Recipients ought to carefully limit the extent to which they process
- other protocol elements, including (but not limited to) request
- methods, response status phrases, header field-names, numeric values,
- and body chunks. Failure to limit such processing can result in
- buffer overflows, arithmetic overflows, or increased vulnerability to
- denial-of-service attacks.
-
-9.4. Response Splitting
-
- Response splitting (a.k.a, CRLF injection) is a common technique,
- used in various attacks on Web usage, that exploits the line-based
- nature of HTTP message framing and the ordered association of
- requests to responses on persistent connections [Klein]. This
- technique can be particularly damaging when the requests pass through
- a shared cache.
-
- Response splitting exploits a vulnerability in servers (usually
- within an application server) where an attacker can send encoded data
- within some parameter of the request that is later decoded and echoed
- within any of the response header fields of the response. If the
- decoded data is crafted to look like the response has ended and a
-
-
-
-Fielding & Reschke Standards Track [Page 69]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- subsequent response has begun, the response has been split and the
- content within the apparent second response is controlled by the
- attacker. The attacker can then make any other request on the same
- persistent connection and trick the recipients (including
- intermediaries) into believing that the second half of the split is
- an authoritative answer to the second request.
-
- For example, a parameter within the request-target might be read by
- an application server and reused within a redirect, resulting in the
- same parameter being echoed in the Location header field of the
- response. If the parameter is decoded by the application and not
- properly encoded when placed in the response field, the attacker can
- send encoded CRLF octets and other content that will make the
- application's single response look like two or more responses.
-
- A common defense against response splitting is to filter requests for
- data that looks like encoded CR and LF (e.g., "%0D" and "%0A").
- However, that assumes the application server is only performing URI
- decoding, rather than more obscure data transformations like charset
- transcoding, XML entity translation, base64 decoding, sprintf
- reformatting, etc. A more effective mitigation is to prevent
- anything other than the server's core protocol libraries from sending
- a CR or LF within the header section, which means restricting the
- output of header fields to APIs that filter for bad octets and not
- allowing application servers to write directly to the protocol
- stream.
-
-9.5. Request Smuggling
-
- Request smuggling ([Linhart]) is a technique that exploits
- differences in protocol parsing among various recipients to hide
- additional requests (which might otherwise be blocked or disabled by
- policy) within an apparently harmless request. Like response
- splitting, request smuggling can lead to a variety of attacks on HTTP
- usage.
-
- This specification has introduced new requirements on request
- parsing, particularly with regard to message framing in
- Section 3.3.3, to reduce the effectiveness of request smuggling.
-
-9.6. Message Integrity
-
- HTTP does not define a specific mechanism for ensuring message
- integrity, instead relying on the error-detection ability of
- underlying transport protocols and the use of length or
- chunk-delimited framing to detect completeness. Additional integrity
- mechanisms, such as hash functions or digital signatures applied to
- the content, can be selectively added to messages via extensible
-
-
-
-Fielding & Reschke Standards Track [Page 70]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- metadata header fields. Historically, the lack of a single integrity
- mechanism has been justified by the informal nature of most HTTP
- communication. However, the prevalence of HTTP as an information
- access mechanism has resulted in its increasing use within
- environments where verification of message integrity is crucial.
-
- User agents are encouraged to implement configurable means for
- detecting and reporting failures of message integrity such that those
- means can be enabled within environments for which integrity is
- necessary. For example, a browser being used to view medical history
- or drug interaction information needs to indicate to the user when
- such information is detected by the protocol to be incomplete,
- expired, or corrupted during transfer. Such mechanisms might be
- selectively enabled via user agent extensions or the presence of
- message integrity metadata in a response. At a minimum, user agents
- ought to provide some indication that allows a user to distinguish
- between a complete and incomplete response message (Section 3.4) when
- such verification is desired.
-
-9.7. Message Confidentiality
-
- HTTP relies on underlying transport protocols to provide message
- confidentiality when that is desired. HTTP has been specifically
- designed to be independent of the transport protocol, such that it
- can be used over many different forms of encrypted connection, with
- the selection of such transports being identified by the choice of
- URI scheme or within user agent configuration.
-
- The "https" scheme can be used to identify resources that require a
- confidential connection, as described in Section 2.7.2.
-
-9.8. Privacy of Server Log Information
-
- A server is in the position to save personal data about a user's
- requests over time, which might identify their reading patterns or
- subjects of interest. In particular, log information gathered at an
- intermediary often contains a history of user agent interaction,
- across a multitude of sites, that can be traced to individual users.
-
- HTTP log information is confidential in nature; its handling is often
- constrained by laws and regulations. Log information needs to be
- securely stored and appropriate guidelines followed for its analysis.
- Anonymization of personal information within individual entries
- helps, but it is generally not sufficient to prevent real log traces
- from being re-identified based on correlation with other access
- characteristics. As such, access traces that are keyed to a specific
- client are unsafe to publish even if the key is pseudonymous.
-
-
-
-
-Fielding & Reschke Standards Track [Page 71]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- To minimize the risk of theft or accidental publication, log
- information ought to be purged of personally identifiable
- information, including user identifiers, IP addresses, and
- user-provided query parameters, as soon as that information is no
- longer necessary to support operational needs for security, auditing,
- or fraud control.
-
-10. Acknowledgments
-
- This edition of HTTP/1.1 builds on the many contributions that went
- into RFC 1945, RFC 2068, RFC 2145, and RFC 2616, including
- substantial contributions made by the previous authors, editors, and
- Working Group Chairs: Tim Berners-Lee, Ari Luotonen, Roy T. Fielding,
- Henrik Frystyk Nielsen, Jim Gettys, Jeffrey C. Mogul, Larry Masinter,
- and Paul J. Leach. Mark Nottingham oversaw this effort as Working
- Group Chair.
-
- Since 1999, the following contributors have helped improve the HTTP
- specification by reporting bugs, asking smart questions, drafting or
- reviewing text, and evaluating open issues:
-
- Adam Barth, Adam Roach, Addison Phillips, Adrian Chadd, Adrian Cole,
- Adrien W. de Croy, Alan Ford, Alan Ruttenberg, Albert Lunde, Alek
- Storm, Alex Rousskov, Alexandre Morgaut, Alexey Melnikov, Alisha
- Smith, Amichai Rothman, Amit Klein, Amos Jeffries, Andreas Maier,
- Andreas Petersson, Andrei Popov, Anil Sharma, Anne van Kesteren,
- Anthony Bryan, Asbjorn Ulsberg, Ashok Kumar, Balachander
- Krishnamurthy, Barry Leiba, Ben Laurie, Benjamin Carlyle, Benjamin
- Niven-Jenkins, Benoit Claise, Bil Corry, Bill Burke, Bjoern
- Hoehrmann, Bob Scheifler, Boris Zbarsky, Brett Slatkin, Brian Kell,
- Brian McBarron, Brian Pane, Brian Raymor, Brian Smith, Bruce Perens,
- Bryce Nesbitt, Cameron Heavon-Jones, Carl Kugler, Carsten Bormann,
- Charles Fry, Chris Burdess, Chris Newman, Christian Huitema, Cyrus
- Daboo, Dale Robert Anderson, Dan Wing, Dan Winship, Daniel Stenberg,
- Darrel Miller, Dave Cridland, Dave Crocker, Dave Kristol, Dave
- Thaler, David Booth, David Singer, David W. Morris, Diwakar Shetty,
- Dmitry Kurochkin, Drummond Reed, Duane Wessels, Edward Lee, Eitan
- Adler, Eliot Lear, Emile Stephan, Eran Hammer-Lahav, Eric D.
- Williams, Eric J. Bowman, Eric Lawrence, Eric Rescorla, Erik
- Aronesty, EungJun Yi, Evan Prodromou, Felix Geisendoerfer, Florian
- Weimer, Frank Ellermann, Fred Akalin, Fred Bohle, Frederic Kayser,
- Gabor Molnar, Gabriel Montenegro, Geoffrey Sneddon, Gervase Markham,
- Gili Tzabari, Grahame Grieve, Greg Slepak, Greg Wilkins, Grzegorz
- Calkowski, Harald Tveit Alvestrand, Harry Halpin, Helge Hess, Henrik
- Nordstrom, Henry S. Thompson, Henry Story, Herbert van de Sompel,
- Herve Ruellan, Howard Melman, Hugo Haas, Ian Fette, Ian Hickson, Ido
- Safruti, Ilari Liusvaara, Ilya Grigorik, Ingo Struck, J. Ross Nicoll,
- James Cloos, James H. Manger, James Lacey, James M. Snell, Jamie
-
-
-
-Fielding & Reschke Standards Track [Page 72]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- Lokier, Jan Algermissen, Jari Arkko, Jeff Hodges (who came up with
- the term 'effective Request-URI'), Jeff Pinner, Jeff Walden, Jim
- Luther, Jitu Padhye, Joe D. Williams, Joe Gregorio, Joe Orton, Joel
- Jaeggli, John C. Klensin, John C. Mallery, John Cowan, John Kemp,
- John Panzer, John Schneider, John Stracke, John Sullivan, Jonas
- Sicking, Jonathan A. Rees, Jonathan Billington, Jonathan Moore,
- Jonathan Silvera, Jordi Ros, Joris Dobbelsteen, Josh Cohen, Julien
- Pierre, Jungshik Shin, Justin Chapweske, Justin Erenkrantz, Justin
- James, Kalvinder Singh, Karl Dubost, Kathleen Moriarty, Keith
- Hoffman, Keith Moore, Ken Murchison, Koen Holtman, Konstantin
- Voronkov, Kris Zyp, Leif Hedstrom, Lionel Morand, Lisa Dusseault,
- Maciej Stachowiak, Manu Sporny, Marc Schneider, Marc Slemko, Mark
- Baker, Mark Pauley, Mark Watson, Markus Isomaki, Markus Lanthaler,
- Martin J. Duerst, Martin Musatov, Martin Nilsson, Martin Thomson,
- Matt Lynch, Matthew Cox, Matthew Kerwin, Max Clark, Menachem Dodge,
- Meral Shirazipour, Michael Burrows, Michael Hausenblas, Michael
- Scharf, Michael Sweet, Michael Tuexen, Michael Welzl, Mike Amundsen,
- Mike Belshe, Mike Bishop, Mike Kelly, Mike Schinkel, Miles Sabin,
- Murray S. Kucherawy, Mykyta Yevstifeyev, Nathan Rixham, Nicholas
- Shanks, Nico Williams, Nicolas Alvarez, Nicolas Mailhot, Noah Slater,
- Osama Mazahir, Pablo Castro, Pat Hayes, Patrick R. McManus, Paul E.
- Jones, Paul Hoffman, Paul Marquess, Pete Resnick, Peter Lepeska,
- Peter Occil, Peter Saint-Andre, Peter Watkins, Phil Archer, Phil
- Hunt, Philippe Mougin, Phillip Hallam-Baker, Piotr Dobrogost, Poul-
- Henning Kamp, Preethi Natarajan, Rajeev Bector, Ray Polk, Reto
- Bachmann-Gmuer, Richard Barnes, Richard Cyganiak, Rob Trace, Robby
- Simpson, Robert Brewer, Robert Collins, Robert Mattson, Robert
- O'Callahan, Robert Olofsson, Robert Sayre, Robert Siemer, Robert de
- Wilde, Roberto Javier Godoy, Roberto Peon, Roland Zink, Ronny
- Widjaja, Ryan Hamilton, S. Mike Dierken, Salvatore Loreto, Sam
- Johnston, Sam Pullara, Sam Ruby, Saurabh Kulkarni, Scott Lawrence
- (who maintained the original issues list), Sean B. Palmer, Sean
- Turner, Sebastien Barnoud, Shane McCarron, Shigeki Ohtsu, Simon
- Yarde, Stefan Eissing, Stefan Tilkov, Stefanos Harhalakis, Stephane
- Bortzmeyer, Stephen Farrell, Stephen Kent, Stephen Ludin, Stuart
- Williams, Subbu Allamaraju, Subramanian Moonesamy, Susan Hares,
- Sylvain Hellegouarch, Tapan Divekar, Tatsuhiro Tsujikawa, Tatsuya
- Hayashi, Ted Hardie, Ted Lemon, Thomas Broyer, Thomas Fossati, Thomas
- Maslen, Thomas Nadeau, Thomas Nordin, Thomas Roessler, Tim Bray, Tim
- Morgan, Tim Olsen, Tom Zhou, Travis Snoozy, Tyler Close, Vincent
- Murphy, Wenbo Zhu, Werner Baumann, Wilbur Streett, Wilfredo Sanchez
- Vega, William A. Rowe Jr., William Chan, Willy Tarreau, Xiaoshu Wang,
- Yaron Goland, Yngve Nysaeter Pettersen, Yoav Nir, Yogesh Bang,
- Yuchung Cheng, Yutaka Oiwa, Yves Lafon (long-time member of the
- editor team), Zed A. Shaw, and Zhong Yu.
-
- See Section 16 of [RFC2616] for additional acknowledgements from
- prior revisions.
-
-
-
-Fielding & Reschke Standards Track [Page 73]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-11. References
-
-11.1. Normative References
-
- [RFC0793] Postel, J., "Transmission Control Protocol", STD 7,
- RFC 793, September 1981.
-
- [RFC1950] Deutsch, L. and J-L. Gailly, "ZLIB Compressed Data
- Format Specification version 3.3", RFC 1950, May 1996.
-
- [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format
- Specification version 1.3", RFC 1951, May 1996.
-
- [RFC1952] Deutsch, P., Gailly, J-L., Adler, M., Deutsch, L., and
- G. Randers-Pehrson, "GZIP file format specification
- version 4.3", RFC 1952, May 1996.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter,
- "Uniform Resource Identifier (URI): Generic Syntax",
- STD 66, RFC 3986, January 2005.
-
- [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for
- Syntax Specifications: ABNF", STD 68, RFC 5234,
- January 2008.
-
- [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext
- Transfer Protocol (HTTP/1.1): Semantics and Content",
- RFC 7231, June 2014.
-
- [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext
- Transfer Protocol (HTTP/1.1): Conditional Requests",
- RFC 7232, June 2014.
-
- [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed.,
- "Hypertext Transfer Protocol (HTTP/1.1): Range
- Requests", RFC 7233, June 2014.
-
- [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
- Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
- RFC 7234, June 2014.
-
- [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext
- Transfer Protocol (HTTP/1.1): Authentication",
- RFC 7235, June 2014.
-
-
-
-
-Fielding & Reschke Standards Track [Page 74]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- [USASCII] American National Standards Institute, "Coded Character
- Set -- 7-bit American Standard Code for Information
- Interchange", ANSI X3.4, 1986.
-
- [Welch] Welch, T., "A Technique for High-Performance Data
- Compression", IEEE Computer 17(6), June 1984.
-
-11.2. Informative References
-
- [BCP115] Hansen, T., Hardie, T., and L. Masinter, "Guidelines
- and Registration Procedures for New URI Schemes",
- BCP 115, RFC 4395, February 2006.
-
- [BCP13] Freed, N., Klensin, J., and T. Hansen, "Media Type
- Specifications and Registration Procedures", BCP 13,
- RFC 6838, January 2013.
-
- [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration
- Procedures for Message Header Fields", BCP 90,
- RFC 3864, September 2004.
-
- [Georgiev] Georgiev, M., Iyengar, S., Jana, S., Anubhai, R.,
- Boneh, D., and V. Shmatikov, "The Most Dangerous Code
- in the World: Validating SSL Certificates in Non-
- browser Software", In Proceedings of the 2012 ACM
- Conference on Computer and Communications Security (CCS
- '12), pp. 38-49, October 2012,
- <http://doi.acm.org/10.1145/2382196.2382204>.
-
- [ISO-8859-1] International Organization for Standardization,
- "Information technology -- 8-bit single-byte coded
- graphic character sets -- Part 1: Latin alphabet No.
- 1", ISO/IEC 8859-1:1998, 1998.
-
- [Klein] Klein, A., "Divide and Conquer - HTTP Response
- Splitting, Web Cache Poisoning Attacks, and Related
- Topics", March 2004, <http://packetstormsecurity.com/
- papers/general/whitepaper_httpresponse.pdf>.
-
- [Kri2001] Kristol, D., "HTTP Cookies: Standards, Privacy, and
- Politics", ACM Transactions on Internet
- Technology 1(2), November 2001,
- <http://arxiv.org/abs/cs.SE/0105018>.
-
- [Linhart] Linhart, C., Klein, A., Heled, R., and S. Orrin, "HTTP
- Request Smuggling", June 2005,
- <http://www.watchfire.com/news/whitepapers.aspx>.
-
-
-
-
-Fielding & Reschke Standards Track [Page 75]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- [RFC1919] Chatel, M., "Classical versus Transparent IP Proxies",
- RFC 1919, March 1996.
-
- [RFC1945] Berners-Lee, T., Fielding, R., and H. Nielsen,
- "Hypertext Transfer Protocol -- HTTP/1.0", RFC 1945,
- May 1996.
-
- [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet
- Mail Extensions (MIME) Part One: Format of Internet
- Message Bodies", RFC 2045, November 1996.
-
- [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail
- Extensions) Part Three: Message Header Extensions for
- Non-ASCII Text", RFC 2047, November 1996.
-
- [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and
- T. Berners-Lee, "Hypertext Transfer Protocol --
- HTTP/1.1", RFC 2068, January 1997.
-
- [RFC2145] Mogul, J., Fielding, R., Gettys, J., and H. Nielsen,
- "Use and Interpretation of HTTP Version Numbers",
- RFC 2145, May 1997.
-
- [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.
-
- [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within
- HTTP/1.1", RFC 2817, May 2000.
-
- [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
-
- [RFC3040] Cooper, I., Melve, I., and G. Tomlinson, "Internet Web
- Replication and Caching Taxonomy", RFC 3040,
- January 2001.
-
- [RFC4033] Arends, R., Austein, R., Larson, M., Massey, D., and S.
- Rose, "DNS Security Introduction and Requirements",
- RFC 4033, March 2005.
-
- [RFC4559] Jaganathan, K., Zhu, L., and J. Brezak, "SPNEGO-based
- Kerberos and NTLM HTTP Authentication in Microsoft
- Windows", RFC 4559, June 2006.
-
- [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing
- an IANA Considerations Section in RFCs", BCP 26,
- RFC 5226, May 2008.
-
-
-
-
-Fielding & Reschke Standards Track [Page 76]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer
- Security (TLS) Protocol Version 1.2", RFC 5246,
- August 2008.
-
- [RFC5322] Resnick, P., "Internet Message Format", RFC 5322,
- October 2008.
-
- [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
- April 2011.
-
- [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status
- Codes", RFC 6585, April 2012.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 77]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-Appendix A. HTTP Version History
-
- HTTP has been in use since 1990. The first version, later referred
- to as HTTP/0.9, was a simple protocol for hypertext data transfer
- across the Internet, using only a single request method (GET) and no
- metadata. HTTP/1.0, as defined by [RFC1945], added a range of
- request methods and MIME-like messaging, allowing for metadata to be
- transferred and modifiers placed on the request/response semantics.
- However, HTTP/1.0 did not sufficiently take into consideration the
- effects of hierarchical proxies, caching, the need for persistent
- connections, or name-based virtual hosts. The proliferation of
- incompletely implemented applications calling themselves "HTTP/1.0"
- further necessitated a protocol version change in order for two
- communicating applications to determine each other's true
- capabilities.
-
- HTTP/1.1 remains compatible with HTTP/1.0 by including more stringent
- requirements that enable reliable implementations, adding only those
- features that can either be safely ignored by an HTTP/1.0 recipient
- or only be sent when communicating with a party advertising
- conformance with HTTP/1.1.
-
- HTTP/1.1 has been designed to make supporting previous versions easy.
- A general-purpose HTTP/1.1 server ought to be able to understand any
- valid request in the format of HTTP/1.0, responding appropriately
- with an HTTP/1.1 message that only uses features understood (or
- safely ignored) by HTTP/1.0 clients. Likewise, an HTTP/1.1 client
- can be expected to understand any valid HTTP/1.0 response.
-
- Since HTTP/0.9 did not support header fields in a request, there is
- no mechanism for it to support name-based virtual hosts (selection of
- resource by inspection of the Host header field). Any server that
- implements name-based virtual hosts ought to disable support for
- HTTP/0.9. Most requests that appear to be HTTP/0.9 are, in fact,
- badly constructed HTTP/1.x requests caused by a client failing to
- properly encode the request-target.
-
-A.1. Changes from HTTP/1.0
-
- This section summarizes major differences between versions HTTP/1.0
- and HTTP/1.1.
-
-A.1.1. Multihomed Web Servers
-
- The requirements that clients and servers support the Host header
- field (Section 5.4), report an error if it is missing from an
- HTTP/1.1 request, and accept absolute URIs (Section 5.3) are among
- the most important changes defined by HTTP/1.1.
-
-
-
-Fielding & Reschke Standards Track [Page 78]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- 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 Host header field was
- introduced during the development of HTTP/1.1 and, though it was
- quickly implemented by most HTTP/1.0 browsers, additional
- requirements were placed on all HTTP/1.1 requests in order to ensure
- complete adoption. At the time of this writing, most HTTP-based
- services are dependent upon the Host header field for targeting
- requests.
-
-A.1.2. Keep-Alive Connections
-
- In HTTP/1.0, each connection is established by the client prior to
- the request and closed by the server after sending the response.
- However, some implementations implement the explicitly negotiated
- ("Keep-Alive") version of persistent connections described in Section
- 19.7.1 of [RFC2068].
-
- Some clients and servers might wish to be compatible with these
- previous approaches to persistent connections, by explicitly
- negotiating for them with a "Connection: keep-alive" request header
- field. However, some experimental implementations of HTTP/1.0
- persistent connections are faulty; for example, if an HTTP/1.0 proxy
- server doesn't understand Connection, it will erroneously forward
- that header field to the next inbound server, which would result in a
- hung connection.
-
- One attempted solution was the introduction of a Proxy-Connection
- header field, targeted specifically at proxies. In practice, this
- was also unworkable, because proxies are often deployed in multiple
- layers, bringing about the same problem discussed above.
-
- As a result, clients are encouraged not to send the Proxy-Connection
- header field in any requests.
-
- Clients are also encouraged to consider the use of Connection:
- keep-alive in requests carefully; while they can enable persistent
- connections with HTTP/1.0 servers, clients using them will need to
- monitor the connection for "hung" requests (which indicate that the
- client ought stop sending the header field), and this mechanism ought
- not be used by clients at all when a proxy is being used.
-
-A.1.3. Introduction of Transfer-Encoding
-
- HTTP/1.1 introduces the Transfer-Encoding header field
- (Section 3.3.1). Transfer codings need to be decoded prior to
- forwarding an HTTP message over a MIME-compliant protocol.
-
-
-
-Fielding & Reschke Standards Track [Page 79]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-A.2. Changes from RFC 2616
-
- HTTP's approach to error handling has been explained. (Section 2.5)
-
- The HTTP-version ABNF production has been clarified to be case-
- sensitive. Additionally, version numbers have been restricted to
- single digits, due to the fact that implementations are known to
- handle multi-digit version numbers incorrectly. (Section 2.6)
-
- Userinfo (i.e., username and password) are now disallowed in HTTP and
- HTTPS URIs, because of security issues related to their transmission
- on the wire. (Section 2.7.1)
-
- The HTTPS URI scheme is now defined by this specification;
- previously, it was done in Section 2.4 of [RFC2818]. Furthermore, it
- implies end-to-end security. (Section 2.7.2)
-
- HTTP messages can be (and often are) buffered by implementations;
- despite it sometimes being available as a stream, HTTP is
- fundamentally a message-oriented protocol. Minimum supported sizes
- for various protocol elements have been suggested, to improve
- interoperability. (Section 3)
-
- Invalid whitespace around field-names is now required to be rejected,
- because accepting it represents a security vulnerability. The ABNF
- productions defining header fields now only list the field value.
- (Section 3.2)
-
- Rules about implicit linear whitespace between certain grammar
- productions have been removed; now whitespace is only allowed where
- specifically defined in the ABNF. (Section 3.2.3)
-
- Header fields that span multiple lines ("line folding") are
- deprecated. (Section 3.2.4)
-
- The NUL octet is no longer allowed in comment and quoted-string text,
- and handling of backslash-escaping in them has been clarified. The
- quoted-pair rule no longer allows escaping control characters other
- than HTAB. Non-US-ASCII content in header fields and the reason
- phrase has been obsoleted and made opaque (the TEXT rule was
- removed). (Section 3.2.6)
-
- Bogus Content-Length header fields are now required to be handled as
- errors by recipients. (Section 3.3.2)
-
- The algorithm for determining the message body length has been
- clarified to indicate all of the special cases (e.g., driven by
- methods or status codes) that affect it, and that new protocol
-
-
-
-Fielding & Reschke Standards Track [Page 80]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- elements cannot define such special cases. CONNECT is a new, special
- case in determining message body length. "multipart/byteranges" is no
- longer a way of determining message body length detection.
- (Section 3.3.3)
-
- The "identity" transfer coding token has been removed. (Sections 3.3
- and 4)
-
- Chunk length does not include the count of the octets in the chunk
- header and trailer. Line folding in chunk extensions is disallowed.
- (Section 4.1)
-
- The meaning of the "deflate" content coding has been clarified.
- (Section 4.2.2)
-
- The segment + query components of RFC 3986 have been used to define
- the request-target, instead of abs_path from RFC 1808. The
- asterisk-form of the request-target is only allowed with the OPTIONS
- method. (Section 5.3)
-
- The term "Effective Request URI" has been introduced. (Section 5.5)
-
- Gateways do not need to generate Via header fields anymore.
- (Section 5.7.1)
-
- Exactly when "close" connection options have to be sent has been
- clarified. Also, "hop-by-hop" header fields are required to appear
- in the Connection header field; just because they're defined as hop-
- by-hop in this specification doesn't exempt them. (Section 6.1)
-
- The limit of two connections per server has been removed. An
- idempotent sequence of requests is no longer required to be retried.
- The requirement to retry requests under certain circumstances when
- the server prematurely closes the connection has been removed. Also,
- some extraneous requirements about when servers are allowed to close
- connections prematurely have been removed. (Section 6.3)
-
- The semantics of the Upgrade header field is now defined in responses
- other than 101 (this was incorporated from [RFC2817]). Furthermore,
- the ordering in the field value is now significant. (Section 6.7)
-
- Empty list elements in list productions (e.g., a list header field
- containing ", ,") have been deprecated. (Section 7)
-
- Registration of Transfer Codings now requires IETF Review
- (Section 8.4)
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 81]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- This specification now defines the Upgrade Token Registry, previously
- defined in Section 7.2 of [RFC2817]. (Section 8.6)
-
- The expectation to support HTTP/0.9 requests has been removed.
- (Appendix A)
-
- Issues with the Keep-Alive and Proxy-Connection header fields in
- requests are pointed out, with use of the latter being discouraged
- altogether. (Appendix A.1.2)
-
-Appendix B. Collected ABNF
-
- BWS = OWS
-
- Connection = *( "," OWS ) connection-option *( OWS "," [ OWS
- connection-option ] )
-
- Content-Length = 1*DIGIT
-
- HTTP-message = start-line *( header-field CRLF ) CRLF [ message-body
- ]
- HTTP-name = %x48.54.54.50 ; HTTP
- HTTP-version = HTTP-name "/" DIGIT "." DIGIT
- Host = uri-host [ ":" port ]
-
- OWS = *( SP / HTAB )
-
- RWS = 1*( SP / HTAB )
-
- TE = [ ( "," / t-codings ) *( OWS "," [ OWS t-codings ] ) ]
- Trailer = *( "," OWS ) field-name *( OWS "," [ OWS field-name ] )
- Transfer-Encoding = *( "," OWS ) transfer-coding *( OWS "," [ OWS
- transfer-coding ] )
-
- URI-reference = <URI-reference, see [RFC3986], Section 4.1>
- Upgrade = *( "," OWS ) protocol *( OWS "," [ OWS protocol ] )
-
- Via = *( "," OWS ) ( received-protocol RWS received-by [ RWS comment
- ] ) *( OWS "," [ OWS ( received-protocol RWS received-by [ RWS
- comment ] ) ] )
-
- absolute-URI = <absolute-URI, see [RFC3986], Section 4.3>
- absolute-form = absolute-URI
- absolute-path = 1*( "/" segment )
- asterisk-form = "*"
- authority = <authority, see [RFC3986], Section 3.2>
- authority-form = authority
-
-
-
-
-Fielding & Reschke Standards Track [Page 82]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- chunk = chunk-size [ chunk-ext ] CRLF chunk-data CRLF
- chunk-data = 1*OCTET
- chunk-ext = *( ";" chunk-ext-name [ "=" chunk-ext-val ] )
- chunk-ext-name = token
- chunk-ext-val = token / quoted-string
- chunk-size = 1*HEXDIG
- chunked-body = *chunk last-chunk trailer-part CRLF
- comment = "(" *( ctext / quoted-pair / comment ) ")"
- connection-option = token
- ctext = HTAB / SP / %x21-27 ; '!'-'''
- / %x2A-5B ; '*'-'['
- / %x5D-7E ; ']'-'~'
- / obs-text
-
- field-content = field-vchar [ 1*( SP / HTAB ) field-vchar ]
- field-name = token
- field-value = *( field-content / obs-fold )
- field-vchar = VCHAR / obs-text
- fragment = <fragment, see [RFC3986], Section 3.5>
-
- header-field = field-name ":" OWS field-value OWS
- http-URI = "http://" authority path-abempty [ "?" query ] [ "#"
- fragment ]
- https-URI = "https://" authority path-abempty [ "?" query ] [ "#"
- fragment ]
-
- last-chunk = 1*"0" [ chunk-ext ] CRLF
-
- message-body = *OCTET
- method = token
-
- obs-fold = CRLF 1*( SP / HTAB )
- obs-text = %x80-FF
- origin-form = absolute-path [ "?" query ]
-
- partial-URI = relative-part [ "?" query ]
- path-abempty = <path-abempty, see [RFC3986], Section 3.3>
- port = <port, see [RFC3986], Section 3.2.3>
- protocol = protocol-name [ "/" protocol-version ]
- protocol-name = token
- protocol-version = token
- pseudonym = token
-
- qdtext = HTAB / SP / "!" / %x23-5B ; '#'-'['
- / %x5D-7E ; ']'-'~'
- / obs-text
- query = <query, see [RFC3986], Section 3.4>
- quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text )
-
-
-
-Fielding & Reschke Standards Track [Page 83]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE
-
- rank = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] )
- reason-phrase = *( HTAB / SP / VCHAR / obs-text )
- received-by = ( uri-host [ ":" port ] ) / pseudonym
- received-protocol = [ protocol-name "/" ] protocol-version
- relative-part = <relative-part, see [RFC3986], Section 4.2>
- request-line = method SP request-target SP HTTP-version CRLF
- request-target = origin-form / absolute-form / authority-form /
- asterisk-form
-
- scheme = <scheme, see [RFC3986], Section 3.1>
- segment = <segment, see [RFC3986], Section 3.3>
- start-line = request-line / status-line
- status-code = 3DIGIT
- status-line = HTTP-version SP status-code SP reason-phrase CRLF
-
- t-codings = "trailers" / ( transfer-coding [ t-ranking ] )
- t-ranking = OWS ";" OWS "q=" rank
- tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
- "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
- token = 1*tchar
- trailer-part = *( header-field CRLF )
- transfer-coding = "chunked" / "compress" / "deflate" / "gzip" /
- transfer-extension
- transfer-extension = token *( OWS ";" OWS transfer-parameter )
- transfer-parameter = token BWS "=" BWS ( token / quoted-string )
-
- uri-host = <host, see [RFC3986], Section 3.2.2>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 84]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-Index
-
- A
- absolute-form (of request-target) 42
- accelerator 10
- application/http Media Type 63
- asterisk-form (of request-target) 43
- authoritative response 67
- authority-form (of request-target) 42-43
-
- B
- browser 7
-
- C
- cache 11
- cacheable 12
- captive portal 11
- chunked (Coding Format) 28, 32, 36
- client 7
- close 51, 56
- compress (Coding Format) 38
- connection 7
- Connection header field 51, 56
- Content-Length header field 30
-
- D
- deflate (Coding Format) 38
- Delimiters 27
- downstream 10
-
- E
- effective request URI 45
-
- G
- gateway 10
- Grammar
- absolute-form 42
- absolute-path 16
- absolute-URI 16
- ALPHA 6
- asterisk-form 41, 43
- authority 16
- authority-form 42-43
- BWS 25
- chunk 36
- chunk-data 36
- chunk-ext 36
- chunk-ext-name 36
-
-
-
-Fielding & Reschke Standards Track [Page 85]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- chunk-ext-val 36
- chunk-size 36
- chunked-body 36
- comment 27
- Connection 51
- connection-option 51
- Content-Length 30
- CR 6
- CRLF 6
- ctext 27
- CTL 6
- DIGIT 6
- DQUOTE 6
- field-content 23
- field-name 23, 40
- field-value 23
- field-vchar 23
- fragment 16
- header-field 23, 37
- HEXDIG 6
- Host 44
- HTAB 6
- HTTP-message 19
- HTTP-name 14
- http-URI 17
- HTTP-version 14
- https-URI 18
- last-chunk 36
- LF 6
- message-body 28
- method 21
- obs-fold 23
- obs-text 27
- OCTET 6
- origin-form 42
- OWS 25
- partial-URI 16
- port 16
- protocol-name 47
- protocol-version 47
- pseudonym 47
- qdtext 27
- query 16
- quoted-pair 27
- quoted-string 27
- rank 39
- reason-phrase 22
- received-by 47
-
-
-
-Fielding & Reschke Standards Track [Page 86]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- received-protocol 47
- request-line 21
- request-target 41
- RWS 25
- scheme 16
- segment 16
- SP 6
- start-line 21
- status-code 22
- status-line 22
- t-codings 39
- t-ranking 39
- tchar 27
- TE 39
- token 27
- Trailer 40
- trailer-part 37
- transfer-coding 35
- Transfer-Encoding 28
- transfer-extension 35
- transfer-parameter 35
- Upgrade 57
- uri-host 16
- URI-reference 16
- VCHAR 6
- Via 47
- gzip (Coding Format) 39
-
- H
- header field 19
- header section 19
- headers 19
- Host header field 44
- http URI scheme 17
- https URI scheme 17
- I
- inbound 9
- interception proxy 11
- intermediary 9
-
- M
- Media Type
- application/http 63
- message/http 62
- message 7
- message/http Media Type 62
- method 21
-
-
-
-
-Fielding & Reschke Standards Track [Page 87]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
- N
- non-transforming proxy 49
-
- O
- origin server 7
- origin-form (of request-target) 42
- outbound 10
-
- P
- phishing 67
- proxy 10
-
- R
- recipient 7
- request 7
- request-target 21
- resource 16
- response 7
- reverse proxy 10
-
- S
- sender 7
- server 7
- spider 7
-
- T
- target resource 40
- target URI 40
- TE header field 39
- Trailer header field 40
- Transfer-Encoding header field 28
- transforming proxy 49
- transparent proxy 11
- tunnel 10
-
- U
- Upgrade header field 57
- upstream 9
- URI scheme
- http 17
- https 17
- user agent 7
-
- V
- Via header field 47
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 88]
-\f
-RFC 7230 HTTP/1.1 Message Syntax and Routing June 2014
-
-
-Authors' Addresses
-
- Roy T. Fielding (editor)
- Adobe Systems Incorporated
- 345 Park Ave
- San Jose, CA 95110
- USA
-
- EMail: fielding@gbiv.com
- URI: http://roy.gbiv.com/
-
-
- Julian F. Reschke (editor)
- greenbytes GmbH
- Hafenweg 16
- Muenster, NW 48155
- Germany
-
- EMail: julian.reschke@greenbytes.de
- URI: http://greenbytes.de/tech/webdav/
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 89]
-\f
+++ /dev/null
-
-
-
-
-
-
-Internet Engineering Task Force (IETF) R. Fielding, Ed.
-Request for Comments: 7231 Adobe
-Obsoletes: 2616 J. Reschke, Ed.
-Updates: 2817 greenbytes
-Category: Standards Track June 2014
-ISSN: 2070-1721
-
-
- Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
-
-Abstract
-
- The Hypertext Transfer Protocol (HTTP) is a stateless application-
- level protocol for distributed, collaborative, hypertext information
- systems. This document defines the semantics of HTTP/1.1 messages,
- as expressed by request methods, request header fields, response
- status codes, and response header fields, along with the payload of
- messages (metadata and body content) and mechanisms for content
- negotiation.
-
-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 5741.
-
- 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/rfc7231.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 1]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-Copyright Notice
-
- Copyright (c) 2014 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.
-
- This document may contain material from IETF Documents or IETF
- Contributions published or made publicly available before November
- 10, 2008. The person(s) controlling the copyright in some of this
- material may not have granted the IETF Trust the right to allow
- modifications of such material outside the IETF Standards Process.
- Without obtaining an adequate license from the person(s) controlling
- the copyright in such materials, this document may not be modified
- outside the IETF Standards Process, and derivative works of it may
- not be created outside the IETF Standards Process, except to format
- it for publication as an RFC or to translate it into languages other
- than English.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 2]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-Table of Contents
-
- 1. Introduction ....................................................6
- 1.1. Conformance and Error Handling .............................6
- 1.2. Syntax Notation ............................................6
- 2. Resources .......................................................7
- 3. Representations .................................................7
- 3.1. Representation Metadata ....................................8
- 3.1.1. Processing Representation Data ......................8
- 3.1.2. Encoding for Compression or Integrity ..............11
- 3.1.3. Audience Language ..................................13
- 3.1.4. Identification .....................................14
- 3.2. Representation Data .......................................17
- 3.3. Payload Semantics .........................................17
- 3.4. Content Negotiation .......................................18
- 3.4.1. Proactive Negotiation ..............................19
- 3.4.2. Reactive Negotiation ...............................20
- 4. Request Methods ................................................21
- 4.1. Overview ..................................................21
- 4.2. Common Method Properties ..................................22
- 4.2.1. Safe Methods .......................................22
- 4.2.2. Idempotent Methods .................................23
- 4.2.3. Cacheable Methods ..................................24
- 4.3. Method Definitions ........................................24
- 4.3.1. GET ................................................24
- 4.3.2. HEAD ...............................................25
- 4.3.3. POST ...............................................25
- 4.3.4. PUT ................................................26
- 4.3.5. DELETE .............................................29
- 4.3.6. CONNECT ............................................30
- 4.3.7. OPTIONS ............................................31
- 4.3.8. TRACE ..............................................32
- 5. Request Header Fields ..........................................33
- 5.1. Controls ..................................................33
- 5.1.1. Expect .............................................34
- 5.1.2. Max-Forwards .......................................36
- 5.2. Conditionals ..............................................36
- 5.3. Content Negotiation .......................................37
- 5.3.1. Quality Values .....................................37
- 5.3.2. Accept .............................................38
- 5.3.3. Accept-Charset .....................................40
- 5.3.4. Accept-Encoding ....................................41
- 5.3.5. Accept-Language ....................................42
- 5.4. Authentication Credentials ................................44
- 5.5. Request Context ...........................................44
- 5.5.1. From ...............................................44
- 5.5.2. Referer ............................................45
- 5.5.3. User-Agent .........................................46
-
-
-
-Fielding & Reschke Standards Track [Page 3]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- 6. Response Status Codes ..........................................47
- 6.1. Overview of Status Codes ..................................48
- 6.2. Informational 1xx .........................................50
- 6.2.1. 100 Continue .......................................50
- 6.2.2. 101 Switching Protocols ............................50
- 6.3. Successful 2xx ............................................51
- 6.3.1. 200 OK .............................................51
- 6.3.2. 201 Created ........................................52
- 6.3.3. 202 Accepted .......................................52
- 6.3.4. 203 Non-Authoritative Information ..................52
- 6.3.5. 204 No Content .....................................53
- 6.3.6. 205 Reset Content ..................................53
- 6.4. Redirection 3xx ...........................................54
- 6.4.1. 300 Multiple Choices ...............................55
- 6.4.2. 301 Moved Permanently ..............................56
- 6.4.3. 302 Found ..........................................56
- 6.4.4. 303 See Other ......................................57
- 6.4.5. 305 Use Proxy ......................................58
- 6.4.6. 306 (Unused) .......................................58
- 6.4.7. 307 Temporary Redirect .............................58
- 6.5. Client Error 4xx ..........................................58
- 6.5.1. 400 Bad Request ....................................58
- 6.5.2. 402 Payment Required ...............................59
- 6.5.3. 403 Forbidden ......................................59
- 6.5.4. 404 Not Found ......................................59
- 6.5.5. 405 Method Not Allowed .............................59
- 6.5.6. 406 Not Acceptable .................................60
- 6.5.7. 408 Request Timeout ................................60
- 6.5.8. 409 Conflict .......................................60
- 6.5.9. 410 Gone ...........................................60
- 6.5.10. 411 Length Required ...............................61
- 6.5.11. 413 Payload Too Large .............................61
- 6.5.12. 414 URI Too Long ..................................61
- 6.5.13. 415 Unsupported Media Type ........................62
- 6.5.14. 417 Expectation Failed ............................62
- 6.5.15. 426 Upgrade Required ..............................62
- 6.6. Server Error 5xx ..........................................62
- 6.6.1. 500 Internal Server Error ..........................63
- 6.6.2. 501 Not Implemented ................................63
- 6.6.3. 502 Bad Gateway ....................................63
- 6.6.4. 503 Service Unavailable ............................63
- 6.6.5. 504 Gateway Timeout ................................63
- 6.6.6. 505 HTTP Version Not Supported .....................64
- 7. Response Header Fields .........................................64
- 7.1. Control Data ..............................................64
-ed 7.1.1. Origination Date ...................................65
- 7.1.2. Location ...........................................68
- 7.1.3. Retry-After ........................................69
-
-
-
-Fielding & Reschke Standards Track [Page 4]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- 7.1.4. Vary ...............................................70
- 7.2. Validator Header Fields ...................................71
- 7.3. Authentication Challenges .................................72
- 7.4. Response Context ..........................................72
- 7.4.1. Allow ..............................................72
- 7.4.2. Server .............................................73
- 8. IANA Considerations ............................................73
- 8.1. Method Registry ...........................................73
- 8.1.1. Procedure ..........................................74
- 8.1.2. Considerations for New Methods .....................74
- 8.1.3. Registrations ......................................75
- 8.2. Status Code Registry ......................................75
- 8.2.1. Procedure ..........................................75
- 8.2.2. Considerations for New Status Codes ................76
- 8.2.3. Registrations ......................................76
- 8.3. Header Field Registry .....................................77
- 8.3.1. Considerations for New Header Fields ...............78
- 8.3.2. Registrations ......................................80
- 8.4. Content Coding Registry ...................................81
- 8.4.1. Procedure ..........................................81
- 8.4.2. Registrations ......................................81
- 9. Security Considerations ........................................81
- 9.1. Attacks Based on File and Path Names ......................82
- 9.2. Attacks Based on Command, Code, or Query Injection ........82
- 9.3. Disclosure of Personal Information ........................83
- 9.4. Disclosure of Sensitive Information in URIs ...............83
- 9.5. Disclosure of Fragment after Redirects ....................84
- 9.6. Disclosure of Product Information .........................84
- 9.7. Browser Fingerprinting ....................................84
- 10. Acknowledgments ...............................................85
- 11. References ....................................................85
- 11.1. Normative References .....................................85
- 11.2. Informative References ...................................86
- Appendix A. Differences between HTTP and MIME .....................89
- A.1. MIME-Version ..............................................89
- A.2. Conversion to Canonical Form ..............................89
- A.3. Conversion of Date Formats ................................90
- A.4. Conversion of Content-Encoding ............................90
- A.5. Conversion of Content-Transfer-Encoding ...................90
- A.6. MHTML and Line Length Limitations .........................90
- Appendix B. Changes from RFC 2616 .................................91
- Appendix C. Imported ABNF .........................................93
- Appendix D. Collected ABNF ........................................94
- Index .............................................................97
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 5]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-1. Introduction
-
- Each Hypertext Transfer Protocol (HTTP) message is either a request
- or a response. A server listens on a connection for a request,
- parses each message received, interprets the message semantics in
- relation to the identified request target, and responds to that
- request with one or more response messages. A client constructs
- request messages to communicate specific intentions, examines
- received responses to see if the intentions were carried out, and
- determines how to interpret the results. This document defines
- HTTP/1.1 request and response semantics in terms of the architecture
- defined in [RFC7230].
-
- HTTP provides a uniform interface for interacting with a resource
- (Section 2), regardless of its type, nature, or implementation, via
- the manipulation and transfer of representations (Section 3).
-
- HTTP semantics include the intentions defined by each request method
- (Section 4), extensions to those semantics that might be described in
- request header fields (Section 5), the meaning of status codes to
- indicate a machine-readable response (Section 6), and the meaning of
- other control data and resource metadata that might be given in
- response header fields (Section 7).
-
- This document also defines representation metadata that describe how
- a payload is intended to be interpreted by a recipient, the request
- header fields that might influence content selection, and the various
- selection algorithms that are collectively referred to as "content
- negotiation" (Section 3.4).
-
-1.1. Conformance and Error Handling
-
- 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].
-
- Conformance criteria and considerations regarding error handling are
- defined in Section 2.5 of [RFC7230].
-
-1.2. Syntax Notation
-
- This specification uses the Augmented Backus-Naur Form (ABNF)
- notation of [RFC5234] with a list extension, defined in Section 7 of
- [RFC7230], that allows for compact definition of comma-separated
- lists using a '#' operator (similar to how the '*' operator indicates
- repetition). Appendix C describes rules imported from other
- documents. Appendix D shows the collected grammar with all list
- operators expanded to standard ABNF notation.
-
-
-
-Fielding & Reschke Standards Track [Page 6]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- This specification uses the terms "character", "character encoding
- scheme", "charset", and "protocol element" as they are defined in
- [RFC6365].
-
-2. Resources
-
- The target of an HTTP request is called a "resource". HTTP does not
- limit the nature of a resource; it merely defines an interface that
- might be used to interact with resources. Each resource is
- identified by a Uniform Resource Identifier (URI), as described in
- Section 2.7 of [RFC7230].
-
- When a client constructs an HTTP/1.1 request message, it sends the
- target URI in one of various forms, as defined in (Section 5.3 of
- [RFC7230]). When a request is received, the server reconstructs an
- effective request URI for the target resource (Section 5.5 of
- [RFC7230]).
-
- One design goal of HTTP is to separate resource identification from
- request semantics, which is made possible by vesting the request
- semantics in the request method (Section 4) and a few
- request-modifying header fields (Section 5). If there is a conflict
- between the method semantics and any semantic implied by the URI
- itself, as described in Section 4.2.1, the method semantics take
- precedence.
-
-3. Representations
-
- Considering that a resource could be anything, and that the uniform
- interface provided by HTTP is similar to a window through which one
- can observe and act upon such a thing only through the communication
- of messages to some independent actor on the other side, an
- abstraction is needed to represent ("take the place of") the current
- or desired state of that thing in our communications. That
- abstraction is called a representation [REST].
-
- For the purposes of HTTP, a "representation" is information that is
- intended to reflect a past, current, or desired state of a given
- resource, in a format that can be readily communicated via the
- protocol, and that consists of a set of representation metadata and a
- potentially unbounded stream of representation data.
-
- An origin server might be provided with, or be capable of generating,
- multiple representations that are each intended to reflect the
- current state of a target resource. In such cases, some algorithm is
- used by the origin server to select one of those representations as
- most applicable to a given request, usually based on content
- negotiation. This "selected representation" is used to provide the
-
-
-
-Fielding & Reschke Standards Track [Page 7]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- data and metadata for evaluating conditional requests [RFC7232] and
- constructing the payload for 200 (OK) and 304 (Not Modified)
- responses to GET (Section 4.3.1).
-
-3.1. Representation Metadata
-
- Representation header fields provide metadata about the
- representation. When a message includes a payload body, the
- representation header fields describe how to interpret the
- representation data enclosed in the payload body. In a response to a
- HEAD request, the representation header fields describe the
- representation data that would have been enclosed in the payload body
- if the same request had been a GET.
-
- The following header fields convey representation metadata:
-
- +-------------------+-----------------+
- | Header Field Name | Defined in... |
- +-------------------+-----------------+
- | Content-Type | Section 3.1.1.5 |
- | Content-Encoding | Section 3.1.2.2 |
- | Content-Language | Section 3.1.3.2 |
- | Content-Location | Section 3.1.4.2 |
- +-------------------+-----------------+
-
-3.1.1. Processing Representation Data
-
-3.1.1.1. Media Type
-
- HTTP uses Internet media types [RFC2046] in the Content-Type
- (Section 3.1.1.5) and Accept (Section 5.3.2) header fields in order
- to provide open and extensible data typing and type negotiation.
- Media types define both a data format and various processing models:
- how to process that data in accordance with each context in which it
- is received.
-
- media-type = type "/" subtype *( OWS ";" OWS parameter )
- type = token
- subtype = token
-
- The type/subtype MAY be followed by parameters in the form of
- name=value pairs.
-
- parameter = token "=" ( token / quoted-string )
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 8]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- The type, subtype, and parameter name tokens are case-insensitive.
- Parameter values might or might not be case-sensitive, depending on
- the semantics of the parameter name. 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.
-
- A parameter value that matches the token production can be
- transmitted either as a token or within a quoted-string. The quoted
- and unquoted values are equivalent. For example, the following
- examples are all equivalent, but the first is preferred for
- consistency:
-
- text/html;charset=utf-8
- text/html;charset=UTF-8
- Text/HTML;Charset="utf-8"
- text/html; charset="utf-8"
-
- Internet media types ought to be registered with IANA according to
- the procedures defined in [BCP13].
-
- Note: Unlike some similar constructs in other header fields, media
- type parameters do not allow whitespace (even "bad" whitespace)
- around the "=" character.
-
-3.1.1.2. Charset
-
- HTTP uses charset names to indicate or negotiate the character
- encoding scheme of a textual representation [RFC6365]. A charset is
- identified by a case-insensitive token.
-
- charset = token
-
- Charset names ought to be registered in the IANA "Character Sets"
- registry (<http://www.iana.org/assignments/character-sets>) according
- to the procedures defined in [RFC2978].
-
-3.1.1.3. Canonicalization and Text Defaults
-
- Internet media types are registered with a canonical form in order to
- be interoperable among systems with varying native encoding formats.
- Representations selected or transferred via HTTP ought to be in
- canonical form, for many of the same reasons described by the
- Multipurpose Internet Mail Extensions (MIME) [RFC2045]. However, the
- performance characteristics of email deployments (i.e., store and
- forward messages to peers) are significantly different from those
- common to HTTP and the Web (server-based information services).
- Furthermore, MIME's constraints for the sake of compatibility with
- older mail transfer protocols do not apply to HTTP (see Appendix A).
-
-
-
-Fielding & Reschke Standards Track [Page 9]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- MIME's canonical form requires that media subtypes of the "text" type
- use CRLF as the text line break. HTTP allows the transfer of text
- media with plain CR or LF alone representing a line break, when such
- line breaks are consistent for an entire representation. An HTTP
- sender MAY generate, and a recipient MUST be able to parse, line
- breaks in text media that consist of CRLF, bare CR, or bare LF. In
- addition, text media in HTTP is not limited to charsets that use
- octets 13 and 10 for CR and LF, respectively. This flexibility
- regarding line breaks applies only to text within a representation
- that has been assigned a "text" media type; it does not apply to
- "multipart" types or HTTP elements outside the payload body (e.g.,
- header fields).
-
- If a representation is encoded with a content-coding, the underlying
- data ought to be in a form defined above prior to being encoded.
-
-3.1.1.4. Multipart Types
-
- MIME provides for a number of "multipart" types -- encapsulations of
- one or more representations within a single message body. All
- multipart types share a common syntax, as defined in Section 5.1.1 of
- [RFC2046], and include a boundary parameter as part of the media type
- value. The message body is itself a protocol element; a sender MUST
- generate only CRLF to represent line breaks between body parts.
-
- HTTP message framing does not use the multipart boundary as an
- indicator of message body length, though it might be used by
- implementations that generate or process the payload. For example,
- the "multipart/form-data" type is often used for carrying form data
- in a request, as described in [RFC2388], and the "multipart/
- byteranges" type is defined by this specification for use in some 206
- (Partial Content) responses [RFC7233].
-
-3.1.1.5. Content-Type
-
- The "Content-Type" header field indicates the media type of the
- associated representation: either the representation enclosed in the
- message payload or the selected representation, as determined by the
- message semantics. The indicated media type defines both the data
- format and how that data is intended to be processed by a recipient,
- within the scope of the received message semantics, after any content
- codings indicated by Content-Encoding are decoded.
-
- Content-Type = media-type
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 10]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- Media types are defined in Section 3.1.1.1. An example of the field
- is
-
- Content-Type: text/html; charset=ISO-8859-4
-
- A sender that generates a message containing a payload body SHOULD
- generate a Content-Type header field in that message unless the
- intended media type of the enclosed representation is unknown to the
- sender. If a Content-Type header field is not present, the recipient
- MAY either assume a media type of "application/octet-stream"
- ([RFC2046], Section 4.5.1) or examine the data to determine its type.
-
- In practice, resource owners do not always properly configure their
- origin server to provide the correct Content-Type for a given
- representation, with the result that some clients will examine a
- payload's content and override the specified type. Clients that do
- so risk drawing incorrect conclusions, which might expose additional
- security risks (e.g., "privilege escalation"). Furthermore, it is
- impossible to determine the sender's intent by examining the data
- format: many data formats match multiple media types that differ only
- in processing semantics. Implementers are encouraged to provide a
- means of disabling such "content sniffing" when it is used.
-
-3.1.2. Encoding for Compression or Integrity
-
-3.1.2.1. Content Codings
-
- Content coding values indicate an encoding transformation that has
- been or can be applied to a representation. Content codings are
- primarily used to allow a representation to be compressed or
- otherwise usefully transformed without losing the identity of its
- underlying media type and without loss of information. Frequently,
- the representation is stored in coded form, transmitted directly, and
- only decoded by the final recipient.
-
- content-coding = token
-
- All content-coding values are case-insensitive and ought to be
- registered within the "HTTP Content Coding Registry", as defined in
- Section 8.4. They are used in the Accept-Encoding (Section 5.3.4)
- and Content-Encoding (Section 3.1.2.2) header fields.
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 11]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- The following content-coding values are defined by this
- specification:
-
- compress (and x-compress): See Section 4.2.1 of [RFC7230].
-
- deflate: See Section 4.2.2 of [RFC7230].
-
- gzip (and x-gzip): See Section 4.2.3 of [RFC7230].
-
-3.1.2.2. Content-Encoding
-
- The "Content-Encoding" header field indicates what content codings
- have been applied to the representation, beyond those inherent in the
- media type, and thus what decoding mechanisms have to be applied in
- order to obtain data in the media type referenced by the Content-Type
- header field. Content-Encoding is primarily used to allow a
- representation's data to be compressed without losing the identity of
- its underlying media type.
-
- Content-Encoding = 1#content-coding
-
- An example of its use is
-
- Content-Encoding: gzip
-
- If one or more encodings have been applied to a representation, the
- sender that applied the encodings MUST generate a Content-Encoding
- header field that lists the content codings in the order in which
- they were applied. Additional information about the encoding
- parameters can be provided by other header fields not defined by this
- specification.
-
- Unlike Transfer-Encoding (Section 3.3.1 of [RFC7230]), the codings
- listed in Content-Encoding are a characteristic of the
- representation; the representation is defined in terms of the coded
- form, and all other metadata about the representation is about the
- coded form unless otherwise noted in the metadata definition.
- Typically, the representation is only decoded just prior to rendering
- or analogous usage.
-
- If the media type includes an inherent encoding, such as a data
- format that is always compressed, then that encoding would not be
- restated in Content-Encoding even if it happens to be the same
- algorithm as one of the content codings. Such a content coding would
- only be listed if, for some bizarre reason, it is applied a second
- time to form the representation. Likewise, an origin server might
- choose to publish the same data as multiple representations that
- differ only in whether the coding is defined as part of Content-Type
-
-
-
-Fielding & Reschke Standards Track [Page 12]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- or Content-Encoding, since some user agents will behave differently
- in their handling of each response (e.g., open a "Save as ..." dialog
- instead of automatic decompression and rendering of content).
-
- An origin server MAY respond with a status code of 415 (Unsupported
- Media Type) if a representation in the request message has a content
- coding that is not acceptable.
-
-3.1.3. Audience Language
-
-3.1.3.1. Language Tags
-
- A language tag, as defined in [RFC5646], 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 header fields. Accept-Language uses the broader
- language-range production defined in Section 5.3.5, whereas
- Content-Language uses the language-tag production defined below.
-
- language-tag = <Language-Tag, see [RFC5646], Section 2.1>
-
- A language tag is a sequence of one or more case-insensitive subtags,
- each separated by a hyphen character ("-", %x2D). In most cases, a
- language tag consists of a primary language subtag that identifies a
- broad family of related languages (e.g., "en" = English), which is
- optionally followed by a series of subtags that refine or narrow that
- language's range (e.g., "en-CA" = the variety of English as
- communicated in Canada). Whitespace is not allowed within a language
- tag. Example tags include:
-
- fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN
-
- See [RFC5646] for further information.
-
-3.1.3.2. Content-Language
-
- The "Content-Language" header field describes the natural language(s)
- of the intended audience for the representation. Note that this
- might not be equivalent to all the languages used within the
- representation.
-
- Content-Language = 1#language-tag
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 13]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- Language tags are defined in Section 3.1.3.1. The primary purpose of
- Content-Language is to allow a user to identify and differentiate
- representations according to the users' own preferred language.
- Thus, if the 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 a
- representation 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.
-
-3.1.4. Identification
-
-3.1.4.1. Identifying a Representation
-
- When a complete or partial representation is transferred in a message
- payload, it is often desirable for the sender to supply, or the
- recipient to determine, an identifier for a resource corresponding to
- that representation.
-
- For a request message:
-
- o If the request has a Content-Location header field, then the
- sender asserts that the payload is a representation of the
- resource identified by the Content-Location field-value. However,
- such an assertion cannot be trusted unless it can be verified by
- other means (not defined by this specification). The information
- might still be useful for revision history links.
-
-
-
-
-Fielding & Reschke Standards Track [Page 14]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- o Otherwise, the payload is unidentified.
-
- For a response message, the following rules are applied in order
- until a match is found:
-
- 1. If the request method is GET or HEAD and the response status code
- is 200 (OK), 204 (No Content), 206 (Partial Content), or 304 (Not
- Modified), the payload is a representation of the resource
- identified by the effective request URI (Section 5.5 of
- [RFC7230]).
-
- 2. If the request method is GET or HEAD and the response status code
- is 203 (Non-Authoritative Information), the payload is a
- potentially modified or enhanced representation of the target
- resource as provided by an intermediary.
-
- 3. If the response has a Content-Location header field and its
- field-value is a reference to the same URI as the effective
- request URI, the payload is a representation of the resource
- identified by the effective request URI.
-
- 4. If the response has a Content-Location header field and its
- field-value is a reference to a URI different from the effective
- request URI, then the sender asserts that the payload is a
- representation of the resource identified by the Content-Location
- field-value. However, such an assertion cannot be trusted unless
- it can be verified by other means (not defined by this
- specification).
-
- 5. Otherwise, the payload is unidentified.
-
-3.1.4.2. Content-Location
-
- The "Content-Location" header field references a URI that can be used
- as an identifier for a specific resource corresponding to the
- representation in this message's payload. In other words, if one
- were to perform a GET request on this URI at the time of this
- message's generation, then a 200 (OK) response would contain the same
- representation that is enclosed as payload in this message.
-
- Content-Location = absolute-URI / partial-URI
-
- The Content-Location value is not a replacement for the effective
- Request URI (Section 5.5 of [RFC7230]). It is representation
- metadata. It has the same syntax and semantics as the header field
- of the same name defined for MIME body parts in Section 4 of
- [RFC2557]. However, its appearance in an HTTP message has some
- special implications for HTTP recipients.
-
-
-
-Fielding & Reschke Standards Track [Page 15]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- If Content-Location is included in a 2xx (Successful) response
- message and its value refers (after conversion to absolute form) to a
- URI that is the same as the effective request URI, then the recipient
- MAY consider the payload to be a current representation of that
- resource at the time indicated by the message origination date. For
- a GET (Section 4.3.1) or HEAD (Section 4.3.2) request, this is the
- same as the default semantics when no Content-Location is provided by
- the server. For a state-changing request like PUT (Section 4.3.4) or
- POST (Section 4.3.3), it implies that the server's response contains
- the new representation of that resource, thereby distinguishing it
- from representations that might only report about the action (e.g.,
- "It worked!"). This allows authoring applications to update their
- local copies without the need for a subsequent GET request.
-
- If Content-Location is included in a 2xx (Successful) response
- message and its field-value refers to a URI that differs from the
- effective request URI, then the origin server claims that the URI is
- an identifier for a different resource corresponding to the enclosed
- representation. Such a claim can only be trusted if both identifiers
- share the same resource owner, which cannot be programmatically
- determined via HTTP.
-
- o For a response to a GET or HEAD request, this is an indication
- that the effective request URI refers to a resource that is
- subject to content negotiation and the Content-Location
- field-value is a more specific identifier for the selected
- representation.
-
- o For a 201 (Created) response to a state-changing method, a
- Content-Location field-value that is identical to the Location
- field-value indicates that this payload is a current
- representation of the newly created resource.
-
- o Otherwise, such a Content-Location indicates that this payload is
- a representation reporting on the requested action's status and
- that the same report is available (for future access with GET) at
- the given URI. For example, a purchase transaction made via a
- POST request might include a receipt document as the payload of
- the 200 (OK) response; the Content-Location field-value provides
- an identifier for retrieving a copy of that same receipt in the
- future.
-
- A user agent that sends Content-Location in a request message is
- stating that its value refers to where the user agent originally
- obtained the content of the enclosed representation (prior to any
- modifications made by that user agent). In other words, the user
- agent is providing a back link to the source of the original
- representation.
-
-
-
-Fielding & Reschke Standards Track [Page 16]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- An origin server that receives a Content-Location field in a request
- message MUST treat the information as transitory request context
- rather than as metadata to be saved verbatim as part of the
- representation. An origin server MAY use that context to guide in
- processing the request or to save it for other uses, such as within
- source links or versioning metadata. However, an origin server MUST
- NOT use such context information to alter the request semantics.
-
- For example, if a client makes a PUT request on a negotiated resource
- and the origin server accepts that PUT (without redirection), then
- the new state of that resource is expected to be consistent with the
- one representation supplied in that PUT; the Content-Location cannot
- be used as a form of reverse content selection identifier to update
- only one of the negotiated representations. If the user agent had
- wanted the latter semantics, it would have applied the PUT directly
- to the Content-Location URI.
-
-3.2. Representation Data
-
- The representation data associated with an HTTP message is either
- provided as the payload body of the message or referred to by the
- message semantics and the effective request URI. The representation
- data is in a format and encoding defined by the representation
- metadata header fields.
-
- The data type of the representation data is determined via the header
- fields Content-Type and Content-Encoding. These define a two-layer,
- ordered encoding model:
-
- representation-data := Content-Encoding( Content-Type( bits ) )
-
-3.3. Payload Semantics
-
- Some HTTP messages transfer a complete or partial representation as
- the message "payload". In some cases, a payload might contain only
- the associated representation's header fields (e.g., responses to
- HEAD) or only some part(s) of the representation data (e.g., the 206
- (Partial Content) status code).
-
- The purpose of a payload in a request is defined by the method
- semantics. For example, a representation in the payload of a PUT
- request (Section 4.3.4) represents the desired state of the target
- resource if the request is successfully applied, whereas a
- representation in the payload of a POST request (Section 4.3.3)
- represents information to be processed by the target resource.
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 17]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- In a response, the payload's purpose is defined by both the request
- method and the response status code. For example, the payload of a
- 200 (OK) response to GET (Section 4.3.1) represents the current state
- of the target resource, as observed at the time of the message
- origination date (Section 7.1.1.2), whereas the payload of the same
- status code in a response to POST might represent either the
- processing result or the new state of the target resource after
- applying the processing. Response messages with an error status code
- usually contain a payload that represents the error condition, such
- that it describes the error state and what next steps are suggested
- for resolving it.
-
- Header fields that specifically describe the payload, rather than the
- associated representation, are referred to as "payload header
- fields". Payload header fields are defined in other parts of this
- specification, due to their impact on message parsing.
-
- +-------------------+----------------------------+
- | Header Field Name | Defined in... |
- +-------------------+----------------------------+
- | Content-Length | Section 3.3.2 of [RFC7230] |
- | Content-Range | Section 4.2 of [RFC7233] |
- | Trailer | Section 4.4 of [RFC7230] |
- | Transfer-Encoding | Section 3.3.1 of [RFC7230] |
- +-------------------+----------------------------+
-
-3.4. Content Negotiation
-
- When responses convey payload information, whether indicating a
- success or an error, the origin server often has different ways of
- representing that information; for example, in different formats,
- languages, or encodings. Likewise, different users or user agents
- might have differing capabilities, characteristics, or preferences
- that could influence which representation, among those available,
- would be best to deliver. For this reason, HTTP provides mechanisms
- for content negotiation.
-
- This specification defines two patterns of content negotiation that
- can be made visible within the protocol: "proactive", where the
- server selects the representation based upon the user agent's stated
- preferences, and "reactive" negotiation, where the server provides a
- list of representations for the user agent to choose from. Other
- patterns of content negotiation include "conditional content", where
- the representation consists of multiple parts that are selectively
- rendered based on user agent parameters, "active content", where the
- representation contains a script that makes additional (more
- specific) requests based on the user agent characteristics, and
- "Transparent Content Negotiation" ([RFC2295]), where content
-
-
-
-Fielding & Reschke Standards Track [Page 18]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- selection is performed by an intermediary. These patterns are not
- mutually exclusive, and each has trade-offs in applicability and
- practicality.
-
- Note that, in all cases, HTTP is not aware of the resource semantics.
- The consistency with which an origin server responds to requests,
- over time and over the varying dimensions of content negotiation, and
- thus the "sameness" of a resource's observed representations over
- time, is determined entirely by whatever entity or algorithm selects
- or generates those responses. HTTP pays no attention to the man
- behind the curtain.
-
-3.4.1. Proactive Negotiation
-
- When content negotiation preferences are sent by the user agent in a
- request to encourage an algorithm located at the server to select the
- preferred representation, it is called proactive negotiation (a.k.a.,
- server-driven negotiation). Selection is based on the available
- representations for a response (the dimensions over which it might
- vary, such as language, content-coding, etc.) compared to various
- information supplied in the request, including both the explicit
- negotiation fields of Section 5.3 and implicit characteristics, such
- as the client's network address or parts of the User-Agent field.
-
- Proactive negotiation is advantageous when the algorithm for
- selecting from among the available representations is difficult to
- describe to a user agent, or when the server desires to send its
- "best guess" to the user agent 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, a user agent MAY send request header fields that
- describe its preferences.
-
- Proactive negotiation has serious disadvantages:
-
- o 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?);
-
- o 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 risk
- to the user's privacy;
-
- o It complicates the implementation of an origin server and the
- algorithms for generating responses to a request; and,
-
-
-
-Fielding & Reschke Standards Track [Page 19]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- o It limits the reusability of responses for shared caching.
-
- A user agent cannot rely on proactive negotiation preferences being
- consistently honored, since the origin server might not implement
- proactive negotiation for the requested resource or might decide that
- sending a response that doesn't conform to the user agent's
- preferences is better than sending a 406 (Not Acceptable) response.
-
- A Vary header field (Section 7.1.4) is often sent in a response
- subject to proactive negotiation to indicate what parts of the
- request information were used in the selection algorithm.
-
-3.4.2. Reactive Negotiation
-
- With reactive negotiation (a.k.a., agent-driven negotiation),
- selection of the best response representation (regardless of the
- status code) is performed by the user agent after receiving an
- initial response from the origin server that contains a list of
- resources for alternative representations. If the user agent is not
- satisfied by the initial response representation, it can perform a
- GET request on one or more of the alternative resources, selected
- based on metadata included in the list, to obtain a different form of
- representation for that response. Selection of alternatives might be
- performed automatically by the user agent or manually by the user
- selecting from a generated (possibly hypertext) menu.
-
- Note that the above refers to representations of the response, in
- general, not representations of the resource. The alternative
- representations are only considered representations of the target
- resource if the response in which those alternatives are provided has
- the semantics of being a representation of the target resource (e.g.,
- a 200 (OK) response to a GET request) or has the semantics of
- providing links to alternative representations for the target
- resource (e.g., a 300 (Multiple Choices) response to a GET request).
-
- A server might choose not to send an initial representation, other
- than the list of alternatives, and thereby indicate that reactive
- negotiation by the user agent is preferred. For example, the
- alternatives listed in responses with the 300 (Multiple Choices) and
- 406 (Not Acceptable) status codes include information about the
- available representations so that the user or user agent can react by
- making a selection.
-
- Reactive 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.
-
-
-
-Fielding & Reschke Standards Track [Page 20]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- Reactive negotiation suffers from the disadvantages of transmitting a
- list of alternatives to the user agent, which degrades user-perceived
- latency if transmitted in the header section, and needing a second
- request to obtain an alternate representation. Furthermore, this
- specification does not define a mechanism for supporting automatic
- selection, though it does not prevent such a mechanism from being
- developed as an extension.
-
-4. Request Methods
-
-4.1. Overview
-
- The request method token is the primary source of request semantics;
- it indicates the purpose for which the client has made this request
- and what is expected by the client as a successful result.
-
- The request method's semantics might be further specialized by the
- semantics of some header fields when present in a request (Section 5)
- if those additional semantics do not conflict with the method. For
- example, a client can send conditional request header fields
- (Section 5.2) to make the requested action conditional on the current
- state of the target resource ([RFC7232]).
-
- method = token
-
- HTTP was originally designed to be usable as an interface to
- distributed object systems. The request method was envisioned as
- applying semantics to a target resource in much the same way as
- invoking a defined method on an identified object would apply
- semantics. The method token is case-sensitive because it might be
- used as a gateway to object-based systems with case-sensitive method
- names.
-
- Unlike distributed objects, the standardized request methods in HTTP
- are not resource-specific, since uniform interfaces provide for
- better visibility and reuse in network-based systems [REST]. Once
- defined, a standardized method ought to have the same semantics when
- applied to any resource, though each resource determines for itself
- whether those semantics are implemented or allowed.
-
- This specification defines a number of standardized methods that are
- commonly used in HTTP, as outlined by the following table. By
- convention, standardized methods are defined in all-uppercase
- US-ASCII letters.
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 21]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- +---------+-------------------------------------------------+-------+
- | Method | Description | Sec. |
- +---------+-------------------------------------------------+-------+
- | GET | Transfer a current representation of the target | 4.3.1 |
- | | resource. | |
- | HEAD | Same as GET, but only transfer the status line | 4.3.2 |
- | | and header section. | |
- | POST | Perform resource-specific processing on the | 4.3.3 |
- | | request payload. | |
- | PUT | Replace all current representations of the | 4.3.4 |
- | | target resource with the request payload. | |
- | DELETE | Remove all current representations of the | 4.3.5 |
- | | target resource. | |
- | CONNECT | Establish a tunnel to the server identified by | 4.3.6 |
- | | the target resource. | |
- | OPTIONS | Describe the communication options for the | 4.3.7 |
- | | target resource. | |
- | TRACE | Perform a message loop-back test along the path | 4.3.8 |
- | | to the target resource. | |
- +---------+-------------------------------------------------+-------+
-
- All general-purpose servers MUST support the methods GET and HEAD.
- All other methods are OPTIONAL.
-
- Additional methods, outside the scope of this specification, have
- been standardized for use in HTTP. All such methods ought to be
- registered within the "Hypertext Transfer Protocol (HTTP) Method
- Registry" maintained by IANA, as defined in Section 8.1.
-
- The set of methods allowed by a target resource can be listed in an
- Allow header field (Section 7.4.1). However, the set of allowed
- methods can change dynamically. When a request method is received
- that is unrecognized or not implemented by an origin server, the
- origin server SHOULD respond with the 501 (Not Implemented) status
- code. When a request method is received that is known by an origin
- server but not allowed for the target resource, the origin server
- SHOULD respond with the 405 (Method Not Allowed) status code.
-
-4.2. Common Method Properties
-
-4.2.1. Safe Methods
-
- Request methods are considered "safe" if their defined semantics are
- essentially read-only; i.e., the client does not request, and does
- not expect, any state change on the origin server as a result of
- applying a safe method to a target resource. Likewise, reasonable
- use of a safe method is not expected to cause any harm, loss of
- property, or unusual burden on the origin server.
-
-
-
-Fielding & Reschke Standards Track [Page 22]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- This definition of safe methods does not prevent an implementation
- from including behavior that is potentially harmful, that is not
- entirely read-only, or that causes side effects while invoking a safe
- method. What is important, however, is that the client did not
- request that additional behavior and cannot be held accountable for
- it. For example, most servers append request information to access
- log files at the completion of every response, regardless of the
- method, and that is considered safe even though the log storage might
- become full and crash the server. Likewise, a safe request initiated
- by selecting an advertisement on the Web will often have the side
- effect of charging an advertising account.
-
- Of the request methods defined by this specification, the GET, HEAD,
- OPTIONS, and TRACE methods are defined to be safe.
-
- The purpose of distinguishing between safe and unsafe methods is to
- allow automated retrieval processes (spiders) and cache performance
- optimization (pre-fetching) to work without fear of causing harm. In
- addition, it allows a user agent to apply appropriate constraints on
- the automated use of unsafe methods when processing potentially
- untrusted content.
-
- A user agent SHOULD distinguish between safe and unsafe methods when
- presenting potential actions to a user, such that the user can be
- made aware of an unsafe action before it is requested.
-
- When a resource is constructed such that parameters within the
- effective request URI have the effect of selecting an action, it is
- the resource owner's responsibility to ensure that the action is
- consistent with the request method semantics. For example, it is
- common for Web-based content editing software to use actions within
- query parameters, such as "page?do=delete". If the purpose of such a
- resource is to perform an unsafe action, then the resource owner MUST
- disable or disallow that action when it is accessed using a safe
- request method. Failure to do so will result in unfortunate side
- effects when automated processes perform a GET on every URI reference
- for the sake of link maintenance, pre-fetching, building a search
- index, etc.
-
-4.2.2. Idempotent Methods
-
- A request method is considered "idempotent" if the intended effect on
- the server of multiple identical requests with that method is the
- same as the effect for a single such request. Of the request methods
- defined by this specification, PUT, DELETE, and safe request methods
- are idempotent.
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 23]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- Like the definition of safe, the idempotent property only applies to
- what has been requested by the user; a server is free to log each
- request separately, retain a revision control history, or implement
- other non-idempotent side effects for each idempotent request.
-
- Idempotent methods are distinguished because the request can be
- repeated automatically if a communication failure occurs before the
- client is able to read the server's response. For example, if a
- client sends a PUT request and the underlying connection is closed
- before any response is received, then the client can establish a new
- connection and retry the idempotent request. It knows that repeating
- the request will have the same intended effect, even if the original
- request succeeded, though the response might differ.
-
-4.2.3. Cacheable Methods
-
- Request methods can be defined as "cacheable" to indicate that
- responses to them are allowed to be stored for future reuse; for
- specific requirements see [RFC7234]. In general, safe methods that
- do not depend on a current or authoritative response are defined as
- cacheable; this specification defines GET, HEAD, and POST as
- cacheable, although the overwhelming majority of cache
- implementations only support GET and HEAD.
-
-4.3. Method Definitions
-
-4.3.1. GET
-
- The GET method requests transfer of a current selected representation
- for the target resource. GET is the primary mechanism of information
- retrieval and the focus of almost all performance optimizations.
- Hence, when people speak of retrieving some identifiable information
- via HTTP, they are generally referring to making a GET request.
-
- It is tempting to think of resource identifiers as remote file system
- pathnames and of representations as being a copy of the contents of
- such files. In fact, that is how many resources are implemented (see
- Section 9.1 for related security considerations). However, there are
- no such limitations in practice. The HTTP interface for a resource
- is just as likely to be implemented as a tree of content objects, a
- programmatic view on various database records, or a gateway to other
- information systems. Even when the URI mapping mechanism is tied to
- a file system, an origin server might be configured to execute the
- files with the request as input and send the output as the
- representation rather than transfer the files directly. Regardless,
- only the origin server needs to know how each of its resource
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 24]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- identifiers corresponds to an implementation and how each
- implementation manages to select and send a current representation of
- the target resource in a response to GET.
-
- A client can alter the semantics of GET to be a "range request",
- requesting transfer of only some part(s) of the selected
- representation, by sending a Range header field in the request
- ([RFC7233]).
-
- A payload within a GET request message has no defined semantics;
- sending a payload body on a GET request might cause some existing
- implementations to reject the request.
-
- The response to a GET request is cacheable; a cache MAY use it to
- satisfy subsequent GET and HEAD requests unless otherwise indicated
- by the Cache-Control header field (Section 5.2 of [RFC7234]).
-
-4.3.2. HEAD
-
- The HEAD method is identical to GET except that the server MUST NOT
- send a message body in the response (i.e., the response terminates at
- the end of the header section). The server SHOULD send the same
- header fields in response to a HEAD request as it would have sent if
- the request had been a GET, except that the payload header fields
- (Section 3.3) MAY be omitted. This method can be used for obtaining
- metadata about the selected representation without transferring the
- representation data and is often used for testing hypertext links for
- validity, accessibility, and recent modification.
-
- A payload within a HEAD request message has no defined semantics;
- sending a payload body on a HEAD request might cause some existing
- implementations to reject the request.
-
- The response to a HEAD request is cacheable; a cache MAY use it to
- satisfy subsequent HEAD requests unless otherwise indicated by the
- Cache-Control header field (Section 5.2 of [RFC7234]). A HEAD
- response might also have an effect on previously cached responses to
- GET; see Section 4.3.5 of [RFC7234].
-
-4.3.3. POST
-
- The POST method requests that the target resource process the
- representation enclosed in the request according to the resource's
- own specific semantics. For example, POST is used for the following
- functions (among others):
-
- o Providing a block of data, such as the fields entered into an HTML
- form, to a data-handling process;
-
-
-
-Fielding & Reschke Standards Track [Page 25]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- o Posting a message to a bulletin board, newsgroup, mailing list,
- blog, or similar group of articles;
-
- o Creating a new resource that has yet to be identified by the
- origin server; and
-
- o Appending data to a resource's existing representation(s).
-
- An origin server indicates response semantics by choosing an
- appropriate status code depending on the result of processing the
- POST request; almost all of the status codes defined by this
- specification might be received in a response to POST (the exceptions
- being 206 (Partial Content), 304 (Not Modified), and 416 (Range Not
- Satisfiable)).
-
- If one or more resources has been created on the origin server as a
- result of successfully processing a POST request, the origin server
- SHOULD send a 201 (Created) response containing a Location header
- field that provides an identifier for the primary resource created
- (Section 7.1.2) and a representation that describes the status of the
- request while referring to the new resource(s).
-
- Responses to POST requests are only cacheable when they include
- explicit freshness information (see Section 4.2.1 of [RFC7234]).
- However, POST caching is not widely implemented. For cases where an
- origin server wishes the client to be able to cache the result of a
- POST in a way that can be reused by a later GET, the origin server
- MAY send a 200 (OK) response containing the result and a
- Content-Location header field that has the same value as the POST's
- effective request URI (Section 3.1.4.2).
-
- If the result of processing a POST would be equivalent to a
- representation of an existing resource, an origin server MAY redirect
- the user agent to that resource by sending a 303 (See Other) response
- with the existing resource's identifier in the Location field. This
- has the benefits of providing the user agent a resource identifier
- and transferring the representation via a method more amenable to
- shared caching, though at the cost of an extra request if the user
- agent does not already have the representation cached.
-
-4.3.4. PUT
-
- The PUT method requests that the state of the target resource be
- created or replaced with the state defined by the representation
- enclosed in the request message payload. A successful PUT of a given
- representation would suggest that a subsequent GET on that same
- target resource will result in an equivalent representation being
- sent in a 200 (OK) response. However, there is no guarantee that
-
-
-
-Fielding & Reschke Standards Track [Page 26]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- such a state change will be observable, since the target resource
- might be acted upon by other user agents in parallel, or might be
- subject to dynamic processing by the origin server, before any
- subsequent GET is received. A successful response only implies that
- the user agent's intent was achieved at the time of its processing by
- the origin server.
-
- If the target resource does not have a current representation and the
- PUT successfully creates one, then the origin server MUST inform the
- user agent by sending a 201 (Created) response. If the target
- resource does have a current representation and that representation
- is successfully modified in accordance with the state of the enclosed
- representation, then the origin server MUST send either a 200 (OK) or
- a 204 (No Content) response to indicate successful completion of the
- request.
-
- An origin server SHOULD ignore unrecognized header fields received in
- a PUT request (i.e., do not save them as part of the resource state).
-
- An origin server SHOULD verify that the PUT representation is
- consistent with any constraints the server has for the target
- resource that cannot or will not be changed by the PUT. This is
- particularly important when the origin server uses internal
- configuration information related to the URI in order to set the
- values for representation metadata on GET responses. When a PUT
- representation is inconsistent with the target resource, the origin
- server SHOULD either make them consistent, by transforming the
- representation or changing the resource configuration, or respond
- with an appropriate error message containing sufficient information
- to explain why the representation is unsuitable. The 409 (Conflict)
- or 415 (Unsupported Media Type) status codes are suggested, with the
- latter being specific to constraints on Content-Type values.
-
- For example, if the target resource is configured to always have a
- Content-Type of "text/html" and the representation being PUT has a
- Content-Type of "image/jpeg", the origin server ought to do one of:
-
- a. reconfigure the target resource to reflect the new media type;
-
- b. transform the PUT representation to a format consistent with that
- of the resource before saving it as the new resource state; or,
-
- c. reject the request with a 415 (Unsupported Media Type) response
- indicating that the target resource is limited to "text/html",
- perhaps including a link to a different resource that would be a
- suitable target for the new representation.
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 27]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- HTTP does not define exactly how a PUT method affects the state of an
- origin server beyond what can be expressed by the intent of the user
- agent request and the semantics of the origin server response. It
- does not define what a resource might be, in any sense of that word,
- beyond the interface provided via HTTP. It does not define how
- resource state is "stored", nor how such storage might change as a
- result of a change in resource state, nor how the origin server
- translates resource state into representations. Generally speaking,
- all implementation details behind the resource interface are
- intentionally hidden by the server.
-
- An origin server MUST NOT send a validator header field
- (Section 7.2), such as an ETag or Last-Modified field, in a
- successful response to PUT unless the request's representation data
- was saved without any transformation applied to the body (i.e., the
- resource's new representation data is identical to the representation
- data received in the PUT request) and the validator field value
- reflects the new representation. This requirement allows a user
- agent to know when the representation body it has in memory remains
- current as a result of the PUT, thus not in need of being retrieved
- again from the origin server, and that the new validator(s) received
- in the response can be used for future conditional requests in order
- to prevent accidental overwrites (Section 5.2).
-
- The fundamental difference between the POST and PUT methods is
- highlighted by the different intent for the enclosed representation.
- The target resource in a POST request is intended to handle the
- enclosed representation according to the resource's own semantics,
- whereas the enclosed representation in a PUT request is defined as
- replacing the state of the target resource. Hence, the intent of PUT
- is idempotent and visible to intermediaries, even though the exact
- effect is only known by the origin server.
-
- Proper interpretation of a PUT request presumes that the user agent
- knows which target resource is desired. A service that selects a
- proper URI on behalf of the client, after receiving a state-changing
- request, SHOULD be implemented using the POST method rather than PUT.
- If the origin server will not make the requested PUT state change to
- the target resource and instead wishes to have it applied to a
- different resource, such as when the resource has been moved to a
- different URI, then the origin server MUST send an appropriate 3xx
- (Redirection) response; the user agent MAY then make its own decision
- regarding whether or not to redirect the request.
-
- A PUT request applied to the target resource can have side effects on
- other resources. For example, an article might have a URI for
- identifying "the current version" (a resource) that is separate from
- the URIs identifying each particular version (different resources
-
-
-
-Fielding & Reschke Standards Track [Page 28]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- that at one point shared the same state as the current version
- resource). A successful PUT request on "the current version" URI
- might therefore create a new version resource in addition to changing
- the state of the target resource, and might also cause links to be
- added between the related resources.
-
- An origin server that allows PUT on a given target resource MUST send
- a 400 (Bad Request) response to a PUT request that contains a
- Content-Range header field (Section 4.2 of [RFC7233]), since the
- payload is likely to be partial content that has been mistakenly PUT
- as a full representation. Partial content updates are possible by
- targeting a separately identified resource with state that overlaps a
- portion of the larger resource, or by using a different method that
- has been specifically defined for partial updates (for example, the
- PATCH method defined in [RFC5789]).
-
- Responses to the PUT method are not cacheable. If a successful PUT
- request passes through a cache that has one or more stored responses
- for the effective request URI, those stored responses will be
- invalidated (see Section 4.4 of [RFC7234]).
-
-4.3.5. DELETE
-
- The DELETE method requests that the origin server remove the
- association between the target resource and its current
- functionality. In effect, this method is similar to the rm command
- in UNIX: it expresses a deletion operation on the URI mapping of the
- origin server rather than an expectation that the previously
- associated information be deleted.
-
- If the target resource has one or more current representations, they
- might or might not be destroyed by the origin server, and the
- associated storage might or might not be reclaimed, depending
- entirely on the nature of the resource and its implementation by the
- origin server (which are beyond the scope of this specification).
- Likewise, other implementation aspects of a resource might need to be
- deactivated or archived as a result of a DELETE, such as database or
- gateway connections. In general, it is assumed that the origin
- server will only allow DELETE on resources for which it has a
- prescribed mechanism for accomplishing the deletion.
-
- Relatively few resources allow the DELETE method -- its primary use
- is for remote authoring environments, where the user has some
- direction regarding its effect. For example, a resource that was
- previously created using a PUT request, or identified via the
- Location header field after a 201 (Created) response to a POST
- request, might allow a corresponding DELETE request to undo those
- actions. Similarly, custom user agent implementations that implement
-
-
-
-Fielding & Reschke Standards Track [Page 29]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- an authoring function, such as revision control clients using HTTP
- for remote operations, might use DELETE based on an assumption that
- the server's URI space has been crafted to correspond to a version
- repository.
-
- If a DELETE method is successfully applied, the origin server SHOULD
- send a 202 (Accepted) status code if the action will likely succeed
- but has not yet been enacted, a 204 (No Content) status code if the
- action has been enacted and no further information is to be supplied,
- or a 200 (OK) status code if the action has been enacted and the
- response message includes a representation describing the status.
-
- A payload within a DELETE request message has no defined semantics;
- sending a payload body on a DELETE request might cause some existing
- implementations to reject the request.
-
- Responses to the DELETE method are not cacheable. If a DELETE
- request passes through a cache that has one or more stored responses
- for the effective request URI, those stored responses will be
- invalidated (see Section 4.4 of [RFC7234]).
-
-4.3.6. CONNECT
-
- The CONNECT method requests that the recipient establish a tunnel to
- the destination origin server identified by the request-target and,
- if successful, thereafter restrict its behavior to blind forwarding
- of packets, in both directions, until the tunnel is closed. Tunnels
- are commonly used to create an end-to-end virtual connection, through
- one or more proxies, which can then be secured using TLS (Transport
- Layer Security, [RFC5246]).
-
- CONNECT is intended only for use in requests to a proxy. An origin
- server that receives a CONNECT request for itself MAY respond with a
- 2xx (Successful) status code to indicate that a connection is
- established. However, most origin servers do not implement CONNECT.
-
- A client sending a CONNECT request MUST send the authority form of
- request-target (Section 5.3 of [RFC7230]); i.e., the request-target
- consists of only the host name and port number of the tunnel
- destination, separated by a colon. For example,
-
- CONNECT server.example.com:80 HTTP/1.1
- Host: server.example.com:80
-
- The recipient proxy can establish a tunnel either by directly
- connecting to the request-target or, if configured to use another
- proxy, by forwarding the CONNECT request to the next inbound proxy.
- Any 2xx (Successful) response indicates that the sender (and all
-
-
-
-Fielding & Reschke Standards Track [Page 30]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- inbound proxies) will switch to tunnel mode immediately after the
- blank line that concludes the successful response's header section;
- data received after that blank line is from the server identified by
- the request-target. Any response other than a successful response
- indicates that the tunnel has not yet been formed and that the
- connection remains governed by HTTP.
-
- A tunnel is closed when a tunnel intermediary detects that either
- side has closed its connection: the intermediary MUST attempt to send
- any outstanding data that came from the closed side to the other
- side, close both connections, and then discard any remaining data
- left undelivered.
-
- Proxy authentication might be used to establish the authority to
- create a tunnel. For example,
-
- CONNECT server.example.com:80 HTTP/1.1
- Host: server.example.com:80
- Proxy-Authorization: basic aGVsbG86d29ybGQ=
-
- There are significant risks in establishing a tunnel to arbitrary
- servers, particularly when the destination is a well-known or
- reserved TCP port that is not intended for Web traffic. For example,
- a CONNECT to a request-target of "example.com:25" would suggest that
- the proxy connect to the reserved port for SMTP traffic; if allowed,
- that could trick the proxy into relaying spam email. Proxies that
- support CONNECT SHOULD restrict its use to a limited set of known
- ports or a configurable whitelist of safe request targets.
-
- A server MUST NOT send any Transfer-Encoding or Content-Length header
- fields in a 2xx (Successful) response to CONNECT. A client MUST
- ignore any Content-Length or Transfer-Encoding header fields received
- in a successful response to CONNECT.
-
- A payload within a CONNECT request message has no defined semantics;
- sending a payload body on a CONNECT request might cause some existing
- implementations to reject the request.
-
- Responses to the CONNECT method are not cacheable.
-
-4.3.7. OPTIONS
-
- The OPTIONS method requests information about the communication
- options available for the target resource, at either the origin
- server or an intervening intermediary. This method allows a client
- to determine the options and/or requirements associated with a
- resource, or the capabilities of a server, without implying a
- resource action.
-
-
-
-Fielding & Reschke Standards Track [Page 31]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- An OPTIONS request with an asterisk ("*") as the request-target
- (Section 5.3 of [RFC7230]) applies 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 conformance (or lack thereof).
-
- If the request-target is not an asterisk, the OPTIONS request applies
- to the options that are available when communicating with the target
- resource.
-
- A server generating a successful response to OPTIONS SHOULD send any
- header fields that might indicate optional features implemented by
- the server and applicable to the target resource (e.g., Allow),
- including potential extensions not defined by this specification.
- The response payload, if any, might also describe the communication
- options in a machine or human-readable representation. A standard
- format for such a representation is not defined by this
- specification, but might be defined by future extensions to HTTP. A
- server MUST generate a Content-Length field with a value of "0" if no
- payload body is to be sent in the response.
-
- A client MAY send a Max-Forwards header field in an OPTIONS request
- to target a specific recipient in the request chain (see
- Section 5.1.2). A proxy MUST NOT generate a Max-Forwards header
- field while forwarding a request unless that request was received
- with a Max-Forwards field.
-
- A client that generates an OPTIONS request containing a payload body
- MUST send a valid Content-Type header field describing the
- representation media type. Although this specification does not
- define any use for such a payload, future extensions to HTTP might
- use the OPTIONS body to make more detailed queries about the target
- resource.
-
- Responses to the OPTIONS method are not cacheable.
-
-4.3.8. TRACE
-
- The TRACE method requests a remote, application-level loop-back of
- the request message. The final recipient of the request SHOULD
- reflect the message received, excluding some fields described below,
- back to the client as the message body of a 200 (OK) response with a
- Content-Type of "message/http" (Section 8.3.1 of [RFC7230]). The
- final recipient is either the origin server or the first server to
- receive a Max-Forwards value of zero (0) in the request
- (Section 5.1.2).
-
-
-
-Fielding & Reschke Standards Track [Page 32]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- A client MUST NOT generate header fields in a TRACE request
- containing sensitive data that might be disclosed by the response.
- For example, it would be foolish for a user agent to send stored user
- credentials [RFC7235] or cookies [RFC6265] in a TRACE request. The
- final recipient of the request SHOULD exclude any request header
- fields that are likely to contain sensitive data when that recipient
- generates the response body.
-
- 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 5.7.1 of
- [RFC7230]) 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.
-
- A client MUST NOT send a message body in a TRACE request.
-
- Responses to the TRACE method are not cacheable.
-
-5. Request Header Fields
-
- A client sends request header fields to provide more information
- about the request context, make the request conditional based on the
- target resource state, suggest preferred formats for the response,
- supply authentication credentials, or modify the expected request
- processing. These fields act as request modifiers, similar to the
- parameters on a programming language method invocation.
-
-5.1. Controls
-
- Controls are request header fields that direct specific handling of
- the request.
-
- +-------------------+--------------------------+
- | Header Field Name | Defined in... |
- +-------------------+--------------------------+
- | Cache-Control | Section 5.2 of [RFC7234] |
- | Expect | Section 5.1.1 |
- | Host | Section 5.4 of [RFC7230] |
- | Max-Forwards | Section 5.1.2 |
- | Pragma | Section 5.4 of [RFC7234] |
- | Range | Section 3.1 of [RFC7233] |
- | TE | Section 4.3 of [RFC7230] |
- +-------------------+--------------------------+
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 33]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-5.1.1. Expect
-
- The "Expect" header field in a request indicates a certain set of
- behaviors (expectations) that need to be supported by the server in
- order to properly handle this request. The only such expectation
- defined by this specification is 100-continue.
-
- Expect = "100-continue"
-
- The Expect field-value is case-insensitive.
-
- A server that receives an Expect field-value other than 100-continue
- MAY respond with a 417 (Expectation Failed) status code to indicate
- that the unexpected expectation cannot be met.
-
- A 100-continue expectation informs recipients that the client is
- about to send a (presumably large) message body in this request and
- wishes to receive a 100 (Continue) interim response if the
- request-line and header fields are not sufficient to cause an
- immediate success, redirect, or error response. This allows the
- client to wait for an indication that it is worthwhile to send the
- message body before actually doing so, which can improve efficiency
- when the message body is huge or when the client anticipates that an
- error is likely (e.g., when sending a state-changing method, for the
- first time, without previously verified authentication credentials).
-
- For example, a request that begins with
-
- PUT /somewhere/fun HTTP/1.1
- Host: origin.example.com
- Content-Type: video/h264
- Content-Length: 1234567890987
- Expect: 100-continue
-
-
- allows the origin server to immediately respond with an error
- message, such as 401 (Unauthorized) or 405 (Method Not Allowed),
- before the client starts filling the pipes with an unnecessary data
- transfer.
-
- Requirements for clients:
-
- o A client MUST NOT generate a 100-continue expectation in a request
- that does not include a message body.
-
- o A client that will wait for a 100 (Continue) response before
- sending the request message body MUST send an Expect header field
- containing a 100-continue expectation.
-
-
-
-Fielding & Reschke Standards Track [Page 34]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- o A client that sends a 100-continue expectation is not required to
- wait for any specific length of time; such a client MAY proceed to
- send the message body even if it has not yet received a response.
- Furthermore, since 100 (Continue) responses cannot be sent through
- an HTTP/1.0 intermediary, such a client SHOULD NOT wait for an
- indefinite period before sending the message body.
-
- o A client that receives a 417 (Expectation Failed) status code in
- response to a request containing a 100-continue expectation SHOULD
- repeat that request without a 100-continue expectation, since the
- 417 response merely indicates that the response chain does not
- support expectations (e.g., it passes through an HTTP/1.0 server).
-
- Requirements for servers:
-
- o A server that receives a 100-continue expectation in an HTTP/1.0
- request MUST ignore that expectation.
-
- o A server MAY omit sending a 100 (Continue) response if it has
- already received some or all of the message body for the
- corresponding request, or if the framing indicates that there is
- no message body.
-
- o A server that sends a 100 (Continue) response MUST ultimately send
- a final status code, once the message body is received and
- processed, unless the connection is closed prematurely.
-
- o A server that responds with a final status code before reading the
- entire message body SHOULD indicate in that response whether it
- intends to close the connection or continue reading and discarding
- the request message (see Section 6.6 of [RFC7230]).
-
- An origin server MUST, upon receiving an HTTP/1.1 (or later)
- request-line and a complete header section that contains a
- 100-continue expectation and indicates a request message body will
- follow, either send an immediate response with a final status code,
- if that status can be determined by examining just the request-line
- and header fields, or send an immediate 100 (Continue) response to
- encourage the client to send the request's message body. The origin
- server MUST NOT wait for the message body before sending the 100
- (Continue) response.
-
- A proxy MUST, upon receiving an HTTP/1.1 (or later) request-line and
- a complete header section that contains a 100-continue expectation
- and indicates a request message body will follow, either send an
- immediate response with a final status code, if that status can be
- determined by examining just the request-line and header fields, or
- begin forwarding the request toward the origin server by sending a
-
-
-
-Fielding & Reschke Standards Track [Page 35]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- corresponding request-line and header section to the next inbound
- server. If the proxy believes (from configuration or past
- interaction) that the next inbound server only supports HTTP/1.0, the
- proxy MAY generate an immediate 100 (Continue) response to encourage
- the client to begin sending the message body.
-
- Note: The Expect header field was added after the original
- publication of HTTP/1.1 [RFC2068] as both the means to request an
- interim 100 (Continue) response and the general mechanism for
- indicating must-understand extensions. However, the extension
- mechanism has not been used by clients and the must-understand
- requirements have not been implemented by many servers, rendering
- the extension mechanism useless. This specification has removed
- the extension mechanism in order to simplify the definition and
- processing of 100-continue.
-
-5.1.2. Max-Forwards
-
- The "Max-Forwards" header field provides a mechanism with the TRACE
- (Section 4.3.8) and OPTIONS (Section 4.3.7) request methods to limit
- the number of times that the request is forwarded by proxies. This
- can be useful when the client is attempting to trace a request that
- appears to be failing or looping mid-chain.
-
- Max-Forwards = 1*DIGIT
-
- The Max-Forwards value is a decimal integer indicating the remaining
- number of times this request message can be forwarded.
-
- Each intermediary that receives 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
- intermediary MUST NOT forward the request; instead, the intermediary
- MUST respond as the final recipient. If the received Max-Forwards
- value is greater than zero, the intermediary MUST generate an updated
- Max-Forwards field in the forwarded message with a field-value that
- is the lesser of a) the received value decremented by one (1) or b)
- the recipient's maximum supported value for Max-Forwards.
-
- A recipient MAY ignore a Max-Forwards header field received with any
- other request methods.
-
-5.2. Conditionals
-
- The HTTP conditional request header fields [RFC7232] allow a client
- to place a precondition on the state of the target resource, so that
- the action corresponding to the method semantics will not be applied
- if the precondition evaluates to false. Each precondition defined by
-
-
-
-Fielding & Reschke Standards Track [Page 36]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- this specification consists of a comparison between a set of
- validators obtained from prior representations of the target resource
- to the current state of validators for the selected representation
- (Section 7.2). Hence, these preconditions evaluate whether the state
- of the target resource has changed since a given state known by the
- client. The effect of such an evaluation depends on the method
- semantics and choice of conditional, as defined in Section 5 of
- [RFC7232].
-
- +---------------------+--------------------------+
- | Header Field Name | Defined in... |
- +---------------------+--------------------------+
- | If-Match | Section 3.1 of [RFC7232] |
- | If-None-Match | Section 3.2 of [RFC7232] |
- | If-Modified-Since | Section 3.3 of [RFC7232] |
- | If-Unmodified-Since | Section 3.4 of [RFC7232] |
- | If-Range | Section 3.2 of [RFC7233] |
- +---------------------+--------------------------+
-
-5.3. Content Negotiation
-
- The following request header fields are sent by a user agent to
- engage in proactive negotiation of the response content, as defined
- in Section 3.4.1. The preferences sent in these fields apply to any
- content in the response, including representations of the target
- resource, representations of error or processing status, and
- potentially even the miscellaneous text strings that might appear
- within the protocol.
-
- +-------------------+---------------+
- | Header Field Name | Defined in... |
- +-------------------+---------------+
- | Accept | Section 5.3.2 |
- | Accept-Charset | Section 5.3.3 |
- | Accept-Encoding | Section 5.3.4 |
- | Accept-Language | Section 5.3.5 |
- +-------------------+---------------+
-
-5.3.1. Quality Values
-
- Many of the request header fields for proactive negotiation use a
- common parameter, named "q" (case-insensitive), to assign a relative
- "weight" to the preference for that associated kind of content. This
- weight is referred to as a "quality value" (or "qvalue") because the
- same parameter name is often used within server configurations to
- assign a weight to the relative quality of the various
- representations that can be selected for a resource.
-
-
-
-
-Fielding & Reschke Standards Track [Page 37]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- The weight is normalized to a real number in the range 0 through 1,
- where 0.001 is the least preferred and 1 is the most preferred; a
- value of 0 means "not acceptable". If no "q" parameter is present,
- the default weight is 1.
-
- weight = OWS ";" OWS "q=" qvalue
- qvalue = ( "0" [ "." 0*3DIGIT ] )
- / ( "1" [ "." 0*3("0") ] )
-
- A sender of qvalue MUST NOT generate more than three digits after the
- decimal point. User configuration of these values ought to be
- limited in the same fashion.
-
-5.3.2. Accept
-
- The "Accept" header field can be used by user agents to specify
- response media types that are acceptable. Accept header fields 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 = #( media-range [ accept-params ] )
-
- media-range = ( "*/*"
- / ( type "/" "*" )
- / ( type "/" subtype )
- ) *( OWS ";" OWS parameter )
- accept-params = weight *( accept-ext )
- accept-ext = OWS ";" OWS 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 can include media type
- parameters that are applicable to that range.
-
- Each media-range might be followed by zero or more applicable media
- type parameters (e.g., charset), an optional "q" parameter for
- indicating a relative weight (Section 5.3.1), and then zero or more
- extension parameters. The "q" parameter is necessary if any
- extensions (accept-ext) are present, since it acts as a separator
- between the two parameter sets.
-
- 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
-
-
-
-
-Fielding & Reschke Standards Track [Page 38]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- 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".
-
- The example
-
- Accept: audio/*; q=0.2, audio/basic
-
- is interpreted as "I prefer audio/basic, but send me any audio type
- if it is the best available after an 80% markdown in quality".
-
- A request without any Accept header field implies that the user agent
- will accept any media type in response. If the header field is
- present in a request and none of the available representations for
- the response have a media type that is listed as acceptable, the
- origin server can either honor the header field by sending a 406 (Not
- Acceptable) response or disregard the header field by treating the
- response as if it is not subject to content negotiation.
-
- 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 equally preferred media types, but if they do not exist, then
- send the text/x-dvi representation, and if that does not exist, send
- the text/plain representation".
-
- 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/plain, text/plain;format=flowed, */*
-
- have the following precedence:
-
- 1. text/plain;format=flowed
-
- 2. text/plain
-
- 3. text/*
-
- 4. */*
-
- The media type quality factor associated with a given type is
- determined by finding the media range with the highest precedence
- that matches the type. For example,
-
-
-
-Fielding & Reschke Standards Track [Page 39]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- 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:
-
- +-------------------+---------------+
- | Media Type | Quality Value |
- +-------------------+---------------+
- | text/html;level=1 | 1 |
- | text/html | 0.7 |
- | text/plain | 0.3 |
- | 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 that cannot interact with other rendering agents, this
- default set ought to be configurable by the user.
-
-5.3.3. Accept-Charset
-
- The "Accept-Charset" header field can be sent by a user agent to
- indicate what charsets are acceptable in textual response content.
- This field allows user agents capable of understanding more
- comprehensive or special-purpose charsets to signal that capability
- to an origin server that is capable of representing information in
- those charsets.
-
- Accept-Charset = 1#( ( charset / "*" ) [ weight ] )
-
- Charset names are defined in Section 3.1.1.2. A user agent MAY
- associate a quality value with each charset to indicate the user's
- relative preference for that charset, as defined in Section 5.3.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 charset that is not mentioned elsewhere in the
- Accept-Charset field. If no "*" is present in an Accept-Charset
- field, then any charsets not explicitly mentioned in the field are
- considered "not acceptable" to the client.
-
- A request without any Accept-Charset header field implies that the
- user agent will accept any charset in response. Most general-purpose
- user agents do not send Accept-Charset, unless specifically
-
-
-
-Fielding & Reschke Standards Track [Page 40]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- configured to do so, because a detailed list of supported charsets
- makes it easier for a server to identify an individual by virtue of
- the user agent's request characteristics (Section 9.7).
-
- If an Accept-Charset header field is present in a request and none of
- the available representations for the response has a charset that is
- listed as acceptable, the origin server can either honor the header
- field, by sending a 406 (Not Acceptable) response, or disregard the
- header field by treating the resource as if it is not subject to
- content negotiation.
-
-5.3.4. Accept-Encoding
-
- The "Accept-Encoding" header field can be used by user agents to
- indicate what response content-codings (Section 3.1.2.1) are
- acceptable in the response. An "identity" token is used as a synonym
- for "no encoding" in order to communicate when no encoding is
- preferred.
-
- Accept-Encoding = #( codings [ weight ] )
- codings = content-coding / "identity" / "*"
-
- Each codings value MAY be given an associated quality value
- representing the preference for that encoding, as defined in
- Section 5.3.1. The asterisk "*" symbol in an Accept-Encoding field
- matches any available content-coding not explicitly listed in the
- header field.
-
- For example,
-
- 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 request without an Accept-Encoding header field implies that the
- user agent has no preferences regarding content-codings. Although
- this allows the server to use any content-coding in a response, it
- does not imply that the user agent will be able to correctly process
- all encodings.
-
- A server tests whether a content-coding for a given representation is
- acceptable using these rules:
-
- 1. If no Accept-Encoding field is in the request, any content-coding
- is considered acceptable by the user agent.
-
-
-
-
-Fielding & Reschke Standards Track [Page 41]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- 2. If the representation has no content-coding, then it is
- acceptable by default unless specifically excluded by the
- Accept-Encoding field stating either "identity;q=0" or "*;q=0"
- without a more specific entry for "identity".
-
- 3. If the representation's 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 5.3.1, a qvalue of 0 means "not acceptable".)
-
- 4. If multiple content-codings are acceptable, then the acceptable
- content-coding with the highest non-zero qvalue is preferred.
-
- An Accept-Encoding header field with a combined field-value that is
- empty implies that the user agent does not want any content-coding in
- response. If an Accept-Encoding header field is present in a request
- and none of the available representations for the response have a
- content-coding that is listed as acceptable, the origin server SHOULD
- send a response without any content-coding.
-
- Note: Most HTTP/1.0 applications do not recognize or obey qvalues
- associated with content-codings. This means that qvalues might
- not work and are not permitted with x-gzip or x-compress.
-
-5.3.5. Accept-Language
-
- The "Accept-Language" header field can be used by user agents to
- indicate the set of natural languages that are preferred in the
- response. Language tags are defined in Section 3.1.3.1.
-
- Accept-Language = 1#( language-range [ weight ] )
- language-range =
- <language-range, see [RFC4647], Section 2.1>
-
- Each language-range can be given an associated quality value
- representing an estimate of the user's preference for the languages
- specified by that range, as defined in Section 5.3.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 request without any Accept-Language header field implies that the
- user agent will accept any language in response. If the header field
- is present in a request and none of the available representations for
- the response have a matching language tag, the origin server can
- either disregard the header field by treating the response as if it
-
-
-
-Fielding & Reschke Standards Track [Page 42]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- is not subject to content negotiation or honor the header field by
- sending a 406 (Not Acceptable) response. However, the latter is not
- encouraged, as doing so can prevent users from accessing content that
- they might be able to use (with translation software, for example).
-
- Note that some recipients treat the order in which language tags are
- listed as an indication of descending priority, particularly for tags
- that are assigned equal quality values (no value is the same as q=1).
- However, this behavior cannot be relied upon. For consistency and to
- maximize interoperability, many user agents assign each language tag
- a unique quality value while also listing them in order of decreasing
- quality. Additional discussion of language priority lists can be
- found in Section 2.3 of [RFC4647].
-
- For matching, Section 3 of [RFC4647] defines several matching
- schemes. Implementations can offer the most appropriate matching
- scheme for their requirements. The "Basic Filtering" scheme
- ([RFC4647], Section 3.3.1) is identical to the matching scheme that
- was previously defined for HTTP in Section 14.4 of [RFC2616].
-
- It might be contrary to the privacy expectations of the user to send
- an Accept-Language header field with the complete linguistic
- preferences of the user in every request (Section 9.7).
-
- Since intelligibility is highly dependent on the individual user,
- user agents need to allow user control over the linguistic preference
- (either through configuration of the user agent itself or by
- defaulting to a user controllable system setting). A user agent that
- does not provide such control to the user MUST NOT send an
- Accept-Language header field.
-
- Note: User agents ought to provide guidance to users when setting
- a preference, since users are rarely familiar with the details of
- language matching as described above. For 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 the list for
- better matching behavior.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 43]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-5.4. Authentication Credentials
-
- Two header fields are used for carrying authentication credentials,
- as defined in [RFC7235]. Note that various custom mechanisms for
- user authentication use the Cookie header field for this purpose, as
- defined in [RFC6265].
-
- +---------------------+--------------------------+
- | Header Field Name | Defined in... |
- +---------------------+--------------------------+
- | Authorization | Section 4.2 of [RFC7235] |
- | Proxy-Authorization | Section 4.4 of [RFC7235] |
- +---------------------+--------------------------+
-
-5.5. Request Context
-
- The following request header fields provide additional information
- about the request context, including information about the user, user
- agent, and resource behind the request.
-
- +-------------------+---------------+
- | Header Field Name | Defined in... |
- +-------------------+---------------+
- | From | Section 5.5.1 |
- | Referer | Section 5.5.2 |
- | User-Agent | Section 5.5.3 |
- +-------------------+---------------+
-
-5.5.1. From
-
- The "From" header field contains an Internet email address for a
- human user who controls the requesting user agent. The address ought
- to be machine-usable, as defined by "mailbox" in Section 3.4 of
- [RFC5322]:
-
- From = mailbox
-
- mailbox = <mailbox, see [RFC5322], Section 3.4>
-
- An example is:
-
- From: webmaster@example.org
-
- The From header field is rarely sent by non-robotic user agents. A
- user agent SHOULD NOT send a From header field without explicit
- configuration by the user, since that might conflict with the user's
- privacy interests or their site's security policy.
-
-
-
-
-Fielding & Reschke Standards Track [Page 44]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- A robotic user agent SHOULD send a valid From header field so that
- the person responsible for running the robot can be contacted if
- problems occur on servers, such as if the robot is sending excessive,
- unwanted, or invalid requests.
-
- A server SHOULD NOT use the From header field for access control or
- authentication, since most recipients will assume that the field
- value is public information.
-
-5.5.2. Referer
-
- The "Referer" [sic] header field allows the user agent to specify a
- URI reference for the resource from which the target URI was obtained
- (i.e., the "referrer", though the field name is misspelled). A user
- agent MUST NOT include the fragment and userinfo components of the
- URI reference [RFC3986], if any, when generating the Referer field
- value.
-
- Referer = absolute-URI / partial-URI
-
- The Referer header field allows servers to generate back-links to
- other resources for simple analytics, logging, optimized caching,
- etc. It also allows obsolete or mistyped links to be found for
- maintenance. Some servers use the Referer header field as a means of
- denying links from other sites (so-called "deep linking") or
- restricting cross-site request forgery (CSRF), but not all requests
- contain it.
-
- Example:
-
- Referer: http://www.example.org/hypertext/Overview.html
-
- If the target URI was obtained from a source that does not have its
- own URI (e.g., input from the user keyboard, or an entry within the
- user's bookmarks/favorites), the user agent MUST either exclude the
- Referer field or send it with a value of "about:blank".
-
- The Referer field has the potential to reveal information about the
- request context or browsing history of the user, which is a privacy
- concern if the referring resource's identifier reveals personal
- information (such as an account name) or a resource that is supposed
- to be confidential (such as behind a firewall or internal to a
- secured service). Most general-purpose user agents do not send the
- Referer header field when the referring resource is a local "file" or
- "data" URI. A user agent MUST NOT send a Referer header field in an
- unsecured HTTP request if the referring page was received with a
- secure protocol. See Section 9.4 for additional security
- considerations.
-
-
-
-Fielding & Reschke Standards Track [Page 45]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- Some intermediaries have been known to indiscriminately remove
- Referer header fields from outgoing requests. This has the
- unfortunate side effect of interfering with protection against CSRF
- attacks, which can be far more harmful to their users.
- Intermediaries and user agent extensions that wish to limit
- information disclosure in Referer ought to restrict their changes to
- specific edits, such as replacing internal domain names with
- pseudonyms or truncating the query and/or path components. An
- intermediary SHOULD NOT modify or delete the Referer header field
- when the field value shares the same scheme and host as the request
- target.
-
-5.5.3. User-Agent
-
- The "User-Agent" header field contains information about the user
- agent originating the request, which is often used by servers to help
- identify the scope of reported interoperability problems, to work
- around or tailor responses to avoid particular user agent
- limitations, and for analytics regarding browser or operating system
- use. A user agent SHOULD send a User-Agent field in each request
- unless specifically configured not to do so.
-
- User-Agent = product *( RWS ( product / comment ) )
-
- The User-Agent field-value consists of one or more product
- identifiers, each followed by zero or more comments (Section 3.2 of
- [RFC7230]), which together identify the user agent software and its
- significant subproducts. By convention, the product identifiers are
- listed in decreasing order of their significance for identifying the
- user agent software. Each product identifier consists of a name and
- optional version.
-
- product = token ["/" product-version]
- product-version = token
-
- A sender SHOULD limit generated product identifiers to what is
- necessary to identify the product; a sender MUST NOT generate
- advertising or other nonessential information within the product
- identifier. A sender SHOULD NOT generate information in
- product-version that is not a version identifier (i.e., successive
- versions of the same product name ought to differ only in the
- product-version portion of the product identifier).
-
- Example:
-
- User-Agent: CERN-LineMode/2.15 libwww/2.17b3
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 46]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- A user agent SHOULD NOT generate a User-Agent field containing
- needlessly fine-grained detail and SHOULD limit the addition of
- subproducts by third parties. Overly long and detailed User-Agent
- field values increase request latency and the risk of a user being
- identified against their wishes ("fingerprinting").
-
- Likewise, implementations are encouraged not to use the product
- tokens of other implementations in order to declare compatibility
- with them, as this circumvents the purpose of the field. If a user
- agent masquerades as a different user agent, recipients can assume
- that the user intentionally desires to see responses tailored for
- that identified user agent, even if they might not work as well for
- the actual user agent being used.
-
-6. Response Status Codes
-
- The status-code element is a three-digit integer code giving the
- result of the attempt to understand and satisfy the request.
-
- HTTP status codes are extensible. HTTP clients are not required to
- understand the meaning of all registered status codes, though such
- understanding is obviously desirable. However, a client MUST
- understand the class of any status code, as indicated by the first
- digit, and treat an unrecognized status code as being equivalent to
- the x00 status code of that class, with the exception that a
- recipient MUST NOT cache a response with an unrecognized status code.
-
- For example, if an unrecognized status code of 471 is received by a
- client, the client can assume that there was something wrong with its
- request and treat the response as if it had received a 400 (Bad
- Request) status code. The response message will usually contain a
- representation that explains the status.
-
- The first digit of the status-code defines the class of response.
- The last two digits do not have any categorization role. There are
- five values for the first digit:
-
- o 1xx (Informational): The request was received, continuing process
-
- o 2xx (Successful): The request was successfully received,
- understood, and accepted
-
- o 3xx (Redirection): Further action needs to be taken in order to
- complete the request
-
- o 4xx (Client Error): The request contains bad syntax or cannot be
- fulfilled
-
-
-
-
-Fielding & Reschke Standards Track [Page 47]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- o 5xx (Server Error): The server failed to fulfill an apparently
- valid request
-
-6.1. Overview of Status Codes
-
- The status codes listed below are defined in this specification,
- Section 4 of [RFC7232], Section 4 of [RFC7233], and Section 3 of
- [RFC7235]. The reason phrases listed here are only recommendations
- -- they can be replaced by local equivalents without affecting the
- protocol.
-
- Responses with status codes that are defined as cacheable by default
- (e.g., 200, 203, 204, 206, 300, 301, 404, 405, 410, 414, and 501 in
- this specification) can be reused by a cache with heuristic
- expiration unless otherwise indicated by the method definition or
- explicit cache controls [RFC7234]; all other status codes are not
- cacheable by default.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 48]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- +------+-------------------------------+--------------------------+
- | Code | Reason-Phrase | Defined in... |
- +------+-------------------------------+--------------------------+
- | 100 | Continue | Section 6.2.1 |
- | 101 | Switching Protocols | Section 6.2.2 |
- | 200 | OK | Section 6.3.1 |
- | 201 | Created | Section 6.3.2 |
- | 202 | Accepted | Section 6.3.3 |
- | 203 | Non-Authoritative Information | Section 6.3.4 |
- | 204 | No Content | Section 6.3.5 |
- | 205 | Reset Content | Section 6.3.6 |
- | 206 | Partial Content | Section 4.1 of [RFC7233] |
- | 300 | Multiple Choices | Section 6.4.1 |
- | 301 | Moved Permanently | Section 6.4.2 |
- | 302 | Found | Section 6.4.3 |
- | 303 | See Other | Section 6.4.4 |
- | 304 | Not Modified | Section 4.1 of [RFC7232] |
- | 305 | Use Proxy | Section 6.4.5 |
- | 307 | Temporary Redirect | Section 6.4.7 |
- | 400 | Bad Request | Section 6.5.1 |
- | 401 | Unauthorized | Section 3.1 of [RFC7235] |
- | 402 | Payment Required | Section 6.5.2 |
- | 403 | Forbidden | Section 6.5.3 |
- | 404 | Not Found | Section 6.5.4 |
- | 405 | Method Not Allowed | Section 6.5.5 |
- | 406 | Not Acceptable | Section 6.5.6 |
- | 407 | Proxy Authentication Required | Section 3.2 of [RFC7235] |
- | 408 | Request Timeout | Section 6.5.7 |
- | 409 | Conflict | Section 6.5.8 |
- | 410 | Gone | Section 6.5.9 |
- | 411 | Length Required | Section 6.5.10 |
- | 412 | Precondition Failed | Section 4.2 of [RFC7232] |
- | 413 | Payload Too Large | Section 6.5.11 |
- | 414 | URI Too Long | Section 6.5.12 |
- | 415 | Unsupported Media Type | Section 6.5.13 |
- | 416 | Range Not Satisfiable | Section 4.4 of [RFC7233] |
- | 417 | Expectation Failed | Section 6.5.14 |
- | 426 | Upgrade Required | Section 6.5.15 |
- | 500 | Internal Server Error | Section 6.6.1 |
- | 501 | Not Implemented | Section 6.6.2 |
- | 502 | Bad Gateway | Section 6.6.3 |
- | 503 | Service Unavailable | Section 6.6.4 |
- | 504 | Gateway Timeout | Section 6.6.5 |
- | 505 | HTTP Version Not Supported | Section 6.6.6 |
- +------+-------------------------------+--------------------------+
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 49]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- Note that this list is not exhaustive -- it does not include
- extension status codes defined in other specifications. The complete
- list of status codes is maintained by IANA. See Section 8.2 for
- details.
-
-6.2. Informational 1xx
-
- The 1xx (Informational) class of status code indicates an interim
- response for communicating connection status or request progress
- prior to completing the requested action and sending a final
- response. 1xx responses are terminated by the first empty line after
- the status-line (the empty line signaling the end of the header
- section). Since HTTP/1.0 did not define any 1xx status codes, a
- server MUST NOT send a 1xx response to an HTTP/1.0 client.
-
- A client MUST be able to parse one or more 1xx responses received
- prior to a final response, even if the client does not expect one. A
- user agent MAY ignore unexpected 1xx responses.
-
- A proxy MUST forward 1xx responses unless the proxy itself requested
- the generation of the 1xx response. For example, if a proxy adds an
- "Expect: 100-continue" field when it forwards a request, then it need
- not forward the corresponding 100 (Continue) response(s).
-
-6.2.1. 100 Continue
-
- The 100 (Continue) status code indicates that the initial part of a
- request has been received and has not yet been rejected by the
- server. The server intends to send a final response after the
- request has been fully received and acted upon.
-
- When the request contains an Expect header field that includes a
- 100-continue expectation, the 100 response indicates that the server
- wishes to receive the request payload body, as described in
- Section 5.1.1. The client ought to continue sending the request and
- discard the 100 response.
-
- If the request did not contain an Expect header field containing the
- 100-continue expectation, the client can simply discard this interim
- response.
-
-6.2.2. 101 Switching Protocols
-
- The 101 (Switching Protocols) status code indicates that the server
- understands and is willing to comply with the client's request, via
- the Upgrade header field (Section 6.7 of [RFC7230]), for a change in
- the application protocol being used on this connection. The server
-
-
-
-
-Fielding & Reschke Standards Track [Page 50]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- MUST generate an Upgrade header field in the response that indicates
- which protocol(s) will be switched to immediately after the empty
- line that terminates the 101 response.
-
- It is assumed that the server will only agree to switch protocols
- when it is advantageous to do so. For example, switching to a newer
- version of HTTP might be advantageous over older versions, and
- switching to a real-time, synchronous protocol might be advantageous
- when delivering resources that use such features.
-
-6.3. Successful 2xx
-
- The 2xx (Successful) class of status code indicates that the client's
- request was successfully received, understood, and accepted.
-
-6.3.1. 200 OK
-
- The 200 (OK) status code indicates that the request has succeeded.
- The payload sent in a 200 response depends on the request method.
- For the methods defined by this specification, the intended meaning
- of the payload can be summarized as:
-
- GET a representation of the target resource;
-
- HEAD the same representation as GET, but without the representation
- data;
-
- POST a representation of the status of, or results obtained from,
- the action;
-
- PUT, DELETE a representation of the status of the action;
-
- OPTIONS a representation of the communications options;
-
- TRACE a representation of the request message as received by the end
- server.
-
- Aside from responses to CONNECT, a 200 response always has a payload,
- though an origin server MAY generate a payload body of zero length.
- If no payload is desired, an origin server ought to send 204 (No
- Content) instead. For CONNECT, no payload is allowed because the
- successful result is a tunnel, which begins immediately after the 200
- response header section.
-
- A 200 response is cacheable by default; i.e., unless otherwise
- indicated by the method definition or explicit cache controls (see
- Section 4.2.2 of [RFC7234]).
-
-
-
-
-Fielding & Reschke Standards Track [Page 51]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-6.3.2. 201 Created
-
- The 201 (Created) status code indicates that the request has been
- fulfilled and has resulted in one or more new resources being
- created. The primary resource created by the request is identified
- by either a Location header field in the response or, if no Location
- field is received, by the effective request URI.
-
- The 201 response payload typically describes and links to the
- resource(s) created. See Section 7.2 for a discussion of the meaning
- and purpose of validator header fields, such as ETag and
- Last-Modified, in a 201 response.
-
-6.3.3. 202 Accepted
-
- The 202 (Accepted) status code indicates that 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 in HTTP for re-sending a status code from an asynchronous
- operation.
-
- The 202 response is intentionally noncommittal. 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 representation sent with this
- response ought to describe the request's current status and point to
- (or embed) a status monitor that can provide the user with an
- estimate of when the request will be fulfilled.
-
-6.3.4. 203 Non-Authoritative Information
-
- The 203 (Non-Authoritative Information) status code indicates that
- the request was successful but the enclosed payload has been modified
- from that of the origin server's 200 (OK) response by a transforming
- proxy (Section 5.7.2 of [RFC7230]). This status code allows the
- proxy to notify recipients when a transformation has been applied,
- since that knowledge might impact later decisions regarding the
- content. For example, future cache validation requests for the
- content might only be applicable along the same request path (through
- the same proxies).
-
- The 203 response is similar to the Warning code of 214 Transformation
- Applied (Section 5.5 of [RFC7234]), which has the advantage of being
- applicable to responses with any status code.
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 52]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- A 203 response is cacheable by default; i.e., unless otherwise
- indicated by the method definition or explicit cache controls (see
- Section 4.2.2 of [RFC7234]).
-
-6.3.5. 204 No Content
-
- The 204 (No Content) status code indicates that the server has
- successfully fulfilled the request and that there is no additional
- content to send in the response payload body. Metadata in the
- response header fields refer to the target resource and its selected
- representation after the requested action was applied.
-
- For example, if a 204 status code is received in response to a PUT
- request and the response contains an ETag header field, then the PUT
- was successful and the ETag field-value contains the entity-tag for
- the new representation of that target resource.
-
- The 204 response allows a server to indicate that the action has been
- successfully applied to the target resource, while implying that the
- user agent does not need to traverse away from its current "document
- view" (if any). The server assumes that the user agent will provide
- some indication of the success to its user, in accord with its own
- interface, and apply any new or updated metadata in the response to
- its active representation.
-
- For example, a 204 status code is commonly used with document editing
- interfaces corresponding to a "save" action, such that the document
- being saved remains available to the user for editing. It is also
- frequently used with interfaces that expect automated data transfers
- to be prevalent, such as within distributed version control systems.
-
- A 204 response is terminated by the first empty line after the header
- fields because it cannot contain a message body.
-
- A 204 response is cacheable by default; i.e., unless otherwise
- indicated by the method definition or explicit cache controls (see
- Section 4.2.2 of [RFC7234]).
-
-6.3.6. 205 Reset Content
-
- The 205 (Reset Content) status code indicates that the server has
- fulfilled the request and desires that the user agent reset the
- "document view", which caused the request to be sent, to its original
- state as received from the origin server.
-
- This response is intended to support a common data entry use case
- where the user receives content that supports data entry (a form,
- notepad, canvas, etc.), enters or manipulates data in that space,
-
-
-
-Fielding & Reschke Standards Track [Page 53]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- causes the entered data to be submitted in a request, and then the
- data entry mechanism is reset for the next entry so that the user can
- easily initiate another input action.
-
- Since the 205 status code implies that no additional content will be
- provided, a server MUST NOT generate a payload in a 205 response. In
- other words, a server MUST do one of the following for a 205
- response: a) indicate a zero-length body for the response by
- including a Content-Length header field with a value of 0; b)
- indicate a zero-length payload for the response by including a
- Transfer-Encoding header field with a value of chunked and a message
- body consisting of a single chunk of zero-length; or, c) close the
- connection immediately after sending the blank line terminating the
- header section.
-
-6.4. Redirection 3xx
-
- The 3xx (Redirection) class of status code indicates that further
- action needs to be taken by the user agent in order to fulfill the
- request. If a Location header field (Section 7.1.2) is provided, the
- user agent MAY automatically redirect its request to the URI
- referenced by the Location field value, even if the specific status
- code is not understood. Automatic redirection needs to done with
- care for methods not known to be safe, as defined in Section 4.2.1,
- since the user might not wish to redirect an unsafe request.
-
- There are several types of redirects:
-
- 1. Redirects that indicate the resource might be available at a
- different URI, as provided by the Location field, as in the
- status codes 301 (Moved Permanently), 302 (Found), and 307
- (Temporary Redirect).
-
- 2. Redirection that offers a choice of matching resources, each
- capable of representing the original request target, as in the
- 300 (Multiple Choices) status code.
-
- 3. Redirection to a different resource, identified by the Location
- field, that can represent an indirect response to the request, as
- in the 303 (See Other) status code.
-
- 4. Redirection to a previously cached result, as in the 304 (Not
- Modified) status code.
-
- Note: In HTTP/1.0, the status codes 301 (Moved Permanently) and
- 302 (Found) were defined for the first type of redirect
- ([RFC1945], Section 9.3). Early user agents split on whether the
- method applied to the redirect target would be the same as the
-
-
-
-Fielding & Reschke Standards Track [Page 54]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- original request or would be rewritten as GET. Although HTTP
- originally defined the former semantics for 301 and 302 (to match
- its original implementation at CERN), and defined 303 (See Other)
- to match the latter semantics, prevailing practice gradually
- converged on the latter semantics for 301 and 302 as well. The
- first revision of HTTP/1.1 added 307 (Temporary Redirect) to
- indicate the former semantics without being impacted by divergent
- practice. Over 10 years later, most user agents still do method
- rewriting for 301 and 302; therefore, this specification makes
- that behavior conformant when the original request is POST.
-
- A client SHOULD detect and intervene in cyclical redirections (i.e.,
- "infinite" redirection loops).
-
- Note: An earlier version of this specification recommended a
- maximum of five redirections ([RFC2068], Section 10.3). Content
- developers need to be aware that some clients might implement such
- a fixed limitation.
-
-6.4.1. 300 Multiple Choices
-
- The 300 (Multiple Choices) status code indicates that the target
- resource has more than one representation, each with its own more
- specific identifier, and information about the alternatives is being
- provided so that the user (or user agent) can select a preferred
- representation by redirecting its request to one or more of those
- identifiers. In other words, the server desires that the user agent
- engage in reactive negotiation to select the most appropriate
- representation(s) for its needs (Section 3.4).
-
- If the server has a preferred choice, the server SHOULD generate a
- Location header field containing a preferred choice's URI reference.
- The user agent MAY use the Location field value for automatic
- redirection.
-
- For request methods other than HEAD, the server SHOULD generate a
- payload in the 300 response containing a list of representation
- metadata and URI reference(s) from which the user or user agent can
- choose the one most preferred. The user agent MAY make a selection
- from that list automatically if it understands the provided media
- type. A specific format for automatic selection is not defined by
- this specification because HTTP tries to remain orthogonal to the
- definition of its payloads. In practice, the representation is
- provided in some easily parsed format believed to be acceptable to
- the user agent, as determined by shared design or content
- negotiation, or in some commonly accepted hypertext format.
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 55]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- A 300 response is cacheable by default; i.e., unless otherwise
- indicated by the method definition or explicit cache controls (see
- Section 4.2.2 of [RFC7234]).
-
- Note: The original proposal for the 300 status code defined the
- URI header field as providing a list of alternative
- representations, such that it would be usable for 200, 300, and
- 406 responses and be transferred in responses to the HEAD method.
- However, lack of deployment and disagreement over syntax led to
- both URI and Alternates (a subsequent proposal) being dropped from
- this specification. It is possible to communicate the list using
- a set of Link header fields [RFC5988], each with a relationship of
- "alternate", though deployment is a chicken-and-egg problem.
-
-6.4.2. 301 Moved Permanently
-
- The 301 (Moved Permanently) status code indicates that the target
- resource has been assigned a new permanent URI and any future
- references to this resource ought to use one of the enclosed URIs.
- Clients with link-editing capabilities ought to automatically re-link
- references to the effective request URI to one or more of the new
- references sent by the server, where possible.
-
- The server SHOULD generate a Location header field in the response
- containing a preferred URI reference for the new permanent URI. The
- user agent MAY use the Location field value for automatic
- redirection. The server's response payload usually contains a short
- hypertext note with a hyperlink to the new URI(s).
-
- Note: For historical reasons, a user agent MAY change the request
- method from POST to GET for the subsequent request. If this
- behavior is undesired, the 307 (Temporary Redirect) status code
- can be used instead.
-
- A 301 response is cacheable by default; i.e., unless otherwise
- indicated by the method definition or explicit cache controls (see
- Section 4.2.2 of [RFC7234]).
-
-6.4.3. 302 Found
-
- The 302 (Found) status code indicates that the target resource
- resides temporarily under a different URI. Since the redirection
- might be altered on occasion, the client ought to continue to use the
- effective request URI for future requests.
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 56]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- The server SHOULD generate a Location header field in the response
- containing a URI reference for the different URI. The user agent MAY
- use the Location field value for automatic redirection. The server's
- response payload usually contains a short hypertext note with a
- hyperlink to the different URI(s).
-
- Note: For historical reasons, a user agent MAY change the request
- method from POST to GET for the subsequent request. If this
- behavior is undesired, the 307 (Temporary Redirect) status code
- can be used instead.
-
-6.4.4. 303 See Other
-
- The 303 (See Other) status code indicates that the server is
- redirecting the user agent to a different resource, as indicated by a
- URI in the Location header field, which is intended to provide an
- indirect response to the original request. A user agent can perform
- a retrieval request targeting that URI (a GET or HEAD request if
- using HTTP), which might also be redirected, and present the eventual
- result as an answer to the original request. Note that the new URI
- in the Location header field is not considered equivalent to the
- effective request URI.
-
- This status code is applicable to any HTTP method. It is primarily
- used to allow the output of a POST action to redirect the user agent
- to a selected resource, since doing so provides the information
- corresponding to the POST response in a form that can be separately
- identified, bookmarked, and cached, independent of the original
- request.
-
- A 303 response to a GET request indicates that the origin server does
- not have a representation of the target resource that can be
- transferred by the server over HTTP. However, the Location field
- value refers to a resource that is descriptive of the target
- resource, such that making a retrieval request on that other resource
- might result in a representation that is useful to recipients without
- implying that it represents the original target resource. Note that
- answers to the questions of what can be represented, what
- representations are adequate, and what might be a useful description
- are outside the scope of HTTP.
-
- Except for responses to a HEAD request, the representation of a 303
- response ought to contain a short hypertext note with a hyperlink to
- the same URI reference provided in the Location header field.
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 57]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-6.4.5. 305 Use Proxy
-
- The 305 (Use Proxy) status code was defined in a previous version of
- this specification and is now deprecated (Appendix B).
-
-6.4.6. 306 (Unused)
-
- The 306 status code was defined in a previous version of this
- specification, is no longer used, and the code is reserved.
-
-6.4.7. 307 Temporary Redirect
-
- The 307 (Temporary Redirect) status code indicates that the target
- resource resides temporarily under a different URI and the user agent
- MUST NOT change the request method if it performs an automatic
- redirection to that URI. Since the redirection can change over time,
- the client ought to continue using the original effective request URI
- for future requests.
-
- The server SHOULD generate a Location header field in the response
- containing a URI reference for the different URI. The user agent MAY
- use the Location field value for automatic redirection. The server's
- response payload usually contains a short hypertext note with a
- hyperlink to the different URI(s).
-
- Note: This status code is similar to 302 (Found), except that it
- does not allow changing the request method from POST to GET. This
- specification defines no equivalent counterpart for 301 (Moved
- Permanently) ([RFC7238], however, defines the status code 308
- (Permanent Redirect) for this purpose).
-
-6.5. Client Error 4xx
-
- The 4xx (Client Error) class of status code indicates that the client
- seems to have erred. Except when responding to a HEAD request, the
- server SHOULD send a representation 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 representation to the user.
-
-6.5.1. 400 Bad Request
-
- The 400 (Bad Request) status code indicates that the server cannot or
- will not process the request due to something that is perceived to be
- a client error (e.g., malformed request syntax, invalid request
- message framing, or deceptive request routing).
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 58]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-6.5.2. 402 Payment Required
-
- The 402 (Payment Required) status code is reserved for future use.
-
-6.5.3. 403 Forbidden
-
- The 403 (Forbidden) status code indicates that the server understood
- the request but refuses to authorize it. A server that wishes to
- make public why the request has been forbidden can describe that
- reason in the response payload (if any).
-
- If authentication credentials were provided in the request, the
- server considers them insufficient to grant access. The client
- SHOULD NOT automatically repeat the request with the same
- credentials. The client MAY repeat the request with new or different
- credentials. However, a request might be forbidden for reasons
- unrelated to the credentials.
-
- An origin server that wishes to "hide" the current existence of a
- forbidden target resource MAY instead respond with a status code of
- 404 (Not Found).
-
-6.5.4. 404 Not Found
-
- The 404 (Not Found) status code indicates that the origin server did
- not find a current representation for the target resource or is not
- willing to disclose that one exists. A 404 status code does not
- indicate whether this lack of representation is temporary or
- permanent; the 410 (Gone) status code is preferred over 404 if the
- origin server knows, presumably through some configurable means, that
- the condition is likely to be permanent.
-
- A 404 response is cacheable by default; i.e., unless otherwise
- indicated by the method definition or explicit cache controls (see
- Section 4.2.2 of [RFC7234]).
-
-6.5.5. 405 Method Not Allowed
-
- The 405 (Method Not Allowed) status code indicates that the method
- received in the request-line is known by the origin server but not
- supported by the target resource. The origin server MUST generate an
- Allow header field in a 405 response containing a list of the target
- resource's currently supported methods.
-
- A 405 response is cacheable by default; i.e., unless otherwise
- indicated by the method definition or explicit cache controls (see
- Section 4.2.2 of [RFC7234]).
-
-
-
-
-Fielding & Reschke Standards Track [Page 59]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-6.5.6. 406 Not Acceptable
-
- The 406 (Not Acceptable) status code indicates that the target
- resource does not have a current representation that would be
- acceptable to the user agent, according to the proactive negotiation
- header fields received in the request (Section 5.3), and the server
- is unwilling to supply a default representation.
-
- The server SHOULD generate a payload containing a list of available
- representation characteristics and corresponding resource identifiers
- from which the user or user agent can choose the one most
- appropriate. A user agent MAY automatically select the most
- appropriate choice from that list. However, this specification does
- not define any standard for such automatic selection, as described in
- Section 6.4.1.
-
-6.5.7. 408 Request Timeout
-
- The 408 (Request Timeout) status code indicates that the server did
- not receive a complete request message within the time that it was
- prepared to wait. A server SHOULD send the "close" connection option
- (Section 6.1 of [RFC7230]) in the response, since 408 implies that
- the server has decided to close the connection rather than continue
- waiting. If the client has an outstanding request in transit, the
- client MAY repeat that request on a new connection.
-
-6.5.8. 409 Conflict
-
- The 409 (Conflict) status code indicates that the request could not
- be completed due to a conflict with the current state of the target
- resource. This code is used in situations where the user might be
- able to resolve the conflict and resubmit the request. The server
- SHOULD generate a payload that includes enough information for a user
- to recognize the source of the conflict.
-
- Conflicts are most likely to occur in response to a PUT request. For
- example, if versioning were being used and the representation being
- PUT included changes to a resource that conflict with those made by
- an earlier (third-party) request, the origin server might use a 409
- response to indicate that it can't complete the request. In this
- case, the response representation would likely contain information
- useful for merging the differences based on the revision history.
-
-6.5.9. 410 Gone
-
- The 410 (Gone) status code indicates that access to the target
- resource is no longer available at the origin server and that this
- condition is likely to be permanent. If the origin server does not
-
-
-
-Fielding & Reschke Standards Track [Page 60]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- know, or has no facility to determine, whether or not the condition
- is permanent, the status code 404 (Not Found) ought to be used
- instead.
-
- 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 associated with the origin 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.
-
- A 410 response is cacheable by default; i.e., unless otherwise
- indicated by the method definition or explicit cache controls (see
- Section 4.2.2 of [RFC7234]).
-
-6.5.10. 411 Length Required
-
- The 411 (Length Required) status code indicates that the server
- refuses to accept the request without a defined Content-Length
- (Section 3.3.2 of [RFC7230]). 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.
-
-6.5.11. 413 Payload Too Large
-
- The 413 (Payload Too Large) status code indicates that the server is
- refusing to process a request because the request payload 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 generate a
- Retry-After header field to indicate that it is temporary and after
- what time the client MAY try again.
-
-6.5.12. 414 URI Too Long
-
- The 414 (URI Too Long) status code indicates that the server is
- refusing to service the request because the request-target (Section
- 5.3 of [RFC7230]) 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 "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 potential security holes.
-
-
-
-Fielding & Reschke Standards Track [Page 61]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- A 414 response is cacheable by default; i.e., unless otherwise
- indicated by the method definition or explicit cache controls (see
- Section 4.2.2 of [RFC7234]).
-
-6.5.13. 415 Unsupported Media Type
-
- The 415 (Unsupported Media Type) status code indicates that the
- origin server is refusing to service the request because the payload
- is in a format not supported by this method on the target resource.
- The format problem might be due to the request's indicated
- Content-Type or Content-Encoding, or as a result of inspecting the
- data directly.
-
-6.5.14. 417 Expectation Failed
-
- The 417 (Expectation Failed) status code indicates that the
- expectation given in the request's Expect header field
- (Section 5.1.1) could not be met by at least one of the inbound
- servers.
-
-6.5.15. 426 Upgrade Required
-
- The 426 (Upgrade Required) status code indicates that the server
- refuses to perform the request using the current protocol but might
- be willing to do so after the client upgrades to a different
- protocol. The server MUST send an Upgrade header field in a 426
- response to indicate the required protocol(s) (Section 6.7 of
- [RFC7230]).
-
- Example:
-
- HTTP/1.1 426 Upgrade Required
- Upgrade: HTTP/3.0
- Connection: Upgrade
- Content-Length: 53
- Content-Type: text/plain
-
- This service requires use of the HTTP/3.0 protocol.
-
-6.6. Server Error 5xx
-
- The 5xx (Server Error) class of status code indicates that the server
- is aware that it has erred or is incapable of performing the
- requested method. Except when responding to a HEAD request, the
- server SHOULD send a representation containing an explanation of the
- error situation, and whether it is a temporary or permanent
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 62]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- condition. A user agent SHOULD display any included representation
- to the user. These response codes are applicable to any request
- method.
-
-6.6.1. 500 Internal Server Error
-
- The 500 (Internal Server Error) status code indicates that the server
- encountered an unexpected condition that prevented it from fulfilling
- the request.
-
-6.6.2. 501 Not Implemented
-
- The 501 (Not Implemented) status code indicates that 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.
-
- A 501 response is cacheable by default; i.e., unless otherwise
- indicated by the method definition or explicit cache controls (see
- Section 4.2.2 of [RFC7234]).
-
-6.6.3. 502 Bad Gateway
-
- The 502 (Bad Gateway) status code indicates that the server, while
- acting as a gateway or proxy, received an invalid response from an
- inbound server it accessed while attempting to fulfill the request.
-
-6.6.4. 503 Service Unavailable
-
- The 503 (Service Unavailable) status code indicates that the server
- is currently unable to handle the request due to a temporary overload
- or scheduled maintenance, which will likely be alleviated after some
- delay. The server MAY send a Retry-After header field
- (Section 7.1.3) to suggest an appropriate amount of time for the
- client to wait before retrying the request.
-
- Note: The existence of the 503 status code does not imply that a
- server has to use it when becoming overloaded. Some servers might
- simply refuse the connection.
-
-6.6.5. 504 Gateway Timeout
-
- The 504 (Gateway Timeout) status code indicates that the server,
- while acting as a gateway or proxy, did not receive a timely response
- from an upstream server it needed to access in order to complete the
- request.
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 63]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-6.6.6. 505 HTTP Version Not Supported
-
- The 505 (HTTP Version Not Supported) status code indicates that the
- server does not support, or refuses to support, the major version of
- HTTP 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 2.6 of
- [RFC7230], other than with this error message. The server SHOULD
- generate a representation for the 505 response that describes why
- that version is not supported and what other protocols are supported
- by that server.
-
-7. Response Header Fields
-
- The response header fields allow the server to pass additional
- information about the response beyond what is placed in the
- status-line. These header fields give information about the server,
- about further access to the target resource, or about related
- resources.
-
- Although each response header field has a defined meaning, in
- general, the precise semantics might be further refined by the
- semantics of the request method and/or response status code.
-
-7.1. Control Data
-
- Response header fields can supply control data that supplements the
- status code, directs caching, or instructs the client where to go
- next.
-
- +-------------------+--------------------------+
- | Header Field Name | Defined in... |
- +-------------------+--------------------------+
- | Age | Section 5.1 of [RFC7234] |
- | Cache-Control | Section 5.2 of [RFC7234] |
- | Expires | Section 5.3 of [RFC7234] |
- | Date | Section 7.1.1.2 |
- | Location | Section 7.1.2 |
- | Retry-After | Section 7.1.3 |
- | Vary | Section 7.1.4 |
- | Warning | Section 5.5 of [RFC7234] |
- +-------------------+--------------------------+
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 64]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-7.1.1. Origination Date
-
-7.1.1.1. Date/Time Formats
-
- Prior to 1995, there were three different formats commonly used by
- servers to communicate timestamps. For compatibility with old
- implementations, all three are defined here. The preferred format is
- a fixed-length and single-zone subset of the date and time
- specification used by the Internet Message Format [RFC5322].
-
- HTTP-date = IMF-fixdate / obs-date
-
- An example of the preferred format is
-
- Sun, 06 Nov 1994 08:49:37 GMT ; IMF-fixdate
-
- Examples of the two obsolete formats are
-
- Sunday, 06-Nov-94 08:49:37 GMT ; obsolete RFC 850 format
- Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format
-
- A recipient that parses a timestamp value in an HTTP header field
- MUST accept all three HTTP-date formats. When a sender generates a
- header field that contains one or more timestamps defined as
- HTTP-date, the sender MUST generate those timestamps in the
- IMF-fixdate format.
-
- An HTTP-date value represents time as an instance of Coordinated
- Universal Time (UTC). The first two formats indicate UTC by the
- three-letter abbreviation for Greenwich Mean Time, "GMT", a
- predecessor of the UTC name; values in the asctime format are assumed
- to be in UTC. A sender that generates HTTP-date values from a local
- clock ought to use NTP ([RFC5905]) or some similar protocol to
- synchronize its clock to UTC.
-
- Preferred format:
-
- IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT
- ; fixed length/zone/capitalization subset of the format
- ; see Section 3.3 of [RFC5322]
-
- day-name = %x4D.6F.6E ; "Mon", case-sensitive
- / %x54.75.65 ; "Tue", case-sensitive
- / %x57.65.64 ; "Wed", case-sensitive
- / %x54.68.75 ; "Thu", case-sensitive
- / %x46.72.69 ; "Fri", case-sensitive
- / %x53.61.74 ; "Sat", case-sensitive
- / %x53.75.6E ; "Sun", case-sensitive
-
-
-
-Fielding & Reschke Standards Track [Page 65]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- date1 = day SP month SP year
- ; e.g., 02 Jun 1982
-
- day = 2DIGIT
- month = %x4A.61.6E ; "Jan", case-sensitive
- / %x46.65.62 ; "Feb", case-sensitive
- / %x4D.61.72 ; "Mar", case-sensitive
- / %x41.70.72 ; "Apr", case-sensitive
- / %x4D.61.79 ; "May", case-sensitive
- / %x4A.75.6E ; "Jun", case-sensitive
- / %x4A.75.6C ; "Jul", case-sensitive
- / %x41.75.67 ; "Aug", case-sensitive
- / %x53.65.70 ; "Sep", case-sensitive
- / %x4F.63.74 ; "Oct", case-sensitive
- / %x4E.6F.76 ; "Nov", case-sensitive
- / %x44.65.63 ; "Dec", case-sensitive
- year = 4DIGIT
-
- GMT = %x47.4D.54 ; "GMT", case-sensitive
-
- time-of-day = hour ":" minute ":" second
- ; 00:00:00 - 23:59:60 (leap second)
-
- hour = 2DIGIT
- minute = 2DIGIT
- second = 2DIGIT
-
- Obsolete formats:
-
- obs-date = rfc850-date / asctime-date
-
- rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT
- date2 = day "-" month "-" 2DIGIT
- ; e.g., 02-Jun-82
-
- day-name-l = %x4D.6F.6E.64.61.79 ; "Monday", case-sensitive
- / %x54.75.65.73.64.61.79 ; "Tuesday", case-sensitive
- / %x57.65.64.6E.65.73.64.61.79 ; "Wednesday", case-sensitive
- / %x54.68.75.72.73.64.61.79 ; "Thursday", case-sensitive
- / %x46.72.69.64.61.79 ; "Friday", case-sensitive
- / %x53.61.74.75.72.64.61.79 ; "Saturday", case-sensitive
- / %x53.75.6E.64.61.79 ; "Sunday", case-sensitive
-
-
- asctime-date = day-name SP date3 SP time-of-day SP year
- date3 = month SP ( 2DIGIT / ( SP 1DIGIT ))
- ; e.g., Jun 2
-
-
-
-
-Fielding & Reschke Standards Track [Page 66]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- HTTP-date is case sensitive. A sender MUST NOT generate additional
- whitespace in an HTTP-date beyond that specifically included as SP in
- the grammar. The semantics of day-name, day, month, year, and
- time-of-day are the same as those defined for the Internet Message
- Format constructs with the corresponding name ([RFC5322], Section
- 3.3).
-
- Recipients of a timestamp value in rfc850-date format, which uses a
- two-digit year, MUST interpret a timestamp that appears to be more
- than 50 years in the future as representing the most recent year in
- the past that had the same last two digits.
-
- Recipients of timestamp values are encouraged to be robust in parsing
- timestamps unless otherwise restricted by the field definition. For
- example, messages are occasionally forwarded over HTTP from a
- non-HTTP source that might generate any of the date and time
- specifications defined by the Internet Message Format.
-
- Note: HTTP requirements for the date/time stamp format apply only
- to their usage within the protocol stream. Implementations are
- not required to use these formats for user presentation, request
- logging, etc.
-
-7.1.1.2. Date
-
- The "Date" header field represents the date and time at which the
- message was originated, having the same semantics as the Origination
- Date Field (orig-date) defined in Section 3.6.1 of [RFC5322]. The
- field value is an HTTP-date, as defined in Section 7.1.1.1.
-
- Date = HTTP-date
-
- An example is
-
- Date: Tue, 15 Nov 1994 08:12:31 GMT
-
- When a Date header field is generated, the sender SHOULD generate its
- field value as the best available approximation of the date and time
- of message generation. In theory, the date ought to represent the
- moment just before the payload is generated. In practice, the date
- can be generated at any time during message origination.
-
- An origin server MUST NOT send a Date header field if it does not
- have a clock capable of providing a reasonable approximation of the
- current instance in Coordinated Universal Time. An origin server MAY
- send a Date header field if the response is in the 1xx
- (Informational) or 5xx (Server Error) class of status codes. An
- origin server MUST send a Date header field in all other cases.
-
-
-
-Fielding & Reschke Standards Track [Page 67]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- A recipient with a clock that receives a response message without a
- Date header field MUST record the time it was received and append a
- corresponding Date header field to the message's header section if it
- is cached or forwarded downstream.
-
- A user agent MAY send a Date header field in a request, though
- generally will not do so unless it is believed to convey useful
- information to the server. For example, custom applications of HTTP
- might convey a Date if the server is expected to adjust its
- interpretation of the user's request based on differences between the
- user agent and server clocks.
-
-7.1.2. Location
-
- The "Location" header field is used in some responses to refer to a
- specific resource in relation to the response. The type of
- relationship is defined by the combination of request method and
- status code semantics.
-
- Location = URI-reference
-
- The field value consists of a single URI-reference. When it has the
- form of a relative reference ([RFC3986], Section 4.2), the final
- value is computed by resolving it against the effective request URI
- ([RFC3986], Section 5).
-
- For 201 (Created) responses, the Location value refers to the primary
- resource created by the request. For 3xx (Redirection) responses,
- the Location value refers to the preferred target resource for
- automatically redirecting the request.
-
- If the Location value provided in a 3xx (Redirection) response does
- not have a fragment component, a user agent MUST process the
- redirection as if the value inherits the fragment component of the
- URI reference used to generate the request target (i.e., the
- redirection inherits the original reference's fragment, if any).
-
- For example, a GET request generated for the URI reference
- "http://www.example.org/~tim" might result in a 303 (See Other)
- response containing the header field:
-
- Location: /People.html#tim
-
- which suggests that the user agent redirect to
- "http://www.example.org/People.html#tim"
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 68]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- Likewise, a GET request generated for the URI reference
- "http://www.example.org/index.html#larry" might result in a 301
- (Moved Permanently) response containing the header field:
-
- Location: http://www.example.net/index.html
-
- which suggests that the user agent redirect to
- "http://www.example.net/index.html#larry", preserving the original
- fragment identifier.
-
- There are circumstances in which a fragment identifier in a Location
- value would not be appropriate. For example, the Location header
- field in a 201 (Created) response is supposed to provide a URI that
- is specific to the created resource.
-
- Note: Some recipients attempt to recover from Location fields that
- are not valid URI references. This specification does not mandate
- or define such processing, but does allow it for the sake of
- robustness.
-
- Note: The Content-Location header field (Section 3.1.4.2) differs
- from Location in that the Content-Location refers to the most
- specific resource corresponding to the enclosed representation.
- It is therefore possible for a response to contain both the
- Location and Content-Location header fields.
-
-7.1.3. Retry-After
-
- Servers send the "Retry-After" header field to indicate how long the
- user agent ought to wait before making a follow-up request. When
- sent with a 503 (Service Unavailable) response, Retry-After indicates
- how long the service is expected to be unavailable to the client.
- When sent with any 3xx (Redirection) response, Retry-After indicates
- the minimum time that the user agent is asked to wait before issuing
- the redirected request.
-
- The value of this field can be either an HTTP-date or a number of
- seconds to delay after the response is received.
-
- Retry-After = HTTP-date / delay-seconds
-
- A delay-seconds value is a non-negative decimal integer, representing
- time in seconds.
-
- delay-seconds = 1*DIGIT
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 69]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- 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.
-
-7.1.4. Vary
-
- The "Vary" header field in a response describes what parts of a
- request message, aside from the method, Host header field, and
- request target, might influence the origin server's process for
- selecting and representing this response. The value consists of
- either a single asterisk ("*") or a list of header field names
- (case-insensitive).
-
- Vary = "*" / 1#field-name
-
- A Vary field value of "*" signals that anything about the request
- might play a role in selecting the response representation, possibly
- including elements outside the message syntax (e.g., the client's
- network address). A recipient will not be able to determine whether
- this response is appropriate for a later request without forwarding
- the request to the origin server. A proxy MUST NOT generate a Vary
- field with a "*" value.
-
- A Vary field value consisting of a comma-separated list of names
- indicates that the named request header fields, known as the
- selecting header fields, might have a role in selecting the
- representation. The potential selecting header fields are not
- limited to those defined by this specification.
-
- For example, a response that contains
-
- Vary: accept-encoding, accept-language
-
- indicates that the origin server might have used the request's
- Accept-Encoding and Accept-Language fields (or lack thereof) as
- determining factors while choosing the content for this response.
-
- An origin server might send Vary with a list of fields for two
- purposes:
-
- 1. To inform cache recipients that they MUST NOT use this response
- to satisfy a later request unless the later request has the same
- values for the listed fields as the original request (Section 4.1
- of [RFC7234]). In other words, Vary expands the cache key
- required to match a new request to the stored cache entry.
-
-
-
-Fielding & Reschke Standards Track [Page 70]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- 2. To inform user agent recipients that this response is subject to
- content negotiation (Section 5.3) and that a different
- representation might be sent in a subsequent request if
- additional parameters are provided in the listed header fields
- (proactive negotiation).
-
- An origin server SHOULD send a Vary header field when its algorithm
- for selecting a representation varies based on aspects of the request
- message other than the method and request target, unless the variance
- cannot be crossed or the origin server has been deliberately
- configured to prevent cache transparency. For example, there is no
- need to send the Authorization field name in Vary because reuse
- across users is constrained by the field definition (Section 4.2 of
- [RFC7235]). Likewise, an origin server might use Cache-Control
- directives (Section 5.2 of [RFC7234]) to supplant Vary if it
- considers the variance less significant than the performance cost of
- Vary's impact on caching.
-
-7.2. Validator Header Fields
-
- Validator header fields convey metadata about the selected
- representation (Section 3). In responses to safe requests, validator
- fields describe the selected representation chosen by the origin
- server while handling the response. Note that, depending on the
- status code semantics, the selected representation for a given
- response is not necessarily the same as the representation enclosed
- as response payload.
-
- In a successful response to a state-changing request, validator
- fields describe the new representation that has replaced the prior
- selected representation as a result of processing the request.
-
- For example, an ETag header field in a 201 (Created) response
- communicates the entity-tag of the newly created resource's
- representation, so that it can be used in later conditional requests
- to prevent the "lost update" problem [RFC7232].
-
- +-------------------+--------------------------+
- | Header Field Name | Defined in... |
- +-------------------+--------------------------+
- | ETag | Section 2.3 of [RFC7232] |
- | Last-Modified | Section 2.2 of [RFC7232] |
- +-------------------+--------------------------+
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 71]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-7.3. Authentication Challenges
-
- Authentication challenges indicate what mechanisms are available for
- the client to provide authentication credentials in future requests.
-
- +--------------------+--------------------------+
- | Header Field Name | Defined in... |
- +--------------------+--------------------------+
- | WWW-Authenticate | Section 4.1 of [RFC7235] |
- | Proxy-Authenticate | Section 4.3 of [RFC7235] |
- +--------------------+--------------------------+
-
-7.4. Response Context
-
- The remaining response header fields provide more information about
- the target resource for potential use in later requests.
-
- +-------------------+--------------------------+
- | Header Field Name | Defined in... |
- +-------------------+--------------------------+
- | Accept-Ranges | Section 2.3 of [RFC7233] |
- | Allow | Section 7.4.1 |
- | Server | Section 7.4.2 |
- +-------------------+--------------------------+
-
-7.4.1. Allow
-
- The "Allow" header field lists the set of methods advertised as
- supported by the target resource. The purpose of this field is
- strictly to inform the recipient of valid request methods associated
- with the resource.
-
- Allow = #method
-
- Example of use:
-
- Allow: GET, HEAD, PUT
-
- The actual set of allowed methods is defined by the origin server at
- the time of each request. An origin server MUST generate an Allow
- field in a 405 (Method Not Allowed) response and MAY do so in any
- other response. An empty Allow field value indicates that the
- resource allows no methods, which might occur in a 405 response if
- the resource has been temporarily disabled by configuration.
-
- A proxy MUST NOT modify the Allow header field -- it does not need to
- understand all of the indicated methods in order to handle them
- according to the generic message handling rules.
-
-
-
-Fielding & Reschke Standards Track [Page 72]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-7.4.2. Server
-
- The "Server" header field contains information about the software
- used by the origin server to handle the request, which is often used
- by clients to help identify the scope of reported interoperability
- problems, to work around or tailor requests to avoid particular
- server limitations, and for analytics regarding server or operating
- system use. An origin server MAY generate a Server field in its
- responses.
-
- Server = product *( RWS ( product / comment ) )
-
- The Server field-value consists of one or more product identifiers,
- each followed by zero or more comments (Section 3.2 of [RFC7230]),
- which together identify the origin server software and its
- significant subproducts. By convention, the product identifiers are
- listed in decreasing order of their significance for identifying the
- origin server software. Each product identifier consists of a name
- and optional version, as defined in Section 5.5.3.
-
- Example:
-
- Server: CERN/3.0 libwww/2.17
-
- An origin server SHOULD NOT generate a Server field containing
- needlessly fine-grained detail and SHOULD limit the addition of
- subproducts by third parties. Overly long and detailed Server field
- values increase response latency and potentially reveal internal
- implementation details that might make it (slightly) easier for
- attackers to find and exploit known security holes.
-
-8. IANA Considerations
-
-8.1. Method Registry
-
- The "Hypertext Transfer Protocol (HTTP) Method Registry" defines the
- namespace for the request method token (Section 4). The method
- registry has been created and is now maintained at
- <http://www.iana.org/assignments/http-methods>.
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 73]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-8.1.1. Procedure
-
- HTTP method registrations MUST include the following fields:
-
- o Method Name (see Section 4)
-
- o Safe ("yes" or "no", see Section 4.2.1)
-
- o Idempotent ("yes" or "no", see Section 4.2.2)
-
- o Pointer to specification text
-
- Values to be added to this namespace require IETF Review (see
- [RFC5226], Section 4.1).
-
-8.1.2. Considerations for New Methods
-
- Standardized methods are generic; that is, they are potentially
- applicable to any resource, not just one particular media type, kind
- of resource, or application. As such, it is preferred that new
- methods be registered in a document that isn't specific to a single
- application or data format, since orthogonal technologies deserve
- orthogonal specification.
-
- Since message parsing (Section 3.3 of [RFC7230]) needs to be
- independent of method semantics (aside from responses to HEAD),
- definitions of new methods cannot change the parsing algorithm or
- prohibit the presence of a message body on either the request or the
- response message. Definitions of new methods can specify that only a
- zero-length message body is allowed by requiring a Content-Length
- header field with a value of "0".
-
- A new method definition needs to indicate whether it is safe
- (Section 4.2.1), idempotent (Section 4.2.2), cacheable
- (Section 4.2.3), what semantics are to be associated with the payload
- body if any is present in the request and what refinements the method
- makes to header field or status code semantics. If the new method is
- cacheable, its definition ought to describe how, and under what
- conditions, a cache can store a response and use it to satisfy a
- subsequent request. The new method ought to describe whether it can
- be made conditional (Section 5.2) and, if so, how a server responds
- when the condition is false. Likewise, if the new method might have
- some use for partial response semantics ([RFC7233]), it ought to
- document this, too.
-
- Note: Avoid defining a method name that starts with "M-", since
- that prefix might be misinterpreted as having the semantics
- assigned to it by [RFC2774].
-
-
-
-Fielding & Reschke Standards Track [Page 74]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-8.1.3. Registrations
-
- The "Hypertext Transfer Protocol (HTTP) Method Registry" has been
- populated with the registrations below:
-
- +---------+------+------------+---------------+
- | Method | Safe | Idempotent | Reference |
- +---------+------+------------+---------------+
- | CONNECT | no | no | Section 4.3.6 |
- | DELETE | no | yes | Section 4.3.5 |
- | GET | yes | yes | Section 4.3.1 |
- | HEAD | yes | yes | Section 4.3.2 |
- | OPTIONS | yes | yes | Section 4.3.7 |
- | POST | no | no | Section 4.3.3 |
- | PUT | no | yes | Section 4.3.4 |
- | TRACE | yes | yes | Section 4.3.8 |
- +---------+------+------------+---------------+
-
-8.2. Status Code Registry
-
- The "Hypertext Transfer Protocol (HTTP) Status Code Registry" defines
- the namespace for the response status-code token (Section 6). The
- status code registry is maintained at
- <http://www.iana.org/assignments/http-status-codes>.
-
- This section replaces the registration procedure for HTTP Status
- Codes previously defined in Section 7.1 of [RFC2817].
-
-8.2.1. Procedure
-
- A registration MUST include the following fields:
-
- o Status Code (3 digits)
-
- o Short Description
-
- o Pointer to specification text
-
- Values to be added to the HTTP status code namespace require IETF
- Review (see [RFC5226], Section 4.1).
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 75]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-8.2.2. Considerations for New Status Codes
-
- When it is necessary to express semantics for a response that are not
- defined by current status codes, a new status code can be registered.
- Status codes are generic; they are potentially applicable to any
- resource, not just one particular media type, kind of resource, or
- application of HTTP. As such, it is preferred that new status codes
- be registered in a document that isn't specific to a single
- application.
-
- New status codes are required to fall under one of the categories
- defined in Section 6. To allow existing parsers to process the
- response message, new status codes cannot disallow a payload,
- although they can mandate a zero-length payload body.
-
- Proposals for new status codes that are not yet widely deployed ought
- to avoid allocating a specific number for the code until there is
- clear consensus that it will be registered; instead, early drafts can
- use a notation such as "4NN", or "3N0" .. "3N9", to indicate the
- class of the proposed status code(s) without consuming a number
- prematurely.
-
- The definition of a new status code ought to explain the request
- conditions that would cause a response containing that status code
- (e.g., combinations of request header fields and/or method(s)) along
- with any dependencies on response header fields (e.g., what fields
- are required, what fields can modify the semantics, and what header
- field semantics are further refined when used with the new status
- code).
-
- The definition of a new status code ought to specify whether or not
- it is cacheable. Note that all status codes can be cached if the
- response they occur in has explicit freshness information; however,
- status codes that are defined as being cacheable are allowed to be
- cached without explicit freshness information. Likewise, the
- definition of a status code can place constraints upon cache
- behavior. See [RFC7234] for more information.
-
- Finally, the definition of a new status code ought to indicate
- whether the payload has any implied association with an identified
- resource (Section 3.1.4.1).
-
-8.2.3. Registrations
-
- The status code registry has been updated with the registrations
- below:
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 76]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- +-------+-------------------------------+----------------+
- | Value | Description | Reference |
- +-------+-------------------------------+----------------+
- | 100 | Continue | Section 6.2.1 |
- | 101 | Switching Protocols | Section 6.2.2 |
- | 200 | OK | Section 6.3.1 |
- | 201 | Created | Section 6.3.2 |
- | 202 | Accepted | Section 6.3.3 |
- | 203 | Non-Authoritative Information | Section 6.3.4 |
- | 204 | No Content | Section 6.3.5 |
- | 205 | Reset Content | Section 6.3.6 |
- | 300 | Multiple Choices | Section 6.4.1 |
- | 301 | Moved Permanently | Section 6.4.2 |
- | 302 | Found | Section 6.4.3 |
- | 303 | See Other | Section 6.4.4 |
- | 305 | Use Proxy | Section 6.4.5 |
- | 306 | (Unused) | Section 6.4.6 |
- | 307 | Temporary Redirect | Section 6.4.7 |
- | 400 | Bad Request | Section 6.5.1 |
- | 402 | Payment Required | Section 6.5.2 |
- | 403 | Forbidden | Section 6.5.3 |
- | 404 | Not Found | Section 6.5.4 |
- | 405 | Method Not Allowed | Section 6.5.5 |
- | 406 | Not Acceptable | Section 6.5.6 |
- | 408 | Request Timeout | Section 6.5.7 |
- | 409 | Conflict | Section 6.5.8 |
- | 410 | Gone | Section 6.5.9 |
- | 411 | Length Required | Section 6.5.10 |
- | 413 | Payload Too Large | Section 6.5.11 |
- | 414 | URI Too Long | Section 6.5.12 |
- | 415 | Unsupported Media Type | Section 6.5.13 |
- | 417 | Expectation Failed | Section 6.5.14 |
- | 426 | Upgrade Required | Section 6.5.15 |
- | 500 | Internal Server Error | Section 6.6.1 |
- | 501 | Not Implemented | Section 6.6.2 |
- | 502 | Bad Gateway | Section 6.6.3 |
- | 503 | Service Unavailable | Section 6.6.4 |
- | 504 | Gateway Timeout | Section 6.6.5 |
- | 505 | HTTP Version Not Supported | Section 6.6.6 |
- +-------+-------------------------------+----------------+
-
-8.3. Header Field Registry
-
- HTTP header fields are registered within the "Message Headers"
- registry located at
- <http://www.iana.org/assignments/message-headers>, as defined by
- [BCP90].
-
-
-
-
-Fielding & Reschke Standards Track [Page 77]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-8.3.1. Considerations for New Header Fields
-
- Header fields are key:value pairs that can be used to communicate
- data about the message, its payload, the target resource, or the
- connection (i.e., control data). See Section 3.2 of [RFC7230] for a
- general definition of header field syntax in HTTP messages.
-
- The requirements for header field names are defined in [BCP90].
-
- Authors of specifications defining new fields are advised to keep the
- name as short as practical and not to prefix the name with "X-"
- unless the header field will never be used on the Internet. (The
- "X-" prefix idiom has been extensively misused in practice; it was
- intended to only be used as a mechanism for avoiding name collisions
- inside proprietary software or intranet processing, since the prefix
- would ensure that private names never collide with a newly registered
- Internet name; see [BCP178] for further information).
-
- New header field values typically have their syntax defined using
- ABNF ([RFC5234]), using the extension defined in Section 7 of
- [RFC7230] as necessary, and are usually constrained to the range of
- US-ASCII characters. Header fields needing a greater range of
- characters can use an encoding such as the one defined in [RFC5987].
-
- Leading and trailing whitespace in raw field values is removed upon
- field parsing (Section 3.2.4 of [RFC7230]). Field definitions where
- leading or trailing whitespace in values is significant will have to
- use a container syntax such as quoted-string (Section 3.2.6 of
- [RFC7230]).
-
- Because commas (",") are used as a generic delimiter between
- field-values, they need to be treated with care if they are allowed
- in the field-value. Typically, components that might contain a comma
- are protected with double-quotes using the quoted-string ABNF
- production.
-
- For example, a textual date and a URI (either of which might contain
- a comma) could be safely carried in field-values like these:
-
- Example-URI-Field: "http://example.com/a.html,foo",
- "http://without-a-comma.example.com/"
- Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005"
-
- Note that double-quote delimiters almost always are used with the
- quoted-string production; using a different syntax inside
- double-quotes will likely cause unnecessary confusion.
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 78]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- Many header fields use a format including (case-insensitively) named
- parameters (for instance, Content-Type, defined in Section 3.1.1.5).
- Allowing both unquoted (token) and quoted (quoted-string) syntax for
- the parameter value enables recipients to use existing parser
- components. When allowing both forms, the meaning of a parameter
- value ought to be independent of the syntax used for it (for an
- example, see the notes on parameter handling for media types in
- Section 3.1.1.1).
-
- Authors of specifications defining new header fields are advised to
- consider documenting:
-
- o Whether the field is a single value or whether it can be a list
- (delimited by commas; see Section 3.2 of [RFC7230]).
-
- If it does not use the list syntax, document how to treat messages
- where the field occurs multiple times (a sensible default would be
- to ignore the field, but this might not always be the right
- choice).
-
- Note that intermediaries and software libraries might combine
- multiple header field instances into a single one, despite the
- field's definition not allowing the list syntax. A robust format
- enables recipients to discover these situations (good example:
- "Content-Type", as the comma can only appear inside quoted
- strings; bad example: "Location", as a comma can occur inside a
- URI).
-
- o Under what conditions the header field can be used; e.g., only in
- responses or requests, in all messages, only on responses to a
- particular request method, etc.
-
- o Whether the field should be stored by origin servers that
- understand it upon a PUT request.
-
- o Whether the field semantics are further refined by the context,
- such as by existing request methods or status codes.
-
- o Whether it is appropriate to list the field-name in the Connection
- header field (i.e., if the header field is to be hop-by-hop; see
- Section 6.1 of [RFC7230]).
-
- o Under what conditions intermediaries are allowed to insert,
- delete, or modify the field's value.
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 79]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- o Whether it is appropriate to list the field-name in a Vary
- response header field (e.g., when the request header field is used
- by an origin server's content selection algorithm; see
- Section 7.1.4).
-
- o Whether the header field is useful or allowable in trailers (see
- Section 4.1 of [RFC7230]).
-
- o Whether the header field ought to be preserved across redirects.
-
- o Whether it introduces any additional security considerations, such
- as disclosure of privacy-related data.
-
-8.3.2. Registrations
-
- The "Message Headers" registry has been updated with the following
- permanent registrations:
-
- +-------------------+----------+----------+-----------------+
- | Header Field Name | Protocol | Status | Reference |
- +-------------------+----------+----------+-----------------+
- | Accept | http | standard | Section 5.3.2 |
- | Accept-Charset | http | standard | Section 5.3.3 |
- | Accept-Encoding | http | standard | Section 5.3.4 |
- | Accept-Language | http | standard | Section 5.3.5 |
- | Allow | http | standard | Section 7.4.1 |
- | Content-Encoding | http | standard | Section 3.1.2.2 |
- | Content-Language | http | standard | Section 3.1.3.2 |
- | Content-Location | http | standard | Section 3.1.4.2 |
- | Content-Type | http | standard | Section 3.1.1.5 |
- | Date | http | standard | Section 7.1.1.2 |
- | Expect | http | standard | Section 5.1.1 |
- | From | http | standard | Section 5.5.1 |
- | Location | http | standard | Section 7.1.2 |
- | Max-Forwards | http | standard | Section 5.1.2 |
- | MIME-Version | http | standard | Appendix A.1 |
- | Referer | http | standard | Section 5.5.2 |
- | Retry-After | http | standard | Section 7.1.3 |
- | Server | http | standard | Section 7.4.2 |
- | User-Agent | http | standard | Section 5.5.3 |
- | Vary | http | standard | Section 7.1.4 |
- +-------------------+----------+----------+-----------------+
-
- The change controller for the above registrations is: "IETF
- (iesg@ietf.org) - Internet Engineering Task Force".
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 80]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-8.4. Content Coding Registry
-
- The "HTTP Content Coding Registry" defines the namespace for content
- coding names (Section 4.2 of [RFC7230]). The content coding registry
- is maintained at <http://www.iana.org/assignments/http-parameters>.
-
-8.4.1. Procedure
-
- Content coding registrations MUST include the following fields:
-
- o Name
-
- o Description
-
- o Pointer to specification text
-
- Names of content codings MUST NOT overlap with names of transfer
- codings (Section 4 of [RFC7230]), unless the encoding transformation
- is identical (as is the case for the compression codings defined in
- Section 4.2 of [RFC7230]).
-
- Values to be added to this namespace require IETF Review (see Section
- 4.1 of [RFC5226]) and MUST conform to the purpose of content coding
- defined in this section.
-
-8.4.2. Registrations
-
- The "HTTP Content Coding Registry" has been updated with the
- registrations below:
-
- +----------+----------------------------------------+---------------+
- | Name | Description | Reference |
- +----------+----------------------------------------+---------------+
- | identity | Reserved (synonym for "no encoding" in | Section 5.3.4 |
- | | Accept-Encoding) | |
- +----------+----------------------------------------+---------------+
-
-9. Security Considerations
-
- This section is meant to inform developers, information providers,
- and users of known security concerns relevant to HTTP semantics and
- its use for transferring information over the Internet.
- Considerations related to message syntax, parsing, and routing are
- discussed in Section 9 of [RFC7230].
-
- The list of considerations below is not exhaustive. Most security
- concerns related to HTTP semantics are about securing server-side
- applications (code behind the HTTP interface), securing user agent
-
-
-
-Fielding & Reschke Standards Track [Page 81]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- processing of payloads received via HTTP, or secure use of the
- Internet in general, rather than security of the protocol. Various
- organizations maintain topical information and links to current
- research on Web application security (e.g., [OWASP]).
-
-9.1. Attacks Based on File and Path Names
-
- Origin servers frequently make use of their local file system to
- manage the mapping from effective request URI to resource
- representations. Most file systems are not designed to protect
- against malicious file or path names. Therefore, an origin server
- needs to avoid accessing names that have a special significance to
- the system when mapping the request target to files, folders, or
- directories.
-
- For example, UNIX, Microsoft Windows, and other operating systems use
- ".." as a path component to indicate a directory level above the
- current one, and they use specially named paths or file names to send
- data to system devices. Similar naming conventions might exist
- within other types of storage systems. Likewise, local storage
- systems have an annoying tendency to prefer user-friendliness over
- security when handling invalid or unexpected characters,
- recomposition of decomposed characters, and case-normalization of
- case-insensitive names.
-
- Attacks based on such special names tend to focus on either denial-
- of-service (e.g., telling the server to read from a COM port) or
- disclosure of configuration and source files that are not meant to be
- served.
-
-9.2. Attacks Based on Command, Code, or Query Injection
-
- Origin servers often use parameters within the URI as a means of
- identifying system services, selecting database entries, or choosing
- a data source. However, data received in a request cannot be
- trusted. An attacker could construct any of the request data
- elements (method, request-target, header fields, or body) to contain
- data that might be misinterpreted as a command, code, or query when
- passed through a command invocation, language interpreter, or
- database interface.
-
- For example, SQL injection is a common attack wherein additional
- query language is inserted within some part of the request-target or
- header fields (e.g., Host, Referer, etc.). If the received data is
- used directly within a SELECT statement, the query language might be
- interpreted as a database command instead of a simple string value.
- This type of implementation vulnerability is extremely common, in
- spite of being easy to prevent.
-
-
-
-Fielding & Reschke Standards Track [Page 82]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- In general, resource implementations ought to avoid use of request
- data in contexts that are processed or interpreted as instructions.
- Parameters ought to be compared to fixed strings and acted upon as a
- result of that comparison, rather than passed through an interface
- that is not prepared for untrusted data. Received data that isn't
- based on fixed parameters ought to be carefully filtered or encoded
- to avoid being misinterpreted.
-
- Similar considerations apply to request data when it is stored and
- later processed, such as within log files, monitoring tools, or when
- included within a data format that allows embedded scripts.
-
-9.3. Disclosure of Personal Information
-
- Clients are often privy to large amounts of personal information,
- including both information provided by the user to interact with
- resources (e.g., the user's name, location, mail address, passwords,
- encryption keys, etc.) and information about the user's browsing
- activity over time (e.g., history, bookmarks, etc.). Implementations
- need to prevent unintentional disclosure of personal information.
-
-9.4. Disclosure of Sensitive Information in URIs
-
- URIs are intended to be shared, not secured, even when they identify
- secure resources. URIs are often shown on displays, added to
- templates when a page is printed, and stored in a variety of
- unprotected bookmark lists. It is therefore unwise to include
- information within a URI that is sensitive, personally identifiable,
- or a risk to disclose.
-
- Authors of services ought to avoid GET-based forms for the submission
- of sensitive data because that data will be placed in the
- request-target. Many existing servers, proxies, and user agents log
- or display the request-target in places where it might be visible to
- third parties. Such services ought to use POST-based form submission
- instead.
-
- Since the Referer header field tells a target site about the context
- that resulted in a request, it has the potential to reveal
- information about the user's immediate browsing history and any
- personal information that might be found in the referring resource's
- URI. Limitations on the Referer header field are described in
- Section 5.5.2 to address some of its security considerations.
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 83]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-9.5. Disclosure of Fragment after Redirects
-
- Although fragment identifiers used within URI references are not sent
- in requests, implementers ought to be aware that they will be visible
- to the user agent and any extensions or scripts running as a result
- of the response. In particular, when a redirect occurs and the
- original request's fragment identifier is inherited by the new
- reference in Location (Section 7.1.2), this might have the effect of
- disclosing one site's fragment to another site. If the first site
- uses personal information in fragments, it ought to ensure that
- redirects to other sites include a (possibly empty) fragment
- component in order to block that inheritance.
-
-9.6. Disclosure of Product Information
-
- The User-Agent (Section 5.5.3), Via (Section 5.7.1 of [RFC7230]), and
- Server (Section 7.4.2) header fields often reveal information about
- the respective sender's software systems. In theory, this can make
- it easier for an attacker to exploit known security holes; in
- practice, attackers tend to try all potential holes regardless of the
- apparent software versions being used.
-
- Proxies that serve as a portal through a network firewall ought to
- take special precautions regarding the transfer of header information
- that might identify hosts behind the firewall. The Via header field
- allows intermediaries to replace sensitive machine names with
- pseudonyms.
-
-9.7. Browser Fingerprinting
-
- Browser fingerprinting is a set of techniques for identifying a
- specific user agent over time through its unique set of
- characteristics. These characteristics might include information
- related to its TCP behavior, feature capabilities, and scripting
- environment, though of particular interest here is the set of unique
- characteristics that might be communicated via HTTP. Fingerprinting
- is considered a privacy concern because it enables tracking of a user
- agent's behavior over time without the corresponding controls that
- the user might have over other forms of data collection (e.g.,
- cookies). Many general-purpose user agents (i.e., Web browsers) have
- taken steps to reduce their fingerprints.
-
- There are a number of request header fields that might reveal
- information to servers that is sufficiently unique to enable
- fingerprinting. The From header field is the most obvious, though it
- is expected that From will only be sent when self-identification is
- desired by the user. Likewise, Cookie header fields are deliberately
-
-
-
-
-Fielding & Reschke Standards Track [Page 84]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- designed to enable re-identification, so fingerprinting concerns only
- apply to situations where cookies are disabled or restricted by the
- user agent's configuration.
-
- The User-Agent header field might contain enough information to
- uniquely identify a specific device, usually when combined with other
- characteristics, particularly if the user agent sends excessive
- details about the user's system or extensions. However, the source
- of unique information that is least expected by users is proactive
- negotiation (Section 5.3), including the Accept, Accept-Charset,
- Accept-Encoding, and Accept-Language header fields.
-
- In addition to the fingerprinting concern, detailed use of the
- Accept-Language header field can reveal information the user might
- consider to be of a private nature. For example, understanding a
- given language set might be strongly correlated to membership in a
- particular ethnic group. An approach that limits such loss of
- privacy would be for a user agent to omit the sending of
- Accept-Language except for sites that have been whitelisted, perhaps
- via interaction after detecting a Vary header field that indicates
- language negotiation might be useful.
-
- In environments where proxies are used to enhance privacy, user
- agents ought to be conservative in sending proactive negotiation
- header fields. General-purpose user agents that provide a high
- degree of header field configurability ought to inform users about
- the loss of privacy that might result if too much detail is provided.
- As an extreme privacy measure, proxies could filter the proactive
- negotiation header fields in relayed requests.
-
-10. Acknowledgments
-
- See Section 10 of [RFC7230].
-
-11. References
-
-11.1. Normative References
-
- [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.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
-
-
-Fielding & Reschke Standards Track [Page 85]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
- Resource Identifier (URI): Generic Syntax", STD 66,
- RFC 3986, January 2005.
-
- [RFC4647] Phillips, A., Ed. and M. Davis, Ed., "Matching of Language
- Tags", BCP 47, RFC 4647, September 2006.
-
- [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", STD 68, RFC 5234, January 2008.
-
- [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying
- Languages", BCP 47, RFC 5646, September 2009.
-
- [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in
- Internationalization in the IETF", BCP 166, RFC 6365,
- September 2011.
-
- [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Message Syntax and Routing",
- RFC 7230, June 2014.
-
- [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Conditional Requests", RFC 7232,
- June 2014.
-
- [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed.,
- "Hypertext Transfer Protocol (HTTP/1.1): Range Requests",
- RFC 7233, June 2014.
-
- [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
- Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
- RFC 7234, June 2014.
-
- [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Authentication", RFC 7235, June 2014.
-
-11.2. Informative References
-
- [BCP13] Freed, N., Klensin, J., and T. Hansen, "Media Type
- Specifications and Registration Procedures", BCP 13,
- RFC 6838, January 2013.
-
- [BCP178] Saint-Andre, P., Crocker, D., and M. Nottingham,
- "Deprecating the "X-" Prefix and Similar Constructs in
- Application Protocols", BCP 178, RFC 6648, June 2012.
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 86]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration
- Procedures for Message Header Fields", BCP 90, RFC 3864,
- September 2004.
-
- [OWASP] van der Stock, A., Ed., "A Guide to Building Secure Web
- Applications and Web Services", The Open Web Application
- Security Project (OWASP) 2.0.1, July 2005,
- <https://www.owasp.org/>.
-
- [REST] Fielding, R., "Architectural Styles and the Design of
- Network-based Software Architectures",
- Doctoral Dissertation, University of California, Irvine,
- September 2000,
- <http://roy.gbiv.com/pubs/dissertation/top.htm>.
-
- [RFC1945] Berners-Lee, T., Fielding, R., and H. Nielsen, "Hypertext
- Transfer Protocol -- HTTP/1.0", RFC 1945, May 1996.
-
- [RFC2049] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part Five: Conformance Criteria and
- Examples", RFC 2049, November 1996.
-
- [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T.
- Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1",
- RFC 2068, January 1997.
-
- [RFC2295] Holtman, K. and A. Mutz, "Transparent Content Negotiation
- in HTTP", RFC 2295, March 1998.
-
- [RFC2388] Masinter, L., "Returning Values from Forms: multipart/
- form-data", RFC 2388, August 1998.
-
- [RFC2557] Palme, F., Hopmann, A., Shelness, N., and E. Stefferud,
- "MIME Encapsulation of Aggregate Documents, such as HTML
- (MHTML)", RFC 2557, March 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.
-
- [RFC2774] Frystyk, H., Leach, P., and S. Lawrence, "An HTTP
- Extension Framework", RFC 2774, February 2000.
-
- [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within
- HTTP/1.1", RFC 2817, May 2000.
-
- [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration
- Procedures", BCP 19, RFC 2978, October 2000.
-
-
-
-Fielding & Reschke Standards Track [Page 87]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
- IANA Considerations Section in RFCs", BCP 26, RFC 5226,
- May 2008.
-
- [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
- (TLS) Protocol Version 1.2", RFC 5246, August 2008.
-
- [RFC5322] Resnick, P., "Internet Message Format", RFC 5322,
- October 2008.
-
- [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
- RFC 5789, March 2010.
-
- [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch,
- "Network Time Protocol Version 4: Protocol and Algorithms
- Specification", RFC 5905, June 2010.
-
- [RFC5987] Reschke, J., "Character Set and Language Encoding for
- Hypertext Transfer Protocol (HTTP) Header Field
- Parameters", RFC 5987, August 2010.
-
- [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
-
- [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
- April 2011.
-
- [RFC6266] Reschke, J., "Use of the Content-Disposition Header Field
- in the Hypertext Transfer Protocol (HTTP)", RFC 6266,
- June 2011.
-
- [RFC7238] Reschke, J., "The Hypertext Transfer Protocol (HTTP)
- Status Code 308 (Permanent Redirect)", RFC 7238,
- June 2014.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 88]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-Appendix A. Differences between HTTP and MIME
-
- HTTP/1.1 uses many of the constructs defined for the Internet Message
- Format [RFC5322] and the Multipurpose Internet Mail Extensions (MIME)
- [RFC2045] to allow a message body to be transmitted in an open
- variety of representations and with extensible header fields.
- However, RFC 2045 is focused only on email; applications of HTTP have
- many characteristics that differ from email; hence, HTTP has features
- that differ from MIME. 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 MIME.
- Proxies and gateways to and from strict MIME environments need to be
- aware of these differences and provide the appropriate conversions
- where necessary.
-
-A.1. MIME-Version
-
- HTTP is not a MIME-compliant protocol. However, messages can include
- a single MIME-Version 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
- conformance with the MIME protocol (as defined in [RFC2045]).
- Senders are responsible for ensuring full conformance (where
- possible) when exporting HTTP messages to strict MIME environments.
-
-A.2. Conversion to Canonical Form
-
- MIME requires that an Internet mail body part be converted to
- canonical form prior to being transferred, as described in Section 4
- of [RFC2049]. Section 3.1.1.3 of this document describes the forms
- allowed for subtypes of the "text" media type when transmitted over
- HTTP. [RFC2046] requires that content with a type of "text"
- represent line breaks as CRLF and forbids the use of CR or LF outside
- of line break sequences. HTTP allows CRLF, bare CR, and bare LF to
- indicate a line break within text content.
-
- A proxy or gateway from HTTP to a strict MIME environment ought to
- translate all line breaks within the text media types described in
- Section 3.1.1.3 of this document to the RFC 2049 canonical form of
- CRLF. Note, however, this might be complicated by the presence of a
- Content-Encoding and by the fact that HTTP allows the use of some
- charsets that do not use octets 13 and 10 to represent CR and LF,
- respectively.
-
-
-
-
-Fielding & Reschke Standards Track [Page 89]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- 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.
-
-A.3. Conversion of Date Formats
-
- HTTP/1.1 uses a restricted set of date formats (Section 7.1.1.1) to
- simplify the process of date comparison. Proxies and gateways from
- other protocols ought to 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.
-
-A.4. Conversion of Content-Encoding
-
- MIME 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 ought to either change the value of the Content-Type header
- field or decode the representation 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 the MIME standards).
-
-A.5. Conversion of Content-Transfer-Encoding
-
- HTTP does not use the Content-Transfer-Encoding field of MIME.
- Proxies and gateways from MIME-compliant protocols to HTTP need to
- remove any Content-Transfer-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
- transport" is defined by the limitations of the protocol being used.
- Such a proxy or gateway ought to transform and label the data with an
- appropriate Content-Transfer-Encoding if doing so will improve the
- likelihood of safe transport over the destination protocol.
-
-A.6. MHTML and Line Length Limitations
-
- HTTP implementations that share code with MHTML [RFC2557]
- 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 transfers message-bodies as
-
-
-
-Fielding & Reschke Standards Track [Page 90]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- payload and, aside from the "multipart/byteranges" type (Appendix A
- of [RFC7233]), does not interpret the content or any MIME header
- lines that might be contained therein.
-
-Appendix B. Changes from RFC 2616
-
- The primary changes in this revision have been editorial in nature:
- extracting the messaging syntax and partitioning HTTP semantics into
- separate documents for the core features, conditional requests,
- partial requests, caching, and authentication. The conformance
- language has been revised to clearly target requirements and the
- terminology has been improved to distinguish payload from
- representations and representations from resources.
-
- A new requirement has been added that semantics embedded in a URI be
- disabled when those semantics are inconsistent with the request
- method, since this is a common cause of interoperability failure.
- (Section 2)
-
- An algorithm has been added for determining if a payload is
- associated with a specific identifier. (Section 3.1.4.1)
-
- The default charset of ISO-8859-1 for text media types has been
- removed; the default is now whatever the media type definition says.
- Likewise, special treatment of ISO-8859-1 has been removed from the
- Accept-Charset header field. (Section 3.1.1.3 and Section 5.3.3)
-
- The definition of Content-Location has been changed to no longer
- affect the base URI for resolving relative URI references, due to
- poor implementation support and the undesirable effect of potentially
- breaking relative links in content-negotiated resources.
- (Section 3.1.4.2)
-
- To be consistent with the method-neutral parsing algorithm of
- [RFC7230], the definition of GET has been relaxed so that requests
- can have a body, even though a body has no meaning for GET.
- (Section 4.3.1)
-
- Servers are no longer required to handle all Content-* header fields
- and use of Content-Range has been explicitly banned in PUT requests.
- (Section 4.3.4)
-
- Definition of the CONNECT method has been moved from [RFC2817] to
- this specification. (Section 4.3.6)
-
- The OPTIONS and TRACE request methods have been defined as being
- safe. (Section 4.3.7 and Section 4.3.8)
-
-
-
-
-Fielding & Reschke Standards Track [Page 91]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- The Expect header field's extension mechanism has been removed due to
- widely-deployed broken implementations. (Section 5.1.1)
-
- The Max-Forwards header field has been restricted to the OPTIONS and
- TRACE methods; previously, extension methods could have used it as
- well. (Section 5.1.2)
-
- The "about:blank" URI has been suggested as a value for the Referer
- header field when no referring URI is applicable, which distinguishes
- that case from others where the Referer field is not sent or has been
- removed. (Section 5.5.2)
-
- The following status codes are now cacheable (that is, they can be
- stored and reused by a cache without explicit freshness information
- present): 204, 404, 405, 414, 501. (Section 6)
-
- The 201 (Created) status description has been changed to allow for
- the possibility that more than one resource has been created.
- (Section 6.3.2)
-
- The definition of 203 (Non-Authoritative Information) has been
- broadened to include cases of payload transformations as well.
- (Section 6.3.4)
-
- The set of request methods that are safe to automatically redirect is
- no longer closed; user agents are able to make that determination
- based upon the request method semantics. The redirect status codes
- 301, 302, and 307 no longer have normative requirements on response
- payloads and user interaction. (Section 6.4)
-
- The status codes 301 and 302 have been changed to allow user agents
- to rewrite the method from POST to GET. (Sections 6.4.2 and 6.4.3)
-
- The description of the 303 (See Other) status code has been changed
- to allow it to be cached if explicit freshness information is given,
- and a specific definition has been added for a 303 response to GET.
- (Section 6.4.4)
-
- The 305 (Use Proxy) status code has been deprecated due to security
- concerns regarding in-band configuration of a proxy. (Section 6.4.5)
-
- The 400 (Bad Request) status code has been relaxed so that it isn't
- limited to syntax errors. (Section 6.5.1)
-
- The 426 (Upgrade Required) status code has been incorporated from
- [RFC2817]. (Section 6.5.15)
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 92]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- The target of requirements on HTTP-date and the Date header field
- have been reduced to those systems generating the date, rather than
- all systems sending a date. (Section 7.1.1)
-
- The syntax of the Location header field has been changed to allow all
- URI references, including relative references and fragments, along
- with some clarifications as to when use of fragments would not be
- appropriate. (Section 7.1.2)
-
- Allow has been reclassified as a response header field, removing the
- option to specify it in a PUT request. Requirements relating to the
- content of Allow have been relaxed; correspondingly, clients are not
- required to always trust its value. (Section 7.4.1)
-
- A Method Registry has been defined. (Section 8.1)
-
- The Status Code Registry has been redefined by this specification;
- previously, it was defined in Section 7.1 of [RFC2817].
- (Section 8.2)
-
- Registration of content codings has been changed to require IETF
- Review. (Section 8.4)
-
- The Content-Disposition header field has been removed since it is now
- defined by [RFC6266].
-
- The Content-MD5 header field has been removed because it was
- inconsistently implemented with respect to partial responses.
-
-Appendix C. Imported ABNF
-
- The following core rules are included by reference, as defined in
- Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return),
- CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double
- quote), HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF
- (line feed), OCTET (any 8-bit sequence of data), SP (space), and
- VCHAR (any visible US-ASCII character).
-
- The rules below are defined in [RFC7230]:
-
- BWS = <BWS, see [RFC7230], Section 3.2.3>
- OWS = <OWS, see [RFC7230], Section 3.2.3>
- RWS = <RWS, see [RFC7230], Section 3.2.3>
- URI-reference = <URI-reference, see [RFC7230], Section 2.7>
- absolute-URI = <absolute-URI, see [RFC7230], Section 2.7>
- comment = <comment, see [RFC7230], Section 3.2.6>
- field-name = <comment, see [RFC7230], Section 3.2>
- partial-URI = <partial-URI, see [RFC7230], Section 2.7>
-
-
-
-Fielding & Reschke Standards Track [Page 93]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- quoted-string = <quoted-string, see [RFC7230], Section 3.2.6>
- token = <token, see [RFC7230], Section 3.2.6>
-
-Appendix D. Collected ABNF
-
- In the collected ABNF below, list rules are expanded as per Section
- 1.2 of [RFC7230].
-
- Accept = [ ( "," / ( media-range [ accept-params ] ) ) *( OWS "," [
- OWS ( media-range [ accept-params ] ) ] ) ]
- Accept-Charset = *( "," OWS ) ( ( charset / "*" ) [ weight ] ) *( OWS
- "," [ OWS ( ( charset / "*" ) [ weight ] ) ] )
- Accept-Encoding = [ ( "," / ( codings [ weight ] ) ) *( OWS "," [ OWS
- ( codings [ weight ] ) ] ) ]
- Accept-Language = *( "," OWS ) ( language-range [ weight ] ) *( OWS
- "," [ OWS ( language-range [ weight ] ) ] )
- Allow = [ ( "," / method ) *( OWS "," [ OWS method ] ) ]
-
- BWS = <BWS, see [RFC7230], Section 3.2.3>
-
- Content-Encoding = *( "," OWS ) content-coding *( OWS "," [ OWS
- content-coding ] )
- Content-Language = *( "," OWS ) language-tag *( OWS "," [ OWS
- language-tag ] )
- Content-Location = absolute-URI / partial-URI
- Content-Type = media-type
-
- Date = HTTP-date
-
- Expect = "100-continue"
-
- From = mailbox
-
- GMT = %x47.4D.54 ; GMT
-
- HTTP-date = IMF-fixdate / obs-date
-
- IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT
-
- Location = URI-reference
-
- Max-Forwards = 1*DIGIT
-
- OWS = <OWS, see [RFC7230], Section 3.2.3>
-
- RWS = <RWS, see [RFC7230], Section 3.2.3>
- Referer = absolute-URI / partial-URI
- Retry-After = HTTP-date / delay-seconds
-
-
-
-Fielding & Reschke Standards Track [Page 94]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- Server = product *( RWS ( product / comment ) )
-
- URI-reference = <URI-reference, see [RFC7230], Section 2.7>
- User-Agent = product *( RWS ( product / comment ) )
-
- Vary = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name ]
- ) )
-
- absolute-URI = <absolute-URI, see [RFC7230], Section 2.7>
- accept-ext = OWS ";" OWS token [ "=" ( token / quoted-string ) ]
- accept-params = weight *accept-ext
- asctime-date = day-name SP date3 SP time-of-day SP year
-
- charset = token
- codings = content-coding / "identity" / "*"
- comment = <comment, see [RFC7230], Section 3.2.6>
- content-coding = token
-
- date1 = day SP month SP year
- date2 = day "-" month "-" 2DIGIT
- date3 = month SP ( 2DIGIT / ( SP DIGIT ) )
- day = 2DIGIT
- day-name = %x4D.6F.6E ; Mon
- / %x54.75.65 ; Tue
- / %x57.65.64 ; Wed
- / %x54.68.75 ; Thu
- / %x46.72.69 ; Fri
- / %x53.61.74 ; Sat
- / %x53.75.6E ; Sun
- day-name-l = %x4D.6F.6E.64.61.79 ; Monday
- / %x54.75.65.73.64.61.79 ; Tuesday
- / %x57.65.64.6E.65.73.64.61.79 ; Wednesday
- / %x54.68.75.72.73.64.61.79 ; Thursday
- / %x46.72.69.64.61.79 ; Friday
- / %x53.61.74.75.72.64.61.79 ; Saturday
- / %x53.75.6E.64.61.79 ; Sunday
- delay-seconds = 1*DIGIT
-
- field-name = <comment, see [RFC7230], Section 3.2>
-
- hour = 2DIGIT
-
- language-range = <language-range, see [RFC4647], Section 2.1>
- language-tag = <Language-Tag, see [RFC5646], Section 2.1>
-
- mailbox = <mailbox, see [RFC5322], Section 3.4>
- media-range = ( "*/*" / ( type "/*" ) / ( type "/" subtype ) ) *( OWS
- ";" OWS parameter )
-
-
-
-Fielding & Reschke Standards Track [Page 95]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- media-type = type "/" subtype *( OWS ";" OWS parameter )
- method = token
- minute = 2DIGIT
- month = %x4A.61.6E ; Jan
- / %x46.65.62 ; Feb
- / %x4D.61.72 ; Mar
- / %x41.70.72 ; Apr
- / %x4D.61.79 ; May
- / %x4A.75.6E ; Jun
- / %x4A.75.6C ; Jul
- / %x41.75.67 ; Aug
- / %x53.65.70 ; Sep
- / %x4F.63.74 ; Oct
- / %x4E.6F.76 ; Nov
- / %x44.65.63 ; Dec
-
- obs-date = rfc850-date / asctime-date
-
- parameter = token "=" ( token / quoted-string )
- partial-URI = <partial-URI, see [RFC7230], Section 2.7>
- product = token [ "/" product-version ]
- product-version = token
- quoted-string = <quoted-string, see [RFC7230], Section 3.2.6>
- qvalue = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] )
-
- rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT
-
- second = 2DIGIT
- subtype = token
-
- time-of-day = hour ":" minute ":" second
- token = <token, see [RFC7230], Section 3.2.6>
- type = token
-
- weight = OWS ";" OWS "q=" qvalue
-
- year = 4DIGIT
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 96]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
-Index
-
- 1
- 1xx Informational (status code class) 50
-
- 2
- 2xx Successful (status code class) 51
-
- 3
- 3xx Redirection (status code class) 54
-
- 4
- 4xx Client Error (status code class) 58
-
- 5
- 5xx Server Error (status code class) 62
-
- 1
- 100 Continue (status code) 50
- 100-continue (expect value) 34
- 101 Switching Protocols (status code) 50
-
- 2
- 200 OK (status code) 51
- 201 Created (status code) 52
- 202 Accepted (status code) 52
- 203 Non-Authoritative Information (status code) 52
- 204 No Content (status code) 53
- 205 Reset Content (status code) 53
-
- 3
- 300 Multiple Choices (status code) 55
- 301 Moved Permanently (status code) 56
- 302 Found (status code) 56
- 303 See Other (status code) 57
- 305 Use Proxy (status code) 58
- 306 (Unused) (status code) 58
- 307 Temporary Redirect (status code) 58
-
- 4
- 400 Bad Request (status code) 58
- 402 Payment Required (status code) 59
- 403 Forbidden (status code) 59
- 404 Not Found (status code) 59
- 405 Method Not Allowed (status code) 59
- 406 Not Acceptable (status code) 59
- 408 Request Timeout (status code) 60
- 409 Conflict (status code) 60
-
-
-
-Fielding & Reschke Standards Track [Page 97]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- 410 Gone (status code) 60
- 411 Length Required (status code) 61
- 413 Payload Too Large (status code) 61
- 414 URI Too Long (status code) 61
- 415 Unsupported Media Type (status code) 62
- 417 Expectation Failed (status code) 62
- 426 Upgrade Required (status code) 62
-
- 5
- 500 Internal Server Error (status code) 63
- 501 Not Implemented (status code) 63
- 502 Bad Gateway (status code) 63
- 503 Service Unavailable (status code) 63
- 504 Gateway Timeout (status code) 63
- 505 HTTP Version Not Supported (status code) 64
-
- A
- Accept header field 38
- Accept-Charset header field 40
- Accept-Encoding header field 41
- Accept-Language header field 42
- Allow header field 72
-
- C
- cacheable 24
- compress (content coding) 11
- conditional request 36
- CONNECT method 30
- content coding 11
- content negotiation 6
- Content-Encoding header field 12
- Content-Language header field 13
- Content-Location header field 15
- Content-Transfer-Encoding header field 89
- Content-Type header field 10
-
- D
- Date header field 67
- deflate (content coding) 11
- DELETE method 29
-
- E
- Expect header field 34
-
- F
- From header field 44
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 98]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- G
- GET method 24
- Grammar
- Accept 38
- Accept-Charset 40
- Accept-Encoding 41
- accept-ext 38
- Accept-Language 42
- accept-params 38
- Allow 72
- asctime-date 66
- charset 9
- codings 41
- content-coding 11
- Content-Encoding 12
- Content-Language 13
- Content-Location 15
- Content-Type 10
- Date 67
- date1 65
- day 65
- day-name 65
- day-name-l 65
- delay-seconds 69
- Expect 34
- From 44
- GMT 65
- hour 65
- HTTP-date 65
- IMF-fixdate 65
- language-range 42
- language-tag 13
- Location 68
- Max-Forwards 36
- media-range 38
- media-type 8
- method 21
- minute 65
- month 65
- obs-date 66
- parameter 8
- product 46
- product-version 46
- qvalue 38
- Referer 45
- Retry-After 69
- rfc850-date 66
- second 65
-
-
-
-Fielding & Reschke Standards Track [Page 99]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- Server 73
- subtype 8
- time-of-day 65
- type 8
- User-Agent 46
- Vary 70
- weight 38
- year 65
- gzip (content coding) 11
-
- H
- HEAD method 25
-
- I
- idempotent 23
-
- L
- Location header field 68
-
- M
- Max-Forwards header field 36
- MIME-Version header field 89
-
- O
- OPTIONS method 31
-
- P
- payload 17
- POST method 25
- PUT method 26
-
- R
- Referer header field 45
- representation 7
- Retry-After header field 69
-
- S
- safe 22
- selected representation 7, 71
- Server header field 73
- Status Codes Classes
- 1xx Informational 50
- 2xx Successful 51
- 3xx Redirection 54
- 4xx Client Error 58
- 5xx Server Error 62
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 100]
-\f
-RFC 7231 HTTP/1.1 Semantics and Content June 2014
-
-
- T
- TRACE method 32
-
- U
- User-Agent header field 46
-
- V
- Vary header field 70
-
- X
- x-compress (content coding) 11
- x-gzip (content coding) 11
-
-Authors' Addresses
-
- Roy T. Fielding (editor)
- Adobe Systems Incorporated
- 345 Park Ave
- San Jose, CA 95110
- USA
-
- EMail: fielding@gbiv.com
- URI: http://roy.gbiv.com/
-
-
- Julian F. Reschke (editor)
- greenbytes GmbH
- Hafenweg 16
- Muenster, NW 48155
- Germany
-
- EMail: julian.reschke@greenbytes.de
- URI: http://greenbytes.de/tech/webdav/
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 101]
-\f
+++ /dev/null
-
-
-
-
-
-
-Internet Engineering Task Force (IETF) R. Fielding, Ed.
-Request for Comments: 7232 Adobe
-Obsoletes: 2616 J. Reschke, Ed.
-Category: Standards Track greenbytes
-ISSN: 2070-1721 June 2014
-
-
- Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests
-
-Abstract
-
- The Hypertext Transfer Protocol (HTTP) is a stateless application-
- level protocol for distributed, collaborative, hypertext information
- systems. This document defines HTTP/1.1 conditional requests,
- including metadata header fields for indicating state changes,
- request header fields for making preconditions on such state, and
- rules for constructing the responses to a conditional request when
- one or more preconditions evaluate to false.
-
-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 5741.
-
- 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/rfc7232.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 1]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
-Copyright Notice
-
- Copyright (c) 2014 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.
-
- This document may contain material from IETF Documents or IETF
- Contributions published or made publicly available before November
- 10, 2008. The person(s) controlling the copyright in some of this
- material may not have granted the IETF Trust the right to allow
- modifications of such material outside the IETF Standards Process.
- Without obtaining an adequate license from the person(s) controlling
- the copyright in such materials, this document may not be modified
- outside the IETF Standards Process, and derivative works of it may
- not be created outside the IETF Standards Process, except to format
- it for publication as an RFC or to translate it into languages other
- than English.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 2]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
-Table of Contents
-
- 1. Introduction ....................................................4
- 1.1. Conformance and Error Handling .............................4
- 1.2. Syntax Notation ............................................4
- 2. Validators ......................................................5
- 2.1. Weak versus Strong .........................................5
- 2.2. Last-Modified ..............................................7
- 2.2.1. Generation ..........................................7
- 2.2.2. Comparison ..........................................8
- 2.3. ETag .......................................................9
- 2.3.1. Generation .........................................10
- 2.3.2. Comparison .........................................10
- 2.3.3. Example: Entity-Tags Varying on
- Content-Negotiated Resources .......................11
- 2.4. When to Use Entity-Tags and Last-Modified Dates ...........12
- 3. Precondition Header Fields .....................................13
- 3.1. If-Match ..................................................13
- 3.2. If-None-Match .............................................14
- 3.3. If-Modified-Since .........................................16
- 3.4. If-Unmodified-Since .......................................17
- 3.5. If-Range ..................................................18
- 4. Status Code Definitions ........................................18
- 4.1. 304 Not Modified ..........................................18
- 4.2. 412 Precondition Failed ...................................19
- 5. Evaluation .....................................................19
- 6. Precedence .....................................................20
- 7. IANA Considerations ............................................22
- 7.1. Status Code Registration ..................................22
- 7.2. Header Field Registration .................................22
- 8. Security Considerations ........................................22
- 9. Acknowledgments ................................................23
- 10. References ....................................................24
- 10.1. Normative References .....................................24
- 10.2. Informative References ...................................24
- Appendix A. Changes from RFC 2616 .................................25
- Appendix B. Imported ABNF .........................................25
- Appendix C. Collected ABNF ........................................26
- Index .............................................................27
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 3]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
-1. Introduction
-
- Conditional requests are HTTP requests [RFC7231] that include one or
- more header fields indicating a precondition to be tested before
- applying the method semantics to the target resource. This document
- defines the HTTP/1.1 conditional request mechanisms in terms of the
- architecture, syntax notation, and conformance criteria defined in
- [RFC7230].
-
- Conditional GET requests are the most efficient mechanism for HTTP
- cache updates [RFC7234]. Conditionals can also be applied to
- state-changing methods, such as PUT and DELETE, to prevent the "lost
- update" problem: one client accidentally overwriting the work of
- another client that has been acting in parallel.
-
- Conditional request preconditions are based on the state of the
- target resource as a whole (its current value set) or the state as
- observed in a previously obtained representation (one value in that
- set). A resource might have multiple current representations, each
- with its own observable state. The conditional request mechanisms
- assume that the mapping of requests to a "selected representation"
- (Section 3 of [RFC7231]) will be consistent over time if the server
- intends to take advantage of conditionals. Regardless, if the
- mapping is inconsistent and the server is unable to select the
- appropriate representation, then no harm will result when the
- precondition evaluates to false.
-
- The conditional request preconditions defined by this specification
- (Section 3) are evaluated when applicable to the recipient
- (Section 5) according to their order of precedence (Section 6).
-
-1.1. Conformance and Error Handling
-
- 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].
-
- Conformance criteria and considerations regarding error handling are
- defined in Section 2.5 of [RFC7230].
-
-1.2. Syntax Notation
-
- This specification uses the Augmented Backus-Naur Form (ABNF)
- notation of [RFC5234] with a list extension, defined in Section 7 of
- [RFC7230], that allows for compact definition of comma-separated
- lists using a '#' operator (similar to how the '*' operator indicates
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 4]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- repetition). Appendix B describes rules imported from other
- documents. Appendix C shows the collected grammar with all list
- operators expanded to standard ABNF notation.
-
-2. Validators
-
- This specification defines two forms of metadata that are commonly
- used to observe resource state and test for preconditions:
- modification dates (Section 2.2) and opaque entity tags
- (Section 2.3). Additional metadata that reflects resource state has
- been defined by various extensions of HTTP, such as Web Distributed
- Authoring and Versioning (WebDAV, [RFC4918]), that are beyond the
- scope of this specification. A resource metadata value is referred
- to as a "validator" when it is used within a precondition.
-
-2.1. Weak versus Strong
-
- Validators come in two flavors: strong or weak. Weak validators are
- easy to generate but are far less useful for comparisons. Strong
- validators are ideal for comparisons but can be very difficult (and
- occasionally impossible) to generate efficiently. Rather than impose
- that all forms of resource adhere to the same strength of validator,
- HTTP exposes the type of validator in use and imposes restrictions on
- when weak validators can be used as preconditions.
-
- A "strong validator" is representation metadata that changes value
- whenever a change occurs to the representation data that would be
- observable in the payload body of a 200 (OK) response to GET.
-
- A strong validator might change for reasons other than a change to
- the representation data, such as when a semantically significant part
- of the representation metadata is changed (e.g., Content-Type), but
- it is in the best interests of the origin server to only change the
- value when it is necessary to invalidate the stored responses held by
- remote caches and authoring tools.
-
- Cache entries might persist for arbitrarily long periods, regardless
- of expiration times. Thus, a cache might attempt to validate an
- entry using a validator that it obtained in the distant past. A
- strong validator is unique across all versions of all representations
- associated with a particular resource over time. However, there is
- no implication of uniqueness across representations of different
- resources (i.e., the same strong validator might be in use for
- representations of multiple resources at the same time and does not
- imply that those representations are equivalent).
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 5]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- There are a variety of strong validators used in practice. The best
- are based on strict revision control, wherein each change to a
- representation always results in a unique node name and revision
- identifier being assigned before the representation is made
- accessible to GET. A collision-resistant hash function applied to
- the representation data is also sufficient if the data is available
- prior to the response header fields being sent and the digest does
- not need to be recalculated every time a validation request is
- received. However, if a resource has distinct representations that
- differ only in their metadata, such as might occur with content
- negotiation over media types that happen to share the same data
- format, then the origin server needs to incorporate additional
- information in the validator to distinguish those representations.
-
- In contrast, a "weak validator" is representation metadata that might
- not change for every change to the representation data. This
- weakness might be due to limitations in how the value is calculated,
- such as clock resolution, an inability to ensure uniqueness for all
- possible representations of the resource, or a desire of the resource
- owner to group representations by some self-determined set of
- equivalency rather than unique sequences of data. An origin server
- SHOULD change a weak entity-tag whenever it considers prior
- representations to be unacceptable as a substitute for the current
- representation. In other words, a weak entity-tag ought to change
- whenever the origin server wants caches to invalidate old responses.
-
- For example, the representation of a weather report that changes in
- content every second, based on dynamic measurements, might be grouped
- into sets of equivalent representations (from the origin server's
- perspective) with the same weak validator in order to allow cached
- representations to be valid for a reasonable period of time (perhaps
- adjusted dynamically based on server load or weather quality).
- Likewise, a representation's modification time, if defined with only
- one-second resolution, might be a weak validator if it is possible
- for the representation to be modified twice during a single second
- and retrieved between those modifications.
-
- Likewise, a validator is weak if it is shared by two or more
- representations of a given resource at the same time, unless those
- representations have identical representation data. For example, if
- the origin server sends the same validator for a representation with
- a gzip content coding applied as it does for a representation with no
- content coding, then that validator is weak. However, two
- simultaneous representations might share the same strong validator if
- they differ only in the representation metadata, such as when two
- different media types are available for the same representation data.
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 6]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- Strong validators are usable for all conditional requests, including
- cache validation, partial content ranges, and "lost update"
- avoidance. Weak validators are only usable when the client does not
- require exact equality with previously obtained representation data,
- such as when validating a cache entry or limiting a web traversal to
- recent changes.
-
-2.2. Last-Modified
-
- The "Last-Modified" header field in a response provides a timestamp
- indicating the date and time at which the origin server believes the
- selected representation was last modified, as determined at the
- conclusion of handling the request.
-
- Last-Modified = HTTP-date
-
- An example of its use is
-
- Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
-
-2.2.1. Generation
-
- An origin server SHOULD send Last-Modified for any selected
- representation for which a last modification date can be reasonably
- and consistently determined, since its use in conditional requests
- and evaluating cache freshness ([RFC7234]) results in a substantial
- reduction of HTTP traffic on the Internet and can be a significant
- factor in improving service scalability and reliability.
-
- A representation is typically the sum of many parts behind the
- resource interface. The last-modified time would usually be the most
- recent time that any of those parts were changed. How that value is
- determined for any given resource is an implementation detail beyond
- the scope of this specification. What matters to HTTP is how
- recipients of the Last-Modified header field can use its value to
- make conditional requests and test the validity of locally cached
- responses.
-
- An origin server SHOULD obtain the Last-Modified value of the
- representation as close as possible to the time that it generates the
- Date field value for its response. This allows a recipient to make
- an accurate assessment of the representation's modification time,
- especially if the representation changes near the time that the
- response is generated.
-
- An origin server with a clock MUST NOT send a Last-Modified date that
- is later than the server's time of message origination (Date). If
- the last modification time is derived from implementation-specific
-
-
-
-Fielding & Reschke Standards Track [Page 7]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- metadata that evaluates to some time in the future, according to the
- origin server's clock, then the origin server MUST replace that value
- with the message origination date. This prevents a future
- modification date from having an adverse impact on cache validation.
-
- An origin server without a clock MUST NOT assign Last-Modified values
- to a response unless these values were associated with the resource
- by some other system or user with a reliable clock.
-
-2.2.2. Comparison
-
- 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:
-
- o The validator is being compared by an origin server to the actual
- current validator for the representation and,
-
- o That origin server reliably knows that the associated
- representation did not change twice during the second covered by
- the presented validator.
-
- or
-
- o The validator is about to be used by a client in an
- If-Modified-Since, If-Unmodified-Since, or If-Range header field,
- because the client has a cache entry for the associated
- representation, and
-
- o That cache entry includes a Date value, which gives the time when
- the origin server sent the original response, and
-
- o The presented Last-Modified time is at least 60 seconds before the
- Date value.
-
- or
-
- o The validator is being compared by an intermediate cache to the
- validator stored in its cache entry for the representation, and
-
- o That cache entry includes a Date value, which gives the time when
- the origin server sent the original response, and
-
- o The presented Last-Modified time is at least 60 seconds before the
- Date value.
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 8]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- 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.
-
-2.3. ETag
-
- The "ETag" header field in a response provides the current entity-tag
- for the selected representation, as determined at the conclusion of
- handling the request. An entity-tag is an opaque validator for
- differentiating between multiple representations of the same
- resource, regardless of whether those multiple representations are
- due to resource state changes over time, content negotiation
- resulting in multiple representations being valid at the same time,
- or both. An entity-tag consists of an opaque quoted string, possibly
- prefixed by a weakness indicator.
-
- ETag = entity-tag
-
- entity-tag = [ weak ] opaque-tag
- weak = %x57.2F ; "W/", case-sensitive
- opaque-tag = DQUOTE *etagc DQUOTE
- etagc = %x21 / %x23-7E / obs-text
- ; VCHAR except double quotes, plus obs-text
-
- Note: Previously, opaque-tag was defined to be a quoted-string
- ([RFC2616], Section 3.11); thus, some recipients might perform
- backslash unescaping. Servers therefore ought to avoid backslash
- characters in entity tags.
-
- An entity-tag can be more reliable for validation than a modification
- date in situations where it is inconvenient to store modification
- dates, where the one-second resolution of HTTP date values is not
- sufficient, or where modification dates are not consistently
- maintained.
-
- Examples:
-
- ETag: "xyzzy"
- ETag: W/"xyzzy"
- ETag: ""
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 9]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- An entity-tag can be either a weak or strong validator, with strong
- being the default. If an origin server provides an entity-tag for a
- representation and the generation of that entity-tag does not satisfy
- all of the characteristics of a strong validator (Section 2.1), then
- the origin server MUST mark the entity-tag as weak by prefixing its
- opaque value with "W/" (case-sensitive).
-
-2.3.1. Generation
-
- The principle behind entity-tags is that only the service author
- knows the implementation of a resource well enough to select the most
- accurate and efficient validation mechanism for that resource, and
- that any such mechanism can be mapped to a simple sequence of octets
- for easy comparison. Since the value is opaque, there is no need for
- the client to be aware of how each entity-tag is constructed.
-
- For example, a resource that has implementation-specific versioning
- applied to all changes might use an internal revision number, perhaps
- combined with a variance identifier for content negotiation, to
- accurately differentiate between representations. Other
- implementations might use a collision-resistant hash of
- representation content, a combination of various file attributes, or
- a modification timestamp that has sub-second resolution.
-
- An origin server SHOULD send an ETag for any selected representation
- for which detection of changes can be reasonably and consistently
- determined, since the entity-tag's use in conditional requests and
- evaluating cache freshness ([RFC7234]) can result in a substantial
- reduction of HTTP network traffic and can be a significant factor in
- improving service scalability and reliability.
-
-2.3.2. Comparison
-
- There are two entity-tag comparison functions, depending on whether
- or not the comparison context allows the use of weak validators:
-
- o Strong comparison: two entity-tags are equivalent if both are not
- weak and their opaque-tags match character-by-character.
-
- o Weak comparison: two entity-tags are equivalent if their
- opaque-tags match character-by-character, regardless of either or
- both being tagged as "weak".
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 10]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- The example below shows the results for a set of entity-tag pairs and
- both the weak and strong comparison function results:
-
- +--------+--------+-------------------+-----------------+
- | ETag 1 | ETag 2 | Strong Comparison | Weak Comparison |
- +--------+--------+-------------------+-----------------+
- | W/"1" | W/"1" | no match | match |
- | W/"1" | W/"2" | no match | no match |
- | W/"1" | "1" | no match | match |
- | "1" | "1" | match | match |
- +--------+--------+-------------------+-----------------+
-
-2.3.3. Example: Entity-Tags Varying on Content-Negotiated Resources
-
- Consider a resource that is subject to content negotiation (Section
- 3.4 of [RFC7231]), and where the representations sent in response to
- a GET request vary based on the Accept-Encoding request header field
- (Section 5.3.4 of [RFC7231]):
-
- >> Request:
-
- GET /index HTTP/1.1
- Host: www.example.com
- Accept-Encoding: gzip
-
-
- In this case, the response might or might not use the gzip content
- coding. If it does not, the response might look like:
-
- >> Response:
-
- HTTP/1.1 200 OK
- Date: Fri, 26 Mar 2010 00:05:00 GMT
- ETag: "123-a"
- Content-Length: 70
- Vary: Accept-Encoding
- Content-Type: text/plain
-
- Hello World!
- Hello World!
- Hello World!
- Hello World!
- Hello World!
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 11]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- An alternative representation that does use gzip content coding would
- be:
-
- >> Response:
-
- HTTP/1.1 200 OK
- Date: Fri, 26 Mar 2010 00:05:00 GMT
- ETag: "123-b"
- Content-Length: 43
- Vary: Accept-Encoding
- Content-Type: text/plain
- Content-Encoding: gzip
-
- ...binary data...
-
- Note: Content codings are a property of the representation data,
- so a strong entity-tag for a content-encoded representation has to
- be distinct from the entity tag of an unencoded representation to
- prevent potential conflicts during cache updates and range
- requests. In contrast, transfer codings (Section 4 of [RFC7230])
- apply only during message transfer and do not result in distinct
- entity-tags.
-
-2.4. When to Use Entity-Tags and Last-Modified Dates
-
- In 200 (OK) responses to GET or HEAD, an origin server:
-
- o SHOULD send an entity-tag validator unless it is not feasible to
- generate one.
-
- o 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.
-
- o SHOULD send a Last-Modified value if it is feasible to send one.
-
- In other words, the preferred behavior for an origin server is to
- send both a strong entity-tag and a Last-Modified value in successful
- responses to a retrieval request.
-
- A client:
-
- o MUST send that entity-tag in any cache validation request (using
- If-Match or If-None-Match) if an entity-tag has been provided by
- the origin server.
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 12]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- o SHOULD send the Last-Modified value in non-subrange cache
- validation requests (using If-Modified-Since) if only a
- Last-Modified value has been provided by the origin server.
-
- o MAY send the Last-Modified value in subrange cache validation
- requests (using If-Unmodified-Since) if only a Last-Modified value
- has been provided by an HTTP/1.0 origin server. The user agent
- SHOULD provide a way to disable this, in case of difficulty.
-
- o SHOULD send both validators in cache validation requests if both
- an entity-tag and a Last-Modified value have been provided by the
- origin server. This allows both HTTP/1.0 and HTTP/1.1 caches to
- respond appropriately.
-
-3. Precondition Header Fields
-
- This section defines the syntax and semantics of HTTP/1.1 header
- fields for applying preconditions on requests. Section 5 defines
- when the preconditions are applied. Section 6 defines the order of
- evaluation when more than one precondition is present.
-
-3.1. If-Match
-
- The "If-Match" header field makes the request method conditional on
- the recipient origin server either having at least one current
- representation of the target resource, when the field-value is "*",
- or having a current representation of the target resource that has an
- entity-tag matching a member of the list of entity-tags provided in
- the field-value.
-
- An origin server MUST use the strong comparison function when
- comparing entity-tags for If-Match (Section 2.3.2), since the client
- intends this precondition to prevent the method from being applied if
- there have been any changes to the representation data.
-
- If-Match = "*" / 1#entity-tag
-
- Examples:
-
- If-Match: "xyzzy"
- If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
- If-Match: *
-
- If-Match is most often used with state-changing methods (e.g., POST,
- PUT, DELETE) to prevent accidental overwrites when multiple user
- agents might be acting in parallel on the same resource (i.e., to
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 13]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- prevent the "lost update" problem). It can also be used with safe
- methods to abort a request if the selected representation does not
- match one already stored (or partially stored) from a prior request.
-
- An origin server that receives an If-Match header field MUST evaluate
- the condition prior to performing the method (Section 5). If the
- field-value is "*", the condition is false if the origin server does
- not have a current representation for the target resource. If the
- field-value is a list of entity-tags, the condition is false if none
- of the listed tags match the entity-tag of the selected
- representation.
-
- An origin server MUST NOT perform the requested method if a received
- If-Match condition evaluates to false; instead, the origin server
- MUST respond with either a) the 412 (Precondition Failed) status code
- or b) one of the 2xx (Successful) status codes if the origin server
- has verified that a state change is being requested and the final
- state is already reflected in the current state of the target
- resource (i.e., the change requested by the user agent has already
- succeeded, but the user agent might not be aware of it, perhaps
- because the prior response was lost or a compatible change was made
- by some other user agent). In the latter case, the origin server
- MUST NOT send a validator header field in the response unless it can
- verify that the request is a duplicate of an immediately prior change
- made by the same user agent.
-
- The If-Match header field can be ignored by caches and intermediaries
- because it is not applicable to a stored response.
-
-3.2. If-None-Match
-
- The "If-None-Match" header field makes the request method conditional
- on a recipient cache or origin server either not having any current
- representation of the target resource, when the field-value is "*",
- or having a selected representation with an entity-tag that does not
- match any of those listed in the field-value.
-
- A recipient MUST use the weak comparison function when comparing
- entity-tags for If-None-Match (Section 2.3.2), since weak entity-tags
- can be used for cache validation even if there have been changes to
- the representation data.
-
- If-None-Match = "*" / 1#entity-tag
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 14]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- 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: *
-
- If-None-Match is primarily used in conditional GET requests to enable
- efficient updates of cached information with a minimum amount of
- transaction overhead. When a client desires to update one or more
- stored responses that have entity-tags, the client SHOULD generate an
- If-None-Match header field containing a list of those entity-tags
- when making a GET request; this allows recipient servers to send a
- 304 (Not Modified) response to indicate when one of those stored
- responses matches the selected representation.
-
- If-None-Match can also be used with a value of "*" to prevent an
- unsafe request method (e.g., PUT) from inadvertently modifying an
- existing representation of the target resource when the client
- believes that the resource does not have a current representation
- (Section 4.2.1 of [RFC7231]). This is a variation on the "lost
- update" problem that might arise if more than one client attempts to
- create an initial representation for the target resource.
-
- An origin server that receives an If-None-Match header field MUST
- evaluate the condition prior to performing the method (Section 5).
- If the field-value is "*", the condition is false if the origin
- server has a current representation for the target resource. If the
- field-value is a list of entity-tags, the condition is false if one
- of the listed tags match the entity-tag of the selected
- representation.
-
- An origin server MUST NOT perform the requested method if the
- condition evaluates to false; instead, the origin server MUST respond
- with either a) the 304 (Not Modified) status code if the request
- method is GET or HEAD or b) the 412 (Precondition Failed) status code
- for all other request methods.
-
- Requirements on cache handling of a received If-None-Match header
- field are defined in Section 4.3.2 of [RFC7234].
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 15]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
-3.3. If-Modified-Since
-
- The "If-Modified-Since" header field makes a GET or HEAD request
- method conditional on the selected representation's modification date
- being more recent than the date provided in the field-value.
- Transfer of the selected representation's data is avoided if that
- data has not changed.
-
- If-Modified-Since = HTTP-date
-
- An example of the field is:
-
- If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT
-
- A recipient MUST ignore If-Modified-Since if the request contains an
- If-None-Match header field; the condition in If-None-Match is
- considered to be a more accurate replacement for the condition in
- If-Modified-Since, and the two are only combined for the sake of
- interoperating with older intermediaries that might not implement
- If-None-Match.
-
- A recipient MUST ignore the If-Modified-Since header field if the
- received field-value is not a valid HTTP-date, or if the request
- method is neither GET nor HEAD.
-
- A recipient MUST interpret an If-Modified-Since field-value's
- timestamp in terms of the origin server's clock.
-
- If-Modified-Since is typically used for two distinct purposes: 1) to
- allow efficient updates of a cached representation that does not have
- an entity-tag and 2) to limit the scope of a web traversal to
- resources that have recently changed.
-
- When used for cache updates, a cache will typically use the value of
- the cached message's Last-Modified field to generate the field value
- of If-Modified-Since. This behavior is most interoperable for cases
- where clocks are poorly synchronized or when the server has chosen to
- only honor exact timestamp matches (due to a problem with
- Last-Modified dates that appear to go "back in time" when the origin
- server's clock is corrected or a representation is restored from an
- archived backup). However, caches occasionally generate the field
- value based on other data, such as the Date header field of the
- cached message or the local clock time that the message was received,
- particularly when the cached message does not contain a Last-Modified
- field.
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 16]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- When used for limiting the scope of retrieval to a recent time
- window, a user agent will generate an If-Modified-Since field value
- based on either its own local clock or a Date header field received
- from the server in a prior response. Origin servers that choose an
- exact timestamp match based on the selected representation's
- Last-Modified field will not be able to help the user agent limit its
- data transfers to only those changed during the specified window.
-
- An origin server that receives an If-Modified-Since header field
- SHOULD evaluate the condition prior to performing the method
- (Section 5). The origin server SHOULD NOT perform the requested
- method if the selected representation's last modification date is
- earlier than or equal to the date provided in the field-value;
- instead, the origin server SHOULD generate a 304 (Not Modified)
- response, including only those metadata that are useful for
- identifying or updating a previously cached response.
-
- Requirements on cache handling of a received If-Modified-Since header
- field are defined in Section 4.3.2 of [RFC7234].
-
-3.4. If-Unmodified-Since
-
- The "If-Unmodified-Since" header field makes the request method
- conditional on the selected representation's last modification date
- being earlier than or equal to the date provided in the field-value.
- This field accomplishes the same purpose as If-Match for cases where
- the user agent does not have an entity-tag for the representation.
-
- If-Unmodified-Since = HTTP-date
-
- An example of the field is:
-
- If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT
-
- A recipient MUST ignore If-Unmodified-Since if the request contains
- an If-Match header field; the condition in If-Match is considered to
- be a more accurate replacement for the condition in
- If-Unmodified-Since, and the two are only combined for the sake of
- interoperating with older intermediaries that might not implement
- If-Match.
-
- A recipient MUST ignore the If-Unmodified-Since header field if the
- received field-value is not a valid HTTP-date.
-
- A recipient MUST interpret an If-Unmodified-Since field-value's
- timestamp in terms of the origin server's clock.
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 17]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- If-Unmodified-Since is most often used with state-changing methods
- (e.g., POST, PUT, DELETE) to prevent accidental overwrites when
- multiple user agents might be acting in parallel on a resource that
- does not supply entity-tags with its representations (i.e., to
- prevent the "lost update" problem). It can also be used with safe
- methods to abort a request if the selected representation does not
- match one already stored (or partially stored) from a prior request.
-
- An origin server that receives an If-Unmodified-Since header field
- MUST evaluate the condition prior to performing the method
- (Section 5). The origin server MUST NOT perform the requested method
- if the selected representation's last modification date is more
- recent than the date provided in the field-value; instead the origin
- server MUST respond with either a) the 412 (Precondition Failed)
- status code or b) one of the 2xx (Successful) status codes if the
- origin server has verified that a state change is being requested and
- the final state is already reflected in the current state of the
- target resource (i.e., the change requested by the user agent has
- already succeeded, but the user agent might not be aware of that
- because the prior response message was lost or a compatible change
- was made by some other user agent). In the latter case, the origin
- server MUST NOT send a validator header field in the response unless
- it can verify that the request is a duplicate of an immediately prior
- change made by the same user agent.
-
- The If-Unmodified-Since header field can be ignored by caches and
- intermediaries because it is not applicable to a stored response.
-
-3.5. If-Range
-
- The "If-Range" header field provides a special conditional request
- mechanism that is similar to the If-Match and If-Unmodified-Since
- header fields but that instructs the recipient to ignore the Range
- header field if the validator doesn't match, resulting in transfer of
- the new selected representation instead of a 412 (Precondition
- Failed) response. If-Range is defined in Section 3.2 of [RFC7233].
-
-4. Status Code Definitions
-
-4.1. 304 Not Modified
-
- The 304 (Not Modified) status code indicates that a conditional GET
- or HEAD request has been received and would have resulted in a 200
- (OK) response if it were not for the fact that the condition
- evaluated to false. In other words, there is no need for the server
- to transfer a representation of the target resource because the
- request indicates that the client, which made the request
-
-
-
-
-Fielding & Reschke Standards Track [Page 18]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- conditional, already has a valid representation; the server is
- therefore redirecting the client to make use of that stored
- representation as if it were the payload of a 200 (OK) response.
-
- The server generating a 304 response MUST generate any of the
- following header fields that would have been sent in a 200 (OK)
- response to the same request: Cache-Control, Content-Location, Date,
- ETag, Expires, and Vary.
-
- Since the goal of a 304 response is to minimize information transfer
- when the recipient already has one or more cached representations, a
- sender SHOULD NOT generate representation metadata other than the
- above listed fields unless said metadata exists for the purpose of
- guiding cache updates (e.g., Last-Modified might be useful if the
- response does not have an ETag field).
-
- Requirements on a cache that receives a 304 response are defined in
- Section 4.3.4 of [RFC7234]. If the conditional request originated
- with an outbound client, such as a user agent with its own cache
- sending a conditional GET to a shared proxy, then the proxy SHOULD
- forward the 304 response to that client.
-
- A 304 response cannot contain a message-body; it is always terminated
- by the first empty line after the header fields.
-
-4.2. 412 Precondition Failed
-
- The 412 (Precondition Failed) status code indicates that one or more
- conditions given in the request header fields evaluated to false when
- tested on the server. This response code allows the client to place
- preconditions on the current resource state (its current
- representations and metadata) and, thus, prevent the request method
- from being applied if the target resource is in an unexpected state.
-
-5. Evaluation
-
- Except when excluded below, a recipient cache or origin server MUST
- evaluate received request preconditions after it has successfully
- performed its normal request checks and just before it would perform
- the action associated with the request method. A server MUST ignore
- all received preconditions if its response to the same request
- without those conditions would have been a status code other than a
- 2xx (Successful) or 412 (Precondition Failed). In other words,
- redirects and failures take precedence over the evaluation of
- preconditions in conditional requests.
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 19]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- A server that is not the origin server for the target resource and
- cannot act as a cache for requests on the target resource MUST NOT
- evaluate the conditional request header fields defined by this
- specification, and it MUST forward them if the request is forwarded,
- since the generating client intends that they be evaluated by a
- server that can provide a current representation. Likewise, a server
- MUST ignore the conditional request header fields defined by this
- specification when received with a request method that does not
- involve the selection or modification of a selected representation,
- such as CONNECT, OPTIONS, or TRACE.
-
- Conditional request header fields that are defined by extensions to
- HTTP might place conditions on all recipients, on the state of the
- target resource in general, or on a group of resources. For
- instance, the "If" header field in WebDAV can make a request
- conditional on various aspects of multiple resources, such as locks,
- if the recipient understands and implements that field ([RFC4918],
- Section 10.4).
-
- Although conditional request header fields are defined as being
- usable with the HEAD method (to keep HEAD's semantics consistent with
- those of GET), there is no point in sending a conditional HEAD
- because a successful response is around the same size as a 304 (Not
- Modified) response and more useful than a 412 (Precondition Failed)
- response.
-
-6. Precedence
-
- When more than one conditional request header field is present in a
- request, the order in which the fields are evaluated becomes
- important. In practice, the fields defined in this document are
- consistently implemented in a single, logical order, since "lost
- update" preconditions have more strict requirements than cache
- validation, a validated cache is more efficient than a partial
- response, and entity tags are presumed to be more accurate than date
- validators.
-
- A recipient cache or origin server MUST evaluate the request
- preconditions defined by this specification in the following order:
-
- 1. When recipient is the origin server and If-Match is present,
- evaluate the If-Match precondition:
-
- * if true, continue to step 3
-
- * if false, respond 412 (Precondition Failed) unless it can be
- determined that the state-changing request has already
- succeeded (see Section 3.1)
-
-
-
-Fielding & Reschke Standards Track [Page 20]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- 2. When recipient is the origin server, If-Match is not present, and
- If-Unmodified-Since is present, evaluate the If-Unmodified-Since
- precondition:
-
- * if true, continue to step 3
-
- * if false, respond 412 (Precondition Failed) unless it can be
- determined that the state-changing request has already
- succeeded (see Section 3.4)
-
- 3. When If-None-Match is present, evaluate the If-None-Match
- precondition:
-
- * if true, continue to step 5
-
- * if false for GET/HEAD, respond 304 (Not Modified)
-
- * if false for other methods, respond 412 (Precondition Failed)
-
- 4. When the method is GET or HEAD, If-None-Match is not present, and
- If-Modified-Since is present, evaluate the If-Modified-Since
- precondition:
-
- * if true, continue to step 5
-
- * if false, respond 304 (Not Modified)
-
- 5. When the method is GET and both Range and If-Range are present,
- evaluate the If-Range precondition:
-
- * if the validator matches and the Range specification is
- applicable to the selected representation, respond 206
- (Partial Content) [RFC7233]
-
- 6. Otherwise,
-
- * all conditions are met, so perform the requested action and
- respond according to its success or failure.
-
- Any extension to HTTP/1.1 that defines additional conditional request
- header fields ought to define its own expectations regarding the
- order for evaluating such fields in relation to those defined in this
- document and other conditionals that might be found in practice.
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 21]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
-7. IANA Considerations
-
-7.1. Status Code Registration
-
- The "Hypertext Transfer Protocol (HTTP) Status Code Registry" located
- at <http://www.iana.org/assignments/http-status-codes> has been
- updated with the registrations below:
-
- +-------+---------------------+-------------+
- | Value | Description | Reference |
- +-------+---------------------+-------------+
- | 304 | Not Modified | Section 4.1 |
- | 412 | Precondition Failed | Section 4.2 |
- +-------+---------------------+-------------+
-
-7.2. Header Field Registration
-
- HTTP header fields are registered within the "Message Headers"
- registry maintained at
- <http://www.iana.org/assignments/message-headers/>.
-
- This document defines the following HTTP header fields, so their
- associated registry entries have been updated according to the
- permanent registrations below (see [BCP90]):
-
- +---------------------+----------+----------+-------------+
- | Header Field Name | Protocol | Status | Reference |
- +---------------------+----------+----------+-------------+
- | ETag | http | standard | Section 2.3 |
- | If-Match | http | standard | Section 3.1 |
- | If-Modified-Since | http | standard | Section 3.3 |
- | If-None-Match | http | standard | Section 3.2 |
- | If-Unmodified-Since | http | standard | Section 3.4 |
- | Last-Modified | http | standard | Section 2.2 |
- +---------------------+----------+----------+-------------+
-
- The change controller is: "IETF (iesg@ietf.org) - Internet
- Engineering Task Force".
-
-8. Security Considerations
-
- This section is meant to inform developers, information providers,
- and users of known security concerns specific to the HTTP conditional
- request mechanisms. More general security considerations are
- addressed in HTTP "Message Syntax and Routing" [RFC7230] and
- "Semantics and Content" [RFC7231].
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 22]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
- The validators defined by this specification are not intended to
- ensure the validity of a representation, guard against malicious
- changes, or detect man-in-the-middle attacks. At best, they enable
- more efficient cache updates and optimistic concurrent writes when
- all participants are behaving nicely. At worst, the conditions will
- fail and the client will receive a response that is no more harmful
- than an HTTP exchange without conditional requests.
-
- An entity-tag can be abused in ways that create privacy risks. For
- example, a site might deliberately construct a semantically invalid
- entity-tag that is unique to the user or user agent, send it in a
- cacheable response with a long freshness time, and then read that
- entity-tag in later conditional requests as a means of re-identifying
- that user or user agent. Such an identifying tag would become a
- persistent identifier for as long as the user agent retained the
- original cache entry. User agents that cache representations ought
- to ensure that the cache is cleared or replaced whenever the user
- performs privacy-maintaining actions, such as clearing stored cookies
- or changing to a private browsing mode.
-
-9. Acknowledgments
-
- See Section 10 of [RFC7230].
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 23]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
-10. References
-
-10.1. Normative References
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", STD 68, RFC 5234, January 2008.
-
- [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Message Syntax and Routing",
- RFC 7230, June 2014.
-
- [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
- June 2014.
-
- [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed.,
- "Hypertext Transfer Protocol (HTTP/1.1): Range Requests",
- RFC 7233, June 2014.
-
- [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
- Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
- RFC 7234, June 2014.
-
-10.2. Informative References
-
- [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration
- Procedures for Message Header Fields", BCP 90, RFC 3864,
- September 2004.
-
- [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.
-
- [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed
- Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 24]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
-Appendix A. Changes from RFC 2616
-
- The definition of validator weakness has been expanded and clarified.
- (Section 2.1)
-
- Weak entity-tags are now allowed in all requests except range
- requests. (Sections 2.1 and 3.2)
-
- The ETag header field ABNF has been changed to not use quoted-string,
- thus avoiding escaping issues. (Section 2.3)
-
- ETag is defined to provide an entity tag for the selected
- representation, thereby clarifying what it applies to in various
- situations (such as a PUT response). (Section 2.3)
-
- The precedence for evaluation of conditional requests has been
- defined. (Section 6)
-
-Appendix B. Imported ABNF
-
- The following core rules are included by reference, as defined in
- Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return),
- CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double
- quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any
- 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII
- character).
-
- The rules below are defined in [RFC7230]:
-
- OWS = <OWS, see [RFC7230], Section 3.2.3>
- obs-text = <obs-text, see [RFC7230], Section 3.2.6>
-
- The rules below are defined in other parts:
-
- HTTP-date = <HTTP-date, see [RFC7231], Section 7.1.1.1>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 25]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
-Appendix C. Collected ABNF
-
- In the collected ABNF below, list rules are expanded as per Section
- 1.2 of [RFC7230].
-
- ETag = entity-tag
-
- HTTP-date = <HTTP-date, see [RFC7231], Section 7.1.1.1>
-
- If-Match = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS
- entity-tag ] ) )
- If-Modified-Since = HTTP-date
- If-None-Match = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS
- entity-tag ] ) )
- If-Unmodified-Since = HTTP-date
-
- Last-Modified = HTTP-date
-
- OWS = <OWS, see [RFC7230], Section 3.2.3>
-
- entity-tag = [ weak ] opaque-tag
- etagc = "!" / %x23-7E ; '#'-'~'
- / obs-text
-
- obs-text = <obs-text, see [RFC7230], Section 3.2.6>
- opaque-tag = DQUOTE *etagc DQUOTE
-
- weak = %x57.2F ; W/
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 26]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
-Index
-
- 3
- 304 Not Modified (status code) 19
-
- 4
- 412 Precondition Failed (status code) 18
-
- E
- ETag header field 9
-
- G
- Grammar
- entity-tag 9
- ETag 9
- etagc 9
- If-Match 13
- If-Modified-Since 15
- If-None-Match 14
- If-Unmodified-Since 17
- Last-Modified 7
- opaque-tag 9
- weak 9
-
- I
- If-Match header field 13
- If-Modified-Since header field 16
- If-None-Match header field 14
- If-Unmodified-Since header field 17
-
- L
- Last-Modified header field 7
-
- M
- metadata 5
-
- S
- selected representation 4
-
- V
- validator 5
- strong 5
- weak 5
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 27]
-\f
-RFC 7232 HTTP/1.1 Conditional Requests June 2014
-
-
-Authors' Addresses
-
- Roy T. Fielding (editor)
- Adobe Systems Incorporated
- 345 Park Ave
- San Jose, CA 95110
- USA
-
- EMail: fielding@gbiv.com
- URI: http://roy.gbiv.com/
-
-
- Julian F. Reschke (editor)
- greenbytes GmbH
- Hafenweg 16
- Muenster, NW 48155
- Germany
-
- EMail: julian.reschke@greenbytes.de
- URI: http://greenbytes.de/tech/webdav/
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 28]
-\f
+++ /dev/null
-
-
-
-
-
-
-Internet Engineering Task Force (IETF) R. Fielding, Ed.
-Request for Comments: 7233 Adobe
-Obsoletes: 2616 Y. Lafon, Ed.
-Category: Standards Track W3C
-ISSN: 2070-1721 J. Reschke, Ed.
- greenbytes
- June 2014
-
-
- Hypertext Transfer Protocol (HTTP/1.1): Range Requests
-
-Abstract
-
- The Hypertext Transfer Protocol (HTTP) is a stateless application-
- level protocol for distributed, collaborative, hypertext information
- systems. This document defines range requests and the rules for
- constructing and combining responses to those requests.
-
-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 5741.
-
- 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/rfc7233.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 1]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
-Copyright Notice
-
- Copyright (c) 2014 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.
-
- This document may contain material from IETF Documents or IETF
- Contributions published or made publicly available before November
- 10, 2008. The person(s) controlling the copyright in some of this
- material may not have granted the IETF Trust the right to allow
- modifications of such material outside the IETF Standards Process.
- Without obtaining an adequate license from the person(s) controlling
- the copyright in such materials, this document may not be modified
- outside the IETF Standards Process, and derivative works of it may
- not be created outside the IETF Standards Process, except to format
- it for publication as an RFC or to translate it into languages other
- than English.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 2]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
-Table of Contents
-
- 1. Introduction ....................................................4
- 1.1. Conformance and Error Handling .............................4
- 1.2. Syntax Notation ............................................4
- 2. Range Units .....................................................5
- 2.1. Byte Ranges ................................................5
- 2.2. Other Range Units ..........................................7
- 2.3. Accept-Ranges ..............................................7
- 3. Range Requests ..................................................8
- 3.1. Range ......................................................8
- 3.2. If-Range ...................................................9
- 4. Responses to a Range Request ...................................10
- 4.1. 206 Partial Content .......................................10
- 4.2. Content-Range .............................................12
- 4.3. Combining Ranges ..........................................14
- 4.4. 416 Range Not Satisfiable .................................15
- 5. IANA Considerations ............................................16
- 5.1. Range Unit Registry .......................................16
- 5.1.1. Procedure ..........................................16
- 5.1.2. Registrations ......................................16
- 5.2. Status Code Registration ..................................17
- 5.3. Header Field Registration .................................17
- 5.4. Internet Media Type Registration ..........................17
- 5.4.1. Internet Media Type multipart/byteranges ...........18
- 6. Security Considerations ........................................19
- 6.1. Denial-of-Service Attacks Using Range .....................19
- 7. Acknowledgments ................................................19
- 8. References .....................................................20
- 8.1. Normative References ......................................20
- 8.2. Informative References ....................................20
- Appendix A. Internet Media Type multipart/byteranges ..............21
- Appendix B. Changes from RFC 2616 .................................22
- Appendix C. Imported ABNF .........................................22
- Appendix D. Collected ABNF ........................................23
- Index .............................................................24
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 3]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
-1. Introduction
-
- Hypertext Transfer Protocol (HTTP) clients often encounter
- interrupted data transfers as a result of canceled requests or
- dropped connections. When a client has stored a partial
- representation, it is desirable to request the remainder of that
- representation in a subsequent request rather than transfer the
- entire representation. Likewise, devices with limited local storage
- might benefit from being able to request only a subset of a larger
- representation, such as a single page of a very large document, or
- the dimensions of an embedded image.
-
- This document defines HTTP/1.1 range requests, partial responses, and
- the multipart/byteranges media type. Range requests are an OPTIONAL
- feature of HTTP, designed so that recipients not implementing this
- feature (or not supporting it for the target resource) can respond as
- if it is a normal GET request without impacting interoperability.
- Partial responses are indicated by a distinct status code to not be
- mistaken for full responses by caches that might not implement the
- feature.
-
- Although the range request mechanism is designed to allow for
- extensible range types, this specification only defines requests for
- byte ranges.
-
-1.1. Conformance and Error Handling
-
- 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].
-
- Conformance criteria and considerations regarding error handling are
- defined in Section 2.5 of [RFC7230].
-
-1.2. Syntax Notation
-
- This specification uses the Augmented Backus-Naur Form (ABNF)
- notation of [RFC5234] with a list extension, defined in Section 7 of
- [RFC7230], that allows for compact definition of comma-separated
- lists using a '#' operator (similar to how the '*' operator indicates
- repetition). Appendix C describes rules imported from other
- documents. Appendix D shows the collected grammar with all list
- operators expanded to standard ABNF notation.
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 4]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
-2. Range Units
-
- A representation can be partitioned into subranges according to
- various structural units, depending on the structure inherent in the
- representation's media type. This "range unit" is used in the
- Accept-Ranges (Section 2.3) response header field to advertise
- support for range requests, the Range (Section 3.1) request header
- field to delineate the parts of a representation that are requested,
- and the Content-Range (Section 4.2) payload header field to describe
- which part of a representation is being transferred.
-
- range-unit = bytes-unit / other-range-unit
-
-2.1. Byte Ranges
-
- Since representation data is transferred in payloads as a sequence of
- octets, a byte range is a meaningful substructure for any
- representation transferable over HTTP (Section 3 of [RFC7231]). The
- "bytes" range unit is defined for expressing subranges of the data's
- octet sequence.
-
- bytes-unit = "bytes"
-
- A byte-range request can specify a single range of bytes or a set of
- ranges within a single representation.
-
- 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.
-
- Examples of byte-ranges-specifier values:
-
- o The first 500 bytes (byte offsets 0-499, inclusive):
-
- bytes=0-499
-
- o The second 500 bytes (byte offsets 500-999, inclusive):
-
- bytes=500-999
-
-
-
-
-
-Fielding, et al. Standards Track [Page 5]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
- A byte-range-spec is invalid if the last-byte-pos value is present
- and less than the first-byte-pos.
-
- A client can limit the number of bytes requested without knowing the
- size of the selected representation. If the last-byte-pos value is
- absent, or if the value is greater than or equal to the current
- length of the representation data, the byte range is interpreted as
- the remainder of the representation (i.e., the server replaces the
- value of last-byte-pos with a value that is one less than the current
- length of the selected representation).
-
- A client can request the last N bytes of the selected representation
- using a suffix-byte-range-spec.
-
- suffix-byte-range-spec = "-" suffix-length
- suffix-length = 1*DIGIT
-
- If the selected representation is shorter than the specified
- suffix-length, the entire representation is used.
-
- Additional examples, assuming a representation of length 10000:
-
- o The final 500 bytes (byte offsets 9500-9999, inclusive):
-
- bytes=-500
-
- Or:
-
- bytes=9500-
-
- o The first and last bytes only (bytes 0 and 9999):
-
- bytes=0-0,-1
-
- o Other valid (but not canonical) specifications of the second 500
- bytes (byte offsets 500-999, inclusive):
-
- bytes=500-600,601-999
- bytes=500-700,601-999
-
- If a valid byte-range-set includes at least one byte-range-spec with
- a first-byte-pos that is less than the current length of the
- representation, 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.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 6]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
- In the byte-range syntax, first-byte-pos, last-byte-pos, and
- suffix-length are expressed as decimal number of octets. Since there
- is no predefined limit to the length of a payload, recipients MUST
- anticipate potentially large decimal numerals and prevent parsing
- errors due to integer conversion overflows.
-
-2.2. Other Range Units
-
- Range units are intended to be extensible. New range units ought to
- be registered with IANA, as defined in Section 5.1.
-
- other-range-unit = token
-
-2.3. Accept-Ranges
-
- The "Accept-Ranges" header field allows a server to indicate that it
- supports range requests for the target resource.
-
- Accept-Ranges = acceptable-ranges
- acceptable-ranges = 1#range-unit / "none"
-
- An origin server that supports byte-range requests for a given target
- resource MAY send
-
- Accept-Ranges: bytes
-
- to indicate what range units are supported. A client MAY generate
- range requests without having received this header field for the
- resource involved. Range units are defined in Section 2.
-
- A server that does not support any kind of range request for the
- target resource MAY send
-
- Accept-Ranges: none
-
- to advise the client not to attempt a range request.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 7]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
-3. Range Requests
-
-3.1. Range
-
- The "Range" header field on a GET request modifies the method
- semantics to request transfer of only one or more subranges of the
- selected representation data, rather than the entire selected
- representation data.
-
- Range = byte-ranges-specifier / other-ranges-specifier
- other-ranges-specifier = other-range-unit "=" other-range-set
- other-range-set = 1*VCHAR
-
- A server MAY ignore the Range header field. However, origin servers
- and intermediate caches ought to support byte ranges when possible,
- since Range supports efficient recovery from partially failed
- transfers and partial retrieval of large representations. A server
- MUST ignore a Range header field received with a request method other
- than GET.
-
- An origin server MUST ignore a Range header field that contains a
- range unit it does not understand. A proxy MAY discard a Range
- header field that contains a range unit it does not understand.
-
- A server that supports range requests MAY ignore or reject a Range
- header field that consists of more than two overlapping ranges, or a
- set of many small ranges that are not listed in ascending order,
- since both are indications of either a broken client or a deliberate
- denial-of-service attack (Section 6.1). A client SHOULD NOT request
- multiple ranges that are inherently less efficient to process and
- transfer than a single range that encompasses the same data.
-
- A client that is requesting multiple ranges SHOULD list those ranges
- in ascending order (the order in which they would typically be
- received in a complete representation) unless there is a specific
- need to request a later part earlier. For example, a user agent
- processing a large representation with an internal catalog of parts
- might need to request later parts first, particularly if the
- representation consists of pages stored in reverse order and the user
- agent wishes to transfer one page at a time.
-
- The Range header field is evaluated after evaluating the precondition
- header fields defined in [RFC7232], and only if the result in absence
- of the Range header field would be a 200 (OK) response. In other
- words, Range is ignored when a conditional GET would result in a 304
- (Not Modified) response.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 8]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
- The If-Range header field (Section 3.2) can be used as a precondition
- to applying the Range header field.
-
- If all of the preconditions are true, the server supports the Range
- header field for the target resource, and the specified range(s) are
- valid and satisfiable (as defined in Section 2.1), the server SHOULD
- send a 206 (Partial Content) response with a payload containing one
- or more partial representations that correspond to the satisfiable
- ranges requested, as defined in Section 4.
-
- If all of the preconditions are true, the server supports the Range
- header field for the target resource, and the specified range(s) are
- invalid or unsatisfiable, the server SHOULD send a 416 (Range Not
- Satisfiable) response.
-
-3.2. If-Range
-
- If a client has a partial copy of a representation and wishes to have
- an up-to-date copy of the entire representation, it could use the
- Range header field with a conditional GET (using either or both of
- If-Unmodified-Since and If-Match.) However, if the precondition
- fails because the representation has been modified, the client would
- then have to make a second request to obtain the entire current
- representation.
-
- The "If-Range" header field allows a client to "short-circuit" the
- second request. Informally, its meaning is as follows: if the
- representation is unchanged, send me the part(s) that I am requesting
- in Range; otherwise, send me the entire representation.
-
- If-Range = entity-tag / HTTP-date
-
- A client MUST NOT generate an If-Range header field in a request that
- does not contain a Range header field. A server MUST ignore an
- If-Range header field received in a request that does not contain a
- Range header field. An origin server MUST ignore an If-Range header
- field received in a request for a target resource that does not
- support Range requests.
-
- A client MUST NOT generate an If-Range header field containing an
- entity-tag that is marked as weak. A client MUST NOT generate an
- If-Range header field containing an HTTP-date unless the client has
- no entity-tag for the corresponding representation and the date is a
- strong validator in the sense defined by Section 2.2.2 of [RFC7232].
-
- A server that evaluates an If-Range precondition MUST use the strong
- comparison function when comparing entity-tags (Section 2.3.2 of
- [RFC7232]) and MUST evaluate the condition as false if an HTTP-date
-
-
-
-Fielding, et al. Standards Track [Page 9]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
- validator is provided that is not a strong validator in the sense
- defined by Section 2.2.2 of [RFC7232]. A valid entity-tag can be
- distinguished from a valid HTTP-date by examining the first two
- characters for a DQUOTE.
-
- If the validator given in the If-Range header field matches the
- current validator for the selected representation of the target
- resource, then the server SHOULD process the Range header field as
- requested. If the validator does not match, the server MUST ignore
- the Range header field. Note that this comparison by exact match,
- including when the validator is an HTTP-date, differs from the
- "earlier than or equal to" comparison used when evaluating an
- If-Unmodified-Since conditional.
-
-4. Responses to a Range Request
-
-4.1. 206 Partial Content
-
- The 206 (Partial Content) status code indicates that the server is
- successfully fulfilling a range request for the target resource by
- transferring one or more parts of the selected representation that
- correspond to the satisfiable ranges found in the request's Range
- header field (Section 3.1).
-
- If a single part is being transferred, the server generating the 206
- response MUST generate a Content-Range header field, describing what
- range of the selected representation is enclosed, and a payload
- consisting of the range. 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
-
- ... 26012 bytes of partial image data ...
-
- If multiple parts are being transferred, the server generating the
- 206 response MUST generate a "multipart/byteranges" payload, as
- defined in Appendix A, and a Content-Type header field containing the
- multipart/byteranges media type and its required boundary parameter.
- To avoid confusion with single-part responses, a server MUST NOT
- generate a Content-Range header field in the HTTP header section of a
- multiple part response (this field will be sent in each part
- instead).
-
-
-
-
-
-Fielding, et al. Standards Track [Page 10]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
- Within the header area of each body part in the multipart payload,
- the server MUST generate a Content-Range header field corresponding
- to the range being enclosed in that body part. If the selected
- representation would have had a Content-Type header field in a 200
- (OK) response, the server SHOULD generate that same Content-Type
- field in the header area of each body part. 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-Length: 1741
- 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--
-
- When multiple ranges are requested, a server MAY coalesce any of the
- ranges that overlap, or that are separated by a gap that is smaller
- than the overhead of sending multiple parts, regardless of the order
- in which the corresponding byte-range-spec appeared in the received
- Range header field. Since the typical overhead between parts of a
- multipart/byteranges payload is around 80 bytes, depending on the
- selected representation's media type and the chosen boundary
- parameter length, it can be less efficient to transfer many small
- disjoint parts than it is to transfer the entire selected
- representation.
-
- A server MUST NOT generate a multipart response to a request for a
- single range, since a client that does not request multiple parts
- might not support multipart responses. However, a server MAY
- generate a multipart/byteranges payload with only a single body part
- if multiple ranges were requested and only one range was found to be
- satisfiable or only one range remained after coalescing. A client
- that cannot process a multipart/byteranges response MUST NOT generate
- a request that asks for multiple ranges.
-
- When a multipart response payload is generated, the server SHOULD
- send the parts in the same order that the corresponding
- byte-range-spec appeared in the received Range header field,
-
-
-
-Fielding, et al. Standards Track [Page 11]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
- excluding those ranges that were deemed unsatisfiable or that were
- coalesced into other ranges. A client that receives a multipart
- response MUST inspect the Content-Range header field present in each
- body part in order to determine which range is contained in that body
- part; a client cannot rely on receiving the same ranges that it
- requested, nor the same order that it requested.
-
- When a 206 response is generated, the server MUST generate the
- following header fields, in addition to those required above, if the
- field would have been sent in a 200 (OK) response to the same
- request: Date, Cache-Control, ETag, Expires, Content-Location, and
- Vary.
-
- If a 206 is generated in response to a request with an If-Range
- header field, the sender SHOULD NOT generate other representation
- header fields beyond those required above, because the client is
- understood to already have a prior response containing those header
- fields. Otherwise, the sender MUST generate all of the
- representation header fields that would have been sent in a 200 (OK)
- response to the same request.
-
- A 206 response is cacheable by default; i.e., unless otherwise
- indicated by explicit cache controls (see Section 4.2.2 of
- [RFC7234]).
-
-4.2. Content-Range
-
- The "Content-Range" header field is sent in a single part 206
- (Partial Content) response to indicate the partial range of the
- selected representation enclosed as the message payload, sent in each
- part of a multipart 206 response to indicate the range enclosed
- within each body part, and sent in 416 (Range Not Satisfiable)
- responses to provide information about the selected representation.
-
- Content-Range = byte-content-range
- / other-content-range
-
- byte-content-range = bytes-unit SP
- ( byte-range-resp / unsatisfied-range )
-
- byte-range-resp = byte-range "/" ( complete-length / "*" )
- byte-range = first-byte-pos "-" last-byte-pos
- unsatisfied-range = "*/" complete-length
-
- complete-length = 1*DIGIT
-
- other-content-range = other-range-unit SP other-range-resp
- other-range-resp = *CHAR
-
-
-
-Fielding, et al. Standards Track [Page 12]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
- If a 206 (Partial Content) response contains a Content-Range header
- field with a range unit (Section 2) that the recipient does not
- understand, the recipient MUST NOT attempt to recombine it with a
- stored representation. A proxy that receives such a message SHOULD
- forward it downstream.
-
- For byte ranges, a sender SHOULD indicate the complete length of the
- representation from which the range has been extracted, unless the
- complete length is unknown or difficult to determine. An asterisk
- character ("*") in place of the complete-length indicates that the
- representation length was unknown when the header field was
- generated.
-
- The following example illustrates when the complete length of the
- selected representation is known by the sender to be 1234 bytes:
-
- Content-Range: bytes 42-1233/1234
-
- and this second example illustrates when the complete length is
- unknown:
-
- Content-Range: bytes 42-1233/*
-
- A Content-Range field value is invalid if it contains a
- byte-range-resp that has a last-byte-pos value less than its
- first-byte-pos value, or a complete-length value less than or equal
- to its last-byte-pos value. The recipient of an invalid
- Content-Range MUST NOT attempt to recombine the received content with
- a stored representation.
-
- A server generating a 416 (Range Not Satisfiable) response to a
- byte-range request SHOULD send a Content-Range header field with an
- unsatisfied-range value, as in the following example:
-
- Content-Range: bytes */1234
-
- The complete-length in a 416 response indicates the current length of
- the selected representation.
-
- The Content-Range header field has no meaning for status codes that
- do not explicitly describe its semantic. For this specification,
- only the 206 (Partial Content) and 416 (Range Not Satisfiable) status
- codes describe a meaning for Content-Range.
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 13]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
- The following are examples of Content-Range values in which the
- selected representation contains a total of 1234 bytes:
-
- o The first 500 bytes:
-
- Content-Range: bytes 0-499/1234
-
- o The second 500 bytes:
-
- Content-Range: bytes 500-999/1234
-
- o All except for the first 500 bytes:
-
- Content-Range: bytes 500-1233/1234
-
- o The last 500 bytes:
-
- Content-Range: bytes 734-1233/1234
-
-4.3. Combining Ranges
-
- A response might transfer only a subrange of a representation if the
- connection closed prematurely or if the request used one or more
- Range specifications. After several such transfers, a client might
- have received several ranges of the same representation. These
- ranges can only be safely combined if they all have in common the
- same strong validator (Section 2.1 of [RFC7232]).
-
- A client that has received multiple partial responses to GET requests
- on a target resource MAY combine those responses into a larger
- continuous range if they share the same strong validator.
-
- If the most recent response is an incomplete 200 (OK) response, then
- the header fields of that response are used for any combined response
- and replace those of the matching stored responses.
-
- If the most recent response is a 206 (Partial Content) response and
- at least one of the matching stored responses is a 200 (OK), then the
- combined response header fields consist of the most recent 200
- response's header fields. If all of the matching stored responses
- are 206 responses, then the stored response with the most recent
- header fields is used as the source of header fields for the combined
- response, except that the client MUST use other header fields
- provided in the new response, aside from Content-Range, to replace
- all instances of the corresponding header fields in the stored
- response.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 14]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
- The combined response message body consists of the union of partial
- content ranges in the new response and each of the selected
- responses. If the union consists of the entire range of the
- representation, then the client MUST process the combined response as
- if it were a complete 200 (OK) response, including a Content-Length
- header field that reflects the complete length. Otherwise, the
- client MUST process the set of continuous ranges as one of the
- following: an incomplete 200 (OK) response if the combined response
- is a prefix of the representation, a single 206 (Partial Content)
- response containing a multipart/byteranges body, or multiple 206
- (Partial Content) responses, each with one continuous range that is
- indicated by a Content-Range header field.
-
-4.4. 416 Range Not Satisfiable
-
- The 416 (Range Not Satisfiable) status code indicates that none of
- the ranges in the request's Range header field (Section 3.1) overlap
- the current extent of the selected resource or that the set of ranges
- requested has been rejected due to invalid ranges or an excessive
- request of small or overlapping ranges.
-
- For byte ranges, failing to overlap the current extent means that the
- first-byte-pos of all of the byte-range-spec values were greater than
- the current length of the selected representation. When this status
- code is generated in response to a byte-range request, the sender
- SHOULD generate a Content-Range header field specifying the current
- length of the selected representation (Section 4.2).
-
- For example:
-
- HTTP/1.1 416 Range Not Satisfiable
- Date: Fri, 20 Jan 2012 15:41:54 GMT
- Content-Range: bytes */47022
-
- Note: Because servers are free to ignore Range, many
- implementations will simply respond with the entire selected
- representation in a 200 (OK) response. That is partly because
- most clients are prepared to receive a 200 (OK) to complete the
- task (albeit less efficiently) and partly because clients might
- not stop making an invalid partial request until they have
- received a complete representation. Thus, clients cannot depend
- on receiving a 416 (Range Not Satisfiable) response even when it
- is most appropriate.
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 15]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
-5. IANA Considerations
-
-5.1. Range Unit Registry
-
- The "HTTP Range Unit Registry" defines the namespace for the range
- unit names and refers to their corresponding specifications. The
- registry has been created and is now maintained at
- <http://www.iana.org/assignments/http-parameters>.
-
-5.1.1. Procedure
-
- Registration of an HTTP Range Unit MUST include the following fields:
-
- o Name
-
- o Description
-
- o Pointer to specification text
-
- Values to be added to this namespace require IETF Review (see
- [RFC5226], Section 4.1).
-
-5.1.2. Registrations
-
- The initial range unit registry contains the registrations below:
-
- +-------------+---------------------------------------+-------------+
- | Range Unit | Description | Reference |
- | Name | | |
- +-------------+---------------------------------------+-------------+
- | bytes | a range of octets | Section 2.1 |
- | none | reserved as keyword, indicating no | Section 2.3 |
- | | ranges are supported | |
- +-------------+---------------------------------------+-------------+
-
- The change controller is: "IETF (iesg@ietf.org) - Internet
- Engineering Task Force".
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 16]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
-5.2. Status Code Registration
-
- The "Hypertext Transfer Protocol (HTTP) Status Code Registry" located
- at <http://www.iana.org/assignments/http-status-codes> has been
- updated to include the registrations below:
-
- +-------+-----------------------+-------------+
- | Value | Description | Reference |
- +-------+-----------------------+-------------+
- | 206 | Partial Content | Section 4.1 |
- | 416 | Range Not Satisfiable | Section 4.4 |
- +-------+-----------------------+-------------+
-
-5.3. Header Field Registration
-
- HTTP header fields are registered within the "Message Headers"
- registry maintained at
- <http://www.iana.org/assignments/message-headers/>.
-
- This document defines the following HTTP header fields, so their
- associated registry entries have been updated according to the
- permanent registrations below (see [BCP90]):
-
- +-------------------+----------+----------+-------------+
- | Header Field Name | Protocol | Status | Reference |
- +-------------------+----------+----------+-------------+
- | Accept-Ranges | http | standard | Section 2.3 |
- | Content-Range | http | standard | Section 4.2 |
- | If-Range | http | standard | Section 3.2 |
- | Range | http | standard | Section 3.1 |
- +-------------------+----------+----------+-------------+
-
- The change controller is: "IETF (iesg@ietf.org) - Internet
- Engineering Task Force".
-
-5.4. Internet Media Type Registration
-
- IANA maintains the registry of Internet media types [BCP13] at
- <http://www.iana.org/assignments/media-types>.
-
- This document serves as the specification for the Internet media type
- "multipart/byteranges". The following has been registered with IANA.
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 17]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
-5.4.1. Internet Media Type multipart/byteranges
-
- Type name: multipart
-
- Subtype name: byteranges
-
- Required parameters: boundary
-
- Optional parameters: N/A
-
- Encoding considerations: only "7bit", "8bit", or "binary" are
- permitted
-
- Security considerations: see Section 6
-
- Interoperability considerations: N/A
-
- Published specification: This specification (see Appendix A).
-
- Applications that use this media type: HTTP components supporting
- multiple ranges in a single request.
-
- Fragment identifier considerations: N/A
-
- Additional information:
-
- Deprecated alias names for this type: N/A
-
- Magic number(s): N/A
-
- File extension(s): N/A
-
- Macintosh file type code(s): N/A
-
- Person and email address to contact for further information: See
- Authors' Addresses section.
-
- Intended usage: COMMON
-
- Restrictions on usage: N/A
-
- Author: See Authors' Addresses section.
-
- Change controller: IESG
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 18]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
-6. Security Considerations
-
- This section is meant to inform developers, information providers,
- and users of known security concerns specific to the HTTP range
- request mechanisms. More general security considerations are
- addressed in HTTP messaging [RFC7230] and semantics [RFC7231].
-
-6.1. Denial-of-Service Attacks Using Range
-
- Unconstrained multiple range requests are susceptible to denial-of-
- service attacks because the effort required to request many
- overlapping ranges of the same data is tiny compared to the time,
- memory, and bandwidth consumed by attempting to serve the requested
- data in many parts. Servers ought to ignore, coalesce, or reject
- egregious range requests, such as requests for more than two
- overlapping ranges or for many small ranges in a single set,
- particularly when the ranges are requested out of order for no
- apparent reason. Multipart range requests are not designed to
- support random access.
-
-7. Acknowledgments
-
- See Section 10 of [RFC7230].
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 19]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
-8. References
-
-8.1. Normative References
-
- [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part Two: Media Types", RFC 2046,
- November 1996.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", STD 68, RFC 5234, January 2008.
-
- [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Message Syntax and Routing",
- RFC 7230, June 2014.
-
- [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
- June 2014.
-
- [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Conditional Requests", RFC 7232,
- June 2014.
-
- [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
- Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
- RFC 7234, June 2014.
-
-8.2. Informative References
-
- [BCP13] Freed, N., Klensin, J., and T. Hansen, "Media Type
- Specifications and Registration Procedures", BCP 13,
- RFC 6838, January 2013.
-
- [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration
- Procedures for Message Header Fields", BCP 90, RFC 3864,
- September 2004.
-
- [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.
-
- [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
- IANA Considerations Section in RFCs", BCP 26, RFC 5226,
- May 2008.
-
-
-
-
-Fielding, et al. Standards Track [Page 20]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
-Appendix A. Internet Media Type multipart/byteranges
-
- When a 206 (Partial Content) response message includes the content of
- multiple ranges, they are transmitted as body parts in a multipart
- message body ([RFC2046], Section 5.1) with the media type of
- "multipart/byteranges".
-
- The multipart/byteranges media type includes one or more body 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.
-
- Implementation Notes:
-
- 1. Additional CRLFs might precede the first boundary string in the
- body.
-
- 2. Although [RFC2046] permits the boundary string to be quoted, some
- existing implementations handle a quoted boundary string
- incorrectly.
-
- 3. A number of clients and servers were coded to an early draft of
- the byteranges specification that used a media type of multipart/
- x-byteranges, which is almost (but not quite) compatible with
- this type.
-
- Despite the name, the "multipart/byteranges" media type is not
- limited to byte ranges. The following example uses an "exampleunit"
- range unit:
-
- HTTP/1.1 206 Partial Content
- Date: Tue, 14 Nov 1995 06:25:24 GMT
- Last-Modified: Tue, 14 July 04:58:08 GMT
- Content-Length: 2331785
- Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES
-
- --THIS_STRING_SEPARATES
- Content-Type: video/example
- Content-Range: exampleunit 1.2-4.3/25
-
- ...the first range...
- --THIS_STRING_SEPARATES
- Content-Type: video/example
- Content-Range: exampleunit 11.2-14.3/25
-
- ...the second range
- --THIS_STRING_SEPARATES--
-
-
-
-
-Fielding, et al. Standards Track [Page 21]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
-Appendix B. Changes from RFC 2616
-
- Servers are given more leeway in how they respond to a range request,
- in order to mitigate abuse by malicious (or just greedy) clients.
- (Section 3.1)
-
- A weak validator cannot be used in a 206 response. (Section 4.1)
-
- The Content-Range header field only has meaning when the status code
- explicitly defines its use. (Section 4.2)
-
- This specification introduces a Range Unit Registry. (Section 5.1)
-
- multipart/byteranges can consist of a single part. (Appendix A)
-
-Appendix C. Imported ABNF
-
- The following core rules are included by reference, as defined in
- Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return),
- CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double
- quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any
- 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII
- character).
-
- Note that all rules derived from token are to be compared
- case-insensitively, like range-unit and acceptable-ranges.
-
- The rules below are defined in [RFC7230]:
-
- OWS = <OWS, see [RFC7230], Section 3.2.3>
- token = <token, see [RFC7230], Section 3.2.6>
-
- The rules below are defined in other parts:
-
- HTTP-date = <HTTP-date, see [RFC7231], Section 7.1.1.1>
- entity-tag = <entity-tag, see [RFC7232], Section 2.3>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 22]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
-Appendix D. Collected ABNF
-
- In the collected ABNF below, list rules are expanded as per Section
- 1.2 of [RFC7230].
-
- Accept-Ranges = acceptable-ranges
-
- Content-Range = byte-content-range / other-content-range
-
- HTTP-date = <HTTP-date, see [RFC7231], Section 7.1.1.1>
-
- If-Range = entity-tag / HTTP-date
-
- OWS = <OWS, see [RFC7230], Section 3.2.3>
-
- Range = byte-ranges-specifier / other-ranges-specifier
-
- acceptable-ranges = ( *( "," OWS ) range-unit *( OWS "," [ OWS
- range-unit ] ) ) / "none"
-
- byte-content-range = bytes-unit SP ( byte-range-resp /
- unsatisfied-range )
- byte-range = first-byte-pos "-" last-byte-pos
- byte-range-resp = byte-range "/" ( complete-length / "*" )
- byte-range-set = *( "," OWS ) ( byte-range-spec /
- suffix-byte-range-spec ) *( OWS "," [ OWS ( byte-range-spec /
- suffix-byte-range-spec ) ] )
- byte-range-spec = first-byte-pos "-" [ last-byte-pos ]
- byte-ranges-specifier = bytes-unit "=" byte-range-set
- bytes-unit = "bytes"
-
- complete-length = 1*DIGIT
-
- entity-tag = <entity-tag, see [RFC7232], Section 2.3>
-
- first-byte-pos = 1*DIGIT
-
- last-byte-pos = 1*DIGIT
-
- other-content-range = other-range-unit SP other-range-resp
- other-range-resp = *CHAR
- other-range-set = 1*VCHAR
- other-range-unit = token
- other-ranges-specifier = other-range-unit "=" other-range-set
-
- range-unit = bytes-unit / other-range-unit
-
- suffix-byte-range-spec = "-" suffix-length
-
-
-
-Fielding, et al. Standards Track [Page 23]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
- suffix-length = 1*DIGIT
-
- token = <token, see [RFC7230], Section 3.2.6>
-
- unsatisfied-range = "*/" complete-length
-
-Index
-
- 2
- 206 Partial Content (status code) 10
-
- 4
- 416 Range Not Satisfiable (status code) 15
-
- A
- Accept-Ranges header field 7
-
- C
- Content-Range header field 12
-
- G
- Grammar
- Accept-Ranges 7
- acceptable-ranges 7
- byte-content-range 12
- byte-range 12
- byte-range-resp 12
- byte-range-set 5
- byte-range-spec 5
- byte-ranges-specifier 5
- bytes-unit 5
- complete-length 12
- Content-Range 12
- first-byte-pos 5
- If-Range 9
- last-byte-pos 5
- other-content-range 12
- other-range-resp 12
- other-range-unit 5, 7
- Range 8
- range-unit 5
- ranges-specifier 5
- suffix-byte-range-spec 6
- suffix-length 6
- unsatisfied-range 12
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 24]
-\f
-RFC 7233 HTTP/1.1 Range Requests June 2014
-
-
- I
- If-Range header field 9
-
- M
- Media Type
- multipart/byteranges 18, 21
- multipart/x-byteranges 19
- multipart/byteranges Media Type 18, 21
- multipart/x-byteranges Media Type 21
-
- R
- Range header field 8
-
-Authors' Addresses
-
- Roy T. Fielding (editor)
- Adobe Systems Incorporated
- 345 Park Ave
- San Jose, CA 95110
- USA
-
- EMail: fielding@gbiv.com
- URI: http://roy.gbiv.com/
-
-
- Yves Lafon (editor)
- World Wide Web Consortium
- W3C / ERCIM
- 2004, rte des Lucioles
- Sophia-Antipolis, AM 06902
- France
-
- EMail: ylafon@w3.org
- URI: http://www.raubacapeu.net/people/yves/
-
-
- Julian F. Reschke (editor)
- greenbytes GmbH
- Hafenweg 16
- Muenster, NW 48155
- Germany
-
- EMail: julian.reschke@greenbytes.de
- URI: http://greenbytes.de/tech/webdav/
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 25]
-\f
+++ /dev/null
-
-
-
-
-
-
-Internet Engineering Task Force (IETF) R. Fielding, Ed.
-Request for Comments: 7234 Adobe
-Obsoletes: 2616 M. Nottingham, Ed.
-Category: Standards Track Akamai
-ISSN: 2070-1721 J. Reschke, Ed.
- greenbytes
- June 2014
-
-
- Hypertext Transfer Protocol (HTTP/1.1): Caching
-
-Abstract
-
- The Hypertext Transfer Protocol (HTTP) is a stateless application-
- level protocol for distributed, collaborative, hypertext information
- systems. This document defines HTTP caches and the associated header
- fields that control cache behavior or indicate cacheable response
- messages.
-
-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 5741.
-
- 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/rfc7234.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 1]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
-Copyright Notice
-
- Copyright (c) 2014 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.
-
- This document may contain material from IETF Documents or IETF
- Contributions published or made publicly available before November
- 10, 2008. The person(s) controlling the copyright in some of this
- material may not have granted the IETF Trust the right to allow
- modifications of such material outside the IETF Standards Process.
- Without obtaining an adequate license from the person(s) controlling
- the copyright in such materials, this document may not be modified
- outside the IETF Standards Process, and derivative works of it may
- not be created outside the IETF Standards Process, except to format
- it for publication as an RFC or to translate it into languages other
- than English.
-
-Table of Contents
-
- 1. Introduction ....................................................4
- 1.1. Conformance and Error Handling .............................4
- 1.2. Syntax Notation ............................................4
- 1.2.1. Delta Seconds .......................................5
- 2. Overview of Cache Operation .....................................5
- 3. Storing Responses in Caches .....................................6
- 3.1. Storing Incomplete Responses ...............................7
- 3.2. Storing Responses to Authenticated Requests ................7
- 3.3. Combining Partial Content ..................................8
- 4. Constructing Responses from Caches ..............................8
- 4.1. Calculating Secondary Keys with Vary .......................9
- 4.2. Freshness .................................................11
- 4.2.1. Calculating Freshness Lifetime .....................12
- 4.2.2. Calculating Heuristic Freshness ....................13
- 4.2.3. Calculating Age ....................................13
- 4.2.4. Serving Stale Responses ............................15
- 4.3. Validation ................................................16
- 4.3.1. Sending a Validation Request .......................16
- 4.3.2. Handling a Received Validation Request .............16
-
-
-
-Fielding, et al. Standards Track [Page 2]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- 4.3.3. Handling a Validation Response .....................18
- 4.3.4. Freshening Stored Responses upon Validation ........18
- 4.3.5. Freshening Responses via HEAD ......................19
- 4.4. Invalidation ..............................................20
- 5. Header Field Definitions .......................................21
- 5.1. Age .......................................................21
- 5.2. Cache-Control .............................................21
- 5.2.1. Request Cache-Control Directives ...................22
- 5.2.2. Response Cache-Control Directives ..................24
- 5.2.3. Cache Control Extensions ...........................27
- 5.3. Expires ...................................................28
- 5.4. Pragma ....................................................29
- 5.5. Warning ...................................................29
- 5.5.1. Warning: 110 - "Response is Stale" .................31
- 5.5.2. Warning: 111 - "Revalidation Failed" ...............31
- 5.5.3. Warning: 112 - "Disconnected Operation" ............31
- 5.5.4. Warning: 113 - "Heuristic Expiration" ..............31
- 5.5.5. Warning: 199 - "Miscellaneous Warning" .............32
- 5.5.6. Warning: 214 - "Transformation Applied" ............32
- 5.5.7. Warning: 299 - "Miscellaneous Persistent Warning" ..32
- 6. History Lists ..................................................32
- 7. IANA Considerations ............................................32
- 7.1. Cache Directive Registry ..................................32
- 7.1.1. Procedure ..........................................32
- 7.1.2. Considerations for New Cache Control Directives ....33
- 7.1.3. Registrations ......................................33
- 7.2. Warn Code Registry ........................................34
- 7.2.1. Procedure ..........................................34
- 7.2.2. Registrations ......................................34
- 7.3. Header Field Registration .................................34
- 8. Security Considerations ........................................35
- 9. Acknowledgments ................................................36
- 10. References ....................................................36
- 10.1. Normative References .....................................36
- 10.2. Informative References ...................................37
- Appendix A. Changes from RFC 2616 .................................38
- Appendix B. Imported ABNF .........................................39
- Appendix C. Collected ABNF ........................................39
- Index .............................................................41
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 3]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
-1. Introduction
-
- HTTP is typically used for distributed information systems, where
- performance can be improved by the use of response caches. This
- document defines aspects of HTTP/1.1 related to caching and reusing
- response messages.
-
- An HTTP cache is a local store of response messages and the subsystem
- that controls storage, retrieval, and deletion of messages in it. 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 employ a cache, though a cache cannot be
- used by a server that is acting as a tunnel.
-
- A shared cache is a cache that stores responses to be reused by more
- than one user; shared caches are usually (but not always) deployed as
- a part of an intermediary. A private cache, in contrast, is
- dedicated to a single user; often, they are deployed as a component
- of a user agent.
-
- The goal of caching in HTTP/1.1 is to significantly improve
- performance by reusing a prior response message to satisfy a current
- request. A stored response is considered "fresh", as defined in
- Section 4.2, if the response can be reused without "validation"
- (checking with the origin server to see if the cached response
- remains valid for this request). A fresh response can therefore
- reduce both latency and network overhead each time it is reused.
- When a cached response is not fresh, it might still be reusable if it
- can be freshened by validation (Section 4.3) or if the origin is
- unavailable (Section 4.2.4).
-
-1.1. Conformance and Error Handling
-
- 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].
-
- Conformance criteria and considerations regarding error handling are
- defined in Section 2.5 of [RFC7230].
-
-1.2. Syntax Notation
-
- This specification uses the Augmented Backus-Naur Form (ABNF)
- notation of [RFC5234] with a list extension, defined in Section 7 of
- [RFC7230], that allows for compact definition of comma-separated
- lists using a '#' operator (similar to how the '*' operator indicates
-
-
-
-
-
-Fielding, et al. Standards Track [Page 4]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- repetition). Appendix B describes rules imported from other
- documents. Appendix C shows the collected grammar with all list
- operators expanded to standard ABNF notation.
-
-1.2.1. Delta Seconds
-
- The delta-seconds rule specifies a non-negative integer, representing
- time in seconds.
-
- delta-seconds = 1*DIGIT
-
- A recipient parsing a delta-seconds value and converting it to binary
- form ought to use an arithmetic type of at least 31 bits of
- non-negative integer range. If a cache receives a delta-seconds
- value greater than the greatest integer it can represent, or if any
- of its subsequent calculations overflows, the cache MUST consider the
- value to be either 2147483648 (2^31) or the greatest positive integer
- it can conveniently represent.
-
- Note: The value 2147483648 is here for historical reasons,
- effectively represents infinity (over 68 years), and does not need
- to be stored in binary form; an implementation could produce it as
- a canned string if any overflow occurs, even if the calculations
- are performed with an arithmetic type incapable of directly
- representing that number. What matters here is that an overflow
- be detected and not treated as a negative value in later
- calculations.
-
-2. Overview of Cache Operation
-
- Proper cache operation preserves the semantics of HTTP transfers
- ([RFC7231]) while eliminating the transfer of information already
- held in the cache. Although caching is an entirely OPTIONAL feature
- of HTTP, it can be assumed that reusing a cached response is
- desirable and that such reuse is the default behavior when no
- requirement or local configuration prevents it. Therefore, HTTP
- cache requirements are focused on preventing a cache from either
- storing a non-reusable response or reusing a stored response
- inappropriately, rather than mandating that caches always store and
- reuse particular responses.
-
- Each cache entry consists of a cache key and one or more HTTP
- responses corresponding to prior requests that used the same key.
- The most common form of cache entry is a successful result of a
- retrieval request: i.e., a 200 (OK) response to a GET request, which
- contains a representation of the resource identified by the request
- target (Section 4.3.1 of [RFC7231]). However, it is also possible to
- cache permanent redirects, negative results (e.g., 404 (Not Found)),
-
-
-
-Fielding, et al. Standards Track [Page 5]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- incomplete results (e.g., 206 (Partial Content)), and responses to
- methods other than GET if the method's definition allows such caching
- and defines something suitable for use as a cache key.
-
- The primary cache key consists of the request method and target URI.
- However, since HTTP caches in common use today are typically limited
- to caching responses to GET, many caches simply decline other methods
- and use only the URI as the primary cache key.
-
- If a request target is subject to content negotiation, its cache
- entry might consist of multiple stored responses, each differentiated
- by a secondary key for the values of the original request's selecting
- header fields (Section 4.1).
-
-3. Storing Responses in Caches
-
- A cache MUST NOT store a response to any request, unless:
-
- o The request method is understood by the cache and defined as being
- cacheable, and
-
- o the response status code is understood by the cache, and
-
- o the "no-store" cache directive (see Section 5.2) does not appear
- in request or response header fields, and
-
- o the "private" response directive (see Section 5.2.2.6) does not
- appear in the response, if the cache is shared, and
-
- o the Authorization header field (see Section 4.2 of [RFC7235]) does
- not appear in the request, if the cache is shared, unless the
- response explicitly allows it (see Section 3.2), and
-
- o the response either:
-
- * contains an Expires header field (see Section 5.3), or
-
- * contains a max-age response directive (see Section 5.2.2.8), or
-
- * contains a s-maxage response directive (see Section 5.2.2.9)
- and the cache is shared, or
-
- * contains a Cache Control Extension (see Section 5.2.3) that
- allows it to be cached, or
-
- * has a status code that is defined as cacheable by default (see
- Section 4.2.2), or
-
-
-
-
-Fielding, et al. Standards Track [Page 6]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- * contains a public response directive (see Section 5.2.2.5).
-
- Note that any of the requirements listed above can be overridden by a
- cache-control extension; see Section 5.2.3.
-
- In this context, a cache has "understood" a request method or a
- response status code if it recognizes it and implements all specified
- caching-related behavior.
-
- Note that, in normal operation, some caches will not store a response
- that has neither a cache validator nor an explicit expiration time,
- as such responses are not usually useful to store. However, caches
- are not prohibited from storing such responses.
-
-3.1. Storing Incomplete Responses
-
- A response message is considered complete when all of the octets
- indicated by the message framing ([RFC7230]) are received prior to
- the connection being closed. If the request method is GET, the
- response status code is 200 (OK), and the entire response header
- section has been received, a cache MAY store an incomplete response
- message body if the cache entry is recorded as incomplete. Likewise,
- a 206 (Partial Content) response MAY be stored as if it were an
- incomplete 200 (OK) cache entry. However, a cache MUST NOT store
- incomplete or partial-content responses if it does not support the
- Range and Content-Range header fields or if it does not understand
- the range units used in those fields.
-
- A cache MAY complete a stored incomplete response by making a
- subsequent range request ([RFC7233]) and combining the successful
- response with the stored entry, as defined in Section 3.3. A cache
- MUST NOT use an incomplete response to answer requests unless the
- response has been made complete or the request is partial and
- specifies a range that is wholly within the incomplete response. A
- cache MUST NOT send a partial response to a client without explicitly
- marking it as such using the 206 (Partial Content) status code.
-
-3.2. Storing Responses to Authenticated Requests
-
- A shared cache MUST NOT use a cached response to a request with an
- Authorization header field (Section 4.2 of [RFC7235]) to satisfy any
- subsequent request unless a cache directive that allows such
- responses to be stored is present in the response.
-
- In this specification, the following Cache-Control response
- directives (Section 5.2.2) have such an effect: must-revalidate,
- public, and s-maxage.
-
-
-
-
-Fielding, et al. Standards Track [Page 7]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- Note that cached responses that contain the "must-revalidate" and/or
- "s-maxage" response directives are not allowed to be served stale
- (Section 4.2.4) by shared caches. In particular, a response with
- either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to
- satisfy a subsequent request without revalidating it on the origin
- server.
-
-3.3. Combining Partial Content
-
- A response might transfer only a partial representation if the
- connection closed prematurely or if the request used one or more
- Range specifiers ([RFC7233]). After several such transfers, a cache
- might have received several ranges of the same representation. A
- cache MAY combine these ranges into a single stored response, and
- reuse that response to satisfy later requests, if they all share the
- same strong validator and the cache complies with the client
- requirements in Section 4.3 of [RFC7233].
-
- When combining the new response with one or more stored responses, a
- cache MUST:
-
- o delete any Warning header fields in the stored response with
- warn-code 1xx (see Section 5.5);
-
- o retain any Warning header fields in the stored response with
- warn-code 2xx; and,
-
- o use other header fields provided in the new response, aside from
- Content-Range, to replace all instances of the corresponding
- header fields in the stored response.
-
-4. Constructing Responses from Caches
-
- When presented with a request, a cache MUST NOT reuse a stored
- response, unless:
-
- o The presented effective request URI (Section 5.5 of [RFC7230]) and
- that of the stored response match, and
-
- o the request method associated with the stored response allows it
- to be used for the presented request, and
-
- o selecting header fields nominated by the stored response (if any)
- match those presented (see Section 4.1), and
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 8]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- o the presented request does not contain the no-cache pragma
- (Section 5.4), nor the no-cache cache directive (Section 5.2.1),
- unless the stored response is successfully validated
- (Section 4.3), and
-
- o the stored response does not contain the no-cache cache directive
- (Section 5.2.2.2), unless it is successfully validated
- (Section 4.3), and
-
- o the stored response is either:
-
- * fresh (see Section 4.2), or
-
- * allowed to be served stale (see Section 4.2.4), or
-
- * successfully validated (see Section 4.3).
-
- Note that any of the requirements listed above can be overridden by a
- cache-control extension; see Section 5.2.3.
-
- When a stored response is used to satisfy a request without
- validation, a cache MUST generate an Age header field (Section 5.1),
- replacing any present in the response with a value equal to the
- stored response's current_age; see Section 4.2.3.
-
- A cache MUST write through requests with methods that are unsafe
- (Section 4.2.1 of [RFC7231]) to the origin server; i.e., a cache is
- not allowed to generate a reply to such a request before having
- forwarded the request and having received a corresponding response.
-
- Also, note that unsafe requests might invalidate already-stored
- responses; see Section 4.4.
-
- When more than one suitable response is stored, a cache MUST use the
- most recent response (as determined by the Date header field). It
- can also forward the request with "Cache-Control: max-age=0" or
- "Cache-Control: no-cache" to disambiguate which response to use.
-
- A cache that does not have a clock available MUST NOT use stored
- responses without revalidating them upon every use.
-
-4.1. Calculating Secondary Keys with Vary
-
- When a cache receives a request that can be satisfied by a stored
- response that has a Vary header field (Section 7.1.4 of [RFC7231]),
- it MUST NOT use that response unless all of the selecting header
-
-
-
-
-
-Fielding, et al. Standards Track [Page 9]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- fields nominated by the Vary header field match in both the original
- request (i.e., that associated with the stored response), and the
- presented request.
-
- The selecting header fields from two requests are defined to match if
- and only if those in the first request can be transformed to those in
- the second request by applying any of the following:
-
- o adding or removing whitespace, where allowed in the header field's
- syntax
-
- o combining multiple header fields with the same field name (see
- Section 3.2 of [RFC7230])
-
- o normalizing both header field values in a way that is known to
- have identical semantics, according to the header field's
- specification (e.g., reordering field values when order is not
- significant; case-normalization, where values are defined to be
- case-insensitive)
-
- If (after any normalization that might take place) a header field is
- absent from a request, it can only match another request if it is
- also absent there.
-
- A Vary header field-value of "*" always fails to match.
-
- The stored response with matching selecting header fields is known as
- the selected response.
-
- If multiple selected responses are available (potentially including
- responses without a Vary header field), the cache will need to choose
- one to use. When a selecting header field has a known mechanism for
- doing so (e.g., qvalues on Accept and similar request header fields),
- that mechanism MAY be used to select preferred responses; of the
- remainder, the most recent response (as determined by the Date header
- field) is used, as per Section 4.
-
- If no selected response is available, the cache cannot satisfy the
- presented request. Typically, it is forwarded to the origin server
- in a (possibly conditional; see Section 4.3) request.
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 10]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
-4.2. Freshness
-
- A fresh response is one whose age has not yet exceeded its freshness
- lifetime. Conversely, a stale response is one where it has.
-
- A response's freshness lifetime is the length of time between its
- generation by the origin server and its expiration time. An explicit
- expiration time is the time at which the origin server intends that a
- stored response can no longer be used by a cache without further
- validation, whereas a heuristic expiration time is assigned by a
- cache when no explicit expiration time is available.
-
- A response's age is the time that has passed since it was generated
- by, or successfully validated with, the origin server.
-
- When a response is "fresh" in the cache, it can be used to satisfy
- subsequent requests without contacting the origin server, thereby
- improving efficiency.
-
- The primary mechanism for determining freshness is for an origin
- server to provide an explicit expiration time in the future, using
- either the Expires header field (Section 5.3) or the max-age response
- directive (Section 5.2.2.8). Generally, origin servers will assign
- future explicit expiration times to responses in the belief that the
- representation is not likely to change in a semantically significant
- way before the expiration time is reached.
-
- If an origin server wishes to force a cache to validate every
- request, it can assign an explicit expiration time in the past to
- indicate that the response is already stale. Compliant caches will
- normally validate a stale cached response before reusing it for
- subsequent requests (see Section 4.2.4).
-
- Since origin servers do not always provide explicit expiration times,
- caches are also allowed to use a heuristic to determine an expiration
- time under certain circumstances (see Section 4.2.2).
-
- The calculation to determine if a response is fresh is:
-
- response_is_fresh = (freshness_lifetime > current_age)
-
- freshness_lifetime is defined in Section 4.2.1; current_age is
- defined in Section 4.2.3.
-
- Clients can send the max-age or min-fresh cache directives in a
- request to constrain or relax freshness calculations for the
- corresponding response (Section 5.2.1).
-
-
-
-
-Fielding, et al. Standards Track [Page 11]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- When calculating freshness, to avoid common problems in date parsing:
-
- o Although all date formats are specified to be case-sensitive, a
- cache recipient SHOULD match day, week, and time-zone names
- case-insensitively.
-
- o If a cache recipient's internal implementation of time has less
- resolution than the value of an HTTP-date, the recipient MUST
- internally represent a parsed Expires date as the nearest time
- equal to or earlier than the received value.
-
- o A cache recipient MUST NOT allow local time zones to influence the
- calculation or comparison of an age or expiration time.
-
- o A cache recipient SHOULD consider a date with a zone abbreviation
- other than GMT or UTC to be invalid for calculating expiration.
-
- Note that freshness applies only to cache operation; it cannot be
- used to force a user agent to refresh its display or reload a
- resource. See Section 6 for an explanation of the difference between
- caches and history mechanisms.
-
-4.2.1. Calculating Freshness Lifetime
-
- A cache can calculate the freshness lifetime (denoted as
- freshness_lifetime) of a response by using the first match of the
- following:
-
- o If the cache is shared and the s-maxage response directive
- (Section 5.2.2.9) is present, use its value, or
-
- o If the max-age response directive (Section 5.2.2.8) is present,
- use its value, or
-
- o If the Expires response header field (Section 5.3) is present, use
- its value minus the value of the Date response header field, or
-
- o Otherwise, no explicit expiration time is present in the response.
- A heuristic freshness lifetime might be applicable; see
- Section 4.2.2.
-
- Note that this calculation is not vulnerable to clock skew, since all
- of the information comes from the origin server.
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 12]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- When there is more than one value present for a given directive
- (e.g., two Expires header fields, multiple Cache-Control: max-age
- directives), the directive's value is considered invalid. Caches are
- encouraged to consider responses that have invalid freshness
- information to be stale.
-
-4.2.2. Calculating Heuristic Freshness
-
- Since origin servers do not always provide explicit expiration times,
- a cache MAY assign a heuristic expiration time when an explicit time
- is not specified, employing algorithms that use other header field
- values (such as the Last-Modified time) to estimate a plausible
- expiration time. This specification does not provide specific
- algorithms, but does impose worst-case constraints on their results.
-
- A cache MUST NOT use heuristics to determine freshness when an
- explicit expiration time is present in the stored response. Because
- of the requirements in Section 3, this means that, effectively,
- heuristics can only be used on responses without explicit freshness
- whose status codes are defined as cacheable by default (see Section
- 6.1 of [RFC7231]), and those responses without explicit freshness
- that have been marked as explicitly cacheable (e.g., with a "public"
- response directive).
-
- If the response has a Last-Modified header field (Section 2.2 of
- [RFC7232]), caches are encouraged to use a heuristic expiration value
- that is no more than some fraction of the interval since that time.
- A typical setting of this fraction might be 10%.
-
- When a heuristic is used to calculate freshness lifetime, a cache
- SHOULD generate a Warning header field with a 113 warn-code (see
- Section 5.5.4) in the response if its current_age is more than 24
- hours and such a warning is not already present.
-
- Note: Section 13.9 of [RFC2616] prohibited caches from calculating
- heuristic freshness for URIs with query components (i.e., those
- containing '?'). In practice, this has not been widely
- implemented. Therefore, origin servers are encouraged to send
- explicit directives (e.g., Cache-Control: no-cache) if they wish
- to preclude caching.
-
-4.2.3. Calculating Age
-
- The Age header field is used to convey an estimated age of the
- response message when obtained from a cache. The Age field value is
- the cache's estimate of the number of seconds since the response was
- generated or validated by the origin server. In essence, the Age
-
-
-
-
-Fielding, et al. Standards Track [Page 13]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- 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.
-
- The following data is used for the age calculation:
-
- age_value
-
- The term "age_value" denotes the value of the Age header field
- (Section 5.1), in a form appropriate for arithmetic operation; or
- 0, if not available.
-
- date_value
-
- The term "date_value" denotes the value of the Date header field,
- in a form appropriate for arithmetic operations. See Section
- 7.1.1.2 of [RFC7231] for the definition of the Date header field,
- and for requirements regarding responses without it.
-
- now
-
- The term "now" means "the current value of the clock at the host
- performing the calculation". A host ought to use NTP ([RFC5905])
- or some similar protocol to synchronize its clocks to Coordinated
- Universal Time.
-
- request_time
-
- The current value of the clock at the host at the time the request
- resulting in the stored response was made.
-
- response_time
-
- The current value of the clock at the host at the time the
- response was received.
-
- A response's age can be calculated in two entirely independent ways:
-
- 1. the "apparent_age": response_time 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. the "corrected_age_value", if all of the caches along the
- response path implement HTTP/1.1. A cache MUST interpret this
- value relative to the time the request was initiated, not the
- time that the response was received.
-
-
-
-
-Fielding, et al. Standards Track [Page 14]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- apparent_age = max(0, response_time - date_value);
-
- response_delay = response_time - request_time;
- corrected_age_value = age_value + response_delay;
-
- These are combined as
-
- corrected_initial_age = max(apparent_age, corrected_age_value);
-
- unless the cache is confident in the value of the Age header field
- (e.g., because there are no HTTP/1.0 hops in the Via header field),
- in which case the corrected_age_value MAY be used as the
- corrected_initial_age.
-
- The current_age of a stored response can then be calculated by adding
- the amount of time (in seconds) since the stored response was last
- validated by the origin server to the corrected_initial_age.
-
- resident_time = now - response_time;
- current_age = corrected_initial_age + resident_time;
-
-4.2.4. Serving Stale Responses
-
- A "stale" response is one that either has explicit expiry information
- or is allowed to have heuristic expiry calculated, but is not fresh
- according to the calculations in Section 4.2.
-
- A cache MUST NOT generate a stale response if it is prohibited by an
- explicit in-protocol directive (e.g., by a "no-store" or "no-cache"
- cache directive, a "must-revalidate" cache-response-directive, or an
- applicable "s-maxage" or "proxy-revalidate" cache-response-directive;
- see Section 5.2.2).
-
- A cache MUST NOT send stale responses unless it is disconnected
- (i.e., it cannot contact the origin server or otherwise find a
- forward path) or doing so is explicitly allowed (e.g., by the
- max-stale request directive; see Section 5.2.1).
-
- A cache SHOULD generate a Warning header field with the 110 warn-code
- (see Section 5.5.1) in stale responses. Likewise, a cache SHOULD
- generate a 112 warn-code (see Section 5.5.3) in stale responses if
- the cache is disconnected.
-
- A cache SHOULD NOT generate a new Warning header field when
- forwarding a response that does not have an Age header field, even if
- the response is already stale. A cache need not validate a response
- that merely became stale in transit.
-
-
-
-
-Fielding, et al. Standards Track [Page 15]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
-4.3. Validation
-
- When a cache has one or more stored responses for a requested URI,
- but cannot serve any of them (e.g., because they are not fresh, or
- one cannot be selected; see Section 4.1), it can use the conditional
- request mechanism [RFC7232] in the forwarded request to give the next
- inbound server an opportunity to select a valid stored response to
- use, updating the stored metadata in the process, or to replace the
- stored response(s) with a new response. This process is known as
- "validating" or "revalidating" the stored response.
-
-4.3.1. Sending a Validation Request
-
- When sending a conditional request for cache validation, a cache
- sends one or more precondition header fields containing validator
- metadata from its stored response(s), which is then compared by
- recipients to determine whether a stored response is equivalent to a
- current representation of the resource.
-
- One such validator is the timestamp given in a Last-Modified header
- field (Section 2.2 of [RFC7232]), which can be used in an
- If-Modified-Since header field for response validation, or in an
- If-Unmodified-Since or If-Range header field for representation
- selection (i.e., the client is referring specifically to a previously
- obtained representation with that timestamp).
-
- Another validator is the entity-tag given in an ETag header field
- (Section 2.3 of [RFC7232]). One or more entity-tags, indicating one
- or more stored responses, can be used in an If-None-Match header
- field for response validation, or in an If-Match or If-Range header
- field for representation selection (i.e., the client is referring
- specifically to one or more previously obtained representations with
- the listed entity-tags).
-
-4.3.2. Handling a Received Validation Request
-
- Each client in the request chain may have its own cache, so it is
- common for a cache at an intermediary to receive conditional requests
- from other (outbound) caches. Likewise, some user agents make use of
- conditional requests to limit data transfers to recently modified
- representations or to complete the transfer of a partially retrieved
- representation.
-
- If a cache receives a request that can be satisfied by reusing one of
- its stored 200 (OK) or 206 (Partial Content) responses, the cache
- SHOULD evaluate any applicable conditional header field preconditions
- received in that request with respect to the corresponding validators
- contained within the selected response. A cache MUST NOT evaluate
-
-
-
-Fielding, et al. Standards Track [Page 16]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- conditional header fields that are only applicable to an origin
- server, found in a request with semantics that cannot be satisfied
- with a cached response, or applied to a target resource for which it
- has no stored responses; such preconditions are likely intended for
- some other (inbound) server.
-
- The proper evaluation of conditional requests by a cache depends on
- the received precondition header fields and their precedence, as
- defined in Section 6 of [RFC7232]. The If-Match and
- If-Unmodified-Since conditional header fields are not applicable to a
- cache.
-
- A request containing an If-None-Match header field (Section 3.2 of
- [RFC7232]) indicates that the client wants to validate one or more of
- its own stored responses in comparison to whichever stored response
- is selected by the cache. If the field-value is "*", or if the
- field-value is a list of entity-tags and at least one of them matches
- the entity-tag of the selected stored response, a cache recipient
- SHOULD generate a 304 (Not Modified) response (using the metadata of
- the selected stored response) instead of sending that stored
- response.
-
- When a cache decides to revalidate its own stored responses for a
- request that contains an If-None-Match list of entity-tags, the cache
- MAY combine the received list with a list of entity-tags from its own
- stored set of responses (fresh or stale) and send the union of the
- two lists as a replacement If-None-Match header field value in the
- forwarded request. If a stored response contains only partial
- content, the cache MUST NOT include its entity-tag in the union
- unless the request is for a range that would be fully satisfied by
- that partial stored response. If the response to the forwarded
- request is 304 (Not Modified) and has an ETag header field value with
- an entity-tag that is not in the client's list, the cache MUST
- generate a 200 (OK) response for the client by reusing its
- corresponding stored response, as updated by the 304 response
- metadata (Section 4.3.4).
-
- If an If-None-Match header field is not present, a request containing
- an If-Modified-Since header field (Section 3.3 of [RFC7232])
- indicates that the client wants to validate one or more of its own
- stored responses by modification date. A cache recipient SHOULD
- generate a 304 (Not Modified) response (using the metadata of the
- selected stored response) if one of the following cases is true: 1)
- the selected stored response has a Last-Modified field-value that is
- earlier than or equal to the conditional timestamp; 2) no
- Last-Modified field is present in the selected stored response, but
- it has a Date field-value that is earlier than or equal to the
- conditional timestamp; or, 3) neither Last-Modified nor Date is
-
-
-
-Fielding, et al. Standards Track [Page 17]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- present in the selected stored response, but the cache recorded it as
- having been received at a time earlier than or equal to the
- conditional timestamp.
-
- A cache that implements partial responses to range requests, as
- defined in [RFC7233], also needs to evaluate a received If-Range
- header field (Section 3.2 of [RFC7233]) with respect to its selected
- stored response.
-
-4.3.3. Handling a Validation Response
-
- Cache handling of a response to a conditional request is dependent
- upon its status code:
-
- o A 304 (Not Modified) response status code indicates that the
- stored response can be updated and reused; see Section 4.3.4.
-
- o A full response (i.e., one with a payload body) indicates that
- none of the stored responses nominated in the conditional request
- is suitable. Instead, the cache MUST use the full response to
- satisfy the request and MAY replace the stored response(s).
-
- o However, if a cache receives a 5xx (Server Error) response while
- attempting to validate a response, it can either forward this
- response to the requesting client, or act as if the server failed
- to respond. In the latter case, the cache MAY send a previously
- stored response (see Section 4.2.4).
-
-4.3.4. Freshening Stored Responses upon Validation
-
- When a cache receives a 304 (Not Modified) response and already has
- one or more stored 200 (OK) responses for the same cache key, the
- cache needs to identify which of the stored responses are updated by
- this new response and then update the stored response(s) with the new
- information provided in the 304 response.
-
- The stored response to update is identified by using the first match
- (if any) of the following:
-
- o If the new response contains a strong validator (see Section 2.1
- of [RFC7232]), then that strong validator identifies the selected
- representation for update. All of the stored responses with the
- same strong validator are selected. If none of the stored
- responses contain the same strong validator, then the cache MUST
- NOT use the new response to update any stored responses.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 18]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- o If the new response contains a weak validator and that validator
- corresponds to one of the cache's stored responses, then the most
- recent of those matching stored responses is selected for update.
-
- o If the new response does not include any form of validator (such
- as in the case where a client generates an If-Modified-Since
- request from a source other than the Last-Modified response header
- field), and there is only one stored response, and that stored
- response also lacks a validator, then that stored response is
- selected for update.
-
- If a stored response is selected for update, the cache MUST:
-
- o delete any Warning header fields in the stored response with
- warn-code 1xx (see Section 5.5);
-
- o retain any Warning header fields in the stored response with
- warn-code 2xx; and,
-
- o use other header fields provided in the 304 (Not Modified)
- response to replace all instances of the corresponding header
- fields in the stored response.
-
-4.3.5. Freshening Responses via HEAD
-
- A response to the HEAD method is identical to what an equivalent
- request made with a GET would have been, except it lacks a body.
- This property of HEAD responses can be used to invalidate or update a
- cached GET response if the more efficient conditional GET request
- mechanism is not available (due to no validators being present in the
- stored response) or if transmission of the representation body is not
- desired even if it has changed.
-
- When a cache makes an inbound HEAD request for a given request target
- and receives a 200 (OK) response, the cache SHOULD update or
- invalidate each of its stored GET responses that could have been
- selected for that request (see Section 4.1).
-
- For each of the stored responses that could have been selected, if
- the stored response and HEAD response have matching values for any
- received validator fields (ETag and Last-Modified) and, if the HEAD
- response has a Content-Length header field, the value of
- Content-Length matches that of the stored response, the cache SHOULD
- update the stored response as described below; otherwise, the cache
- SHOULD consider the stored response to be stale.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 19]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- If a cache updates a stored response with the metadata provided in a
- HEAD response, the cache MUST:
-
- o delete any Warning header fields in the stored response with
- warn-code 1xx (see Section 5.5);
-
- o retain any Warning header fields in the stored response with
- warn-code 2xx; and,
-
- o use other header fields provided in the HEAD response to replace
- all instances of the corresponding header fields in the stored
- response and append new header fields to the stored response's
- header section unless otherwise restricted by the Cache-Control
- header field.
-
-4.4. Invalidation
-
- Because unsafe request methods (Section 4.2.1 of [RFC7231]) such as
- PUT, POST or DELETE have the potential for changing state on the
- origin server, intervening caches can use them to keep their contents
- up to date.
-
- A cache MUST invalidate the effective Request URI (Section 5.5 of
- [RFC7230]) as well as the URI(s) in the Location and Content-Location
- response header fields (if present) when a non-error status code is
- received in response to an unsafe request method.
-
- However, a cache MUST NOT invalidate a URI from a Location or
- Content-Location response header field if the host part of that URI
- differs from the host part in the effective request URI (Section 5.5
- of [RFC7230]). This helps prevent denial-of-service attacks.
-
- A cache MUST invalidate the effective request URI (Section 5.5 of
- [RFC7230]) when it receives a non-error response to a request with a
- method whose safety is unknown.
-
- Here, a "non-error response" is one with a 2xx (Successful) or 3xx
- (Redirection) status code. "Invalidate" means that the cache will
- either remove all stored responses related to the effective request
- URI or will mark these as "invalid" and in need of a mandatory
- validation before they can be sent in response to a subsequent
- request.
-
- Note that this does not guarantee that all appropriate responses are
- invalidated. For example, a state-changing request might invalidate
- responses in the caches it travels through, but relevant responses
- still might be stored in other caches that it has not.
-
-
-
-
-Fielding, et al. Standards Track [Page 20]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
-5. Header Field Definitions
-
- This section defines the syntax and semantics of HTTP/1.1 header
- fields related to caching.
-
-5.1. Age
-
- The "Age" header field conveys the sender's estimate of the amount of
- time since the response was generated or successfully validated at
- the origin server. Age values are calculated as specified in
- Section 4.2.3.
-
- Age = delta-seconds
-
- The Age field-value is a non-negative integer, representing time in
- seconds (see Section 1.2.1).
-
- The presence of an Age header field implies that the response was not
- generated or validated by the origin server for this request.
- However, lack of an Age header field does not imply the origin was
- contacted, since the response might have been received from an
- HTTP/1.0 cache that does not implement Age.
-
-5.2. Cache-Control
-
- The "Cache-Control" header field is used to specify directives for
- caches along the request/response chain. Such 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.
-
- A cache MUST obey the requirements of the Cache-Control directives
- defined in this section. See Section 5.2.3 for information about how
- Cache-Control directives defined elsewhere are handled.
-
- Note: Some HTTP/1.0 caches might not implement Cache-Control.
-
- A proxy, whether or not it implements a cache, MUST pass cache
- directives through in forwarded messages, 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 target a directive to a specific cache.
-
- Cache directives are identified by a token, to be compared
- case-insensitively, and have an optional argument, that can use both
- token and quoted-string syntax. For the directives defined below
- that define arguments, recipients ought to accept both forms, even if
- one is documented to be preferred. For any directive not defined by
- this specification, a recipient MUST accept both forms.
-
-
-
-Fielding, et al. Standards Track [Page 21]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- Cache-Control = 1#cache-directive
-
- cache-directive = token [ "=" ( token / quoted-string ) ]
-
- For the cache directives defined below, no argument is defined (nor
- allowed) unless stated otherwise.
-
-5.2.1. Request Cache-Control Directives
-
-5.2.1.1. max-age
-
- Argument syntax:
-
- delta-seconds (see Section 1.2.1)
-
- The "max-age" request directive indicates that the client is
- unwilling to accept a response whose age is greater than the
- specified number of seconds. Unless the max-stale request directive
- is also present, the client is not willing to accept a stale
- response.
-
- This directive uses the token form of the argument syntax: e.g.,
- 'max-age=5' not 'max-age="5"'. A sender SHOULD NOT generate the
- quoted-string form.
-
-5.2.1.2. max-stale
-
- Argument syntax:
-
- delta-seconds (see Section 1.2.1)
-
- The "max-stale" request directive indicates that the client is
- willing to accept a response that has exceeded its freshness
- lifetime. If max-stale is assigned a value, then the client is
- willing to accept a response that has exceeded its freshness lifetime
- 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.
-
- This directive uses the token form of the argument syntax: e.g.,
- 'max-stale=10' not 'max-stale="10"'. A sender SHOULD NOT generate
- the quoted-string form.
-
-5.2.1.3. min-fresh
-
- Argument syntax:
-
- delta-seconds (see Section 1.2.1)
-
-
-
-Fielding, et al. Standards Track [Page 22]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- The "min-fresh" request directive 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.
-
- This directive uses the token form of the argument syntax: e.g.,
- 'min-fresh=20' not 'min-fresh="20"'. A sender SHOULD NOT generate
- the quoted-string form.
-
-5.2.1.4. no-cache
-
- The "no-cache" request directive indicates that a cache MUST NOT use
- a stored response to satisfy the request without successful
- validation on the origin server.
-
-5.2.1.5. no-store
-
- The "no-store" request directive indicates that a cache MUST NOT
- store any part of either this request or any response to it. This
- directive applies to both private 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.
-
- This directive is NOT 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.
-
- Note that if a request containing this directive is satisfied from a
- cache, the no-store request directive does not apply to the already
- stored response.
-
-5.2.1.6. no-transform
-
- The "no-transform" request directive indicates that an intermediary
- (whether or not it implements a cache) MUST NOT transform the
- payload, as defined in Section 5.7.2 of [RFC7230].
-
-5.2.1.7. only-if-cached
-
- The "only-if-cached" request directive indicates that the client only
- wishes to obtain a stored response. If it receives this directive, a
- cache SHOULD either respond using a stored response that is
- consistent with the other constraints of the request, or respond with
-
-
-
-
-Fielding, et al. Standards Track [Page 23]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- a 504 (Gateway Timeout) status code. If a group of caches is being
- operated as a unified system with good internal connectivity, a
- member cache MAY forward such a request within that group of caches.
-
-5.2.2. Response Cache-Control Directives
-
-5.2.2.1. must-revalidate
-
- The "must-revalidate" response directive indicates that once it has
- become stale, a cache MUST NOT use the response to satisfy subsequent
- requests without successful validation on the origin server.
-
- The must-revalidate directive is necessary to support reliable
- operation for certain protocol features. In all circumstances a
- cache MUST obey the must-revalidate directive; in particular, if a
- cache cannot reach the origin server for any reason, it MUST generate
- a 504 (Gateway Timeout) response.
-
- The must-revalidate directive ought to be used by servers if and only
- if failure to validate a request on the representation could result
- in incorrect operation, such as a silently unexecuted financial
- transaction.
-
-5.2.2.2. no-cache
-
- Argument syntax:
-
- #field-name
-
- The "no-cache" response directive indicates that the response MUST
- NOT be used to satisfy a subsequent request without successful
- validation on the origin server. This allows an origin server to
- prevent a cache from using it to satisfy a request without contacting
- it, even by caches that have been configured to send stale responses.
-
- If the no-cache response directive specifies 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, any header
- fields in the response that have the field-name(s) listed 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.
-
- The field-names given are not limited to the set of header fields
- defined by this specification. Field names are case-insensitive.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 24]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- This directive uses the quoted-string form of the argument syntax. A
- sender SHOULD NOT generate the token form (even if quoting appears
- not to be needed for single-entry lists).
-
- Note: Although it has been back-ported to many implementations, some
- HTTP/1.0 caches will not recognize or obey this directive. Also,
- no-cache response directives with field-names are often handled by
- caches as if an unqualified no-cache directive was received; i.e.,
- the special handling for the qualified form is not widely
- implemented.
-
-5.2.2.3. no-store
-
- The "no-store" response directive indicates that a cache MUST NOT
- store any part of either the immediate request or response. This
- directive applies to both private 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.
-
- This directive is NOT 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.
-
-5.2.2.4. no-transform
-
- The "no-transform" response directive indicates that an intermediary
- (regardless of whether it implements a cache) MUST NOT transform the
- payload, as defined in Section 5.7.2 of [RFC7230].
-
-5.2.2.5. public
-
- The "public" response directive indicates that any cache MAY store
- the response, even if the response would normally be non-cacheable or
- cacheable only within a private cache. (See Section 3.2 for
- additional details related to the use of public in response to a
- request containing Authorization, and Section 3 for details of how
- public affects responses that would normally not be stored, due to
- their status codes not being defined as cacheable by default; see
- Section 4.2.2.)
-
-5.2.2.6. private
-
- Argument syntax:
-
- #field-name
-
-
-
-Fielding, et al. Standards Track [Page 25]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- The "private" response directive indicates that the response message
- is intended for a single user and MUST NOT be stored by a shared
- cache. A private cache MAY store the response and reuse it for later
- requests, even if the response would normally be non-cacheable.
-
- If the private response directive specifies one or more field-names,
- this requirement is limited to the field-values associated with the
- listed response header fields. That is, a shared cache MUST NOT
- store the specified field-names(s), whereas it MAY store the
- remainder of the response message.
-
- The field-names given are not limited to the set of header fields
- defined by this specification. Field names are case-insensitive.
-
- This directive uses the quoted-string form of the argument syntax. A
- sender SHOULD NOT generate the token form (even if quoting appears
- not to be needed for single-entry lists).
-
- Note: This usage of the word "private" only controls where the
- response can be stored; it cannot ensure the privacy of the message
- content. Also, private response directives with field-names are
- often handled by caches as if an unqualified private directive was
- received; i.e., the special handling for the qualified form is not
- widely implemented.
-
-5.2.2.7. proxy-revalidate
-
- The "proxy-revalidate" response directive has the same meaning as the
- must-revalidate response directive, except that it does not apply to
- private caches.
-
-5.2.2.8. max-age
-
- Argument syntax:
-
- delta-seconds (see Section 1.2.1)
-
- The "max-age" response directive indicates that the response is to be
- considered stale after its age is greater than the specified number
- of seconds.
-
- This directive uses the token form of the argument syntax: e.g.,
- 'max-age=5' not 'max-age="5"'. A sender SHOULD NOT generate the
- quoted-string form.
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 26]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
-5.2.2.9. s-maxage
-
- Argument syntax:
-
- delta-seconds (see Section 1.2.1)
-
- The "s-maxage" response directive indicates that, in shared caches,
- the maximum age specified by this directive overrides the maximum age
- specified by either the max-age directive or the Expires header
- field. The s-maxage directive also implies the semantics of the
- proxy-revalidate response directive.
-
- This directive uses the token form of the argument syntax: e.g.,
- 's-maxage=10' not 's-maxage="10"'. A sender SHOULD NOT generate the
- quoted-string form.
-
-5.2.3. 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 value. A cache
- MUST ignore unrecognized cache directives.
-
- Informational extensions (those that do not require a change in cache
- behavior) can 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 old directive are supplied, such that applications that do not
- understand the new directive will default to the behavior specified
- by the old directive, and those that understand the new directive
- will recognize it as modifying the requirements associated with the
- old directive. In this way, extensions to the existing cache-control
- directives can be made without breaking deployed caches.
-
- For example, consider a hypothetical new response directive called
- "community" that acts as a modifier to the private directive: in
- addition to private caches, any cache that is shared only by members
- of the named community is allowed to 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 that recognizes such a community cache-extension could
- broaden its behavior in accordance with that extension. A cache that
- does not recognize the community cache-extension would ignore it and
- adhere to the private directive.
-
-
-
-Fielding, et al. Standards Track [Page 27]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
-5.3. Expires
-
- The "Expires" header field gives the date/time after which the
- response is considered stale. See Section 4.2 for further discussion
- of the freshness 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 Expires value is an HTTP-date timestamp, as defined in Section
- 7.1.1.1 of [RFC7231].
-
- Expires = HTTP-date
-
- For example
-
- Expires: Thu, 01 Dec 1994 16:00:00 GMT
-
- A cache recipient MUST interpret invalid date formats, especially the
- value "0", as representing a time in the past (i.e., "already
- expired").
-
- If a response includes a Cache-Control field with the max-age
- directive (Section 5.2.2.8), a recipient MUST ignore the Expires
- field. Likewise, if a response includes the s-maxage directive
- (Section 5.2.2.9), a shared cache recipient MUST ignore the Expires
- field. In both these cases, the value in Expires is only intended
- for recipients that have not yet implemented the Cache-Control field.
-
- An origin server without a clock MUST NOT generate an Expires field
- unless its value represents a fixed time in the past (always expired)
- or its value has been associated with the resource by a system or
- user with a reliable clock.
-
- Historically, HTTP required the Expires field-value to be no more
- than a year in the future. While longer freshness lifetimes are no
- longer prohibited, extremely large values have been demonstrated to
- cause problems (e.g., clock overflows due to use of 32-bit integers
- for time values), and many caches will evict a response far sooner
- than that.
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 28]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
-5.4. Pragma
-
- The "Pragma" header field allows backwards compatibility with
- HTTP/1.0 caches, so that clients can specify a "no-cache" request
- that they will understand (as Cache-Control was not defined until
- HTTP/1.1). When the Cache-Control header field is also present and
- understood in a request, Pragma is ignored.
-
- In HTTP/1.0, Pragma was defined as an extensible field for
- implementation-specified directives for recipients. This
- specification deprecates such extensions to improve interoperability.
-
- Pragma = 1#pragma-directive
- pragma-directive = "no-cache" / extension-pragma
- extension-pragma = token [ "=" ( token / quoted-string ) ]
-
- When the Cache-Control header field is not present in a request,
- caches MUST consider the no-cache request pragma-directive as having
- the same effect as if "Cache-Control: no-cache" were present (see
- Section 5.2.1).
-
- When sending a no-cache request, a client ought to include both the
- pragma and cache-control directives, unless Cache-Control: no-cache
- is purposefully omitted to target other Cache-Control response
- directives at HTTP/1.1 caches. For example:
-
- GET / HTTP/1.1
- Host: www.example.com
- Cache-Control: max-age=30
- Pragma: no-cache
-
- will constrain HTTP/1.1 caches to serve a response no older than 30
- seconds, while precluding implementations that do not understand
- Cache-Control from serving a cached response.
-
- Note: Because the meaning of "Pragma: no-cache" in responses is
- not specified, it does not provide a reliable replacement for
- "Cache-Control: no-cache" in them.
-
-5.5. Warning
-
- The "Warning" header field is used to carry additional information
- about the status or transformation of a message that might not be
- reflected in the status code. This information is typically used to
- warn about possible incorrectness introduced by caching operations or
- transformations applied to the payload of the message.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 29]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- Warnings can be used for other purposes, both cache-related and
- otherwise. The use of a warning, rather than an error status code,
- distinguishes these responses from true failures.
-
- Warning header fields can in general be applied to any message,
- however some warn-codes are specific to caches and can only be
- applied to response messages.
-
- Warning = 1#warning-value
-
- warning-value = warn-code SP warn-agent SP warn-text
- [ SP warn-date ]
-
- warn-code = 3DIGIT
- warn-agent = ( uri-host [ ":" port ] ) / pseudonym
- ; the name or pseudonym of the server adding
- ; the Warning header field, for use in debugging
- ; a single "-" is recommended when agent unknown
- warn-text = quoted-string
- warn-date = DQUOTE HTTP-date DQUOTE
-
- Multiple warnings can be generated in a response (either by the
- origin server or by a cache), including multiple warnings with the
- same warn-code number that only differ in warn-text.
-
- A user agent that receives one or more Warning header fields SHOULD
- inform the user of as many of them as possible, in the order that
- they appear in the response. Senders that generate multiple Warning
- header fields are encouraged to order them with this user agent
- behavior in mind. A sender that generates new Warning header fields
- MUST append them after any existing Warning header fields.
-
- Warnings are assigned three digit warn-codes. The first digit
- indicates whether the Warning is required to be deleted from a stored
- response after validation:
-
- o 1xx warn-codes describe the freshness or validation status of the
- response, and so they MUST be deleted by a cache after validation.
- They can only be generated by a cache when validating a cached
- entry, and MUST NOT be generated in any other situation.
-
- o 2xx warn-codes describe some aspect of the representation that is
- not rectified by a validation (for example, a lossy compression of
- the representation) and they MUST NOT be deleted by a cache after
- validation, unless a full response is sent, in which case they
- MUST be.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 30]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- If a sender generates one or more 1xx warn-codes in a message to be
- sent to a recipient known to implement only HTTP/1.0, the sender MUST
- include in each corresponding warning-value a warn-date that matches
- the Date header field in the message. For example:
-
- HTTP/1.1 200 OK
- Date: Sat, 25 Aug 2012 23:34:45 GMT
- Warning: 112 - "network down" "Sat, 25 Aug 2012 23:34:45 GMT"
-
-
- Warnings have accompanying warn-text that describes the error, e.g.,
- for logging. It is advisory only, and its content does not affect
- interpretation of the warn-code.
-
- If a recipient that uses, evaluates, or displays Warning header
- fields receives a warn-date that is different from the Date value in
- the same message, the recipient MUST exclude the warning-value
- containing that warn-date before storing, forwarding, or using the
- message. This allows recipients to exclude warning-values that were
- improperly retained after a cache validation. If all of the
- warning-values are excluded, the recipient MUST exclude the Warning
- header field as well.
-
- The following warn-codes are defined by this specification, each with
- a recommended warn-text in English, and a description of its meaning.
- The procedure for defining additional warn codes is described in
- Section 7.2.1.
-
-5.5.1. Warning: 110 - "Response is Stale"
-
- A cache SHOULD generate this whenever the sent response is stale.
-
-5.5.2. Warning: 111 - "Revalidation Failed"
-
- A cache SHOULD generate this when sending a stale response because an
- attempt to validate the response failed, due to an inability to reach
- the server.
-
-5.5.3. Warning: 112 - "Disconnected Operation"
-
- A cache SHOULD generate this if it is intentionally disconnected from
- the rest of the network for a period of time.
-
-5.5.4. Warning: 113 - "Heuristic Expiration"
-
- A cache SHOULD generate this if it heuristically chose a freshness
- lifetime greater than 24 hours and the response's age is greater than
- 24 hours.
-
-
-
-Fielding, et al. Standards Track [Page 31]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
-5.5.5. Warning: 199 - "Miscellaneous Warning"
-
- The warning text can 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.
-
-5.5.6. Warning: 214 - "Transformation Applied"
-
- This Warning code MUST be added by a proxy if it applies any
- transformation to the representation, such as changing the
- content-coding, media-type, or modifying the representation data,
- unless this Warning code already appears in the response.
-
-5.5.7. Warning: 299 - "Miscellaneous Persistent Warning"
-
- The warning text can include arbitrary information to be presented to
- a human user or logged. A system receiving this warning MUST NOT
- take any automated action.
-
-6. History Lists
-
- User agents often have history mechanisms, such as "Back" buttons and
- history lists, that can be used to redisplay a representation
- retrieved earlier in a session.
-
- The freshness model (Section 4.2) does not necessarily apply to
- history mechanisms. That is, a history mechanism can display a
- previous representation even if it has expired.
-
- This does not prohibit the history mechanism from telling the user
- that a view might be stale or from honoring cache directives (e.g.,
- Cache-Control: no-store).
-
-7. IANA Considerations
-
-7.1. Cache Directive Registry
-
- The "Hypertext Transfer Protocol (HTTP) Cache Directive Registry"
- defines the namespace for the cache directives. It has been created
- and is now maintained at
- <http://www.iana.org/assignments/http-cache-directives>.
-
-7.1.1. Procedure
-
- A registration MUST include the following fields:
-
- o Cache Directive Name
-
-
-
-Fielding, et al. Standards Track [Page 32]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- o Pointer to specification text
-
- Values to be added to this namespace require IETF Review (see
- [RFC5226], Section 4.1).
-
-7.1.2. Considerations for New Cache Control Directives
-
- New extension directives ought to consider defining:
-
- o What it means for a directive to be specified multiple times,
-
- o When the directive does not take an argument, what it means when
- an argument is present,
-
- o When the directive requires an argument, what it means when it is
- missing,
-
- o Whether the directive is specific to requests, responses, or able
- to be used in either.
-
- See also Section 5.2.3.
-
-7.1.3. Registrations
-
- The registry has been populated with the registrations below:
-
- +------------------------+----------------------------------+
- | Cache Directive | Reference |
- +------------------------+----------------------------------+
- | max-age | Section 5.2.1.1, Section 5.2.2.8 |
- | max-stale | Section 5.2.1.2 |
- | min-fresh | Section 5.2.1.3 |
- | must-revalidate | Section 5.2.2.1 |
- | no-cache | Section 5.2.1.4, Section 5.2.2.2 |
- | no-store | Section 5.2.1.5, Section 5.2.2.3 |
- | no-transform | Section 5.2.1.6, Section 5.2.2.4 |
- | only-if-cached | Section 5.2.1.7 |
- | private | Section 5.2.2.6 |
- | proxy-revalidate | Section 5.2.2.7 |
- | public | Section 5.2.2.5 |
- | s-maxage | Section 5.2.2.9 |
- | stale-if-error | [RFC5861], Section 4 |
- | stale-while-revalidate | [RFC5861], Section 3 |
- +------------------------+----------------------------------+
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 33]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
-7.2. Warn Code Registry
-
- The "Hypertext Transfer Protocol (HTTP) Warn Codes" registry defines
- the namespace for warn codes. It has been created and is now
- maintained at <http://www.iana.org/assignments/http-warn-codes>.
-
-7.2.1. Procedure
-
- A registration MUST include the following fields:
-
- o Warn Code (3 digits)
-
- o Short Description
-
- o Pointer to specification text
-
- Values to be added to this namespace require IETF Review (see
- [RFC5226], Section 4.1).
-
-7.2.2. Registrations
-
- The registry has been populated with the registrations below:
-
- +-----------+----------------------------------+---------------+
- | Warn Code | Short Description | Reference |
- +-----------+----------------------------------+---------------+
- | 110 | Response is Stale | Section 5.5.1 |
- | 111 | Revalidation Failed | Section 5.5.2 |
- | 112 | Disconnected Operation | Section 5.5.3 |
- | 113 | Heuristic Expiration | Section 5.5.4 |
- | 199 | Miscellaneous Warning | Section 5.5.5 |
- | 214 | Transformation Applied | Section 5.5.6 |
- | 299 | Miscellaneous Persistent Warning | Section 5.5.7 |
- +-----------+----------------------------------+---------------+
-
-7.3. Header Field Registration
-
- HTTP header fields are registered within the "Message Headers"
- registry maintained at
- <http://www.iana.org/assignments/message-headers/>.
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 34]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- This document defines the following HTTP header fields, so the
- "Permanent Message Header Field Names" registry has been updated
- accordingly (see [BCP90]).
-
- +-------------------+----------+----------+-------------+
- | Header Field Name | Protocol | Status | Reference |
- +-------------------+----------+----------+-------------+
- | Age | http | standard | Section 5.1 |
- | Cache-Control | http | standard | Section 5.2 |
- | Expires | http | standard | Section 5.3 |
- | Pragma | http | standard | Section 5.4 |
- | Warning | http | standard | Section 5.5 |
- +-------------------+----------+----------+-------------+
-
- The change controller is: "IETF (iesg@ietf.org) - Internet
- Engineering Task Force".
-
-8. Security Considerations
-
- This section is meant to inform developers, information providers,
- and users of known security concerns specific to HTTP caching. More
- general security considerations are addressed in HTTP messaging
- [RFC7230] and semantics [RFC7231].
-
- Caches expose 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 need to be protected as sensitive
- information.
-
- In particular, various attacks might be amplified by being stored in
- a shared cache; such "cache poisoning" attacks use the cache to
- distribute a malicious payload to many clients, and are especially
- effective when an attacker can use implementation flaws, elevated
- privileges, or other techniques to insert such a response into a
- cache. One common attack vector for cache poisoning is to exploit
- differences in message parsing on proxies and in user agents; see
- Section 3.3.3 of [RFC7230] for the relevant requirements.
-
- Likewise, implementation flaws (as well as misunderstanding of cache
- operation) might lead to caching of sensitive information (e.g.,
- authentication credentials) that is thought to be private, exposing
- it to unauthorized parties.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 35]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- Furthermore, the very use of a cache can bring about privacy
- concerns. For example, if two users share a cache, and the first one
- browses to a site, the second may be able to detect that the other
- has been to that site, because the resources from it load more
- quickly, thanks to the cache.
-
- Note that the Set-Cookie response header field [RFC6265] does not
- inhibit caching; a cacheable response with a Set-Cookie header field
- can be (and often is) used to satisfy subsequent requests to caches.
- Servers who wish to control caching of these responses are encouraged
- to emit appropriate Cache-Control response header fields.
-
-9. Acknowledgments
-
- See Section 10 of [RFC7230].
-
-10. References
-
-10.1. Normative References
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", STD 68, RFC 5234, January 2008.
-
- [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Message Syntax and Routing",
- RFC 7230, June 2014.
-
- [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
- June 2014.
-
- [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Conditional Requests", RFC 7232,
- June 2014.
-
- [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed.,
- "Hypertext Transfer Protocol (HTTP/1.1): Range Requests",
- RFC 7233, June 2014.
-
- [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Authentication", RFC 7235, June 2014.
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 36]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
-10.2. Informative References
-
- [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration
- Procedures for Message Header Fields", BCP 90, RFC 3864,
- September 2004.
-
- [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.
-
- [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
- IANA Considerations Section in RFCs", BCP 26, RFC 5226,
- May 2008.
-
- [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale
- Content", RFC 5861, April 2010.
-
- [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch,
- "Network Time Protocol Version 4: Protocol and Algorithms
- Specification", RFC 5905, June 2010.
-
- [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
- April 2011.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 37]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
-Appendix A. Changes from RFC 2616
-
- The specification has been substantially rewritten for clarity.
-
- The conditions under which an authenticated response can be cached
- have been clarified. (Section 3.2)
-
- New status codes can now define that caches are allowed to use
- heuristic freshness with them. Caches are now allowed to calculate
- heuristic freshness for URIs with query components. (Section 4.2.2)
-
- The algorithm for calculating age is now less conservative. Caches
- are now required to handle dates with time zones as if they're
- invalid, because it's not possible to accurately guess.
- (Section 4.2.3)
-
- The Content-Location response header field is no longer used to
- determine the appropriate response to use when validating.
- (Section 4.3)
-
- The algorithm for selecting a cached negotiated response to use has
- been clarified in several ways. In particular, it now explicitly
- allows header-specific canonicalization when processing selecting
- header fields. (Section 4.1)
-
- Requirements regarding denial-of-service attack avoidance when
- performing invalidation have been clarified. (Section 4.4)
-
- Cache invalidation only occurs when a successful response is
- received. (Section 4.4)
-
- Cache directives are explicitly defined to be case-insensitive.
- Handling of multiple instances of cache directives when only one is
- expected is now defined. (Section 5.2)
-
- The "no-store" request directive doesn't apply to responses; i.e., a
- cache can satisfy a request with no-store on it and does not
- invalidate it. (Section 5.2.1.5)
-
- The qualified forms of the private and no-cache cache directives are
- noted to not be widely implemented; for example, "private=foo" is
- interpreted by many caches as simply "private". Additionally, the
- meaning of the qualified form of no-cache has been clarified.
- (Section 5.2.2)
-
- The "no-cache" response directive's meaning has been clarified.
- (Section 5.2.2.2)
-
-
-
-
-Fielding, et al. Standards Track [Page 38]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- The one-year limit on Expires header field values has been removed;
- instead, the reasoning for using a sensible value is given.
- (Section 5.3)
-
- The Pragma header field is now only defined for backwards
- compatibility; future pragmas are deprecated. (Section 5.4)
-
- Some requirements regarding production and processing of the Warning
- header fields have been relaxed, as it is not widely implemented.
- Furthermore, the Warning header field no longer uses RFC 2047
- encoding, nor does it allow multiple languages, as these aspects were
- not implemented. (Section 5.5)
-
- This specification introduces the Cache Directive and Warn Code
- Registries, and defines considerations for new cache directives.
- (Section 7.1 and Section 7.2)
-
-Appendix B. Imported ABNF
-
- The following core rules are included by reference, as defined in
- Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return),
- CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double
- quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any
- 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII
- character).
-
- The rules below are defined in [RFC7230]:
-
- OWS = <OWS, see [RFC7230], Section 3.2.3>
- field-name = <field-name, see [RFC7230], Section 3.2>
- quoted-string = <quoted-string, see [RFC7230], Section 3.2.6>
- token = <token, see [RFC7230], Section 3.2.6>
-
- port = <port, see [RFC7230], Section 2.7>
- pseudonym = <pseudonym, see [RFC7230], Section 5.7.1>
- uri-host = <uri-host, see [RFC7230], Section 2.7>
-
- The rules below are defined in other parts:
-
- HTTP-date = <HTTP-date, see [RFC7231], Section 7.1.1.1>
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 39]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
-Appendix C. Collected ABNF
-
- In the collected ABNF below, list rules are expanded as per Section
- 1.2 of [RFC7230].
-
- Age = delta-seconds
-
- Cache-Control = *( "," OWS ) cache-directive *( OWS "," [ OWS
- cache-directive ] )
-
- Expires = HTTP-date
-
- HTTP-date = <HTTP-date, see [RFC7231], Section 7.1.1.1>
-
- OWS = <OWS, see [RFC7230], Section 3.2.3>
-
- Pragma = *( "," OWS ) pragma-directive *( OWS "," [ OWS
- pragma-directive ] )
-
- Warning = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value ]
- )
-
- cache-directive = token [ "=" ( token / quoted-string ) ]
-
- delta-seconds = 1*DIGIT
-
- extension-pragma = token [ "=" ( token / quoted-string ) ]
-
- field-name = <field-name, see [RFC7230], Section 3.2>
-
- port = <port, see [RFC7230], Section 2.7>
- pragma-directive = "no-cache" / extension-pragma
- pseudonym = <pseudonym, see [RFC7230], Section 5.7.1>
-
- quoted-string = <quoted-string, see [RFC7230], Section 3.2.6>
-
- token = <token, see [RFC7230], Section 3.2.6>
-
- uri-host = <uri-host, see [RFC7230], Section 2.7>
-
- warn-agent = ( uri-host [ ":" port ] ) / pseudonym
- warn-code = 3DIGIT
- warn-date = DQUOTE HTTP-date DQUOTE
- warn-text = quoted-string
- warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date
- ]
-
-
-
-
-
-Fielding, et al. Standards Track [Page 40]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
-Index
-
- 1
- 110 (warn-code) 31
- 111 (warn-code) 31
- 112 (warn-code) 31
- 113 (warn-code) 31
- 199 (warn-code) 32
-
- 2
- 214 (warn-code) 32
- 299 (warn-code) 32
-
- A
- age 11
- Age header field 21
-
- C
- cache 4
- cache entry 5
- cache key 5-6
- Cache-Control header field 21
-
- D
- Disconnected Operation (warn-text) 31
-
- E
- Expires header field 28
- explicit expiration time 11
-
- F
- fresh 11
- freshness lifetime 11
-
- G
- Grammar
- Age 21
- Cache-Control 22
- cache-directive 22
- delta-seconds 5
- Expires 28
- extension-pragma 29
- Pragma 29
- pragma-directive 29
- warn-agent 29
- warn-code 29
- warn-date 29
- warn-text 29
-
-
-
-Fielding, et al. Standards Track [Page 41]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
- Warning 29
- warning-value 29
-
- H
- Heuristic Expiration (warn-text) 31
- heuristic expiration time 11
- M
- max-age (cache directive) 22, 26
- max-stale (cache directive) 22
- min-fresh (cache directive) 22
- Miscellaneous Persistent Warning (warn-text) 32
- Miscellaneous Warning (warn-text) 32
- must-revalidate (cache directive) 24
-
- N
- no-cache (cache directive) 23, 25
- no-store (cache directive) 23, 24
- no-transform (cache directive) 23, 25
-
- O
- only-if-cached (cache directive) 23
-
- P
- Pragma header field 29
- private (cache directive) 25
- private cache 4
- proxy-revalidate (cache directive) 26
- public (cache directive) 25
-
- R
- Response is Stale (warn-text) 30
- Revalidation Failed (warn-text) 31
-
- S
- s-maxage (cache directive) 27
- shared cache 4
- stale 11
- strong validator 18
-
- T
- Transformation Applied (warn-text) 32
-
- V
- validator 16
-
- W
- Warning header field 29
-
-
-
-
-Fielding, et al. Standards Track [Page 42]
-\f
-RFC 7234 HTTP/1.1 Caching June 2014
-
-
-Authors' Addresses
-
- Roy T. Fielding (editor)
- Adobe Systems Incorporated
- 345 Park Ave
- San Jose, CA 95110
- USA
-
- EMail: fielding@gbiv.com
- URI: http://roy.gbiv.com/
-
-
- Mark Nottingham (editor)
- Akamai
-
- EMail: mnot@mnot.net
- URI: http://www.mnot.net/
-
-
- Julian F. Reschke (editor)
- greenbytes GmbH
- Hafenweg 16
- Muenster, NW 48155
- Germany
-
- EMail: julian.reschke@greenbytes.de
- URI: http://greenbytes.de/tech/webdav/
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 43]
-\f
+++ /dev/null
-
-
-
-
-
-
-Internet Engineering Task Force (IETF) R. Fielding, Ed.
-Request for Comments: 7235 Adobe
-Obsoletes: 2616 J. Reschke, Ed.
-Updates: 2617 greenbytes
-Category: Standards Track June 2014
-ISSN: 2070-1721
-
-
- Hypertext Transfer Protocol (HTTP/1.1): Authentication
-
-Abstract
-
- The Hypertext Transfer Protocol (HTTP) is a stateless application-
- level protocol for distributed, collaborative, hypermedia information
- systems. This document defines the HTTP Authentication framework.
-
-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 5741.
-
- 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/rfc7235.
-
-Copyright Notice
-
- Copyright (c) 2014 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.
-
- This document may contain material from IETF Documents or IETF
- Contributions published or made publicly available before November
- 10, 2008. The person(s) controlling the copyright in some of this
-
-
-
-Fielding & Reschke Standards Track [Page 1]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
- material may not have granted the IETF Trust the right to allow
- modifications of such material outside the IETF Standards Process.
- Without obtaining an adequate license from the person(s) controlling
- the copyright in such materials, this document may not be modified
- outside the IETF Standards Process, and derivative works of it may
- not be created outside the IETF Standards Process, except to format
- it for publication as an RFC or to translate it into languages other
- than English.
-
-Table of Contents
-
- 1. Introduction ....................................................3
- 1.1. Conformance and Error Handling .............................3
- 1.2. Syntax Notation ............................................3
- 2. Access Authentication Framework .................................3
- 2.1. Challenge and Response .....................................3
- 2.2. Protection Space (Realm) ...................................5
- 3. Status Code Definitions .........................................6
- 3.1. 401 Unauthorized ...........................................6
- 3.2. 407 Proxy Authentication Required ..........................6
- 4. Header Field Definitions ........................................7
- 4.1. WWW-Authenticate ...........................................7
- 4.2. Authorization ..............................................8
- 4.3. Proxy-Authenticate .........................................8
- 4.4. Proxy-Authorization ........................................9
- 5. IANA Considerations .............................................9
- 5.1. Authentication Scheme Registry .............................9
- 5.1.1. Procedure ...........................................9
- 5.1.2. Considerations for New Authentication Schemes ......10
- 5.2. Status Code Registration ..................................11
- 5.3. Header Field Registration .................................11
- 6. Security Considerations ........................................12
- 6.1. Confidentiality of Credentials ............................12
- 6.2. Authentication Credentials and Idle Clients ...............12
- 6.3. Protection Spaces .........................................13
- 7. Acknowledgments ................................................14
- 8. References .....................................................14
- 8.1. Normative References ......................................14
- 8.2. Informative References ....................................14
- Appendix A. Changes from RFCs 2616 and 2617 .......................16
- Appendix B. Imported ABNF .........................................16
- Appendix C. Collected ABNF ........................................17
- Index .............................................................18
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 2]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
-1. Introduction
-
- HTTP provides a general framework for access control and
- authentication, via an extensible set of challenge-response
- authentication schemes, which can be used by a server to challenge a
- client request and by a client to provide authentication information.
- This document defines HTTP/1.1 authentication in terms of the
- architecture defined in "Hypertext Transfer Protocol (HTTP/1.1):
- Message Syntax and Routing" [RFC7230], including the general
- framework previously described in "HTTP Authentication: Basic and
- Digest Access Authentication" [RFC2617] and the related fields and
- status codes previously defined in "Hypertext Transfer Protocol --
- HTTP/1.1" [RFC2616].
-
- The IANA Authentication Scheme Registry (Section 5.1) lists
- registered authentication schemes and their corresponding
- specifications, including the "basic" and "digest" authentication
- schemes previously defined by RFC 2617.
-
-1.1. Conformance and Error Handling
-
- 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].
-
- Conformance criteria and considerations regarding error handling are
- defined in Section 2.5 of [RFC7230].
-
-1.2. Syntax Notation
-
- This specification uses the Augmented Backus-Naur Form (ABNF)
- notation of [RFC5234] with a list extension, defined in Section 7 of
- [RFC7230], that allows for compact definition of comma-separated
- lists using a '#' operator (similar to how the '*' operator indicates
- repetition). Appendix B describes rules imported from other
- documents. Appendix C shows the collected grammar with all list
- operators expanded to standard ABNF notation.
-
-2. Access Authentication Framework
-
-2.1. Challenge and Response
-
- HTTP provides a simple challenge-response authentication framework
- that can be used by a server to challenge a client request and by a
- client to provide authentication information. It uses a case-
- insensitive token as a means to identify the authentication scheme,
- followed by additional information necessary for achieving
-
-
-
-
-Fielding & Reschke Standards Track [Page 3]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
- authentication via that scheme. The latter can be either a comma-
- separated list of parameters or a single sequence of characters
- capable of holding base64-encoded information.
-
- Authentication parameters are name=value pairs, where the name token
- is matched case-insensitively, and each parameter name MUST only
- occur once per challenge.
-
- auth-scheme = token
-
- auth-param = token BWS "=" BWS ( token / quoted-string )
-
- token68 = 1*( ALPHA / DIGIT /
- "-" / "." / "_" / "~" / "+" / "/" ) *"="
-
- The token68 syntax allows the 66 unreserved URI characters
- ([RFC3986]), plus a few others, so that it can hold a base64,
- base64url (URL and filename safe alphabet), base32, or base16 (hex)
- encoding, with or without padding, but excluding whitespace
- ([RFC4648]).
-
- A 401 (Unauthorized) response message is used by an origin server to
- challenge the authorization of a user agent, including a
- WWW-Authenticate header field containing at least one challenge
- applicable to the requested resource.
-
- A 407 (Proxy Authentication Required) response message is used by a
- proxy to challenge the authorization of a client, including a
- Proxy-Authenticate header field containing at least one challenge
- applicable to the proxy for the requested resource.
-
- challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ]
-
- Note: Many clients fail to parse a challenge that contains an
- unknown scheme. A workaround for this problem is to list well-
- supported schemes (such as "basic") first.
-
- A user agent that wishes to authenticate itself with an origin server
- -- usually, but not necessarily, after receiving a 401 (Unauthorized)
- -- can 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) -- can do so by including a Proxy-Authorization header
- field with the request.
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 4]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
- Both the Authorization field value and the Proxy-Authorization field
- value contain the client's credentials for the realm of the resource
- being requested, based upon a challenge received in a response
- (possibly at some point in the past). When creating their values,
- the user agent ought to do so by selecting the challenge with what it
- considers to be the most secure auth-scheme that it understands,
- obtaining credentials from the user as appropriate. Transmission of
- credentials within header field values implies significant security
- considerations regarding the confidentiality of the underlying
- connection, as described in Section 6.1.
-
- credentials = auth-scheme [ 1*SP ( token68 / #auth-param ) ]
-
- Upon receipt of a request for a protected resource that omits
- credentials, contains invalid credentials (e.g., a bad password) or
- partial credentials (e.g., when the authentication scheme requires
- more than one round trip), an origin server SHOULD send a 401
- (Unauthorized) response that contains a WWW-Authenticate header field
- with at least one (possibly new) challenge applicable to the
- requested resource.
-
- Likewise, upon receipt of a request that omits proxy credentials or
- contains invalid or partial proxy credentials, a proxy that requires
- authentication SHOULD generate a 407 (Proxy Authentication Required)
- response that contains a Proxy-Authenticate header field with at
- least one (possibly new) challenge applicable to the proxy.
-
- A server that receives valid credentials that are not adequate to
- gain access ought to respond with the 403 (Forbidden) status code
- (Section 6.5.3 of [RFC7231]).
-
- HTTP does not restrict applications to this simple challenge-response
- framework for access authentication. Additional mechanisms can be
- used, such as authentication at the transport level or via message
- encapsulation, and with additional header fields specifying
- authentication information. However, such additional mechanisms are
- not defined by this specification.
-
-2.2. Protection Space (Realm)
-
- The "realm" authentication parameter is reserved for use by
- authentication schemes that wish to indicate a scope of protection.
-
- A protection space is defined by the canonical root URI (the scheme
- and authority components of the effective request URI; see Section
- 5.5 of [RFC7230]) of the server being accessed, in combination with
- the realm value if present. These realms allow the protected
- resources on a server to be partitioned into a set of protection
-
-
-
-Fielding & Reschke Standards Track [Page 5]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
- spaces, each with its own authentication scheme and/or authorization
- database. The realm value is a string, generally assigned by the
- origin server, that can have additional semantics specific to the
- authentication scheme. Note that a response can have multiple
- challenges with the same auth-scheme but with different realms.
-
- The protection space determines the domain over which credentials can
- be automatically applied. If a prior request has been authorized,
- the user agent MAY reuse the same credentials for all other requests
- within that protection space for a period of time determined by the
- authentication scheme, parameters, and/or user preferences (such as a
- configurable inactivity timeout). Unless specifically allowed by the
- authentication scheme, a single protection space cannot extend
- outside the scope of its server.
-
- For historical reasons, a sender MUST only generate the quoted-string
- syntax. Recipients might have to support both token and
- quoted-string syntax for maximum interoperability with existing
- clients that have been accepting both notations for a long time.
-
-3. Status Code Definitions
-
-3.1. 401 Unauthorized
-
- The 401 (Unauthorized) status code indicates that the request has not
- been applied because it lacks valid authentication credentials for
- the target resource. The server generating a 401 response MUST send
- a WWW-Authenticate header field (Section 4.1) containing at least one
- challenge applicable to the target resource.
-
- If the request included authentication credentials, then the 401
- response indicates that authorization has been refused for those
- credentials. The user agent MAY repeat the request with a new or
- replaced Authorization header field (Section 4.2). 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 agent SHOULD present the enclosed representation to the
- user, since it usually contains relevant diagnostic information.
-
-3.2. 407 Proxy Authentication Required
-
- The 407 (Proxy Authentication Required) status code is similar to 401
- (Unauthorized), but it indicates that the client needs to
- authenticate itself in order to use a proxy. The proxy MUST send a
- Proxy-Authenticate header field (Section 4.3) containing a challenge
- applicable to that proxy for the target resource. The client MAY
- repeat the request with a new or replaced Proxy-Authorization header
- field (Section 4.4).
-
-
-
-Fielding & Reschke Standards Track [Page 6]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
-4. Header Field Definitions
-
- This section defines the syntax and semantics of header fields
- related to the HTTP authentication framework.
-
-4.1. WWW-Authenticate
-
- The "WWW-Authenticate" header field indicates the authentication
- scheme(s) and parameters applicable to the target resource.
-
- WWW-Authenticate = 1#challenge
-
- A server generating a 401 (Unauthorized) response MUST send a
- WWW-Authenticate header field containing at least one challenge. A
- server MAY generate a WWW-Authenticate header field in other response
- messages to indicate that supplying credentials (or different
- credentials) might affect the response.
-
- A proxy forwarding a response MUST NOT modify any WWW-Authenticate
- fields in that response.
-
- User agents are advised to take special care in parsing the field
- value, as it might contain more than one challenge, and each
- challenge can contain a comma-separated list of authentication
- parameters. Furthermore, the header field itself can occur multiple
- times.
-
- For instance:
-
- WWW-Authenticate: Newauth realm="apps", type=1,
- title="Login to \"apps\"", Basic realm="simple"
-
- This header field contains two challenges; one for the "Newauth"
- scheme with a realm value of "apps", and two additional parameters
- "type" and "title", and another one for the "Basic" scheme with a
- realm value of "simple".
-
- Note: The challenge grammar production uses the list syntax as
- well. Therefore, a sequence of comma, whitespace, and comma can
- be considered either as applying to the preceding challenge, or to
- be an empty entry in the list of challenges. In practice, this
- ambiguity does not affect the semantics of the header field value
- and thus is harmless.
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 7]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
-4.2. Authorization
-
- The "Authorization" header field allows a user agent to authenticate
- itself with an origin server -- usually, but not necessarily, after
- receiving a 401 (Unauthorized) response. Its value consists of
- credentials containing the authentication information of the user
- agent for the realm of the resource being requested.
-
- Authorization = credentials
-
- If a request is authenticated and a realm specified, the same
- credentials are presumed to 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).
-
- A proxy forwarding a request MUST NOT modify any Authorization fields
- in that request. See Section 3.2 of [RFC7234] for details of and
- requirements pertaining to handling of the Authorization field by
- HTTP caches.
-
-4.3. Proxy-Authenticate
-
- The "Proxy-Authenticate" header field consists of at least one
- challenge that indicates the authentication scheme(s) and parameters
- applicable to the proxy for this effective request URI (Section 5.5
- of [RFC7230]). A proxy MUST send at least one Proxy-Authenticate
- header field in each 407 (Proxy Authentication Required) response
- that it generates.
-
- Proxy-Authenticate = 1#challenge
-
- Unlike WWW-Authenticate, the Proxy-Authenticate header field applies
- only to the next outbound client on the response chain. This is
- because only the client that chose a given proxy is likely to have
- the credentials necessary for authentication. However, when multiple
- proxies are used within the same administrative domain, such as
- office and regional caching proxies within a large corporate network,
- it is common for credentials to be generated by the user agent and
- passed through the hierarchy until consumed. Hence, in such a
- configuration, it will appear as if Proxy-Authenticate is being
- forwarded because each proxy will send the same challenge set.
-
- Note that the parsing considerations for WWW-Authenticate apply to
- this header field as well; see Section 4.1 for details.
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 8]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
-4.4. Proxy-Authorization
-
- The "Proxy-Authorization" header field allows the client to identify
- itself (or its user) to a proxy that requires authentication. Its
- value consists of credentials containing the authentication
- information of the client for the proxy and/or realm of the resource
- being requested.
-
- Proxy-Authorization = credentials
-
- Unlike Authorization, the Proxy-Authorization header field applies
- only to the next inbound proxy that demanded authentication using the
- Proxy-Authenticate field. When multiple proxies are used in a chain,
- the Proxy-Authorization header field is consumed by the first inbound
- 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.
-
-5. IANA Considerations
-
-5.1. Authentication Scheme Registry
-
- The "Hypertext Transfer Protocol (HTTP) Authentication Scheme
- Registry" defines the namespace for the authentication schemes in
- challenges and credentials. It has been created and is now
- maintained at <http://www.iana.org/assignments/http-authschemes>.
-
-5.1.1. Procedure
-
- Registrations MUST include the following fields:
-
- o Authentication Scheme Name
-
- o Pointer to specification text
-
- o Notes (optional)
-
- Values to be added to this namespace require IETF Review (see
- [RFC5226], Section 4.1).
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 9]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
-5.1.2. Considerations for New Authentication Schemes
-
- There are certain aspects of the HTTP Authentication Framework that
- put constraints on how new authentication schemes can work:
-
- o HTTP authentication is presumed to be stateless: all of the
- information necessary to authenticate a request MUST be provided
- in the request, rather than be dependent on the server remembering
- prior requests. Authentication based on, or bound to, the
- underlying connection is outside the scope of this specification
- and inherently flawed unless steps are taken to ensure that the
- connection cannot be used by any party other than the
- authenticated user (see Section 2.3 of [RFC7230]).
-
- o The authentication parameter "realm" is reserved for defining
- protection spaces as described in Section 2.2. New schemes MUST
- NOT use it in a way incompatible with that definition.
-
- o The "token68" notation was introduced for compatibility with
- existing authentication schemes and can only be used once per
- challenge or credential. Thus, new schemes ought to use the
- auth-param syntax instead, because otherwise future extensions
- will be impossible.
-
- o The parsing of challenges and credentials is defined by this
- specification and cannot be modified by new authentication
- schemes. When the auth-param syntax is used, all parameters ought
- to support both token and quoted-string syntax, and syntactical
- constraints ought to be defined on the field value after parsing
- (i.e., quoted-string processing). This is necessary so that
- recipients can use a generic parser that applies to all
- authentication schemes.
-
- Note: The fact that the value syntax for the "realm" parameter is
- restricted to quoted-string was a bad design choice not to be
- repeated for new parameters.
-
- o Definitions of new schemes ought to define the treatment of
- unknown extension parameters. In general, a "must-ignore" rule is
- preferable to a "must-understand" rule, because otherwise it will
- be hard to introduce new parameters in the presence of legacy
- recipients. Furthermore, it's good to describe the policy for
- defining new parameters (such as "update the specification" or
- "use this registry").
-
- o Authentication schemes need to document whether they are usable in
- origin-server authentication (i.e., using WWW-Authenticate),
- and/or proxy authentication (i.e., using Proxy-Authenticate).
-
-
-
-Fielding & Reschke Standards Track [Page 10]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
- o The credentials carried in an Authorization header field are
- specific to the user agent and, therefore, have the same effect on
- HTTP caches as the "private" Cache-Control response directive
- (Section 5.2.2.6 of [RFC7234]), within the scope of the request in
- which they appear.
-
- Therefore, new authentication schemes that choose not to carry
- credentials in the Authorization header field (e.g., using a newly
- defined header field) will need to explicitly disallow caching, by
- mandating the use of either Cache-Control request directives
- (e.g., "no-store", Section 5.2.1.5 of [RFC7234]) or response
- directives (e.g., "private").
-
-5.2. Status Code Registration
-
- The "Hypertext Transfer Protocol (HTTP) Status Code Registry" located
- at <http://www.iana.org/assignments/http-status-codes> has been
- updated with the registrations below:
-
- +-------+-------------------------------+-------------+
- | Value | Description | Reference |
- +-------+-------------------------------+-------------+
- | 401 | Unauthorized | Section 3.1 |
- | 407 | Proxy Authentication Required | Section 3.2 |
- +-------+-------------------------------+-------------+
-
-5.3. Header Field Registration
-
- HTTP header fields are registered within the "Message Headers"
- registry maintained at
- <http://www.iana.org/assignments/message-headers/>.
-
- This document defines the following HTTP header fields, so the
- "Permanent Message Header Field Names" registry has been updated
- accordingly (see [BCP90]).
-
- +---------------------+----------+----------+-------------+
- | Header Field Name | Protocol | Status | Reference |
- +---------------------+----------+----------+-------------+
- | Authorization | http | standard | Section 4.2 |
- | Proxy-Authenticate | http | standard | Section 4.3 |
- | Proxy-Authorization | http | standard | Section 4.4 |
- | WWW-Authenticate | http | standard | Section 4.1 |
- +---------------------+----------+----------+-------------+
-
- The change controller is: "IETF (iesg@ietf.org) - Internet
- Engineering Task Force".
-
-
-
-
-Fielding & Reschke Standards Track [Page 11]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
-6. Security Considerations
-
- This section is meant to inform developers, information providers,
- and users of known security concerns specific to HTTP authentication.
- More general security considerations are addressed in HTTP messaging
- [RFC7230] and semantics [RFC7231].
-
- Everything about the topic of HTTP authentication is a security
- consideration, so the list of considerations below is not exhaustive.
- Furthermore, it is limited to security considerations regarding the
- authentication framework, in general, rather than discussing all of
- the potential considerations for specific authentication schemes
- (which ought to be documented in the specifications that define those
- schemes). Various organizations maintain topical information and
- links to current research on Web application security (e.g.,
- [OWASP]), including common pitfalls for implementing and using the
- authentication schemes found in practice.
-
-6.1. Confidentiality of Credentials
-
- The HTTP authentication framework does not define a single mechanism
- for maintaining the confidentiality of credentials; instead, each
- authentication scheme defines how the credentials are encoded prior
- to transmission. While this provides flexibility for the development
- of future authentication schemes, it is inadequate for the protection
- of existing schemes that provide no confidentiality on their own, or
- that do not sufficiently protect against replay attacks.
- Furthermore, if the server expects credentials that are specific to
- each individual user, the exchange of those credentials will have the
- effect of identifying that user even if the content within
- credentials remains confidential.
-
- HTTP depends on the security properties of the underlying transport-
- or session-level connection to provide confidential transmission of
- header fields. In other words, if a server limits access to
- authenticated users using this framework, the server needs to ensure
- that the connection is properly secured in accordance with the nature
- of the authentication scheme used. For example, services that depend
- on individual user authentication often require a connection to be
- secured with TLS ("Transport Layer Security", [RFC5246]) prior to
- exchanging any credentials.
-
-6.2. Authentication Credentials and Idle Clients
-
- Existing HTTP clients and user agents typically retain authentication
- information indefinitely. HTTP does not provide a mechanism for the
- origin server to direct clients to discard these cached credentials,
- since the protocol has no awareness of how credentials are obtained
-
-
-
-Fielding & Reschke Standards Track [Page 12]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
- or managed by the user agent. The mechanisms for expiring or
- revoking credentials can be specified as part of an authentication
- scheme definition.
-
- Circumstances under which credential caching can interfere with the
- application's security model include but are not limited to:
-
- o Clients that have been idle for an extended period, following
- which the server might wish to cause the client to re-prompt the
- user for credentials.
-
- o Applications that 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.
-
- User agents that cache credentials are encouraged to provide a
- readily accessible mechanism for discarding cached credentials under
- user control.
-
-6.3. Protection Spaces
-
- Authentication schemes that solely rely on the "realm" mechanism for
- establishing a protection space will expose credentials to all
- resources on an origin server. Clients that have successfully made
- authenticated requests with a resource can use the same
- authentication credentials for other resources on the same origin
- server. This makes it possible for a different resource to harvest
- authentication credentials for other resources.
-
- This is of particular concern when an origin server hosts resources
- for multiple parties under the same canonical root URI (Section 2.2).
- Possible mitigation strategies include restricting direct access to
- authentication credentials (i.e., not making the content of the
- Authorization request header field available), and separating
- protection spaces by using a different host name (or port number) for
- each party.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 13]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
-7. Acknowledgments
-
- This specification takes over the definition of the HTTP
- Authentication Framework, previously defined in RFC 2617. We thank
- John Franks, Phillip M. Hallam-Baker, Jeffery L. Hostetler, Scott D.
- Lawrence, Paul J. Leach, Ari Luotonen, and Lawrence C. Stewart for
- their work on that specification. See Section 6 of [RFC2617] for
- further acknowledgements.
-
- See Section 10 of [RFC7230] for the Acknowledgments related to this
- document revision.
-
-8. References
-
-8.1. Normative References
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", STD 68, RFC 5234, January 2008.
-
- [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Message Syntax and Routing",
- RFC 7230, June 2014.
-
- [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
- June 2014.
-
- [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
- Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
- RFC 7234, June 2014.
-
-8.2. Informative References
-
- [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration
- Procedures for Message Header Fields", BCP 90, RFC 3864,
- September 2004.
-
- [OWASP] van der Stock, A., Ed., "A Guide to Building Secure Web
- Applications and Web Services", The Open Web Application
- Security Project (OWASP) 2.0.1, July 2005,
- <https://www.owasp.org/>.
-
- [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.
-
-
-
-Fielding & Reschke Standards Track [Page 14]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
- [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.
-
- [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
- Resource Identifier (URI): Generic Syntax", STD 66,
- RFC 3986, January 2005.
-
- [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
- Encodings", RFC 4648, October 2006.
-
- [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
- IANA Considerations Section in RFCs", BCP 26, RFC 5226,
- May 2008.
-
- [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
- (TLS) Protocol Version 1.2", RFC 5246, August 2008.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 15]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
-Appendix A. Changes from RFCs 2616 and 2617
-
- The framework for HTTP Authentication is now defined by this
- document, rather than RFC 2617.
-
- The "realm" parameter is no longer always required on challenges;
- consequently, the ABNF allows challenges without any auth parameters.
- (Section 2)
-
- The "token68" alternative to auth-param lists has been added for
- consistency with legacy authentication schemes such as "Basic".
- (Section 2)
-
- This specification introduces the Authentication Scheme Registry,
- along with considerations for new authentication schemes.
- (Section 5.1)
-
-Appendix B. Imported ABNF
-
- The following core rules are included by reference, as defined in
- Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return),
- CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double
- quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any
- 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII
- character).
-
- The rules below are defined in [RFC7230]:
-
- BWS = <BWS, see [RFC7230], Section 3.2.3>
- OWS = <OWS, see [RFC7230], Section 3.2.3>
- quoted-string = <quoted-string, see [RFC7230], Section 3.2.6>
- token = <token, see [RFC7230], Section 3.2.6>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 16]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
-Appendix C. Collected ABNF
-
- In the collected ABNF below, list rules are expanded as per Section
- 1.2 of [RFC7230].
-
- Authorization = credentials
-
- BWS = <BWS, see [RFC7230], Section 3.2.3>
-
- OWS = <OWS, see [RFC7230], Section 3.2.3>
-
- Proxy-Authenticate = *( "," OWS ) challenge *( OWS "," [ OWS
- challenge ] )
- Proxy-Authorization = credentials
-
- WWW-Authenticate = *( "," OWS ) challenge *( OWS "," [ OWS challenge
- ] )
-
- auth-param = token BWS "=" BWS ( token / quoted-string )
- auth-scheme = token
-
- challenge = auth-scheme [ 1*SP ( token68 / [ ( "," / auth-param ) *(
- OWS "," [ OWS auth-param ] ) ] ) ]
- credentials = auth-scheme [ 1*SP ( token68 / [ ( "," / auth-param )
- *( OWS "," [ OWS auth-param ] ) ] ) ]
-
- quoted-string = <quoted-string, see [RFC7230], Section 3.2.6>
-
- token = <token, see [RFC7230], Section 3.2.6>
- token68 = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" )
- *"="
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 17]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
-Index
-
- 4
- 401 Unauthorized (status code) 6
- 407 Proxy Authentication Required (status code) 6
-
- A
- Authorization header field 8
-
- C
- Canonical Root URI 5
-
- G
- Grammar
- auth-param 4
- auth-scheme 4
- Authorization 8
- challenge 4
- credentials 5
- Proxy-Authenticate 8
- Proxy-Authorization 9
- token68 4
- WWW-Authenticate 7
-
- P
- Protection Space 5
- Proxy-Authenticate header field 8
- Proxy-Authorization header field 9
-
- R
- Realm 5
-
- W
- WWW-Authenticate header field 7
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 18]
-\f
-RFC 7235 HTTP/1.1 Authentication June 2014
-
-
-Authors' Addresses
-
- Roy T. Fielding (editor)
- Adobe Systems Incorporated
- 345 Park Ave
- San Jose, CA 95110
- USA
-
- EMail: fielding@gbiv.com
- URI: http://roy.gbiv.com/
-
-
- Julian F. Reschke (editor)
- greenbytes GmbH
- Hafenweg 16
- Muenster, NW 48155
- Germany
-
- EMail: julian.reschke@greenbytes.de
- URI: http://greenbytes.de/tech/webdav/
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding & Reschke Standards Track [Page 19]
-\f
+++ /dev/null
-
-
-
-
-
-
-Internet Engineering Task Force (IETF) A. Petersson
-Request for Comments: 7239 M. Nilsson
-Category: Standards Track Opera Software
-ISSN: 2070-1721 June 2014
-
-
- Forwarded HTTP Extension
-
-Abstract
-
- This document defines an HTTP extension header field that allows
- proxy components to disclose information lost in the proxying
- process, for example, the originating IP address of a request or IP
- address of the proxy on the user-agent-facing interface. In a path
- of proxying components, this makes it possible to arrange it so that
- each subsequent component will have access to, for example, all IP
- addresses used in the chain of proxied HTTP requests.
-
- This document also specifies guidelines for a proxy administrator to
- anonymize the origin of a request.
-
-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 5741.
-
- 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/rfc7239.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Petersson & Nilsson Standards Track [Page 1]
-\f
-RFC 7239 Forwarded HTTP Extension June 2014
-
-
-Copyright Notice
-
- Copyright (c) 2014 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 ....................................................3
- 2. Notational Conventions ..........................................4
- 3. Syntax Notations ................................................4
- 4. Forwarded HTTP Header Field .....................................4
- 5. Parameters ......................................................6
- 5.1. Forwarded By ...............................................6
- 5.2. Forwarded For ..............................................6
- 5.3. Forwarded Host .............................................7
- 5.4. Forwarded Proto ............................................7
- 5.5. Extensions .................................................7
- 6. Node Identifiers ................................................8
- 6.1. IPv4 and IPv6 Identifiers ..................................9
- 6.2. The "unknown" Identifier ...................................9
- 6.3. Obfuscated Identifier ......................................9
- 7. Implementation Considerations ..................................10
- 7.1. HTTP Lists ................................................10
- 7.2. Header Field Preservation .................................10
- 7.3. Relation to Via ...........................................10
- 7.4. Transition ................................................11
- 7.5. Example Usage .............................................11
- 8. Security Considerations ........................................12
- 8.1. Header Validity and Integrity .............................12
- 8.2. Information Leak ..........................................12
- 8.3. Privacy Considerations ....................................12
- 9. IANA Considerations ............................................14
- 10. References ....................................................14
- 10.1. Normative References .....................................14
- 10.2. Informative References ...................................15
- Appendix A. Acknowledgments .......................................16
-
-
-
-
-
-Petersson & Nilsson Standards Track [Page 2]
-\f
-RFC 7239 Forwarded HTTP Extension June 2014
-
-
-1. Introduction
-
- In today's HTTP landscape, there are a multitude of different
- applications that act as proxies for the user agents. In many cases,
- these proxies exists without the action or knowledge of the end-user.
- These cases occur, for example, when the proxy exists as a part of
- the infrastructure within the organization running the web server.
- Such proxies may be used for features such as load balancing or
- crypto offload. Another example is when the proxy is used within the
- same organization as the user, and the proxy is used to cache
- resources. However, these proxies make the requests appear as if
- they originated from the proxy's IP address, and they may change
- other information in the original request. This represents a loss of
- information from the original request.
-
- This loss of information can cause problems for a web server that has
- a specific use for the clients' IP addresses that will not be met by
- using the address of the proxy or other information changed by the
- proxy. The main uses of this information are for diagnostics, access
- control, and abuse management. Diagnostic functions can include
- event logging, troubleshooting, and statistics gathering, and the
- information collected is usually only stored for short periods of
- time and only gathered in response to a particular problem or a
- complaint from the client. Access control can be operated by
- configuring a list of client IP addresses from which access is
- permitted, but this approach will not work if a proxy is used, unless
- the proxy is trusted and is, itself, configured with a list of
- allowed client addresses for the server. Cases of abuse require
- identification of the abuser and this uses many of the same features
- identified for diagnostics.
-
- Most of the time that a proxy is used, this loss of information is
- not the primary purpose, or even a desired effect, of using the
- proxy. Thus, to restore the desired functionality when a proxy is in
- use, a way of disclosing the original information at the HTTP level
- is needed. Clearly, however, when the purpose of using a proxy is to
- provide client anonymity, the proxy will not use the feature defined
- in this document.
-
- It should be noted that the use of a reverse proxy also hides
- information. Again, where the loss of information is not a
- deliberate function of the use of the reverse proxy, it can be
- desirable to find a way to encode the information within the HTTP
- messages so that the consumer can see it.
-
- A common way to disclose this information is by using the non-
- standard header fields such as X-Forwarded-For, X-Forwarded-By, and
- X-Forwarded-Proto. There are many benefits to using a standardized
-
-
-
-Petersson & Nilsson Standards Track [Page 3]
-\f
-RFC 7239 Forwarded HTTP Extension June 2014
-
-
- approach to commonly desired protocol function: not least is
- interoperability between implementations. This document standardizes
- a header field called "Forwarded" and provides the syntax and
- semantics for disclosing such information. "Forwarded" also combines
- all the information within one single header field, making it
- possible to correlate that information. With the header field format
- described in this document, it is possible to know what information
- belongs together, as long as the proxies are trusted. Such
- conclusions are not possible to make with the X-Forwarded class of
- header fields. The header field defined in this document is optional
- such that implementations of proxies that are intended to provide
- privacy are not required to operate or implement the header field.
-
- Note that similar issues to those described for proxies also arise
- with use of NATs. This is discussed further in [RFC6269].
-
-2. Notational 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 [RFC2119].
-
-3. Syntax Notations
-
- This specification uses the Augmented Backus-Naur Form (ABNF)
- notation of [RFC5234] with the list rule extension defined in Section
- 7 of [RFC7230].
-
-4. Forwarded HTTP Header Field
-
- The "Forwarded" HTTP header field is an OPTIONAL header field that,
- when used, contains a list of parameter-identifier pairs that
- disclose information that is altered or lost when a proxy is involved
- in the path of the request. Due to the sensitive nature of the data
- passed in this header field (see Sections 8.2 and 8.3), this header
- field should be turned off by default. Further, each parameter
- should be configured individually. "Forwarded" is only for use in
- HTTP requests and is not to be used in HTTP responses. This applies
- to forwarding proxies, as well as reverse proxies. Information
- passed in this header field can be, for example, the source IP
- address of the request, the IP address of the incoming interface on
- the proxy, or whether HTTP or HTTPS was used. If the request is
- passing through several proxies, each proxy can add a set of
- parameters; it can also remove previously added "Forwarded" header
- fields.
-
-
-
-
-
-
-Petersson & Nilsson Standards Track [Page 4]
-\f
-RFC 7239 Forwarded HTTP Extension June 2014
-
-
- The top-level list is represented as a list of HTTP header
- field-values as defined in Section 3.2 of [RFC7230]. The first
- element in this list holds information added by the first proxy that
- implements and uses this header field, and each subsequent element
- holds information added by each subsequent proxy. Because this
- header field is optional, any proxy in the chain may choose not to
- update this header field. Each field-value is a semicolon-separated
- list; this sublist consists of parameter-identifier pairs.
- Parameter-identifier pairs are grouped together by an equals sign.
- Each parameter MUST NOT occur more than once per field-value. The
- parameter names are case-insensitive. The header field value can be
- defined in ABNF syntax as:
-
- Forwarded = 1#forwarded-element
-
- forwarded-element =
- [ forwarded-pair ] *( ";" [ forwarded-pair ] )
-
- forwarded-pair = token "=" value
- value = token / quoted-string
-
- token = <Defined in [RFC7230], Section 3.2.6>
- quoted-string = <Defined in [RFC7230], Section 3.2.6>
-
- Examples:
-
- Forwarded: for="_gazonk"
- Forwarded: For="[2001:db8:cafe::17]:4711"
- Forwarded: for=192.0.2.60;proto=http;by=203.0.113.43
- Forwarded: for=192.0.2.43, for=198.51.100.17
-
- Note that as ":" and "[]" are not valid characters in "token", IPv6
- addresses are written as "quoted-string".
-
- A proxy server that wants to add a new "Forwarded" header field value
- can either append it to the last existing "Forwarded" header field
- after a comma separator or add a new field at the end of the header
- block. A proxy MAY remove all "Forwarded" header fields from a
- request. It MUST, however, ensure that the correct header field is
- updated in case of multiple "Forwarded" header fields.
-
-
-
-
-
-
-
-
-
-
-
-Petersson & Nilsson Standards Track [Page 5]
-\f
-RFC 7239 Forwarded HTTP Extension June 2014
-
-
-5. Parameters
-
- This document specifies a number of parameters and valid values for
- each of them:
-
- o "by" identifies the user-agent facing interface of the proxy.
-
- o "for" identifies the node making the request to the proxy.
-
- o "host" is the host request header field as received by the proxy.
-
- o "proto" indicates what protocol was used to make the request.
-
-5.1. Forwarded By
-
- The "by" parameter is used to disclose the interface where the
- request came in to the proxy server. When proxies choose to use the
- "by" parameter, its default configuration SHOULD contain an
- obfuscated identifier as described in Section 6.3. If the server
- receiving proxied requests requires some address-based functionality,
- this parameter MAY instead contain an IP address (and, potentially, a
- port number). A third option is the "unknown" identifier described
- in Section 6.2.
-
- The syntax of a "by" value, after potential quoted-string unescaping,
- conforms to the "node" ABNF described in Section 6.
-
- This is primarily added by reverse proxies that wish to forward this
- information to the backend server. It can also be interesting in a
- multihomed environment to signal to backend servers from which the
- request came.
-
-5.2. Forwarded For
-
- The "for" parameter is used to disclose information about the client
- that initiated the request and subsequent proxies in a chain of
- proxies. When proxies choose to use the "for" parameter, its default
- configuration SHOULD contain an obfuscated identifier as described in
- Section 6.3. If the server receiving proxied requests requires some
- address-based functionality, this parameter MAY instead contain an IP
- address (and, potentially, a port number). A third option is the
- "unknown" identifier described in Section 6.2.
-
- The syntax of a "for" value, after potential quoted-string
- unescaping, conforms to the "node" ABNF described in Section 6.
-
-
-
-
-
-
-Petersson & Nilsson Standards Track [Page 6]
-\f
-RFC 7239 Forwarded HTTP Extension June 2014
-
-
- In a chain of proxy servers where this is fully utilized, the first
- "for" parameter will disclose the client where the request was first
- made, followed by any subsequent proxy identifiers. The last proxy
- in the chain is not part of the list of "for" parameters. The last
- proxy's IP address, and optionally a port number, are, however,
- readily available as the remote IP address at the transport layer.
- It can, however, be more relevant to read information about the last
- proxy from preceding "Forwarded" header field's "by" parameter, if
- present.
-
-5.3. Forwarded Host
-
- The "host" parameter is used to forward the original value of the
- "Host" header field. This can be used, for example, by the origin
- server if a reverse proxy is rewriting the "Host" header field to
- some internal host name.
-
- The syntax for a "host" value, after potential quoted-string
- unescaping, MUST conform to the Host ABNF described in Section 5.4 of
- [RFC7230].
-
-5.4. Forwarded Proto
-
- The "proto" parameter has the value of the used protocol type. The
- syntax of a "proto" value, after potential quoted-string unescaping,
- MUST conform to the URI scheme name as defined in Section 3.1 in
- [RFC3986] and registered with IANA according to [RFC4395]. Typical
- values are "http" or "https".
-
- For example, in an environment where a reverse proxy is also used as
- a crypto offloader, this allows the origin server to rewrite URLs in
- a document to match the type of connection as the user agent
- requested, even though all connections to the origin server are
- unencrypted HTTP.
-
-5.5. Extensions
-
- Extensions allow for additional parameters and values. Extensions
- can be particularly useful in reverse proxy environments. All
- extension parameters SHOULD be registered in the "HTTP Forwarded
- Parameter" registry. If certain extensions are expected to have
- widespread deployment, they SHOULD also be standardized. This is
- further discussed in Section 9.
-
-
-
-
-
-
-
-
-Petersson & Nilsson Standards Track [Page 7]
-\f
-RFC 7239 Forwarded HTTP Extension June 2014
-
-
-6. Node Identifiers
-
- The node identifier is one of the following:
-
- o The client's IP address, with an optional port number
-
- o A token indicating that the IP address of the client is not known
- to the proxy server
-
- o A generated token, allowing for tracing and debugging, while
- allowing the internal structure or sensitive information to be
- hidden
-
- The node identifier is defined by the ABNF syntax as:
-
- node = nodename [ ":" node-port ]
- nodename = IPv4address / "[" IPv6address "]" /
- "unknown" / obfnode
-
- IPv4address = <Defined in [RFC3986], Section 3.2.2>
- IPv6address = <Defined in [RFC3986], Section 3.2.2>
- obfnode = "_" 1*( ALPHA / DIGIT / "." / "_" / "-")
-
- node-port = port / obfport
- port = 1*5DIGIT
- obfport = "_" 1*(ALPHA / DIGIT / "." / "_" / "-")
-
- DIGIT = <Defined in [RFC5234], Section 3.4>
- ALPHA = <Defined in [RFC5234], Section B.1>
-
- Each of the identifiers may optionally have the port identifier, for
- example, allowing the identification of the endpoint in a NATed
- environment. The "node-port" can be identified either by its port
- number or by a generated token obfuscating the real port number. An
- obfuscated port may be used in situations where the possessor of the
- proxy wants the ability to trace requests -- for example, in debug
- purposes -- but does not want to reveal internal information.
-
- Note that the ABNF above also allows port numbers to be appended to
- the "unknown" identifier. Interpretation of such notation is,
- however, left to the possessor of a proxy adding such a value to the
- header field. To distinguish an "obfport" from a port, the "obfport"
- MUST have a leading underscore. Further, it MUST also consist of
- only "ALPHA", "DIGIT", and the characters ".", "_", and "-".
-
- It is important to note that an IPv6 address and any nodename with
- node-port specified MUST be quoted, since ":" is not an allowed
- character in "token".
-
-
-
-Petersson & Nilsson Standards Track [Page 8]
-\f
-RFC 7239 Forwarded HTTP Extension June 2014
-
-
- Examples:
-
- "192.0.2.43:47011"
- "[2001:db8:cafe::17]:47011"
-
-6.1. IPv4 and IPv6 Identifiers
-
- The ABNF rules for "IPv6address" and "IPv4address" are defined in
- [RFC3986]. The "IPv6address" SHOULD comply with textual
- representation recommendations [RFC5952] (for example, lowercase,
- compression of zeros).
-
- Note that the IP address may be one from the internal nets, as
- defined in [RFC1918] and [RFC4193]. Also, note that an IPv6 address
- is always enclosed in square brackets.
-
-6.2. The "unknown" Identifier
-
- The "unknown" identifier is used when the identity of the preceding
- entity is not known, but the proxy server still wants to signal that
- a forwarding of the request was made. One example would be a proxy
- server process generating an outgoing request without direct access
- to the incoming request TCP socket.
-
-6.3. Obfuscated Identifier
-
- A generated identifier may be used where there is a wish to keep the
- internal IP addresses secret, while still allowing the "Forwarded"
- header field to be used for tracing and debugging. This can also be
- useful if the proxy uses some sort of interface labels and there is a
- desire to pass them rather than an IP address. Unless static
- assignment of identifiers is necessary for the server's use of the
- identifiers, obfuscated identifiers SHOULD be randomly generated for
- each request. If the server requires that identifiers persist across
- requests, they SHOULD NOT persist longer than client IP addresses.
- To distinguish the obfuscated identifier from other identifiers, it
- MUST have a leading underscore "_". Furthermore, it MUST also
- consist of only "ALPHA", "DIGIT", and the characters ".", "_", and
- "-".
- Example:
-
- Forwarded: for=_hidden, for=_SEVKISEK
-
-
-
-
-
-
-
-
-
-Petersson & Nilsson Standards Track [Page 9]
-\f
-RFC 7239 Forwarded HTTP Extension June 2014
-
-
-7. Implementation Considerations
-
-7.1. HTTP Lists
-
- Note that an HTTP list allows white spaces to occur between the
- identifiers, and the list may be split over multiple header fields.
- As an example, the header field
-
- Forwarded: for=192.0.2.43,for="[2001:db8:cafe::17]",for=unknown
-
- is equivalent to the header field
-
- Forwarded: for=192.0.2.43, for="[2001:db8:cafe::17]", for=unknown
-
- which is equivalent to the header fields
-
- Forwarded: for=192.0.2.43
- Forwarded: for="[2001:db8:cafe::17]", for=unknown
-
-7.2. Header Field Preservation
-
- There are some cases when this header field should be kept and some
- cases where it should not be kept. A directly forwarded request
- should preserve and possibly extend it. If a single incoming request
- causes the proxy to make multiple outbound requests, special care
- must be taken to decide whether or not the header field should be
- preserved. In many cases, the header field should be preserved, but
- if the outbound request is not a direct consequence of the incoming
- request, the header field should not be preserved. Consider also the
- case when a proxy has detected a content mismatch in a 304 response
- and is following the instructions in [RFC7232], Section 4.1 to repeat
- the request unconditionally, in which case the new request is still
- basically a direct consequence of the origin request, and the header
- field should probably be kept.
-
-7.3. Relation to Via
-
- The "Via" header field (see [RFC7230], Section 5.7.1) is a header
- field with a similar use case as this header field. The "Via" header
- field, however, only provides information about the proxy itself, and
- thereby leaves out the information about the client connecting to the
- proxy server. The "Forwarded" header field, on the other hand, has
- relaying information from the client-facing side of the proxy server
- as its main purpose. As "Via" is already widely deployed, its format
- cannot be changed to address the problems that "Forwarded" addresses.
-
-
-
-
-
-
-Petersson & Nilsson Standards Track [Page 10]
-\f
-RFC 7239 Forwarded HTTP Extension June 2014
-
-
- Note that it is not possible to combine information from this header
- field with the information from the Via header field. Some proxies
- will not update the "Forwarded" header field, some proxies will not
- update the Via header field, and some proxies will update both.
-
-7.4. Transition
-
- If a proxy gets incoming requests with X-Forwarded-* header fields
- present, it is encouraged to convert these into the header field
- described in this document, if it can be done in a sensible way. If
- the request only contains one type -- for example, X-Forwarded-For --
- this can be translated to "Forwarded", by prepending each element
- with "for=". Note that IPv6 addresses may not be quoted in
- X-Forwarded-For and may not be enclosed by square brackets, but they
- are quoted and enclosed in square brackets in "Forwarded".
-
- X-Forwarded-For: 192.0.2.43, 2001:db8:cafe::17
-
- becomes:
-
- Forwarded: for=192.0.2.43, for="[2001:db8:cafe::17]"
-
- However, special care must be taken if, for example, both
- X-Forwarded-For and X-Forwarded-By exist. In such cases, it may not
- be possible to do a conversion, since it is not possible to know in
- which order the already existing fields were added. Also, note that
- removing the X-Forwarded-For header field may cause issues for
- parties that have not yet implemented support for this new header
- field.
-
-7.5. Example Usage
-
- A request from a client with IP address 192.0.2.43 passes through a
- proxy with IP address 198.51.100.17, then through another proxy with
- IP address 203.0.113.60 before reaching an origin server. This
- could, for example, be an office client behind a corporate malware
- filter talking to a origin server through a reverse proxy.
-
- o The HTTP request between the client and the first proxy has no
- "Forwarded" header field.
-
- o The HTTP request between the first and second proxy has a
- "Forwarded: for=192.0.2.43" header field.
-
- o The HTTP request between the second proxy and the origin server
- has a "Forwarded: for=192.0.2.43,
- for=198.51.100.17;by=203.0.113.60;proto=http;host=example.com"
- header field.
-
-
-
-Petersson & Nilsson Standards Track [Page 11]
-\f
-RFC 7239 Forwarded HTTP Extension June 2014
-
-
- Note that, at some points in a connection chain, the information
- might not be updated in the "Forwarded" header field, either because
- of lack of support of this HTTP extension or because of a policy
- decision not to disclose information about this network component.
-
-8. Security Considerations
-
-8.1. Header Validity and Integrity
-
- The "Forwarded" HTTP header field cannot be relied upon to be
- correct, as it may be modified, whether mistakenly or for malicious
- reasons, by every node on the way to the server, including the client
- making the request.
-
- One approach to ensure that the "Forwarded" HTTP header field is
- correct is to verify the correctness of proxies and to whitelist them
- as trusted. This approach has at least two weaknesses. First, the
- chain of IP addresses listed before the request came to the proxy
- cannot be trusted. Second, unless the communication between proxies
- and the endpoint is secured, the data can be modified by an attacker
- with access to the network.
-
-8.2. Information Leak
-
- The "Forwarded" HTTP header field can reveal internal structures of
- the network setup behind the NAT or proxy setup, which may be
- undesired. This can be addressed either by using obfuscated
- elements, by preventing the internal nodes from updating the HTTP
- header field, or by having an egress proxy remove entries that reveal
- internal network information.
-
- This header field should never be copied into response messages by
- origin servers or intermediaries, as it can reveal the whole proxy
- chain to the client. As a side effect, special care must be taken in
- hosting environments not to allow the TRACE request where the
- "Forwarded" field is used, as it would appear in the body of the
- response message.
-
-8.3. Privacy Considerations
-
- In recent years, there have been growing concerns about privacy.
- There is a trade-off between ensuring privacy for users versus
- disclosing information that is useful, for example, for debugging,
- statistics, and generating location-dependent content. The
- "Forwarded" HTTP header field, by design, exposes information that
- some users consider privacy sensitive, in order to allow for such
- uses. For any proxy, if the HTTP request contains header fields that
-
-
-
-
-Petersson & Nilsson Standards Track [Page 12]
-\f
-RFC 7239 Forwarded HTTP Extension June 2014
-
-
- specifically request privacy semantics, the proxy SHOULD NOT use the
- "Forwarded" header field, nor in any other manner pass private
- information, such as IP addresses, on to the next hop.
-
- The client's IP address, that may be forwarded in the "for" parameter
- of this header field, is considered to be privacy sensitive by many
- people, as the IP address may be able to uniquely identify a client,
- what operator the user is using, and possibly a rough estimation of
- where the user is geographically located.
-
- Proxies using this extension will preserve the information of a
- direct connection. This has an end-user privacy impact regardless of
- whether the end-user or deployer knows or expects that this is the
- case.
-
- Implementers and deployers of such proxies need to consider whether,
- and how, deploying this extension affects user privacy.
-
- The default configuration for both the "by" and "for" parameters
- SHOULD contain obfuscated identifiers. These identifiers SHOULD be
- randomly generated per request. If identifiers that persist across
- requests are required, their lifetimes SHOULD be limited and they
- SHOULD NOT persist longer than client IP addresses. When generating
- obfuscated identifiers, care must be taken not to include potentially
- sensitive information in them.
-
- Note that users' IP addresses may already be forwarded by proxies
- using the header field X-Forwarded-For, which is widely used. It
- should also be noted that if the user were doing the connection
- directly without passing the proxy, the client's IP address would be
- sent to the web server. Users that do not actively choose an
- anonymizing proxy cannot rely on having their IP address shielded.
- These users who want to minimize the risk of being tracked must also
- note that there are other ways information may leak, for example, by
- browser header field fingerprinting. The Forwarded header field
- itself, even when used without a uniquely identifying client
- identifier, may make fingerprinting more feasible by revealing the
- chain of proxies traversed by the client's request.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Petersson & Nilsson Standards Track [Page 13]
-\f
-RFC 7239 Forwarded HTTP Extension June 2014
-
-
-9. IANA Considerations
-
- This document specifies the HTTP header field listed below, which has
- been added to the "Permanent Message Header Field Names" registry
- defined in [RFC3864].
-
- Header field: Forwarded
- Applicable protocol: http
- Status: standard
- Author/Change controller:
- IETF (iesg@ietf.org)
- Internet Engineering Task Force
- Specification document(s): this specification (Section 4)
- Related information: None
-
- The "Forwarded" header field contains parameters for which IANA has
- created and now maintains a new registry entitled "HTTP Forwarded
- Parameters". Initial registrations are given below. For future
- assignments, the registration procedure is IETF Review [RFC5226].
- The security and privacy implications of all new parameters should be
- thoroughly documented. New parameters and their values MUST conform
- with the forwarded-pair as defined in ABNF in Section 4. Further, a
- short description should be provided in the registration.
-
- +-------------+---------------------------------------+-------------+
- | Parameter | Description | Reference |
- | name | | |
- +-------------+---------------------------------------+-------------+
- | by | IP address of incoming interface of a | Section 5.1 |
- | | proxy | |
- | for | IP address of client making a request | Section 5.2 |
- | | through a proxy | |
- | host | Host header field of the incoming | Section 5.3 |
- | | request | |
- | proto | Application protocol used for | Section 5.4 |
- | | incoming request | |
- +-------------+---------------------------------------+-------------+
-
- Table 1: Initial Assignments
-
-10. References
-
-10.1. Normative References
-
- [RFC1918] Rekhter, Y., Moskowitz, R., Karrenberg, D., Groot, G., and
- E. Lear, "Address Allocation for Private Internets",
- BCP 5, RFC 1918, February 1996.
-
-
-
-
-Petersson & Nilsson Standards Track [Page 14]
-\f
-RFC 7239 Forwarded HTTP Extension June 2014
-
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
- Procedures for Message Header Fields", BCP 90, RFC 3864,
- September 2004.
-
- [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
- Resource Identifier (URI): Generic Syntax", STD 66,
- RFC 3986, January 2005.
-
- [RFC4193] Hinden, R. and B. Haberman, "Unique Local IPv6 Unicast
- Addresses", RFC 4193, October 2005.
-
- [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
- Registration Procedures for New URI Schemes", BCP 35,
- RFC 4395, February 2006.
-
- [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
- IANA Considerations Section in RFCs", BCP 26, RFC 5226,
- May 2008.
-
- [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", STD 68, RFC 5234, January 2008.
-
- [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6
- Address Text Representation", RFC 5952, August 2010.
-
- [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Message Syntax and Routing",
- RFC 7230, June 2014.
-
- [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Conditional Requests", RFC 7232,
- June 2014.
-
-10.2. Informative References
-
- [RFC6269] Ford, M., Boucadair, M., Durand, A., Levis, P., and P.
- Roberts, "Issues with IP Address Sharing", RFC 6269,
- June 2011.
-
-
-
-
-
-
-
-
-
-
-Petersson & Nilsson Standards Track [Page 15]
-\f
-RFC 7239 Forwarded HTTP Extension June 2014
-
-
-Appendix A. Acknowledgments
-
- Thanks to Per Cederqvist, Alissa Cooper, Adrian Farrel, Stephen
- Farrell, Ned Freed, Per Hedbor, Amos Jeffries, Poul-Henning Kamp,
- Murray S. Kucherawy, Barry Leiba, Salvatore Loreto, Alexey Melnikov,
- S. Moonesamy, Susan Nichols, Mark Nottingham, Julian Reschke, John
- Sullivan, Willy Tarreau, and Dan Wing for their feedback.
-
-Authors' Addresses
-
- Andreas Petersson
- Opera Software
-
- EMail: andreas@sbin.se
-
-
- Martin Nilsson
- Opera Software
- S:t Larsgatan 12
- Linkoping SE-582 24
-
- EMail: nilsson@opera.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Petersson & Nilsson Standards Track [Page 16]
-\f
+++ /dev/null
-
-
-
-
-
-
-Internet Engineering Task Force (IETF) J. Reschke
-Request for Comments: 7538 greenbytes
-Obsoletes: 7238 April 2015
-Category: Standards Track
-ISSN: 2070-1721
-
-
- The Hypertext Transfer Protocol Status Code 308 (Permanent Redirect)
-
-Abstract
-
- This document specifies the additional Hypertext Transfer Protocol
- (HTTP) status code 308 (Permanent Redirect).
-
-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 5741.
-
- 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/rfc7538.
-
-Copyright Notice
-
- Copyright (c) 2015 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.
-
-
-
-
-
-
-
-
-
-Reschke Standards Track [Page 1]
-\f
-RFC 7538 HTTP Status Code 308 April 2015
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
- 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 2
- 3. 308 Permanent Redirect . . . . . . . . . . . . . . . . . . . 3
- 4. Deployment Considerations . . . . . . . . . . . . . . . . . . 3
- 5. Security Considerations . . . . . . . . . . . . . . . . . . . 4
- 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5
- 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 5
- 7.1. Normative References . . . . . . . . . . . . . . . . . . 5
- 7.2. Informative References . . . . . . . . . . . . . . . . . 5
- Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 6
- Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6
-
-1. Introduction
-
- HTTP defines a set of status codes for the purpose of redirecting a
- request to a different URI ([RFC3986]). The history of these status
- codes is summarized in Section 6.4 of [RFC7231], which also
- classifies the existing status codes into four categories.
-
- The first of these categories contains the status codes 301 (Moved
- Permanently), 302 (Found), and 307 (Temporary Redirect), which can be
- classified as below:
-
- +-------------------------------------------+-----------+-----------+
- | | Permanent | Temporary |
- +-------------------------------------------+-----------+-----------+
- | Allows changing the request method from | 301 | 302 |
- | POST to GET | | |
- | Does not allow changing the request | - | 307 |
- | method from POST to GET | | |
- +-------------------------------------------+-----------+-----------+
-
- Section 6.4.7 of [RFC7231] states that it does not define a permanent
- variant of status code 307; this specification adds the status code
- 308, defining this missing variant (Section 3).
-
- This specification contains no technical changes from the
- Experimental RFC 7238, which it obsoletes.
-
-2. Notational 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 [RFC2119].
-
-
-
-
-
-Reschke Standards Track [Page 2]
-\f
-RFC 7538 HTTP Status Code 308 April 2015
-
-
-3. 308 Permanent Redirect
-
- The 308 (Permanent Redirect) status code indicates that the target
- resource has been assigned a new permanent URI and any future
- references to this resource ought to use one of the enclosed URIs.
- Clients with link editing capabilities ought to automatically re-link
- references to the effective request URI (Section 5.5 of [RFC7230]) to
- one or more of the new references sent by the server, where possible.
-
- The server SHOULD generate a Location header field ([RFC7231],
- Section 7.1.2) in the response containing a preferred URI reference
- for the new permanent URI. The user agent MAY use the Location field
- value for automatic redirection. The server's response payload
- usually contains a short hypertext note with a hyperlink to the new
- URI(s).
-
- A 308 response is cacheable by default; i.e., unless otherwise
- indicated by the method definition or explicit cache controls (see
- [RFC7234], Section 4.2.2).
-
- Note: This status code is similar to 301 (Moved Permanently)
- ([RFC7231], Section 6.4.2), except that it does not allow changing
- the request method from POST to GET.
-
-4. Deployment Considerations
-
- Section 6 of [RFC7231] requires recipients to treat unknown 3xx
- status codes the same way as status code 300 (Multiple Choices)
- ([RFC7231], Section 6.4.1). Thus, servers will not be able to rely
- on automatic redirection happening similar to status codes 301, 302,
- or 307.
-
- Therefore, the use of status code 308 is restricted to cases where
- the server has sufficient confidence in the client's understanding
- the new code or when a fallback to the semantics of status code 300
- is not problematic. Server implementers are advised not to vary the
- status code based on characteristics of the request, such as the
- User-Agent header field ("User-Agent Sniffing") -- doing so usually
- results in code that is both hard to maintain and hard to debug and
- would also require special attention to caching (i.e., setting a
- "Vary" response header field, as defined in Section 7.1.4 of
- [RFC7231]).
-
-
-
-
-
-
-
-
-
-Reschke Standards Track [Page 3]
-\f
-RFC 7538 HTTP Status Code 308 April 2015
-
-
- Note that many existing HTML-based user agents will emulate a refresh
- when encountering an HTML <meta> refresh directive ([HTML],
- Section 4.2.5.3). This can be used as another fallback. For
- example:
-
- Client request:
-
- GET / HTTP/1.1
- Host: example.com
-
-
- Server response:
-
- HTTP/1.1 308 Permanent Redirect
- Content-Type: text/html; charset=UTF-8
- Location: http://example.com/new
- Content-Length: 356
-
- <!DOCTYPE HTML>
- <html>
- <head>
- <title>Permanent Redirect</title>
- <meta http-equiv="refresh"
- content="0; url=http://example.com/new">
- </head>
- <body>
- <p>
- The document has been moved to
- <a href="http://example.com/new"
- >http://example.com/new</a>.
- </p>
- </body>
- </html>
-
-5. Security Considerations
-
- All security considerations that apply to HTTP redirects apply to the
- 308 status code as well (see Section 9 of [RFC7231]).
-
- Unsecured communication over the Internet is subject to man-in-the-
- middle modification of messages, including changing status codes or
- redirect targets. Use of Transport Layer Security (TLS) is one way
- to mitigate those attacks. See Section 9 of [RFC7230] for related
- attacks on authority and message integrity.
-
-
-
-
-
-
-
-Reschke Standards Track [Page 4]
-\f
-RFC 7538 HTTP Status Code 308 April 2015
-
-
-6. IANA Considerations
-
- The "Hypertext Transfer Protocol (HTTP) Status Code Registry"
- (defined in Section 8.2 of [RFC7231] and located at
- <http://www.iana.org/assignments/http-status-codes>) has been updated
- to reference this specification.
-
- +-------+--------------------+----------------------------------+
- | Value | Description | Reference |
- +-------+--------------------+----------------------------------+
- | 308 | Permanent Redirect | Section 3 of this specification |
- +-------+--------------------+----------------------------------+
-
-7. References
-
-7.1. Normative References
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997,
- <http://www.rfc-editor.org/info/rfc2119>.
-
- [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
- Resource Identifier (URI): Generic Syntax", STD 66, RFC
- 3986, January 2005,
- <http://www.rfc-editor.org/info/rfc3986>.
-
- [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Message Syntax and Routing", RFC
- 7230, June 2014, <http://www.rfc-editor.org/info/rfc7230>.
-
- [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
- June 2014, <http://www.rfc-editor.org/info/rfc7231>.
-
- [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
- Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
- RFC 7234, June 2014,
- <http://www.rfc-editor.org/info/rfc7234>.
-
-7.2. Informative References
-
- [HTML] Hickson, I., Berjon, R., Faulkner, S., Leithead, T., Doyle
- Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", W3C
- Recommendation REC-html5-20141028, October 2014,
- <http://www.w3.org/TR/2014/REC-html5-20141028/>.
-
- Latest version available at <http://www.w3.org/TR/html5/>.
-
-
-
-
-Reschke Standards Track [Page 5]
-\f
-RFC 7538 HTTP Status Code 308 April 2015
-
-
-Acknowledgements
-
- The definition for the new status code 308 reuses text from the
- HTTP/1.1 definitions of status codes 301 and 307.
-
- Furthermore, thanks to Ben Campbell, Cyrus Daboo, Adrian Farrell,
- Eran Hammer-Lahav, Bjoern Hoehrmann, Barry Leiba, Subramanian
- Moonesamy, Kathleen Moriarty, Peter Saint-Andre, Robert Sparks, and
- Roy Fielding for feedback on this document.
-
-Author's Address
-
- Julian F. Reschke
- greenbytes GmbH
- Hafenweg 16
- Muenster, NW 48155
- Germany
-
- EMail: julian.reschke@greenbytes.de
- URI: http://greenbytes.de/tech/webdav/
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Reschke Standards Track [Page 6]
-\f
+++ /dev/null
-
-
-
-
-
-
-Internet Engineering Task Force (IETF) M. Belshe
-Request for Comments: 7540 BitGo
-Category: Standards Track R. Peon
-ISSN: 2070-1721 Google, Inc
- M. Thomson, Ed.
- Mozilla
- May 2015
-
-
- Hypertext Transfer Protocol Version 2 (HTTP/2)
-
-Abstract
-
- This specification describes an optimized expression of the semantics
- of the Hypertext Transfer Protocol (HTTP), referred to as HTTP
- version 2 (HTTP/2). HTTP/2 enables a more efficient use of network
- resources and a reduced perception of latency by introducing header
- field compression and allowing multiple concurrent exchanges on the
- same connection. It also introduces unsolicited push of
- representations from servers to clients.
-
- This specification is an alternative to, but does not obsolete, the
- HTTP/1.1 message syntax. HTTP's existing semantics remain unchanged.
-
-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 5741.
-
- 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/rfc7540.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 1]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-Copyright Notice
-
- Copyright (c) 2015 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. HTTP/2 Protocol Overview ........................................5
- 2.1. Document Organization ......................................6
- 2.2. Conventions and Terminology ................................6
- 3. Starting HTTP/2 .................................................7
- 3.1. HTTP/2 Version Identification ..............................8
- 3.2. Starting HTTP/2 for "http" URIs ............................8
- 3.2.1. HTTP2-Settings Header Field .........................9
- 3.3. Starting HTTP/2 for "https" URIs ..........................10
- 3.4. Starting HTTP/2 with Prior Knowledge ......................10
- 3.5. HTTP/2 Connection Preface .................................11
- 4. HTTP Frames ....................................................12
- 4.1. Frame Format ..............................................12
- 4.2. Frame Size ................................................13
- 4.3. Header Compression and Decompression ......................14
- 5. Streams and Multiplexing .......................................15
- 5.1. Stream States .............................................16
- 5.1.1. Stream Identifiers .................................21
- 5.1.2. Stream Concurrency .................................22
- 5.2. Flow Control ..............................................22
- 5.2.1. Flow-Control Principles ............................23
- 5.2.2. Appropriate Use of Flow Control ....................24
- 5.3. Stream Priority ...........................................24
- 5.3.1. Stream Dependencies ................................25
- 5.3.2. Dependency Weighting ...............................26
- 5.3.3. Reprioritization ...................................26
- 5.3.4. Prioritization State Management ....................27
- 5.3.5. Default Priorities .................................28
- 5.4. Error Handling ............................................28
- 5.4.1. Connection Error Handling ..........................29
- 5.4.2. Stream Error Handling ..............................29
-
-
-
-Belshe, et al. Standards Track [Page 2]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- 5.4.3. Connection Termination .............................30
- 5.5. Extending HTTP/2 ..........................................30
- 6. Frame Definitions ..............................................31
- 6.1. DATA ......................................................31
- 6.2. HEADERS ...................................................32
- 6.3. PRIORITY ..................................................34
- 6.4. RST_STREAM ................................................36
- 6.5. SETTINGS ..................................................36
- 6.5.1. SETTINGS Format ....................................38
- 6.5.2. Defined SETTINGS Parameters ........................38
- 6.5.3. Settings Synchronization ...........................39
- 6.6. PUSH_PROMISE ..............................................40
- 6.7. PING ......................................................42
- 6.8. GOAWAY ....................................................43
- 6.9. WINDOW_UPDATE .............................................46
- 6.9.1. The Flow-Control Window ............................47
- 6.9.2. Initial Flow-Control Window Size ...................48
- 6.9.3. Reducing the Stream Window Size ....................49
- 6.10. CONTINUATION .............................................49
- 7. Error Codes ....................................................50
- 8. HTTP Message Exchanges .........................................51
- 8.1. HTTP Request/Response Exchange ............................52
- 8.1.1. Upgrading from HTTP/2 ..............................53
- 8.1.2. HTTP Header Fields .................................53
- 8.1.3. Examples ...........................................57
- 8.1.4. Request Reliability Mechanisms in HTTP/2 ...........60
- 8.2. Server Push ...............................................60
- 8.2.1. Push Requests ......................................61
- 8.2.2. Push Responses .....................................63
- 8.3. The CONNECT Method ........................................64
- 9. Additional HTTP Requirements/Considerations ....................65
- 9.1. Connection Management .....................................65
- 9.1.1. Connection Reuse ...................................66
- 9.1.2. The 421 (Misdirected Request) Status Code ..........66
- 9.2. Use of TLS Features .......................................67
- 9.2.1. TLS 1.2 Features ...................................67
- 9.2.2. TLS 1.2 Cipher Suites ..............................68
- 10. Security Considerations .......................................69
- 10.1. Server Authority .........................................69
- 10.2. Cross-Protocol Attacks ...................................69
- 10.3. Intermediary Encapsulation Attacks .......................70
- 10.4. Cacheability of Pushed Responses .........................70
- 10.5. Denial-of-Service Considerations .........................70
- 10.5.1. Limits on Header Block Size .......................71
- 10.5.2. CONNECT Issues ....................................72
- 10.6. Use of Compression .......................................72
- 10.7. Use of Padding ...........................................73
- 10.8. Privacy Considerations ...................................73
-
-
-
-Belshe, et al. Standards Track [Page 3]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- 11. IANA Considerations ...........................................74
- 11.1. Registration of HTTP/2 Identification Strings ............74
- 11.2. Frame Type Registry ......................................75
- 11.3. Settings Registry ........................................75
- 11.4. Error Code Registry ......................................76
- 11.5. HTTP2-Settings Header Field Registration .................77
- 11.6. PRI Method Registration ..................................78
- 11.7. The 421 (Misdirected Request) HTTP Status Code ...........78
- 11.8. The h2c Upgrade Token ....................................78
- 12. References ....................................................79
- 12.1. Normative References .....................................79
- 12.2. Informative References ...................................81
- Appendix A. TLS 1.2 Cipher Suite Black List .......................83
- Acknowledgements ..................................................95
- Authors' Addresses ................................................96
-
-1. Introduction
-
- The Hypertext Transfer Protocol (HTTP) is a wildly successful
- protocol. However, the way HTTP/1.1 uses the underlying transport
- ([RFC7230], Section 6) has several characteristics that have a
- negative overall effect on application performance today.
-
- In particular, HTTP/1.0 allowed only one request to be outstanding at
- a time on a given TCP connection. HTTP/1.1 added request pipelining,
- but this only partially addressed request concurrency and still
- suffers from head-of-line blocking. Therefore, HTTP/1.0 and HTTP/1.1
- clients that need to make many requests use multiple connections to a
- server in order to achieve concurrency and thereby reduce latency.
-
- Furthermore, HTTP header fields are often repetitive and verbose,
- causing unnecessary network traffic as well as causing the initial
- TCP [TCP] congestion window to quickly fill. This can result in
- excessive latency when multiple requests are made on a new TCP
- connection.
-
- HTTP/2 addresses these issues by defining an optimized mapping of
- HTTP's semantics to an underlying connection. Specifically, it
- allows interleaving of request and response messages on the same
- connection and uses an efficient coding for HTTP header fields. It
- also allows prioritization of requests, letting more important
- requests complete more quickly, further improving performance.
-
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 4]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- The resulting protocol is more friendly to the network because fewer
- TCP connections can be used in comparison to HTTP/1.x. This means
- less competition with other flows and longer-lived connections, which
- in turn lead to better utilization of available network capacity.
-
- Finally, HTTP/2 also enables more efficient processing of messages
- through use of binary message framing.
-
-2. HTTP/2 Protocol Overview
-
- HTTP/2 provides an optimized transport for HTTP semantics. HTTP/2
- supports all of the core features of HTTP/1.1 but aims to be more
- efficient in several ways.
-
- The basic protocol unit in HTTP/2 is a frame (Section 4.1). Each
- frame type serves a different purpose. For example, HEADERS and DATA
- frames form the basis of HTTP requests and responses (Section 8.1);
- other frame types like SETTINGS, WINDOW_UPDATE, and PUSH_PROMISE are
- used in support of other HTTP/2 features.
-
- Multiplexing of requests is achieved by having each HTTP request/
- response exchange associated with its own stream (Section 5).
- Streams are largely independent of each other, so a blocked or
- stalled request or response does not prevent progress on other
- streams.
-
- Flow control and prioritization ensure that it is possible to
- efficiently use multiplexed streams. Flow control (Section 5.2)
- helps to ensure that only data that can be used by a receiver is
- transmitted. Prioritization (Section 5.3) ensures that limited
- resources can be directed to the most important streams first.
-
- HTTP/2 adds a new interaction mode whereby a server can push
- responses to a client (Section 8.2). Server push allows a server to
- speculatively send data to a client that the server anticipates the
- client will need, trading off some network usage against a potential
- latency gain. The server does this by synthesizing a request, which
- it sends as a PUSH_PROMISE frame. The server is then able to send a
- response to the synthetic request on a separate stream.
-
- Because HTTP header fields used in a connection can contain large
- amounts of redundant data, frames that contain them are compressed
- (Section 4.3). This has especially advantageous impact upon request
- sizes in the common case, allowing many requests to be compressed
- into one packet.
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 5]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-2.1. Document Organization
-
- The HTTP/2 specification is split into four parts:
-
- o Starting HTTP/2 (Section 3) covers how an HTTP/2 connection is
- initiated.
-
- o The frame (Section 4) and stream (Section 5) layers describe the
- way HTTP/2 frames are structured and formed into multiplexed
- streams.
-
- o Frame (Section 6) and error (Section 7) definitions include
- details of the frame and error types used in HTTP/2.
-
- o HTTP mappings (Section 8) and additional requirements (Section 9)
- describe how HTTP semantics are expressed using frames and
- streams.
-
- While some of the frame and stream layer concepts are isolated from
- HTTP, this specification does not define a completely generic frame
- layer. The frame and stream layers are tailored to the needs of the
- HTTP protocol and server push.
-
-2.2. Conventions and 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].
-
- All numeric values are in network byte order. Values are unsigned
- unless otherwise indicated. Literal values are provided in decimal
- or hexadecimal as appropriate. Hexadecimal literals are prefixed
- with "0x" to distinguish them from decimal literals.
-
- The following terms are used:
-
- client: The endpoint that initiates an HTTP/2 connection. Clients
- send HTTP requests and receive HTTP responses.
-
- connection: A transport-layer connection between two endpoints.
-
- connection error: An error that affects the entire HTTP/2
- connection.
-
- endpoint: Either the client or server of the connection.
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 6]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- frame: The smallest unit of communication within an HTTP/2
- connection, consisting of a header and a variable-length sequence
- of octets structured according to the frame type.
-
- peer: An endpoint. When discussing a particular endpoint, "peer"
- refers to the endpoint that is remote to the primary subject of
- discussion.
-
- receiver: An endpoint that is receiving frames.
-
- sender: An endpoint that is transmitting frames.
-
- server: The endpoint that accepts an HTTP/2 connection. Servers
- receive HTTP requests and send HTTP responses.
-
- stream: A bidirectional flow of frames within the HTTP/2 connection.
-
- stream error: An error on the individual HTTP/2 stream.
-
- Finally, the terms "gateway", "intermediary", "proxy", and "tunnel"
- are defined in Section 2.3 of [RFC7230]. Intermediaries act as both
- client and server at different times.
-
- The term "payload body" is defined in Section 3.3 of [RFC7230].
-
-3. Starting HTTP/2
-
- An HTTP/2 connection is an application-layer protocol running on top
- of a TCP connection ([TCP]). The client is the TCP connection
- initiator.
-
- HTTP/2 uses the same "http" and "https" URI schemes used by HTTP/1.1.
- HTTP/2 shares the same default port numbers: 80 for "http" URIs and
- 443 for "https" URIs. As a result, implementations processing
- requests for target resource URIs like "http://example.org/foo" or
- "https://example.com/bar" are required to first discover whether the
- upstream server (the immediate peer to which the client wishes to
- establish a connection) supports HTTP/2.
-
- The means by which support for HTTP/2 is determined is different for
- "http" and "https" URIs. Discovery for "http" URIs is described in
- Section 3.2. Discovery for "https" URIs is described in Section 3.3.
-
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 7]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-3.1. HTTP/2 Version Identification
-
- The protocol defined in this document has two identifiers.
-
- o The string "h2" identifies the protocol where HTTP/2 uses
- Transport Layer Security (TLS) [TLS12]. This identifier is used
- in the TLS application-layer protocol negotiation (ALPN) extension
- [TLS-ALPN] field and in any place where HTTP/2 over TLS is
- identified.
-
- The "h2" string is serialized into an ALPN protocol identifier as
- the two-octet sequence: 0x68, 0x32.
-
- o The string "h2c" identifies the protocol where HTTP/2 is run over
- cleartext TCP. This identifier is used in the HTTP/1.1 Upgrade
- header field and in any place where HTTP/2 over TCP is identified.
-
- The "h2c" string is reserved from the ALPN identifier space but
- describes a protocol that does not use TLS.
-
- Negotiating "h2" or "h2c" implies the use of the transport, security,
- framing, and message semantics described in this document.
-
-3.2. Starting HTTP/2 for "http" URIs
-
- A client that makes a request for an "http" URI without prior
- knowledge about support for HTTP/2 on the next hop uses the HTTP
- Upgrade mechanism (Section 6.7 of [RFC7230]). The client does so by
- making an HTTP/1.1 request that includes an Upgrade header field with
- the "h2c" token. Such an HTTP/1.1 request MUST include exactly one
- HTTP2-Settings (Section 3.2.1) header field.
-
- For example:
-
- GET / HTTP/1.1
- Host: server.example.com
- Connection: Upgrade, HTTP2-Settings
- Upgrade: h2c
- HTTP2-Settings: <base64url encoding of HTTP/2 SETTINGS payload>
-
- Requests that contain a payload body MUST be sent in their entirety
- before the client can send HTTP/2 frames. This means that a large
- request can block the use of the connection until it is completely
- sent.
-
- If concurrency of an initial request with subsequent requests is
- important, an OPTIONS request can be used to perform the upgrade to
- HTTP/2, at the cost of an additional round trip.
-
-
-
-Belshe, et al. Standards Track [Page 8]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- A server that does not support HTTP/2 can respond to the request as
- though the Upgrade header field were absent:
-
- HTTP/1.1 200 OK
- Content-Length: 243
- Content-Type: text/html
-
- ...
-
- A server MUST ignore an "h2" token in an Upgrade header field.
- Presence of a token with "h2" implies HTTP/2 over TLS, which is
- instead negotiated as described in Section 3.3.
-
- A server that supports HTTP/2 accepts the upgrade with a 101
- (Switching Protocols) response. After the empty line that terminates
- the 101 response, the server can begin sending HTTP/2 frames. These
- frames MUST include a response to the request that initiated the
- upgrade.
-
- For example:
-
- HTTP/1.1 101 Switching Protocols
- Connection: Upgrade
- Upgrade: h2c
-
- [ HTTP/2 connection ...
-
- The first HTTP/2 frame sent by the server MUST be a server connection
- preface (Section 3.5) consisting of a SETTINGS frame (Section 6.5).
- Upon receiving the 101 response, the client MUST send a connection
- preface (Section 3.5), which includes a SETTINGS frame.
-
- The HTTP/1.1 request that is sent prior to upgrade is assigned a
- stream identifier of 1 (see Section 5.1.1) with default priority
- values (Section 5.3.5). Stream 1 is implicitly "half-closed" from
- the client toward the server (see Section 5.1), since the request is
- completed as an HTTP/1.1 request. After commencing the HTTP/2
- connection, stream 1 is used for the response.
-
-3.2.1. HTTP2-Settings Header Field
-
- A request that upgrades from HTTP/1.1 to HTTP/2 MUST include exactly
- one "HTTP2-Settings" header field. The HTTP2-Settings header field
- is a connection-specific header field that includes parameters that
- govern the HTTP/2 connection, provided in anticipation of the server
- accepting the request to upgrade.
-
- HTTP2-Settings = token68
-
-
-
-Belshe, et al. Standards Track [Page 9]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- A server MUST NOT upgrade the connection to HTTP/2 if this header
- field is not present or if more than one is present. A server MUST
- NOT send this header field.
-
- The content of the HTTP2-Settings header field is the payload of a
- SETTINGS frame (Section 6.5), encoded as a base64url string (that is,
- the URL- and filename-safe Base64 encoding described in Section 5 of
- [RFC4648], with any trailing '=' characters omitted). The ABNF
- [RFC5234] production for "token68" is defined in Section 2.1 of
- [RFC7235].
-
- Since the upgrade is only intended to apply to the immediate
- connection, a client sending the HTTP2-Settings header field MUST
- also send "HTTP2-Settings" as a connection option in the Connection
- header field to prevent it from being forwarded (see Section 6.1 of
- [RFC7230]).
-
- A server decodes and interprets these values as it would any other
- SETTINGS frame. Explicit acknowledgement of these settings
- (Section 6.5.3) is not necessary, since a 101 response serves as
- implicit acknowledgement. Providing these values in the upgrade
- request gives a client an opportunity to provide parameters prior to
- receiving any frames from the server.
-
-3.3. Starting HTTP/2 for "https" URIs
-
- A client that makes a request to an "https" URI uses TLS [TLS12] with
- the application-layer protocol negotiation (ALPN) extension
- [TLS-ALPN].
-
- HTTP/2 over TLS uses the "h2" protocol identifier. The "h2c"
- protocol identifier MUST NOT be sent by a client or selected by a
- server; the "h2c" protocol identifier describes a protocol that does
- not use TLS.
-
- Once TLS negotiation is complete, both the client and the server MUST
- send a connection preface (Section 3.5).
-
-3.4. Starting HTTP/2 with Prior Knowledge
-
- A client can learn that a particular server supports HTTP/2 by other
- means. For example, [ALT-SVC] describes a mechanism for advertising
- this capability.
-
- A client MUST send the connection preface (Section 3.5) and then MAY
- immediately send HTTP/2 frames to such a server; servers can identify
- these connections by the presence of the connection preface. This
-
-
-
-
-Belshe, et al. Standards Track [Page 10]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- only affects the establishment of HTTP/2 connections over cleartext
- TCP; implementations that support HTTP/2 over TLS MUST use protocol
- negotiation in TLS [TLS-ALPN].
-
- Likewise, the server MUST send a connection preface (Section 3.5).
-
- Without additional information, prior support for HTTP/2 is not a
- strong signal that a given server will support HTTP/2 for future
- connections. For example, it is possible for server configurations
- to change, for configurations to differ between instances in
- clustered servers, or for network conditions to change.
-
-3.5. HTTP/2 Connection Preface
-
- In HTTP/2, each endpoint is required to send a connection preface as
- a final confirmation of the protocol in use and to establish the
- initial settings for the HTTP/2 connection. The client and server
- each send a different connection preface.
-
- The client connection preface starts with a sequence of 24 octets,
- which in hex notation is:
-
- 0x505249202a20485454502f322e300d0a0d0a534d0d0a0d0a
-
- That is, the connection preface starts with the string "PRI *
- HTTP/2.0\r\n\r\nSM\r\n\r\n"). This sequence MUST be followed by a
- SETTINGS frame (Section 6.5), which MAY be empty. The client sends
- the client connection preface immediately upon receipt of a 101
- (Switching Protocols) response (indicating a successful upgrade) or
- as the first application data octets of a TLS connection. If
- starting an HTTP/2 connection with prior knowledge of server support
- for the protocol, the client connection preface is sent upon
- connection establishment.
-
- Note: The client connection preface is selected so that a large
- proportion of HTTP/1.1 or HTTP/1.0 servers and intermediaries do
- not attempt to process further frames. Note that this does not
- address the concerns raised in [TALKING].
-
- The server connection preface consists of a potentially empty
- SETTINGS frame (Section 6.5) that MUST be the first frame the server
- sends in the HTTP/2 connection.
-
- The SETTINGS frames received from a peer as part of the connection
- preface MUST be acknowledged (see Section 6.5.3) after sending the
- connection preface.
-
-
-
-
-
-Belshe, et al. Standards Track [Page 11]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- To avoid unnecessary latency, clients are permitted to send
- additional frames to the server immediately after sending the client
- connection preface, without waiting to receive the server connection
- preface. It is important to note, however, that the server
- connection preface SETTINGS frame might include parameters that
- necessarily alter how a client is expected to communicate with the
- server. Upon receiving the SETTINGS frame, the client is expected to
- honor any parameters established. In some configurations, it is
- possible for the server to transmit SETTINGS before the client sends
- additional frames, providing an opportunity to avoid this issue.
-
- Clients and servers MUST treat an invalid connection preface as a
- connection error (Section 5.4.1) of type PROTOCOL_ERROR. A GOAWAY
- frame (Section 6.8) MAY be omitted in this case, since an invalid
- preface indicates that the peer is not using HTTP/2.
-
-4. HTTP Frames
-
- Once the HTTP/2 connection is established, endpoints can begin
- exchanging frames.
-
-4.1. Frame Format
-
- All frames begin with a fixed 9-octet header followed by a variable-
- length payload.
-
- +-----------------------------------------------+
- | Length (24) |
- +---------------+---------------+---------------+
- | Type (8) | Flags (8) |
- +-+-------------+---------------+-------------------------------+
- |R| Stream Identifier (31) |
- +=+=============================================================+
- | Frame Payload (0...) ...
- +---------------------------------------------------------------+
-
- Figure 1: Frame Layout
-
- The fields of the frame header are defined as:
-
- Length: The length of the frame payload expressed as an unsigned
- 24-bit integer. Values greater than 2^14 (16,384) MUST NOT be
- sent unless the receiver has set a larger value for
- SETTINGS_MAX_FRAME_SIZE.
-
- The 9 octets of the frame header are not included in this value.
-
-
-
-
-
-Belshe, et al. Standards Track [Page 12]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- Type: The 8-bit type of the frame. The frame type determines the
- format and semantics of the frame. Implementations MUST ignore
- and discard any frame that has a type that is unknown.
-
- Flags: An 8-bit field reserved for boolean flags specific to the
- frame type.
-
- Flags are assigned semantics specific to the indicated frame type.
- Flags that have no defined semantics for a particular frame type
- MUST be ignored and MUST be left unset (0x0) when sending.
-
- R: A reserved 1-bit field. The semantics of this bit are undefined,
- and the bit MUST remain unset (0x0) when sending and MUST be
- ignored when receiving.
-
- Stream Identifier: A stream identifier (see Section 5.1.1) expressed
- as an unsigned 31-bit integer. The value 0x0 is reserved for
- frames that are associated with the connection as a whole as
- opposed to an individual stream.
-
- The structure and content of the frame payload is dependent entirely
- on the frame type.
-
-4.2. Frame Size
-
- The size of a frame payload is limited by the maximum size that a
- receiver advertises in the SETTINGS_MAX_FRAME_SIZE setting. This
- setting can have any value between 2^14 (16,384) and 2^24-1
- (16,777,215) octets, inclusive.
-
- All implementations MUST be capable of receiving and minimally
- processing frames up to 2^14 octets in length, plus the 9-octet frame
- header (Section 4.1). The size of the frame header is not included
- when describing frame sizes.
-
- Note: Certain frame types, such as PING (Section 6.7), impose
- additional limits on the amount of payload data allowed.
-
- An endpoint MUST send an error code of FRAME_SIZE_ERROR if a frame
- exceeds the size defined in SETTINGS_MAX_FRAME_SIZE, exceeds any
- limit defined for the frame type, or is too small to contain
- mandatory frame data. A frame size error in a frame that could alter
- the state of the entire connection MUST be treated as a connection
- error (Section 5.4.1); this includes any frame carrying a header
- block (Section 4.3) (that is, HEADERS, PUSH_PROMISE, and
- CONTINUATION), SETTINGS, and any frame with a stream identifier of 0.
-
-
-
-
-
-Belshe, et al. Standards Track [Page 13]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- Endpoints are not obligated to use all available space in a frame.
- Responsiveness can be improved by using frames that are smaller than
- the permitted maximum size. Sending large frames can result in
- delays in sending time-sensitive frames (such as RST_STREAM,
- WINDOW_UPDATE, or PRIORITY), which, if blocked by the transmission of
- a large frame, could affect performance.
-
-4.3. Header Compression and Decompression
-
- Just as in HTTP/1, a header field in HTTP/2 is a name with one or
- more associated values. Header fields are used within HTTP request
- and response messages as well as in server push operations (see
- Section 8.2).
-
- Header lists are collections of zero or more header fields. When
- transmitted over a connection, a header list is serialized into a
- header block using HTTP header compression [COMPRESSION]. The
- serialized header block is then divided into one or more octet
- sequences, called header block fragments, and transmitted within the
- payload of HEADERS (Section 6.2), PUSH_PROMISE (Section 6.6), or
- CONTINUATION (Section 6.10) frames.
-
- The Cookie header field [COOKIE] is treated specially by the HTTP
- mapping (see Section 8.1.2.5).
-
- A receiving endpoint reassembles the header block by concatenating
- its fragments and then decompresses the block to reconstruct the
- header list.
-
- A complete header block consists of either:
-
- o a single HEADERS or PUSH_PROMISE frame, with the END_HEADERS flag
- set, or
-
- o a HEADERS or PUSH_PROMISE frame with the END_HEADERS flag cleared
- and one or more CONTINUATION frames, where the last CONTINUATION
- frame has the END_HEADERS flag set.
-
- Header compression is stateful. One compression context and one
- decompression context are used for the entire connection. A decoding
- error in a header block MUST be treated as a connection error
- (Section 5.4.1) of type COMPRESSION_ERROR.
-
- Each header block is processed as a discrete unit. Header blocks
- MUST be transmitted as a contiguous sequence of frames, with no
- interleaved frames of any other type or from any other stream. The
- last frame in a sequence of HEADERS or CONTINUATION frames has the
-
-
-
-
-Belshe, et al. Standards Track [Page 14]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- END_HEADERS flag set. The last frame in a sequence of PUSH_PROMISE
- or CONTINUATION frames has the END_HEADERS flag set. This allows a
- header block to be logically equivalent to a single frame.
-
- Header block fragments can only be sent as the payload of HEADERS,
- PUSH_PROMISE, or CONTINUATION frames because these frames carry data
- that can modify the compression context maintained by a receiver. An
- endpoint receiving HEADERS, PUSH_PROMISE, or CONTINUATION frames
- needs to reassemble header blocks and perform decompression even if
- the frames are to be discarded. A receiver MUST terminate the
- connection with a connection error (Section 5.4.1) of type
- COMPRESSION_ERROR if it does not decompress a header block.
-
-5. Streams and Multiplexing
-
- A "stream" is an independent, bidirectional sequence of frames
- exchanged between the client and server within an HTTP/2 connection.
- Streams have several important characteristics:
-
- o A single HTTP/2 connection can contain multiple concurrently open
- streams, with either endpoint interleaving frames from multiple
- streams.
-
- o Streams can be established and used unilaterally or shared by
- either the client or server.
-
- o Streams can be closed by either endpoint.
-
- o The order in which frames are sent on a stream is significant.
- Recipients process frames in the order they are received. In
- particular, the order of HEADERS and DATA frames is semantically
- significant.
-
- o Streams are identified by an integer. Stream identifiers are
- assigned to streams by the endpoint initiating the stream.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 15]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-5.1. Stream States
-
- The lifecycle of a stream is shown in Figure 2.
-
- +--------+
- send PP | | recv PP
- ,--------| idle |--------.
- / | | \
- v +--------+ v
- +----------+ | +----------+
- | | | send H / | |
- ,------| reserved | | recv H | reserved |------.
- | | (local) | | | (remote) | |
- | +----------+ v +----------+ |
- | | +--------+ | |
- | | recv ES | | send ES | |
- | send H | ,-------| open |-------. | recv H |
- | | / | | \ | |
- | v v +--------+ v v |
- | +----------+ | +----------+ |
- | | half | | | half | |
- | | closed | | send R / | closed | |
- | | (remote) | | recv R | (local) | |
- | +----------+ | +----------+ |
- | | | | |
- | | send ES / | recv ES / | |
- | | send R / v send R / | |
- | | recv R +--------+ recv R | |
- | send R / `----------->| |<-----------' send R / |
- | recv R | closed | recv R |
- `----------------------->| |<----------------------'
- +--------+
-
- send: endpoint sends this frame
- recv: endpoint receives this frame
-
- H: HEADERS frame (with implied CONTINUATIONs)
- PP: PUSH_PROMISE frame (with implied CONTINUATIONs)
- ES: END_STREAM flag
- R: RST_STREAM frame
-
- Figure 2: Stream States
-
- Note that this diagram shows stream state transitions and the frames
- and flags that affect those transitions only. In this regard,
- CONTINUATION frames do not result in state transitions; they are
- effectively part of the HEADERS or PUSH_PROMISE that they follow.
-
-
-
-
-Belshe, et al. Standards Track [Page 16]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- For the purpose of state transitions, the END_STREAM flag is
- processed as a separate event to the frame that bears it; a HEADERS
- frame with the END_STREAM flag set can cause two state transitions.
-
- Both endpoints have a subjective view of the state of a stream that
- could be different when frames are in transit. Endpoints do not
- coordinate the creation of streams; they are created unilaterally by
- either endpoint. The negative consequences of a mismatch in states
- are limited to the "closed" state after sending RST_STREAM, where
- frames might be received for some time after closing.
-
- Streams have the following states:
-
- idle:
- All streams start in the "idle" state.
-
- The following transitions are valid from this state:
-
- * Sending or receiving a HEADERS frame causes the stream to
- become "open". The stream identifier is selected as described
- in Section 5.1.1. The same HEADERS frame can also cause a
- stream to immediately become "half-closed".
-
- * Sending a PUSH_PROMISE frame on another stream reserves the
- idle stream that is identified for later use. The stream state
- for the reserved stream transitions to "reserved (local)".
-
- * Receiving a PUSH_PROMISE frame on another stream reserves an
- idle stream that is identified for later use. The stream state
- for the reserved stream transitions to "reserved (remote)".
-
- * Note that the PUSH_PROMISE frame is not sent on the idle stream
- but references the newly reserved stream in the Promised Stream
- ID field.
-
- Receiving any frame other than HEADERS or PRIORITY on a stream in
- this state MUST be treated as a connection error (Section 5.4.1)
- of type PROTOCOL_ERROR.
-
- reserved (local):
- A stream in the "reserved (local)" state is one that has been
- promised by sending a PUSH_PROMISE frame. A PUSH_PROMISE frame
- reserves an idle stream by associating the stream with an open
- stream that was initiated by the remote peer (see Section 8.2).
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 17]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- In this state, only the following transitions are possible:
-
- * The endpoint can send a HEADERS frame. This causes the stream
- to open in a "half-closed (remote)" state.
-
- * Either endpoint can send a RST_STREAM frame to cause the stream
- to become "closed". This releases the stream reservation.
-
-
- An endpoint MUST NOT send any type of frame other than HEADERS,
- RST_STREAM, or PRIORITY in this state.
-
- A PRIORITY or WINDOW_UPDATE frame MAY be received in this state.
- Receiving any type of frame other than RST_STREAM, PRIORITY, or
- WINDOW_UPDATE on a stream in this state MUST be treated as a
- connection error (Section 5.4.1) of type PROTOCOL_ERROR.
-
- reserved (remote):
- A stream in the "reserved (remote)" state has been reserved by a
- remote peer.
-
- In this state, only the following transitions are possible:
-
- * Receiving a HEADERS frame causes the stream to transition to
- "half-closed (local)".
-
- * Either endpoint can send a RST_STREAM frame to cause the stream
- to become "closed". This releases the stream reservation.
-
- An endpoint MAY send a PRIORITY frame in this state to
- reprioritize the reserved stream. An endpoint MUST NOT send any
- type of frame other than RST_STREAM, WINDOW_UPDATE, or PRIORITY in
- this state.
-
- Receiving any type of frame other than HEADERS, RST_STREAM, or
- PRIORITY on a stream in this state MUST be treated as a connection
- error (Section 5.4.1) of type PROTOCOL_ERROR.
-
- open:
- A stream in the "open" state may be used by both peers to send
- frames of any type. In this state, sending peers observe
- advertised stream-level flow-control limits (Section 5.2).
-
- From this state, either endpoint can send a frame with an
- END_STREAM flag set, which causes the stream to transition into
- one of the "half-closed" states. An endpoint sending an
-
-
-
-
-
-Belshe, et al. Standards Track [Page 18]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- END_STREAM flag causes the stream state to become "half-closed
- (local)"; an endpoint receiving an END_STREAM flag causes the
- stream state to become "half-closed (remote)".
-
- Either endpoint can send a RST_STREAM frame from this state,
- causing it to transition immediately to "closed".
-
- half-closed (local):
- A stream that is in the "half-closed (local)" state cannot be used
- for sending frames other than WINDOW_UPDATE, PRIORITY, and
- RST_STREAM.
-
- A stream transitions from this state to "closed" when a frame that
- contains an END_STREAM flag is received or when either peer sends
- a RST_STREAM frame.
-
- An endpoint can receive any type of frame in this state.
- Providing flow-control credit using WINDOW_UPDATE frames is
- necessary to continue receiving flow-controlled frames. In this
- state, a receiver can ignore WINDOW_UPDATE frames, which might
- arrive for a short period after a frame bearing the END_STREAM
- flag is sent.
-
- PRIORITY frames received in this state are used to reprioritize
- streams that depend on the identified stream.
-
- half-closed (remote):
- A stream that is "half-closed (remote)" is no longer being used by
- the peer to send frames. In this state, an endpoint is no longer
- obligated to maintain a receiver flow-control window.
-
- If an endpoint receives additional frames, other than
- WINDOW_UPDATE, PRIORITY, or RST_STREAM, for a stream that is in
- this state, it MUST respond with a stream error (Section 5.4.2) of
- type STREAM_CLOSED.
-
- A stream that is "half-closed (remote)" can be used by the
- endpoint to send frames of any type. In this state, the endpoint
- continues to observe advertised stream-level flow-control limits
- (Section 5.2).
-
- A stream can transition from this state to "closed" by sending a
- frame that contains an END_STREAM flag or when either peer sends a
- RST_STREAM frame.
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 19]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- closed:
- The "closed" state is the terminal state.
-
- An endpoint MUST NOT send frames other than PRIORITY on a closed
- stream. An endpoint that receives any frame other than PRIORITY
- after receiving a RST_STREAM MUST treat that as a stream error
- (Section 5.4.2) of type STREAM_CLOSED. Similarly, an endpoint
- that receives any frames after receiving a frame with the
- END_STREAM flag set MUST treat that as a connection error
- (Section 5.4.1) of type STREAM_CLOSED, unless the frame is
- permitted as described below.
-
- WINDOW_UPDATE or RST_STREAM frames can be received in this state
- for a short period after a DATA or HEADERS frame containing an
- END_STREAM flag is sent. Until the remote peer receives and
- processes RST_STREAM or the frame bearing the END_STREAM flag, it
- might send frames of these types. Endpoints MUST ignore
- WINDOW_UPDATE or RST_STREAM frames received in this state, though
- endpoints MAY choose to treat frames that arrive a significant
- time after sending END_STREAM as a connection error
- (Section 5.4.1) of type PROTOCOL_ERROR.
-
- PRIORITY frames can be sent on closed streams to prioritize
- streams that are dependent on the closed stream. Endpoints SHOULD
- process PRIORITY frames, though they can be ignored if the stream
- has been removed from the dependency tree (see Section 5.3.4).
-
- If this state is reached as a result of sending a RST_STREAM
- frame, the peer that receives the RST_STREAM might have already
- sent -- or enqueued for sending -- frames on the stream that
- cannot be withdrawn. An endpoint MUST ignore frames that it
- receives on closed streams after it has sent a RST_STREAM frame.
- An endpoint MAY choose to limit the period over which it ignores
- frames and treat frames that arrive after this time as being in
- error.
-
- Flow-controlled frames (i.e., DATA) received after sending
- RST_STREAM are counted toward the connection flow-control window.
- Even though these frames might be ignored, because they are sent
- before the sender receives the RST_STREAM, the sender will
- consider the frames to count against the flow-control window.
-
- An endpoint might receive a PUSH_PROMISE frame after it sends
- RST_STREAM. PUSH_PROMISE causes a stream to become "reserved"
- even if the associated stream has been reset. Therefore, a
- RST_STREAM is needed to close an unwanted promised stream.
-
-
-
-
-
-Belshe, et al. Standards Track [Page 20]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- In the absence of more specific guidance elsewhere in this document,
- implementations SHOULD treat the receipt of a frame that is not
- expressly permitted in the description of a state as a connection
- error (Section 5.4.1) of type PROTOCOL_ERROR. Note that PRIORITY can
- be sent and received in any stream state. Frames of unknown types
- are ignored.
-
- An example of the state transitions for an HTTP request/response
- exchange can be found in Section 8.1. An example of the state
- transitions for server push can be found in Sections 8.2.1 and 8.2.2.
-
-5.1.1. Stream Identifiers
-
- Streams are identified with an unsigned 31-bit integer. Streams
- initiated by a client MUST use odd-numbered stream identifiers; those
- initiated by the server MUST use even-numbered stream identifiers. A
- stream identifier of zero (0x0) is used for connection control
- messages; the stream identifier of zero cannot be used to establish a
- new stream.
-
- HTTP/1.1 requests that are upgraded to HTTP/2 (see Section 3.2) are
- responded to with a stream identifier of one (0x1). After the
- upgrade completes, stream 0x1 is "half-closed (local)" to the client.
- Therefore, stream 0x1 cannot be selected as a new stream identifier
- by a client that upgrades from HTTP/1.1.
-
- The identifier of a newly established stream MUST be numerically
- greater than all streams that the initiating endpoint has opened or
- reserved. This governs streams that are opened using a HEADERS frame
- and streams that are reserved using PUSH_PROMISE. An endpoint that
- receives an unexpected stream identifier MUST respond with a
- connection error (Section 5.4.1) of type PROTOCOL_ERROR.
-
- The first use of a new stream identifier implicitly closes all
- streams in the "idle" state that might have been initiated by that
- peer with a lower-valued stream identifier. For example, if a client
- sends a HEADERS frame on stream 7 without ever sending a frame on
- stream 5, then stream 5 transitions to the "closed" state when the
- first frame for stream 7 is sent or received.
-
- Stream identifiers cannot be reused. Long-lived connections can
- result in an endpoint exhausting the available range of stream
- identifiers. A client that is unable to establish a new stream
- identifier can establish a new connection for new streams. A server
- that is unable to establish a new stream identifier can send a GOAWAY
- frame so that the client is forced to open a new connection for new
- streams.
-
-
-
-
-Belshe, et al. Standards Track [Page 21]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-5.1.2. Stream Concurrency
-
- A peer can limit the number of concurrently active streams using the
- SETTINGS_MAX_CONCURRENT_STREAMS parameter (see Section 6.5.2) within
- a SETTINGS frame. The maximum concurrent streams setting is specific
- to each endpoint and applies only to the peer that receives the
- setting. That is, clients specify the maximum number of concurrent
- streams the server can initiate, and servers specify the maximum
- number of concurrent streams the client can initiate.
-
- Streams that are in the "open" state or in either of the "half-
- closed" states count toward the maximum number of streams that an
- endpoint is permitted to open. Streams in any of these three states
- count toward the limit advertised in the
- SETTINGS_MAX_CONCURRENT_STREAMS setting. Streams in either of the
- "reserved" states do not count toward the stream limit.
-
- Endpoints MUST NOT exceed the limit set by their peer. An endpoint
- that receives a HEADERS frame that causes its advertised concurrent
- stream limit to be exceeded MUST treat this as a stream error
- (Section 5.4.2) of type PROTOCOL_ERROR or REFUSED_STREAM. The choice
- of error code determines whether the endpoint wishes to enable
- automatic retry (see Section 8.1.4) for details).
-
- An endpoint that wishes to reduce the value of
- SETTINGS_MAX_CONCURRENT_STREAMS to a value that is below the current
- number of open streams can either close streams that exceed the new
- value or allow streams to complete.
-
-5.2. Flow Control
-
- Using streams for multiplexing introduces contention over use of the
- TCP connection, resulting in blocked streams. A flow-control scheme
- ensures that streams on the same connection do not destructively
- interfere with each other. Flow control is used for both individual
- streams and for the connection as a whole.
-
- HTTP/2 provides for flow control through use of the WINDOW_UPDATE
- frame (Section 6.9).
-
-
-
-
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 22]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-5.2.1. Flow-Control Principles
-
- HTTP/2 stream flow control aims to allow a variety of flow-control
- algorithms to be used without requiring protocol changes. Flow
- control in HTTP/2 has the following characteristics:
-
- 1. Flow control is specific to a connection. Both types of flow
- control are between the endpoints of a single hop and not over
- the entire end-to-end path.
-
- 2. Flow control is based on WINDOW_UPDATE frames. Receivers
- advertise how many octets they are prepared to receive on a
- stream and for the entire connection. This is a credit-based
- scheme.
-
- 3. Flow control is directional with overall control provided by the
- receiver. A receiver MAY choose to set any window size that it
- desires for each stream and for the entire connection. A sender
- MUST respect flow-control limits imposed by a receiver. Clients,
- servers, and intermediaries all independently advertise their
- flow-control window as a receiver and abide by the flow-control
- limits set by their peer when sending.
-
- 4. The initial value for the flow-control window is 65,535 octets
- for both new streams and the overall connection.
-
- 5. The frame type determines whether flow control applies to a
- frame. Of the frames specified in this document, only DATA
- frames are subject to flow control; all other frame types do not
- consume space in the advertised flow-control window. This
- ensures that important control frames are not blocked by flow
- control.
-
- 6. Flow control cannot be disabled.
-
- 7. HTTP/2 defines only the format and semantics of the WINDOW_UPDATE
- frame (Section 6.9). This document does not stipulate how a
- receiver decides when to send this frame or the value that it
- sends, nor does it specify how a sender chooses to send packets.
- Implementations are able to select any algorithm that suits their
- needs.
-
- Implementations are also responsible for managing how requests and
- responses are sent based on priority, choosing how to avoid head-of-
- line blocking for requests, and managing the creation of new streams.
- Algorithm choices for these could interact with any flow-control
- algorithm.
-
-
-
-
-Belshe, et al. Standards Track [Page 23]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-5.2.2. Appropriate Use of Flow Control
-
- Flow control is defined to protect endpoints that are operating under
- resource constraints. For example, a proxy needs to share memory
- between many connections and also might have a slow upstream
- connection and a fast downstream one. Flow-control addresses cases
- where the receiver is unable to process data on one stream yet wants
- to continue to process other streams in the same connection.
-
- Deployments that do not require this capability can advertise a flow-
- control window of the maximum size (2^31-1) and can maintain this
- window by sending a WINDOW_UPDATE frame when any data is received.
- This effectively disables flow control for that receiver.
- Conversely, a sender is always subject to the flow-control window
- advertised by the receiver.
-
- Deployments with constrained resources (for example, memory) can
- employ flow control to limit the amount of memory a peer can consume.
- Note, however, that this can lead to suboptimal use of available
- network resources if flow control is enabled without knowledge of the
- bandwidth-delay product (see [RFC7323]).
-
- Even with full awareness of the current bandwidth-delay product,
- implementation of flow control can be difficult. When using flow
- control, the receiver MUST read from the TCP receive buffer in a
- timely fashion. Failure to do so could lead to a deadlock when
- critical frames, such as WINDOW_UPDATE, are not read and acted upon.
-
-5.3. Stream Priority
-
- A client can assign a priority for a new stream by including
- prioritization information in the HEADERS frame (Section 6.2) that
- opens the stream. At any other time, the PRIORITY frame
- (Section 6.3) can be used to change the priority of a stream.
-
- The purpose of prioritization is to allow an endpoint to express how
- it would prefer its peer to allocate resources when managing
- concurrent streams. Most importantly, priority can be used to select
- streams for transmitting frames when there is limited capacity for
- sending.
-
- Streams can be prioritized by marking them as dependent on the
- completion of other streams (Section 5.3.1). Each dependency is
- assigned a relative weight, a number that is used to determine the
- relative proportion of available resources that are assigned to
- streams dependent on the same stream.
-
-
-
-
-
-Belshe, et al. Standards Track [Page 24]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- Explicitly setting the priority for a stream is input to a
- prioritization process. It does not guarantee any particular
- processing or transmission order for the stream relative to any other
- stream. An endpoint cannot force a peer to process concurrent
- streams in a particular order using priority. Expressing priority is
- therefore only a suggestion.
-
- Prioritization information can be omitted from messages. Defaults
- are used prior to any explicit values being provided (Section 5.3.5).
-
-5.3.1. Stream Dependencies
-
- Each stream can be given an explicit dependency on another stream.
- Including a dependency expresses a preference to allocate resources
- to the identified stream rather than to the dependent stream.
-
- A stream that is not dependent on any other stream is given a stream
- dependency of 0x0. In other words, the non-existent stream 0 forms
- the root of the tree.
-
- A stream that depends on another stream is a dependent stream. The
- stream upon which a stream is dependent is a parent stream. A
- dependency on a stream that is not currently in the tree -- such as a
- stream in the "idle" state -- results in that stream being given a
- default priority (Section 5.3.5).
-
- When assigning a dependency on another stream, the stream is added as
- a new dependency of the parent stream. Dependent streams that share
- the same parent are not ordered with respect to each other. For
- example, if streams B and C are dependent on stream A, and if stream
- D is created with a dependency on stream A, this results in a
- dependency order of A followed by B, C, and D in any order.
-
- A A
- / \ ==> /|\
- B C B D C
-
- Figure 3: Example of Default Dependency Creation
-
- An exclusive flag allows for the insertion of a new level of
- dependencies. The exclusive flag causes the stream to become the
- sole dependency of its parent stream, causing other dependencies to
- become dependent on the exclusive stream. In the previous example,
- if stream D is created with an exclusive dependency on stream A, this
- results in D becoming the dependency parent of B and C.
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 25]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- A
- A |
- / \ ==> D
- B C / \
- B C
-
- Figure 4: Example of Exclusive Dependency Creation
-
- Inside the dependency tree, a dependent stream SHOULD only be
- allocated resources if either all of the streams that it depends on
- (the chain of parent streams up to 0x0) are closed or it is not
- possible to make progress on them.
-
- A stream cannot depend on itself. An endpoint MUST treat this as a
- stream error (Section 5.4.2) of type PROTOCOL_ERROR.
-
-5.3.2. Dependency Weighting
-
- All dependent streams are allocated an integer weight between 1 and
- 256 (inclusive).
-
- Streams with the same parent SHOULD be allocated resources
- proportionally based on their weight. Thus, if stream B depends on
- stream A with weight 4, stream C depends on stream A with weight 12,
- and no progress can be made on stream A, stream B ideally receives
- one-third of the resources allocated to stream C.
-
-5.3.3. Reprioritization
-
- Stream priorities are changed using the PRIORITY frame. Setting a
- dependency causes a stream to become dependent on the identified
- parent stream.
-
- Dependent streams move with their parent stream if the parent is
- reprioritized. Setting a dependency with the exclusive flag for a
- reprioritized stream causes all the dependencies of the new parent
- stream to become dependent on the reprioritized stream.
-
- If a stream is made dependent on one of its own dependencies, the
- formerly dependent stream is first moved to be dependent on the
- reprioritized stream's previous parent. The moved dependency retains
- its weight.
-
- For example, consider an original dependency tree where B and C
- depend on A, D and E depend on C, and F depends on D. If A is made
- dependent on D, then D takes the place of A. All other dependency
- relationships stay the same, except for F, which becomes dependent on
- A if the reprioritization is exclusive.
-
-
-
-Belshe, et al. Standards Track [Page 26]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- x x x x
- | / \ | |
- A D A D D
- / \ / / \ / \ |
- B C ==> F B C ==> F A OR A
- / \ | / \ /|\
- D E E B C B C F
- | | |
- F E E
- (intermediate) (non-exclusive) (exclusive)
-
- Figure 5: Example of Dependency Reordering
-
-5.3.4. Prioritization State Management
-
- When a stream is removed from the dependency tree, its dependencies
- can be moved to become dependent on the parent of the closed stream.
- The weights of new dependencies are recalculated by distributing the
- weight of the dependency of the closed stream proportionally based on
- the weights of its dependencies.
-
- Streams that are removed from the dependency tree cause some
- prioritization information to be lost. Resources are shared between
- streams with the same parent stream, which means that if a stream in
- that set closes or becomes blocked, any spare capacity allocated to a
- stream is distributed to the immediate neighbors of the stream.
- However, if the common dependency is removed from the tree, those
- streams share resources with streams at the next highest level.
-
- For example, assume streams A and B share a parent, and streams C and
- D both depend on stream A. Prior to the removal of stream A, if
- streams A and D are unable to proceed, then stream C receives all the
- resources dedicated to stream A. If stream A is removed from the
- tree, the weight of stream A is divided between streams C and D. If
- stream D is still unable to proceed, this results in stream C
- receiving a reduced proportion of resources. For equal starting
- weights, C receives one third, rather than one half, of available
- resources.
-
- It is possible for a stream to become closed while prioritization
- information that creates a dependency on that stream is in transit.
- If a stream identified in a dependency has no associated priority
- information, then the dependent stream is instead assigned a default
- priority (Section 5.3.5). This potentially creates suboptimal
- prioritization, since the stream could be given a priority that is
- different from what is intended.
-
-
-
-
-
-Belshe, et al. Standards Track [Page 27]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- To avoid these problems, an endpoint SHOULD retain stream
- prioritization state for a period after streams become closed. The
- longer state is retained, the lower the chance that streams are
- assigned incorrect or default priority values.
-
- Similarly, streams that are in the "idle" state can be assigned
- priority or become a parent of other streams. This allows for the
- creation of a grouping node in the dependency tree, which enables
- more flexible expressions of priority. Idle streams begin with a
- default priority (Section 5.3.5).
-
- The retention of priority information for streams that are not
- counted toward the limit set by SETTINGS_MAX_CONCURRENT_STREAMS could
- create a large state burden for an endpoint. Therefore, the amount
- of prioritization state that is retained MAY be limited.
-
- The amount of additional state an endpoint maintains for
- prioritization could be dependent on load; under high load,
- prioritization state can be discarded to limit resource commitments.
- In extreme cases, an endpoint could even discard prioritization state
- for active or reserved streams. If a limit is applied, endpoints
- SHOULD maintain state for at least as many streams as allowed by
- their setting for SETTINGS_MAX_CONCURRENT_STREAMS. Implementations
- SHOULD also attempt to retain state for streams that are in active
- use in the priority tree.
-
- If it has retained enough state to do so, an endpoint receiving a
- PRIORITY frame that changes the priority of a closed stream SHOULD
- alter the dependencies of the streams that depend on it.
-
-5.3.5. Default Priorities
-
- All streams are initially assigned a non-exclusive dependency on
- stream 0x0. Pushed streams (Section 8.2) initially depend on their
- associated stream. In both cases, streams are assigned a default
- weight of 16.
-
-5.4. Error Handling
-
- HTTP/2 framing permits two classes of error:
-
- o An error condition that renders the entire connection unusable is
- a connection error.
-
- o An error in an individual stream is a stream error.
-
- A list of error codes is included in Section 7.
-
-
-
-
-Belshe, et al. Standards Track [Page 28]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-5.4.1. Connection Error Handling
-
- A connection error is any error that prevents further processing of
- the frame layer or corrupts any connection state.
-
- An endpoint that encounters a connection error SHOULD first send a
- GOAWAY frame (Section 6.8) with the stream identifier of the last
- stream that it successfully received from its peer. The GOAWAY frame
- includes an error code that indicates why the connection is
- terminating. After sending the GOAWAY frame for an error condition,
- the endpoint MUST close the TCP connection.
-
- It is possible that the GOAWAY will not be reliably received by the
- receiving endpoint ([RFC7230], Section 6.6 describes how an immediate
- connection close can result in data loss). In the event of a
- connection error, GOAWAY only provides a best-effort attempt to
- communicate with the peer about why the connection is being
- terminated.
-
- An endpoint can end a connection at any time. In particular, an
- endpoint MAY choose to treat a stream error as a connection error.
- Endpoints SHOULD send a GOAWAY frame when ending a connection,
- providing that circumstances permit it.
-
-5.4.2. Stream Error Handling
-
- A stream error is an error related to a specific stream that does not
- affect processing of other streams.
-
- An endpoint that detects a stream error sends a RST_STREAM frame
- (Section 6.4) that contains the stream identifier of the stream where
- the error occurred. The RST_STREAM frame includes an error code that
- indicates the type of error.
-
- A RST_STREAM is the last frame that an endpoint can send on a stream.
- The peer that sends the RST_STREAM frame MUST be prepared to receive
- any frames that were sent or enqueued for sending by the remote peer.
- These frames can be ignored, except where they modify connection
- state (such as the state maintained for header compression
- (Section 4.3) or flow control).
-
- Normally, an endpoint SHOULD NOT send more than one RST_STREAM frame
- for any stream. However, an endpoint MAY send additional RST_STREAM
- frames if it receives frames on a closed stream after more than a
- round-trip time. This behavior is permitted to deal with misbehaving
- implementations.
-
-
-
-
-
-Belshe, et al. Standards Track [Page 29]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- To avoid looping, an endpoint MUST NOT send a RST_STREAM in response
- to a RST_STREAM frame.
-
-5.4.3. Connection Termination
-
- If the TCP connection is closed or reset while streams remain in
- "open" or "half-closed" state, then the affected streams cannot be
- automatically retried (see Section 8.1.4 for details).
-
-5.5. Extending HTTP/2
-
- HTTP/2 permits extension of the protocol. Within the limitations
- described in this section, protocol extensions can be used to provide
- additional services or alter any aspect of the protocol. Extensions
- are effective only within the scope of a single HTTP/2 connection.
-
- This applies to the protocol elements defined in this document. This
- does not affect the existing options for extending HTTP, such as
- defining new methods, status codes, or header fields.
-
- Extensions are permitted to use new frame types (Section 4.1), new
- settings (Section 6.5.2), or new error codes (Section 7). Registries
- are established for managing these extension points: frame types
- (Section 11.2), settings (Section 11.3), and error codes
- (Section 11.4).
-
- Implementations MUST ignore unknown or unsupported values in all
- extensible protocol elements. Implementations MUST discard frames
- that have unknown or unsupported types. This means that any of these
- extension points can be safely used by extensions without prior
- arrangement or negotiation. However, extension frames that appear in
- the middle of a header block (Section 4.3) are not permitted; these
- MUST be treated as a connection error (Section 5.4.1) of type
- PROTOCOL_ERROR.
-
- Extensions that could change the semantics of existing protocol
- components MUST be negotiated before being used. For example, an
- extension that changes the layout of the HEADERS frame cannot be used
- until the peer has given a positive signal that this is acceptable.
- In this case, it could also be necessary to coordinate when the
- revised layout comes into effect. Note that treating any frames
- other than DATA frames as flow controlled is such a change in
- semantics and can only be done through negotiation.
-
- This document doesn't mandate a specific method for negotiating the
- use of an extension but notes that a setting (Section 6.5.2) could be
- used for that purpose. If both peers set a value that indicates
- willingness to use the extension, then the extension can be used. If
-
-
-
-Belshe, et al. Standards Track [Page 30]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- a setting is used for extension negotiation, the initial value MUST
- be defined in such a fashion that the extension is initially
- disabled.
-
-6. Frame Definitions
-
- This specification defines a number of frame types, each identified
- by a unique 8-bit type code. Each frame type serves a distinct
- purpose in the establishment and management either of the connection
- as a whole or of individual streams.
-
- The transmission of specific frame types can alter the state of a
- connection. If endpoints fail to maintain a synchronized view of the
- connection state, successful communication within the connection will
- no longer be possible. Therefore, it is important that endpoints
- have a shared comprehension of how the state is affected by the use
- any given frame.
-
-6.1. DATA
-
- DATA frames (type=0x0) convey arbitrary, variable-length sequences of
- octets associated with a stream. One or more DATA frames are used,
- for instance, to carry HTTP request or response payloads.
-
- DATA frames MAY also contain padding. Padding can be added to DATA
- frames to obscure the size of messages. Padding is a security
- feature; see Section 10.7.
-
- +---------------+
- |Pad Length? (8)|
- +---------------+-----------------------------------------------+
- | Data (*) ...
- +---------------------------------------------------------------+
- | Padding (*) ...
- +---------------------------------------------------------------+
-
- Figure 6: DATA Frame Payload
-
- The DATA frame contains the following fields:
-
- Pad Length: An 8-bit field containing the length of the frame
- padding in units of octets. This field is conditional (as
- signified by a "?" in the diagram) and is only present if the
- PADDED flag is set.
-
- Data: Application data. The amount of data is the remainder of the
- frame payload after subtracting the length of the other fields
- that are present.
-
-
-
-Belshe, et al. Standards Track [Page 31]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- Padding: Padding octets that contain no application semantic value.
- Padding octets MUST be set to zero when sending. A receiver is
- not obligated to verify padding but MAY treat non-zero padding as
- a connection error (Section 5.4.1) of type PROTOCOL_ERROR.
-
- The DATA frame defines the following flags:
-
- END_STREAM (0x1): When set, bit 0 indicates that this frame is the
- last that the endpoint will send for the identified stream.
- Setting this flag causes the stream to enter one of the "half-
- closed" states or the "closed" state (Section 5.1).
-
- PADDED (0x8): When set, bit 3 indicates that the Pad Length field
- and any padding that it describes are present.
-
- DATA frames MUST be associated with a stream. If a DATA frame is
- received whose stream identifier field is 0x0, the recipient MUST
- respond with a connection error (Section 5.4.1) of type
- PROTOCOL_ERROR.
-
- DATA frames are subject to flow control and can only be sent when a
- stream is in the "open" or "half-closed (remote)" state. The entire
- DATA frame payload is included in flow control, including the Pad
- Length and Padding fields if present. If a DATA frame is received
- whose stream is not in "open" or "half-closed (local)" state, the
- recipient MUST respond with a stream error (Section 5.4.2) of type
- STREAM_CLOSED.
-
- The total number of padding octets is determined by the value of the
- Pad Length field. If the length of the padding is the length of the
- frame payload or greater, the recipient MUST treat this as a
- connection error (Section 5.4.1) of type PROTOCOL_ERROR.
-
- Note: A frame can be increased in size by one octet by including a
- Pad Length field with a value of zero.
-
-6.2. HEADERS
-
- The HEADERS frame (type=0x1) is used to open a stream (Section 5.1),
- and additionally carries a header block fragment. HEADERS frames can
- be sent on a stream in the "idle", "reserved (local)", "open", or
- "half-closed (remote)" state.
-
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 32]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- +---------------+
- |Pad Length? (8)|
- +-+-------------+-----------------------------------------------+
- |E| Stream Dependency? (31) |
- +-+-------------+-----------------------------------------------+
- | Weight? (8) |
- +-+-------------+-----------------------------------------------+
- | Header Block Fragment (*) ...
- +---------------------------------------------------------------+
- | Padding (*) ...
- +---------------------------------------------------------------+
-
- Figure 7: HEADERS Frame Payload
-
- The HEADERS frame payload has the following fields:
-
- Pad Length: An 8-bit field containing the length of the frame
- padding in units of octets. This field is only present if the
- PADDED flag is set.
-
- E: A single-bit flag indicating that the stream dependency is
- exclusive (see Section 5.3). This field is only present if the
- PRIORITY flag is set.
-
- Stream Dependency: A 31-bit stream identifier for the stream that
- this stream depends on (see Section 5.3). This field is only
- present if the PRIORITY flag is set.
-
- Weight: An unsigned 8-bit integer representing a priority weight for
- the stream (see Section 5.3). Add one to the value to obtain a
- weight between 1 and 256. This field is only present if the
- PRIORITY flag is set.
-
- Header Block Fragment: A header block fragment (Section 4.3).
-
- Padding: Padding octets.
-
- The HEADERS frame defines the following flags:
-
- END_STREAM (0x1): When set, bit 0 indicates that the header block
- (Section 4.3) is the last that the endpoint will send for the
- identified stream.
-
- A HEADERS frame carries the END_STREAM flag that signals the end
- of a stream. However, a HEADERS frame with the END_STREAM flag
- set can be followed by CONTINUATION frames on the same stream.
- Logically, the CONTINUATION frames are part of the HEADERS frame.
-
-
-
-
-Belshe, et al. Standards Track [Page 33]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- END_HEADERS (0x4): When set, bit 2 indicates that this frame
- contains an entire header block (Section 4.3) and is not followed
- by any CONTINUATION frames.
-
- A HEADERS frame without the END_HEADERS flag set MUST be followed
- by a CONTINUATION frame for the same stream. A receiver MUST
- treat the receipt of any other type of frame or a frame on a
- different stream as a connection error (Section 5.4.1) of type
- PROTOCOL_ERROR.
-
- PADDED (0x8): When set, bit 3 indicates that the Pad Length field
- and any padding that it describes are present.
-
- PRIORITY (0x20): When set, bit 5 indicates that the Exclusive Flag
- (E), Stream Dependency, and Weight fields are present; see
- Section 5.3.
-
- The payload of a HEADERS frame contains a header block fragment
- (Section 4.3). A header block that does not fit within a HEADERS
- frame is continued in a CONTINUATION frame (Section 6.10).
-
- HEADERS frames MUST be associated with a stream. If a HEADERS frame
- is received whose stream identifier field is 0x0, the recipient MUST
- respond with a connection error (Section 5.4.1) of type
- PROTOCOL_ERROR.
-
- The HEADERS frame changes the connection state as described in
- Section 4.3.
-
- The HEADERS frame can include padding. Padding fields and flags are
- identical to those defined for DATA frames (Section 6.1). Padding
- that exceeds the size remaining for the header block fragment MUST be
- treated as a PROTOCOL_ERROR.
-
- Prioritization information in a HEADERS frame is logically equivalent
- to a separate PRIORITY frame, but inclusion in HEADERS avoids the
- potential for churn in stream prioritization when new streams are
- created. Prioritization fields in HEADERS frames subsequent to the
- first on a stream reprioritize the stream (Section 5.3.3).
-
-6.3. PRIORITY
-
- The PRIORITY frame (type=0x2) specifies the sender-advised priority
- of a stream (Section 5.3). It can be sent in any stream state,
- including idle or closed streams.
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 34]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- +-+-------------------------------------------------------------+
- |E| Stream Dependency (31) |
- +-+-------------+-----------------------------------------------+
- | Weight (8) |
- +-+-------------+
-
- Figure 8: PRIORITY Frame Payload
-
- The payload of a PRIORITY frame contains the following fields:
-
- E: A single-bit flag indicating that the stream dependency is
- exclusive (see Section 5.3).
-
- Stream Dependency: A 31-bit stream identifier for the stream that
- this stream depends on (see Section 5.3).
-
- Weight: An unsigned 8-bit integer representing a priority weight for
- the stream (see Section 5.3). Add one to the value to obtain a
- weight between 1 and 256.
-
- The PRIORITY frame does not define any flags.
-
- The PRIORITY frame always identifies a stream. If a PRIORITY frame
- is received with a stream identifier of 0x0, the recipient MUST
- respond with a connection error (Section 5.4.1) of type
- PROTOCOL_ERROR.
-
- The PRIORITY frame can be sent on a stream in any state, though it
- cannot be sent between consecutive frames that comprise a single
- header block (Section 4.3). Note that this frame could arrive after
- processing or frame sending has completed, which would cause it to
- have no effect on the identified stream. For a stream that is in the
- "half-closed (remote)" or "closed" state, this frame can only affect
- processing of the identified stream and its dependent streams; it
- does not affect frame transmission on that stream.
-
- The PRIORITY frame can be sent for a stream in the "idle" or "closed"
- state. This allows for the reprioritization of a group of dependent
- streams by altering the priority of an unused or closed parent
- stream.
-
- A PRIORITY frame with a length other than 5 octets MUST be treated as
- a stream error (Section 5.4.2) of type FRAME_SIZE_ERROR.
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 35]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-6.4. RST_STREAM
-
- The RST_STREAM frame (type=0x3) allows for immediate termination of a
- stream. RST_STREAM is sent to request cancellation of a stream or to
- indicate that an error condition has occurred.
-
- +---------------------------------------------------------------+
- | Error Code (32) |
- +---------------------------------------------------------------+
-
- Figure 9: RST_STREAM Frame Payload
-
- The RST_STREAM frame contains a single unsigned, 32-bit integer
- identifying the error code (Section 7). The error code indicates why
- the stream is being terminated.
-
- The RST_STREAM frame does not define any flags.
-
- The RST_STREAM frame fully terminates the referenced stream and
- causes it to enter the "closed" state. After receiving a RST_STREAM
- on a stream, the receiver MUST NOT send additional frames for that
- stream, with the exception of PRIORITY. However, after sending the
- RST_STREAM, the sending endpoint MUST be prepared to receive and
- process additional frames sent on the stream that might have been
- sent by the peer prior to the arrival of the RST_STREAM.
-
- RST_STREAM frames MUST be associated with a stream. If a RST_STREAM
- frame is received with a stream identifier of 0x0, the recipient MUST
- treat this as a connection error (Section 5.4.1) of type
- PROTOCOL_ERROR.
-
- RST_STREAM frames MUST NOT be sent for a stream in the "idle" state.
- If a RST_STREAM frame identifying an idle stream is received, the
- recipient MUST treat this as a connection error (Section 5.4.1) of
- type PROTOCOL_ERROR.
-
- A RST_STREAM frame with a length other than 4 octets MUST be treated
- as a connection error (Section 5.4.1) of type FRAME_SIZE_ERROR.
-
-6.5. SETTINGS
-
- The SETTINGS frame (type=0x4) conveys configuration parameters that
- affect how endpoints communicate, such as preferences and constraints
- on peer behavior. The SETTINGS frame is also used to acknowledge the
- receipt of those parameters. Individually, a SETTINGS parameter can
- also be referred to as a "setting".
-
-
-
-
-
-Belshe, et al. Standards Track [Page 36]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- SETTINGS parameters are not negotiated; they describe characteristics
- of the sending peer, which are used by the receiving peer. Different
- values for the same parameter can be advertised by each peer. For
- example, a client might set a high initial flow-control window,
- whereas a server might set a lower value to conserve resources.
-
- A SETTINGS frame MUST be sent by both endpoints at the start of a
- connection and MAY be sent at any other time by either endpoint over
- the lifetime of the connection. Implementations MUST support all of
- the parameters defined by this specification.
-
- Each parameter in a SETTINGS frame replaces any existing value for
- that parameter. Parameters are processed in the order in which they
- appear, and a receiver of a SETTINGS frame does not need to maintain
- any state other than the current value of its parameters. Therefore,
- the value of a SETTINGS parameter is the last value that is seen by a
- receiver.
-
- SETTINGS parameters are acknowledged by the receiving peer. To
- enable this, the SETTINGS frame defines the following flag:
-
- ACK (0x1): When set, bit 0 indicates that this frame acknowledges
- receipt and application of the peer's SETTINGS frame. When this
- bit is set, the payload of the SETTINGS frame MUST be empty.
- Receipt of a SETTINGS frame with the ACK flag set and a length
- field value other than 0 MUST be treated as a connection error
- (Section 5.4.1) of type FRAME_SIZE_ERROR. For more information,
- see Section 6.5.3 ("Settings Synchronization").
-
- SETTINGS frames always apply to a connection, never a single stream.
- The stream identifier for a SETTINGS frame MUST be zero (0x0). If an
- endpoint receives a SETTINGS frame whose stream identifier field is
- anything other than 0x0, the endpoint MUST respond with a connection
- error (Section 5.4.1) of type PROTOCOL_ERROR.
-
- The SETTINGS frame affects connection state. A badly formed or
- incomplete SETTINGS frame MUST be treated as a connection error
- (Section 5.4.1) of type PROTOCOL_ERROR.
-
- A SETTINGS frame with a length other than a multiple of 6 octets MUST
- be treated as a connection error (Section 5.4.1) of type
- FRAME_SIZE_ERROR.
-
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 37]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-6.5.1. SETTINGS Format
-
- The payload of a SETTINGS frame consists of zero or more parameters,
- each consisting of an unsigned 16-bit setting identifier and an
- unsigned 32-bit value.
-
- +-------------------------------+
- | Identifier (16) |
- +-------------------------------+-------------------------------+
- | Value (32) |
- +---------------------------------------------------------------+
-
- Figure 10: Setting Format
-
-6.5.2. Defined SETTINGS Parameters
-
- The following parameters are defined:
-
- SETTINGS_HEADER_TABLE_SIZE (0x1): Allows the sender to inform the
- remote endpoint of the maximum size of the header compression
- table used to decode header blocks, in octets. The encoder can
- select any size equal to or less than this value by using
- signaling specific to the header compression format inside a
- header block (see [COMPRESSION]). The initial value is 4,096
- octets.
-
- SETTINGS_ENABLE_PUSH (0x2): This setting can be used to disable
- server push (Section 8.2). An endpoint MUST NOT send a
- PUSH_PROMISE frame if it receives this parameter set to a value of
- 0. An endpoint that has both set this parameter to 0 and had it
- acknowledged MUST treat the receipt of a PUSH_PROMISE frame as a
- connection error (Section 5.4.1) of type PROTOCOL_ERROR.
-
- The initial value is 1, which indicates that server push is
- permitted. Any value other than 0 or 1 MUST be treated as a
- connection error (Section 5.4.1) of type PROTOCOL_ERROR.
-
- SETTINGS_MAX_CONCURRENT_STREAMS (0x3): Indicates the maximum number
- of concurrent streams that the sender will allow. This limit is
- directional: it applies to the number of streams that the sender
- permits the receiver to create. Initially, there is no limit to
- this value. It is recommended that this value be no smaller than
- 100, so as to not unnecessarily limit parallelism.
-
- A value of 0 for SETTINGS_MAX_CONCURRENT_STREAMS SHOULD NOT be
- treated as special by endpoints. A zero value does prevent the
- creation of new streams; however, this can also happen for any
-
-
-
-
-Belshe, et al. Standards Track [Page 38]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- limit that is exhausted with active streams. Servers SHOULD only
- set a zero value for short durations; if a server does not wish to
- accept requests, closing the connection is more appropriate.
-
- SETTINGS_INITIAL_WINDOW_SIZE (0x4): Indicates the sender's initial
- window size (in octets) for stream-level flow control. The
- initial value is 2^16-1 (65,535) octets.
-
- This setting affects the window size of all streams (see
- Section 6.9.2).
-
- Values above the maximum flow-control window size of 2^31-1 MUST
- be treated as a connection error (Section 5.4.1) of type
- FLOW_CONTROL_ERROR.
-
- SETTINGS_MAX_FRAME_SIZE (0x5): Indicates the size of the largest
- frame payload that the sender is willing to receive, in octets.
-
- The initial value is 2^14 (16,384) octets. The value advertised
- by an endpoint MUST be between this initial value and the maximum
- allowed frame size (2^24-1 or 16,777,215 octets), inclusive.
- Values outside this range MUST be treated as a connection error
- (Section 5.4.1) of type PROTOCOL_ERROR.
-
- SETTINGS_MAX_HEADER_LIST_SIZE (0x6): This advisory setting informs a
- peer of the maximum size of header list that the sender is
- prepared to accept, in octets. The value is based on the
- uncompressed size of header fields, including the length of the
- name and value in octets plus an overhead of 32 octets for each
- header field.
-
- For any given request, a lower limit than what is advertised MAY
- be enforced. The initial value of this setting is unlimited.
-
- An endpoint that receives a SETTINGS frame with any unknown or
- unsupported identifier MUST ignore that setting.
-
-6.5.3. Settings Synchronization
-
- Most values in SETTINGS benefit from or require an understanding of
- when the peer has received and applied the changed parameter values.
- In order to provide such synchronization timepoints, the recipient of
- a SETTINGS frame in which the ACK flag is not set MUST apply the
- updated parameters as soon as possible upon receipt.
-
- The values in the SETTINGS frame MUST be processed in the order they
- appear, with no other frame processing between values. Unsupported
- parameters MUST be ignored. Once all values have been processed, the
-
-
-
-Belshe, et al. Standards Track [Page 39]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- recipient MUST immediately emit a SETTINGS frame with the ACK flag
- set. Upon receiving a SETTINGS frame with the ACK flag set, the
- sender of the altered parameters can rely on the setting having been
- applied.
-
- If the sender of a SETTINGS frame does not receive an acknowledgement
- within a reasonable amount of time, it MAY issue a connection error
- (Section 5.4.1) of type SETTINGS_TIMEOUT.
-
-6.6. PUSH_PROMISE
-
- The PUSH_PROMISE frame (type=0x5) is used to notify the peer endpoint
- in advance of streams the sender intends to initiate. The
- PUSH_PROMISE frame includes the unsigned 31-bit identifier of the
- stream the endpoint plans to create along with a set of headers that
- provide additional context for the stream. Section 8.2 contains a
- thorough description of the use of PUSH_PROMISE frames.
-
- +---------------+
- |Pad Length? (8)|
- +-+-------------+-----------------------------------------------+
- |R| Promised Stream ID (31) |
- +-+-----------------------------+-------------------------------+
- | Header Block Fragment (*) ...
- +---------------------------------------------------------------+
- | Padding (*) ...
- +---------------------------------------------------------------+
-
- Figure 11: PUSH_PROMISE Payload Format
-
- The PUSH_PROMISE frame payload has the following fields:
-
- Pad Length: An 8-bit field containing the length of the frame
- padding in units of octets. This field is only present if the
- PADDED flag is set.
-
- R: A single reserved bit.
-
- Promised Stream ID: An unsigned 31-bit integer that identifies the
- stream that is reserved by the PUSH_PROMISE. The promised stream
- identifier MUST be a valid choice for the next stream sent by the
- sender (see "new stream identifier" in Section 5.1.1).
-
- Header Block Fragment: A header block fragment (Section 4.3)
- containing request header fields.
-
- Padding: Padding octets.
-
-
-
-
-Belshe, et al. Standards Track [Page 40]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- The PUSH_PROMISE frame defines the following flags:
-
- END_HEADERS (0x4): When set, bit 2 indicates that this frame
- contains an entire header block (Section 4.3) and is not followed
- by any CONTINUATION frames.
-
- A PUSH_PROMISE frame without the END_HEADERS flag set MUST be
- followed by a CONTINUATION frame for the same stream. A receiver
- MUST treat the receipt of any other type of frame or a frame on a
- different stream as a connection error (Section 5.4.1) of type
- PROTOCOL_ERROR.
-
- PADDED (0x8): When set, bit 3 indicates that the Pad Length field
- and any padding that it describes are present.
-
- PUSH_PROMISE frames MUST only be sent on a peer-initiated stream that
- is in either the "open" or "half-closed (remote)" state. The stream
- identifier of a PUSH_PROMISE frame indicates the stream it is
- associated with. If the stream identifier field specifies the value
- 0x0, a recipient MUST respond with a connection error (Section 5.4.1)
- of type PROTOCOL_ERROR.
-
- Promised streams are not required to be used in the order they are
- promised. The PUSH_PROMISE only reserves stream identifiers for
- later use.
-
- PUSH_PROMISE MUST NOT be sent if the SETTINGS_ENABLE_PUSH setting of
- the peer endpoint is set to 0. An endpoint that has set this setting
- and has received acknowledgement MUST treat the receipt of a
- PUSH_PROMISE frame as a connection error (Section 5.4.1) of type
- PROTOCOL_ERROR.
-
- Recipients of PUSH_PROMISE frames can choose to reject promised
- streams by returning a RST_STREAM referencing the promised stream
- identifier back to the sender of the PUSH_PROMISE.
-
- A PUSH_PROMISE frame modifies the connection state in two ways.
- First, the inclusion of a header block (Section 4.3) potentially
- modifies the state maintained for header compression. Second,
- PUSH_PROMISE also reserves a stream for later use, causing the
- promised stream to enter the "reserved" state. A sender MUST NOT
- send a PUSH_PROMISE on a stream unless that stream is either "open"
- or "half-closed (remote)"; the sender MUST ensure that the promised
- stream is a valid choice for a new stream identifier (Section 5.1.1)
- (that is, the promised stream MUST be in the "idle" state).
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 41]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- Since PUSH_PROMISE reserves a stream, ignoring a PUSH_PROMISE frame
- causes the stream state to become indeterminate. A receiver MUST
- treat the receipt of a PUSH_PROMISE on a stream that is neither
- "open" nor "half-closed (local)" as a connection error
- (Section 5.4.1) of type PROTOCOL_ERROR. However, an endpoint that
- has sent RST_STREAM on the associated stream MUST handle PUSH_PROMISE
- frames that might have been created before the RST_STREAM frame is
- received and processed.
-
- A receiver MUST treat the receipt of a PUSH_PROMISE that promises an
- illegal stream identifier (Section 5.1.1) as a connection error
- (Section 5.4.1) of type PROTOCOL_ERROR. Note that an illegal stream
- identifier is an identifier for a stream that is not currently in the
- "idle" state.
-
- The PUSH_PROMISE frame can include padding. Padding fields and flags
- are identical to those defined for DATA frames (Section 6.1).
-
-6.7. PING
-
- The PING frame (type=0x6) is a mechanism for measuring a minimal
- round-trip time from the sender, as well as determining whether an
- idle connection is still functional. PING frames can be sent from
- any endpoint.
-
- +---------------------------------------------------------------+
- | |
- | Opaque Data (64) |
- | |
- +---------------------------------------------------------------+
-
- Figure 12: PING Payload Format
-
- In addition to the frame header, PING frames MUST contain 8 octets of
- opaque data in the payload. A sender can include any value it
- chooses and use those octets in any fashion.
-
- Receivers of a PING frame that does not include an ACK flag MUST send
- a PING frame with the ACK flag set in response, with an identical
- payload. PING responses SHOULD be given higher priority than any
- other frame.
-
- The PING frame defines the following flags:
-
- ACK (0x1): When set, bit 0 indicates that this PING frame is a PING
- response. An endpoint MUST set this flag in PING responses. An
- endpoint MUST NOT respond to PING frames containing this flag.
-
-
-
-
-Belshe, et al. Standards Track [Page 42]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- PING frames are not associated with any individual stream. If a PING
- frame is received with a stream identifier field value other than
- 0x0, the recipient MUST respond with a connection error
- (Section 5.4.1) of type PROTOCOL_ERROR.
-
- Receipt of a PING frame with a length field value other than 8 MUST
- be treated as a connection error (Section 5.4.1) of type
- FRAME_SIZE_ERROR.
-
-6.8. GOAWAY
-
- The GOAWAY frame (type=0x7) is used to initiate shutdown of a
- connection or to signal serious error conditions. GOAWAY allows an
- endpoint to gracefully stop accepting new streams while still
- finishing processing of previously established streams. This enables
- administrative actions, like server maintenance.
-
- There is an inherent race condition between an endpoint starting new
- streams and the remote sending a GOAWAY frame. To deal with this
- case, the GOAWAY contains the stream identifier of the last peer-
- initiated stream that was or might be processed on the sending
- endpoint in this connection. For instance, if the server sends a
- GOAWAY frame, the identified stream is the highest-numbered stream
- initiated by the client.
-
- Once sent, the sender will ignore frames sent on streams initiated by
- the receiver if the stream has an identifier higher than the included
- last stream identifier. Receivers of a GOAWAY frame MUST NOT open
- additional streams on the connection, although a new connection can
- be established for new streams.
-
- If the receiver of the GOAWAY has sent data on streams with a higher
- stream identifier than what is indicated in the GOAWAY frame, those
- streams are not or will not be processed. The receiver of the GOAWAY
- frame can treat the streams as though they had never been created at
- all, thereby allowing those streams to be retried later on a new
- connection.
-
- Endpoints SHOULD always send a GOAWAY frame before closing a
- connection so that the remote peer can know whether a stream has been
- partially processed or not. For example, if an HTTP client sends a
- POST at the same time that a server closes a connection, the client
- cannot know if the server started to process that POST request if the
- server does not send a GOAWAY frame to indicate what streams it might
- have acted on.
-
- An endpoint might choose to close a connection without sending a
- GOAWAY for misbehaving peers.
-
-
-
-Belshe, et al. Standards Track [Page 43]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- A GOAWAY frame might not immediately precede closing of the
- connection; a receiver of a GOAWAY that has no more use for the
- connection SHOULD still send a GOAWAY frame before terminating the
- connection.
-
- +-+-------------------------------------------------------------+
- |R| Last-Stream-ID (31) |
- +-+-------------------------------------------------------------+
- | Error Code (32) |
- +---------------------------------------------------------------+
- | Additional Debug Data (*) |
- +---------------------------------------------------------------+
-
- Figure 13: GOAWAY Payload Format
-
- The GOAWAY frame does not define any flags.
-
- The GOAWAY frame applies to the connection, not a specific stream.
- An endpoint MUST treat a GOAWAY frame with a stream identifier other
- than 0x0 as a connection error (Section 5.4.1) of type
- PROTOCOL_ERROR.
-
- The last stream identifier in the GOAWAY frame contains the highest-
- numbered stream identifier for which the sender of the GOAWAY frame
- might have taken some action on or might yet take action on. All
- streams up to and including the identified stream might have been
- processed in some way. The last stream identifier can be set to 0 if
- no streams were processed.
-
- Note: In this context, "processed" means that some data from the
- stream was passed to some higher layer of software that might have
- taken some action as a result.
-
- If a connection terminates without a GOAWAY frame, the last stream
- identifier is effectively the highest possible stream identifier.
-
- On streams with lower- or equal-numbered identifiers that were not
- closed completely prior to the connection being closed, reattempting
- requests, transactions, or any protocol activity is not possible,
- with the exception of idempotent actions like HTTP GET, PUT, or
- DELETE. Any protocol activity that uses higher-numbered streams can
- be safely retried using a new connection.
-
- Activity on streams numbered lower or equal to the last stream
- identifier might still complete successfully. The sender of a GOAWAY
- frame might gracefully shut down a connection by sending a GOAWAY
- frame, maintaining the connection in an "open" state until all in-
- progress streams complete.
-
-
-
-Belshe, et al. Standards Track [Page 44]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- An endpoint MAY send multiple GOAWAY frames if circumstances change.
- For instance, an endpoint that sends GOAWAY with NO_ERROR during
- graceful shutdown could subsequently encounter a condition that
- requires immediate termination of the connection. The last stream
- identifier from the last GOAWAY frame received indicates which
- streams could have been acted upon. Endpoints MUST NOT increase the
- value they send in the last stream identifier, since the peers might
- already have retried unprocessed requests on another connection.
-
- A client that is unable to retry requests loses all requests that are
- in flight when the server closes the connection. This is especially
- true for intermediaries that might not be serving clients using
- HTTP/2. A server that is attempting to gracefully shut down a
- connection SHOULD send an initial GOAWAY frame with the last stream
- identifier set to 2^31-1 and a NO_ERROR code. This signals to the
- client that a shutdown is imminent and that initiating further
- requests is prohibited. After allowing time for any in-flight stream
- creation (at least one round-trip time), the server can send another
- GOAWAY frame with an updated last stream identifier. This ensures
- that a connection can be cleanly shut down without losing requests.
-
- After sending a GOAWAY frame, the sender can discard frames for
- streams initiated by the receiver with identifiers higher than the
- identified last stream. However, any frames that alter connection
- state cannot be completely ignored. For instance, HEADERS,
- PUSH_PROMISE, and CONTINUATION frames MUST be minimally processed to
- ensure the state maintained for header compression is consistent (see
- Section 4.3); similarly, DATA frames MUST be counted toward the
- connection flow-control window. Failure to process these frames can
- cause flow control or header compression state to become
- unsynchronized.
-
- The GOAWAY frame also contains a 32-bit error code (Section 7) that
- contains the reason for closing the connection.
-
- Endpoints MAY append opaque data to the payload of any GOAWAY frame.
- Additional debug data is intended for diagnostic purposes only and
- carries no semantic value. Debug information could contain security-
- or privacy-sensitive data. Logged or otherwise persistently stored
- debug data MUST have adequate safeguards to prevent unauthorized
- access.
-
-
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 45]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-6.9. WINDOW_UPDATE
-
- The WINDOW_UPDATE frame (type=0x8) is used to implement flow control;
- see Section 5.2 for an overview.
-
- Flow control operates at two levels: on each individual stream and on
- the entire connection.
-
- Both types of flow control are hop by hop, that is, only between the
- two endpoints. Intermediaries do not forward WINDOW_UPDATE frames
- between dependent connections. However, throttling of data transfer
- by any receiver can indirectly cause the propagation of flow-control
- information toward the original sender.
-
- Flow control only applies to frames that are identified as being
- subject to flow control. Of the frame types defined in this
- document, this includes only DATA frames. Frames that are exempt
- from flow control MUST be accepted and processed, unless the receiver
- is unable to assign resources to handling the frame. A receiver MAY
- respond with a stream error (Section 5.4.2) or connection error
- (Section 5.4.1) of type FLOW_CONTROL_ERROR if it is unable to accept
- a frame.
-
- +-+-------------------------------------------------------------+
- |R| Window Size Increment (31) |
- +-+-------------------------------------------------------------+
-
- Figure 14: WINDOW_UPDATE Payload Format
-
- The payload of a WINDOW_UPDATE frame is one reserved bit plus an
- unsigned 31-bit integer indicating the number of octets that the
- sender can transmit in addition to the existing flow-control window.
- The legal range for the increment to the flow-control window is 1 to
- 2^31-1 (2,147,483,647) octets.
-
- The WINDOW_UPDATE frame does not define any flags.
-
- The WINDOW_UPDATE frame can be specific to a stream or to the entire
- connection. In the former case, the frame's stream identifier
- indicates the affected stream; in the latter, the value "0" indicates
- that the entire connection is the subject of the frame.
-
- A receiver MUST treat the receipt of a WINDOW_UPDATE frame with an
- flow-control window increment of 0 as a stream error (Section 5.4.2)
- of type PROTOCOL_ERROR; errors on the connection flow-control window
- MUST be treated as a connection error (Section 5.4.1).
-
-
-
-
-
-Belshe, et al. Standards Track [Page 46]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- WINDOW_UPDATE can be sent by a peer that has sent a frame bearing the
- END_STREAM flag. This means that a receiver could receive a
- WINDOW_UPDATE frame on a "half-closed (remote)" or "closed" stream.
- A receiver MUST NOT treat this as an error (see Section 5.1).
-
- A receiver that receives a flow-controlled frame MUST always account
- for its contribution against the connection flow-control window,
- unless the receiver treats this as a connection error
- (Section 5.4.1). This is necessary even if the frame is in error.
- The sender counts the frame toward the flow-control window, but if
- the receiver does not, the flow-control window at the sender and
- receiver can become different.
-
- A WINDOW_UPDATE frame with a length other than 4 octets MUST be
- treated as a connection error (Section 5.4.1) of type
- FRAME_SIZE_ERROR.
-
-6.9.1. The Flow-Control Window
-
- Flow control in HTTP/2 is implemented using a window kept by each
- sender on every stream. The flow-control window is a simple integer
- value that indicates how many octets of data the sender is permitted
- to transmit; as such, its size is a measure of the buffering capacity
- of the receiver.
-
- Two flow-control windows are applicable: the stream flow-control
- window and the connection flow-control window. The sender MUST NOT
- send a flow-controlled frame with a length that exceeds the space
- available in either of the flow-control windows advertised by the
- receiver. Frames with zero length with the END_STREAM flag set (that
- is, an empty DATA frame) MAY be sent if there is no available space
- in either flow-control window.
-
- For flow-control calculations, the 9-octet frame header is not
- counted.
-
- After sending a flow-controlled frame, the sender reduces the space
- available in both windows by the length of the transmitted frame.
-
- The receiver of a frame sends a WINDOW_UPDATE frame as it consumes
- data and frees up space in flow-control windows. Separate
- WINDOW_UPDATE frames are sent for the stream- and connection-level
- flow-control windows.
-
- A sender that receives a WINDOW_UPDATE frame updates the
- corresponding window by the amount specified in the frame.
-
-
-
-
-
-Belshe, et al. Standards Track [Page 47]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- A sender MUST NOT allow a flow-control window to exceed 2^31-1
- octets. If a sender receives a WINDOW_UPDATE that causes a flow-
- control window to exceed this maximum, it MUST terminate either the
- stream or the connection, as appropriate. For streams, the sender
- sends a RST_STREAM with an error code of FLOW_CONTROL_ERROR; for the
- connection, a GOAWAY frame with an error code of FLOW_CONTROL_ERROR
- is sent.
-
- Flow-controlled frames from the sender and WINDOW_UPDATE frames from
- the receiver are completely asynchronous with respect to each other.
- This property allows a receiver to aggressively update the window
- size kept by the sender to prevent streams from stalling.
-
-6.9.2. Initial Flow-Control Window Size
-
- When an HTTP/2 connection is first established, new streams are
- created with an initial flow-control window size of 65,535 octets.
- The connection flow-control window is also 65,535 octets. Both
- endpoints can adjust the initial window size for new streams by
- including a value for SETTINGS_INITIAL_WINDOW_SIZE in the SETTINGS
- frame that forms part of the connection preface. The connection
- flow-control window can only be changed using WINDOW_UPDATE frames.
-
- Prior to receiving a SETTINGS frame that sets a value for
- SETTINGS_INITIAL_WINDOW_SIZE, an endpoint can only use the default
- initial window size when sending flow-controlled frames. Similarly,
- the connection flow-control window is set to the default initial
- window size until a WINDOW_UPDATE frame is received.
-
- In addition to changing the flow-control window for streams that are
- not yet active, a SETTINGS frame can alter the initial flow-control
- window size for streams with active flow-control windows (that is,
- streams in the "open" or "half-closed (remote)" state). When the
- value of SETTINGS_INITIAL_WINDOW_SIZE changes, a receiver MUST adjust
- the size of all stream flow-control windows that it maintains by the
- difference between the new value and the old value.
-
- A change to SETTINGS_INITIAL_WINDOW_SIZE can cause the available
- space in a flow-control window to become negative. A sender MUST
- track the negative flow-control window and MUST NOT send new flow-
- controlled frames until it receives WINDOW_UPDATE frames that cause
- the flow-control window to become positive.
-
- For example, if the client sends 60 KB immediately on connection
- establishment and the server sets the initial window size to be 16
- KB, the client will recalculate the available flow-control window to
-
-
-
-
-
-Belshe, et al. Standards Track [Page 48]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- be -44 KB on receipt of the SETTINGS frame. The client retains a
- negative flow-control window until WINDOW_UPDATE frames restore the
- window to being positive, after which the client can resume sending.
-
- A SETTINGS frame cannot alter the connection flow-control window.
-
- An endpoint MUST treat a change to SETTINGS_INITIAL_WINDOW_SIZE that
- causes any flow-control window to exceed the maximum size as a
- connection error (Section 5.4.1) of type FLOW_CONTROL_ERROR.
-
-6.9.3. Reducing the Stream Window Size
-
- A receiver that wishes to use a smaller flow-control window than the
- current size can send a new SETTINGS frame. However, the receiver
- MUST be prepared to receive data that exceeds this window size, since
- the sender might send data that exceeds the lower limit prior to
- processing the SETTINGS frame.
-
- After sending a SETTINGS frame that reduces the initial flow-control
- window size, a receiver MAY continue to process streams that exceed
- flow-control limits. Allowing streams to continue does not allow the
- receiver to immediately reduce the space it reserves for flow-control
- windows. Progress on these streams can also stall, since
- WINDOW_UPDATE frames are needed to allow the sender to resume
- sending. The receiver MAY instead send a RST_STREAM with an error
- code of FLOW_CONTROL_ERROR for the affected streams.
-
-6.10. CONTINUATION
-
- The CONTINUATION frame (type=0x9) is used to continue a sequence of
- header block fragments (Section 4.3). Any number of CONTINUATION
- frames can be sent, as long as the preceding frame is on the same
- stream and is a HEADERS, PUSH_PROMISE, or CONTINUATION frame without
- the END_HEADERS flag set.
-
- +---------------------------------------------------------------+
- | Header Block Fragment (*) ...
- +---------------------------------------------------------------+
-
- Figure 15: CONTINUATION Frame Payload
-
- The CONTINUATION frame payload contains a header block fragment
- (Section 4.3).
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 49]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- The CONTINUATION frame defines the following flag:
-
- END_HEADERS (0x4): When set, bit 2 indicates that this frame ends a
- header block (Section 4.3).
-
- If the END_HEADERS bit is not set, this frame MUST be followed by
- another CONTINUATION frame. A receiver MUST treat the receipt of
- any other type of frame or a frame on a different stream as a
- connection error (Section 5.4.1) of type PROTOCOL_ERROR.
-
- The CONTINUATION frame changes the connection state as defined in
- Section 4.3.
-
- CONTINUATION frames MUST be associated with a stream. If a
- CONTINUATION frame is received whose stream identifier field is 0x0,
- the recipient MUST respond with a connection error (Section 5.4.1) of
- type PROTOCOL_ERROR.
-
- A CONTINUATION frame MUST be preceded by a HEADERS, PUSH_PROMISE or
- CONTINUATION frame without the END_HEADERS flag set. A recipient
- that observes violation of this rule MUST respond with a connection
- error (Section 5.4.1) of type PROTOCOL_ERROR.
-
-7. Error Codes
-
- Error codes are 32-bit fields that are used in RST_STREAM and GOAWAY
- frames to convey the reasons for the stream or connection error.
-
- Error codes share a common code space. Some error codes apply only
- to either streams or the entire connection and have no defined
- semantics in the other context.
-
- The following error codes are defined:
-
- NO_ERROR (0x0): The associated condition is not a result of an
- error. For example, a GOAWAY might include this code to indicate
- graceful shutdown of a connection.
-
- PROTOCOL_ERROR (0x1): The endpoint detected an unspecific protocol
- error. This error is for use when a more specific error code is
- not available.
-
- INTERNAL_ERROR (0x2): The endpoint encountered an unexpected
- internal error.
-
- FLOW_CONTROL_ERROR (0x3): The endpoint detected that its peer
- violated the flow-control protocol.
-
-
-
-
-Belshe, et al. Standards Track [Page 50]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- SETTINGS_TIMEOUT (0x4): The endpoint sent a SETTINGS frame but did
- not receive a response in a timely manner. See Section 6.5.3
- ("Settings Synchronization").
-
- STREAM_CLOSED (0x5): The endpoint received a frame after a stream
- was half-closed.
-
- FRAME_SIZE_ERROR (0x6): The endpoint received a frame with an
- invalid size.
-
- REFUSED_STREAM (0x7): The endpoint refused the stream prior to
- performing any application processing (see Section 8.1.4 for
- details).
-
- CANCEL (0x8): Used by the endpoint to indicate that the stream is no
- longer needed.
-
- COMPRESSION_ERROR (0x9): The endpoint is unable to maintain the
- header compression context for the connection.
-
- CONNECT_ERROR (0xa): The connection established in response to a
- CONNECT request (Section 8.3) was reset or abnormally closed.
-
- ENHANCE_YOUR_CALM (0xb): The endpoint detected that its peer is
- exhibiting a behavior that might be generating excessive load.
-
- INADEQUATE_SECURITY (0xc): The underlying transport has properties
- that do not meet minimum security requirements (see Section 9.2).
-
- HTTP_1_1_REQUIRED (0xd): The endpoint requires that HTTP/1.1 be used
- instead of HTTP/2.
-
- Unknown or unsupported error codes MUST NOT trigger any special
- behavior. These MAY be treated by an implementation as being
- equivalent to INTERNAL_ERROR.
-
-8. HTTP Message Exchanges
-
- HTTP/2 is intended to be as compatible as possible with current uses
- of HTTP. This means that, from the application perspective, the
- features of the protocol are largely unchanged. To achieve this, all
- request and response semantics are preserved, although the syntax of
- conveying those semantics has changed.
-
- Thus, the specification and requirements of HTTP/1.1 Semantics and
- Content [RFC7231], Conditional Requests [RFC7232], Range Requests
- [RFC7233], Caching [RFC7234], and Authentication [RFC7235] are
- applicable to HTTP/2. Selected portions of HTTP/1.1 Message Syntax
-
-
-
-Belshe, et al. Standards Track [Page 51]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- and Routing [RFC7230], such as the HTTP and HTTPS URI schemes, are
- also applicable in HTTP/2, but the expression of those semantics for
- this protocol are defined in the sections below.
-
-8.1. HTTP Request/Response Exchange
-
- A client sends an HTTP request on a new stream, using a previously
- unused stream identifier (Section 5.1.1). A server sends an HTTP
- response on the same stream as the request.
-
- An HTTP message (request or response) consists of:
-
- 1. for a response only, zero or more HEADERS frames (each followed
- by zero or more CONTINUATION frames) containing the message
- headers of informational (1xx) HTTP responses (see [RFC7230],
- Section 3.2 and [RFC7231], Section 6.2),
-
- 2. one HEADERS frame (followed by zero or more CONTINUATION frames)
- containing the message headers (see [RFC7230], Section 3.2),
-
- 3. zero or more DATA frames containing the payload body (see
- [RFC7230], Section 3.3), and
-
- 4. optionally, one HEADERS frame, followed by zero or more
- CONTINUATION frames containing the trailer-part, if present (see
- [RFC7230], Section 4.1.2).
-
- The last frame in the sequence bears an END_STREAM flag, noting that
- a HEADERS frame bearing the END_STREAM flag can be followed by
- CONTINUATION frames that carry any remaining portions of the header
- block.
-
- Other frames (from any stream) MUST NOT occur between the HEADERS
- frame and any CONTINUATION frames that might follow.
-
- HTTP/2 uses DATA frames to carry message payloads. The "chunked"
- transfer encoding defined in Section 4.1 of [RFC7230] MUST NOT be
- used in HTTP/2.
-
- Trailing header fields are carried in a header block that also
- terminates the stream. Such a header block is a sequence starting
- with a HEADERS frame, followed by zero or more CONTINUATION frames,
- where the HEADERS frame bears an END_STREAM flag. Header blocks
- after the first that do not terminate the stream are not part of an
- HTTP request or response.
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 52]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- A HEADERS frame (and associated CONTINUATION frames) can only appear
- at the start or end of a stream. An endpoint that receives a HEADERS
- frame without the END_STREAM flag set after receiving a final (non-
- informational) status code MUST treat the corresponding request or
- response as malformed (Section 8.1.2.6).
-
- An HTTP request/response exchange fully consumes a single stream. A
- request starts with the HEADERS frame that puts the stream into an
- "open" state. The request ends with a frame bearing END_STREAM,
- which causes the stream to become "half-closed (local)" for the
- client and "half-closed (remote)" for the server. A response starts
- with a HEADERS frame and ends with a frame bearing END_STREAM, which
- places the stream in the "closed" state.
-
- An HTTP response is complete after the server sends -- or the client
- receives -- a frame with the END_STREAM flag set (including any
- CONTINUATION frames needed to complete a header block). A server can
- send a complete response prior to the client sending an entire
- request if the response does not depend on any portion of the request
- that has not been sent and received. When this is true, a server MAY
- request that the client abort transmission of a request without error
- by sending a RST_STREAM with an error code of NO_ERROR after sending
- a complete response (i.e., a frame with the END_STREAM flag).
- Clients MUST NOT discard responses as a result of receiving such a
- RST_STREAM, though clients can always discard responses at their
- discretion for other reasons.
-
-8.1.1. Upgrading from HTTP/2
-
- HTTP/2 removes support for the 101 (Switching Protocols)
- informational status code ([RFC7231], Section 6.2.2).
-
- The semantics of 101 (Switching Protocols) aren't applicable to a
- multiplexed protocol. Alternative protocols are able to use the same
- mechanisms that HTTP/2 uses to negotiate their use (see Section 3).
-
-8.1.2. HTTP Header Fields
-
- HTTP header fields carry information as a series of key-value pairs.
- For a listing of registered HTTP headers, see the "Message Header
- Field" registry maintained at <https://www.iana.org/assignments/
- message-headers>.
-
- Just as in HTTP/1.x, header field names are strings of ASCII
- characters that are compared in a case-insensitive fashion. However,
- header field names MUST be converted to lowercase prior to their
- encoding in HTTP/2. A request or response containing uppercase
- header field names MUST be treated as malformed (Section 8.1.2.6).
-
-
-
-Belshe, et al. Standards Track [Page 53]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-8.1.2.1. Pseudo-Header Fields
-
- While HTTP/1.x used the message start-line (see [RFC7230],
- Section 3.1) to convey the target URI, the method of the request, and
- the status code for the response, HTTP/2 uses special pseudo-header
- fields beginning with ':' character (ASCII 0x3a) for this purpose.
-
- Pseudo-header fields are not HTTP header fields. Endpoints MUST NOT
- generate pseudo-header fields other than those defined in this
- document.
-
- Pseudo-header fields are only valid in the context in which they are
- defined. Pseudo-header fields defined for requests MUST NOT appear
- in responses; pseudo-header fields defined for responses MUST NOT
- appear in requests. Pseudo-header fields MUST NOT appear in
- trailers. Endpoints MUST treat a request or response that contains
- undefined or invalid pseudo-header fields as malformed
- (Section 8.1.2.6).
-
- All pseudo-header fields MUST appear in the header block before
- regular header fields. Any request or response that contains a
- pseudo-header field that appears in a header block after a regular
- header field MUST be treated as malformed (Section 8.1.2.6).
-
-8.1.2.2. Connection-Specific Header Fields
-
- HTTP/2 does not use the Connection header field to indicate
- connection-specific header fields; in this protocol, connection-
- specific metadata is conveyed by other means. An endpoint MUST NOT
- generate an HTTP/2 message containing connection-specific header
- fields; any message containing connection-specific header fields MUST
- be treated as malformed (Section 8.1.2.6).
-
- The only exception to this is the TE header field, which MAY be
- present in an HTTP/2 request; when it is, it MUST NOT contain any
- value other than "trailers".
-
- This means that an intermediary transforming an HTTP/1.x message to
- HTTP/2 will need to remove any header fields nominated by the
- Connection header field, along with the Connection header field
- itself. Such intermediaries SHOULD also remove other connection-
- specific header fields, such as Keep-Alive, Proxy-Connection,
- Transfer-Encoding, and Upgrade, even if they are not nominated by the
- Connection header field.
-
- Note: HTTP/2 purposefully does not support upgrade to another
- protocol. The handshake methods described in Section 3 are
- believed sufficient to negotiate the use of alternative protocols.
-
-
-
-Belshe, et al. Standards Track [Page 54]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-8.1.2.3. Request Pseudo-Header Fields
-
- The following pseudo-header fields are defined for HTTP/2 requests:
-
- o The ":method" pseudo-header field includes the HTTP method
- ([RFC7231], Section 4).
-
- o The ":scheme" pseudo-header field includes the scheme portion of
- the target URI ([RFC3986], Section 3.1).
-
- ":scheme" is not restricted to "http" and "https" schemed URIs. A
- proxy or gateway can translate requests for non-HTTP schemes,
- enabling the use of HTTP to interact with non-HTTP services.
-
- o The ":authority" pseudo-header field includes the authority
- portion of the target URI ([RFC3986], Section 3.2). The authority
- MUST NOT include the deprecated "userinfo" subcomponent for "http"
- or "https" schemed URIs.
-
- To ensure that the HTTP/1.1 request line can be reproduced
- accurately, this pseudo-header field MUST be omitted when
- translating from an HTTP/1.1 request that has a request target in
- origin or asterisk form (see [RFC7230], Section 5.3). Clients
- that generate HTTP/2 requests directly SHOULD use the ":authority"
- pseudo-header field instead of the Host header field. An
- intermediary that converts an HTTP/2 request to HTTP/1.1 MUST
- create a Host header field if one is not present in a request by
- copying the value of the ":authority" pseudo-header field.
-
- o The ":path" pseudo-header field includes the path and query parts
- of the target URI (the "path-absolute" production and optionally a
- '?' character followed by the "query" production (see Sections 3.3
- and 3.4 of [RFC3986]). A request in asterisk form includes the
- value '*' for the ":path" pseudo-header field.
-
- This pseudo-header field MUST NOT be empty for "http" or "https"
- URIs; "http" or "https" URIs that do not contain a path component
- MUST include a value of '/'. The exception to this rule is an
- OPTIONS request for an "http" or "https" URI that does not include
- a path component; these MUST include a ":path" pseudo-header field
- with a value of '*' (see [RFC7230], Section 5.3.4).
-
-
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 55]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- All HTTP/2 requests MUST include exactly one valid value for the
- ":method", ":scheme", and ":path" pseudo-header fields, unless it is
- a CONNECT request (Section 8.3). An HTTP request that omits
- mandatory pseudo-header fields is malformed (Section 8.1.2.6).
-
- HTTP/2 does not define a way to carry the version identifier that is
- included in the HTTP/1.1 request line.
-
-8.1.2.4. Response Pseudo-Header Fields
-
- For HTTP/2 responses, a single ":status" pseudo-header field is
- defined that carries the HTTP status code field (see [RFC7231],
- Section 6). This pseudo-header field MUST be included in all
- responses; otherwise, the response is malformed (Section 8.1.2.6).
-
- HTTP/2 does not define a way to carry the version or reason phrase
- that is included in an HTTP/1.1 status line.
-
-8.1.2.5. Compressing the Cookie Header Field
-
- The Cookie header field [COOKIE] uses a semi-colon (";") to delimit
- cookie-pairs (or "crumbs"). This header field doesn't follow the
- list construction rules in HTTP (see [RFC7230], Section 3.2.2), which
- prevents cookie-pairs from being separated into different name-value
- pairs. This can significantly reduce compression efficiency as
- individual cookie-pairs are updated.
-
- To allow for better compression efficiency, the Cookie header field
- MAY be split into separate header fields, each with one or more
- cookie-pairs. If there are multiple Cookie header fields after
- decompression, these MUST be concatenated into a single octet string
- using the two-octet delimiter of 0x3B, 0x20 (the ASCII string "; ")
- before being passed into a non-HTTP/2 context, such as an HTTP/1.1
- connection, or a generic HTTP server application.
-
- Therefore, the following two lists of Cookie header fields are
- semantically equivalent.
-
- cookie: a=b; c=d; e=f
-
- cookie: a=b
- cookie: c=d
- cookie: e=f
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 56]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-8.1.2.6. Malformed Requests and Responses
-
- A malformed request or response is one that is an otherwise valid
- sequence of HTTP/2 frames but is invalid due to the presence of
- extraneous frames, prohibited header fields, the absence of mandatory
- header fields, or the inclusion of uppercase header field names.
-
- A request or response that includes a payload body can include a
- content-length header field. A request or response is also malformed
- if the value of a content-length header field does not equal the sum
- of the DATA frame payload lengths that form the body. A response
- that is defined to have no payload, as described in [RFC7230],
- Section 3.3.2, can have a non-zero content-length header field, even
- though no content is included in DATA frames.
-
- Intermediaries that process HTTP requests or responses (i.e., any
- intermediary not acting as a tunnel) MUST NOT forward a malformed
- request or response. Malformed requests or responses that are
- detected MUST be treated as a stream error (Section 5.4.2) of type
- PROTOCOL_ERROR.
-
- For malformed requests, a server MAY send an HTTP response prior to
- closing or resetting the stream. Clients MUST NOT accept a malformed
- response. Note that these requirements are intended to protect
- against several types of common attacks against HTTP; they are
- deliberately strict because being permissive can expose
- implementations to these vulnerabilities.
-
-8.1.3. Examples
-
- This section shows HTTP/1.1 requests and responses, with
- illustrations of equivalent HTTP/2 requests and responses.
-
- An HTTP GET request includes request header fields and no payload
- body and is therefore transmitted as a single HEADERS frame, followed
- by zero or more CONTINUATION frames containing the serialized block
- of request header fields. The HEADERS frame in the following has
- both the END_HEADERS and END_STREAM flags set; no CONTINUATION frames
- are sent.
-
- GET /resource HTTP/1.1 HEADERS
- Host: example.org ==> + END_STREAM
- Accept: image/jpeg + END_HEADERS
- :method = GET
- :scheme = https
- :path = /resource
- host = example.org
- accept = image/jpeg
-
-
-
-Belshe, et al. Standards Track [Page 57]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- Similarly, a response that includes only response header fields is
- transmitted as a HEADERS frame (again, followed by zero or more
- CONTINUATION frames) containing the serialized block of response
- header fields.
-
- HTTP/1.1 304 Not Modified HEADERS
- ETag: "xyzzy" ==> + END_STREAM
- Expires: Thu, 23 Jan ... + END_HEADERS
- :status = 304
- etag = "xyzzy"
- expires = Thu, 23 Jan ...
-
- An HTTP POST request that includes request header fields and payload
- data is transmitted as one HEADERS frame, followed by zero or more
- CONTINUATION frames containing the request header fields, followed by
- one or more DATA frames, with the last CONTINUATION (or HEADERS)
- frame having the END_HEADERS flag set and the final DATA frame having
- the END_STREAM flag set:
-
- POST /resource HTTP/1.1 HEADERS
- Host: example.org ==> - END_STREAM
- Content-Type: image/jpeg - END_HEADERS
- Content-Length: 123 :method = POST
- :path = /resource
- {binary data} :scheme = https
-
- CONTINUATION
- + END_HEADERS
- content-type = image/jpeg
- host = example.org
- content-length = 123
-
- DATA
- + END_STREAM
- {binary data}
-
- Note that data contributing to any given header field could be spread
- between header block fragments. The allocation of header fields to
- frames in this example is illustrative only.
-
- A response that includes header fields and payload data is
- transmitted as a HEADERS frame, followed by zero or more CONTINUATION
- frames, followed by one or more DATA frames, with the last DATA frame
- in the sequence having the END_STREAM flag set:
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 58]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- HTTP/1.1 200 OK HEADERS
- Content-Type: image/jpeg ==> - END_STREAM
- Content-Length: 123 + END_HEADERS
- :status = 200
- {binary data} content-type = image/jpeg
- content-length = 123
-
- DATA
- + END_STREAM
- {binary data}
-
- An informational response using a 1xx status code other than 101 is
- transmitted as a HEADERS frame, followed by zero or more CONTINUATION
- frames.
-
- Trailing header fields are sent as a header block after both the
- request or response header block and all the DATA frames have been
- sent. The HEADERS frame starting the trailers header block has the
- END_STREAM flag set.
-
- The following example includes both a 100 (Continue) status code,
- which is sent in response to a request containing a "100-continue"
- token in the Expect header field, and trailing header fields:
-
- HTTP/1.1 100 Continue HEADERS
- Extension-Field: bar ==> - END_STREAM
- + END_HEADERS
- :status = 100
- extension-field = bar
-
- HTTP/1.1 200 OK HEADERS
- Content-Type: image/jpeg ==> - END_STREAM
- Transfer-Encoding: chunked + END_HEADERS
- Trailer: Foo :status = 200
- content-length = 123
- 123 content-type = image/jpeg
- {binary data} trailer = Foo
- 0
- Foo: bar DATA
- - END_STREAM
- {binary data}
-
- HEADERS
- + END_STREAM
- + END_HEADERS
- foo = bar
-
-
-
-
-
-Belshe, et al. Standards Track [Page 59]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-8.1.4. Request Reliability Mechanisms in HTTP/2
-
- In HTTP/1.1, an HTTP client is unable to retry a non-idempotent
- request when an error occurs because there is no means to determine
- the nature of the error. It is possible that some server processing
- occurred prior to the error, which could result in undesirable
- effects if the request were reattempted.
-
- HTTP/2 provides two mechanisms for providing a guarantee to a client
- that a request has not been processed:
-
- o The GOAWAY frame indicates the highest stream number that might
- have been processed. Requests on streams with higher numbers are
- therefore guaranteed to be safe to retry.
-
- o The REFUSED_STREAM error code can be included in a RST_STREAM
- frame to indicate that the stream is being closed prior to any
- processing having occurred. Any request that was sent on the
- reset stream can be safely retried.
-
- Requests that have not been processed have not failed; clients MAY
- automatically retry them, even those with non-idempotent methods.
-
- A server MUST NOT indicate that a stream has not been processed
- unless it can guarantee that fact. If frames that are on a stream
- are passed to the application layer for any stream, then
- REFUSED_STREAM MUST NOT be used for that stream, and a GOAWAY frame
- MUST include a stream identifier that is greater than or equal to the
- given stream identifier.
-
- In addition to these mechanisms, the PING frame provides a way for a
- client to easily test a connection. Connections that remain idle can
- become broken as some middleboxes (for instance, network address
- translators or load balancers) silently discard connection bindings.
- The PING frame allows a client to safely test whether a connection is
- still active without sending a request.
-
-8.2. Server Push
-
- HTTP/2 allows a server to pre-emptively send (or "push") responses
- (along with corresponding "promised" requests) to a client in
- association with a previous client-initiated request. This can be
- useful when the server knows the client will need to have those
- responses available in order to fully process the response to the
- original request.
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 60]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- A client can request that server push be disabled, though this is
- negotiated for each hop independently. The SETTINGS_ENABLE_PUSH
- setting can be set to 0 to indicate that server push is disabled.
-
- Promised requests MUST be cacheable (see [RFC7231], Section 4.2.3),
- MUST be safe (see [RFC7231], Section 4.2.1), and MUST NOT include a
- request body. Clients that receive a promised request that is not
- cacheable, that is not known to be safe, or that indicates the
- presence of a request body MUST reset the promised stream with a
- stream error (Section 5.4.2) of type PROTOCOL_ERROR. Note this could
- result in the promised stream being reset if the client does not
- recognize a newly defined method as being safe.
-
- Pushed responses that are cacheable (see [RFC7234], Section 3) can be
- stored by the client, if it implements an HTTP cache. Pushed
- responses are considered successfully validated on the origin server
- (e.g., if the "no-cache" cache response directive is present
- ([RFC7234], Section 5.2.2)) while the stream identified by the
- promised stream ID is still open.
-
- Pushed responses that are not cacheable MUST NOT be stored by any
- HTTP cache. They MAY be made available to the application
- separately.
-
- The server MUST include a value in the ":authority" pseudo-header
- field for which the server is authoritative (see Section 10.1). A
- client MUST treat a PUSH_PROMISE for which the server is not
- authoritative as a stream error (Section 5.4.2) of type
- PROTOCOL_ERROR.
-
- An intermediary can receive pushes from the server and choose not to
- forward them on to the client. In other words, how to make use of
- the pushed information is up to that intermediary. Equally, the
- intermediary might choose to make additional pushes to the client,
- without any action taken by the server.
-
- A client cannot push. Thus, servers MUST treat the receipt of a
- PUSH_PROMISE frame as a connection error (Section 5.4.1) of type
- PROTOCOL_ERROR. Clients MUST reject any attempt to change the
- SETTINGS_ENABLE_PUSH setting to a value other than 0 by treating the
- message as a connection error (Section 5.4.1) of type PROTOCOL_ERROR.
-
-8.2.1. Push Requests
-
- Server push is semantically equivalent to a server responding to a
- request; however, in this case, that request is also sent by the
- server, as a PUSH_PROMISE frame.
-
-
-
-
-Belshe, et al. Standards Track [Page 61]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- The PUSH_PROMISE frame includes a header block that contains a
- complete set of request header fields that the server attributes to
- the request. It is not possible to push a response to a request that
- includes a request body.
-
- Pushed responses are always associated with an explicit request from
- the client. The PUSH_PROMISE frames sent by the server are sent on
- that explicit request's stream. The PUSH_PROMISE frame also includes
- a promised stream identifier, chosen from the stream identifiers
- available to the server (see Section 5.1.1).
-
- The header fields in PUSH_PROMISE and any subsequent CONTINUATION
- frames MUST be a valid and complete set of request header fields
- (Section 8.1.2.3). The server MUST include a method in the ":method"
- pseudo-header field that is safe and cacheable. If a client receives
- a PUSH_PROMISE that does not include a complete and valid set of
- header fields or the ":method" pseudo-header field identifies a
- method that is not safe, it MUST respond with a stream error
- (Section 5.4.2) of type PROTOCOL_ERROR.
-
- The server SHOULD send PUSH_PROMISE (Section 6.6) frames prior to
- sending any frames that reference the promised responses. This
- avoids a race where clients issue requests prior to receiving any
- PUSH_PROMISE frames.
-
- For example, if the server receives a request for a document
- containing embedded links to multiple image files and the server
- chooses to push those additional images to the client, sending
- PUSH_PROMISE frames before the DATA frames that contain the image
- links ensures that the client is able to see that a resource will be
- pushed before discovering embedded links. Similarly, if the server
- pushes responses referenced by the header block (for instance, in
- Link header fields), sending a PUSH_PROMISE before sending the header
- block ensures that clients do not request those resources.
-
- PUSH_PROMISE frames MUST NOT be sent by the client.
-
- PUSH_PROMISE frames can be sent by the server in response to any
- client-initiated stream, but the stream MUST be in either the "open"
- or "half-closed (remote)" state with respect to the server.
- PUSH_PROMISE frames are interspersed with the frames that comprise a
- response, though they cannot be interspersed with HEADERS and
- CONTINUATION frames that comprise a single header block.
-
- Sending a PUSH_PROMISE frame creates a new stream and puts the stream
- into the "reserved (local)" state for the server and the "reserved
- (remote)" state for the client.
-
-
-
-
-Belshe, et al. Standards Track [Page 62]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-8.2.2. Push Responses
-
- After sending the PUSH_PROMISE frame, the server can begin delivering
- the pushed response as a response (Section 8.1.2.4) on a server-
- initiated stream that uses the promised stream identifier. The
- server uses this stream to transmit an HTTP response, using the same
- sequence of frames as defined in Section 8.1. This stream becomes
- "half-closed" to the client (Section 5.1) after the initial HEADERS
- frame is sent.
-
- Once a client receives a PUSH_PROMISE frame and chooses to accept the
- pushed response, the client SHOULD NOT issue any requests for the
- promised response until after the promised stream has closed.
-
- If the client determines, for any reason, that it does not wish to
- receive the pushed response from the server or if the server takes
- too long to begin sending the promised response, the client can send
- a RST_STREAM frame, using either the CANCEL or REFUSED_STREAM code
- and referencing the pushed stream's identifier.
-
- A client can use the SETTINGS_MAX_CONCURRENT_STREAMS setting to limit
- the number of responses that can be concurrently pushed by a server.
- Advertising a SETTINGS_MAX_CONCURRENT_STREAMS value of zero disables
- server push by preventing the server from creating the necessary
- streams. This does not prohibit a server from sending PUSH_PROMISE
- frames; clients need to reset any promised streams that are not
- wanted.
-
- Clients receiving a pushed response MUST validate that either the
- server is authoritative (see Section 10.1) or the proxy that provided
- the pushed response is configured for the corresponding request. For
- example, a server that offers a certificate for only the
- "example.com" DNS-ID or Common Name is not permitted to push a
- response for "https://www.example.org/doc".
-
- The response for a PUSH_PROMISE stream begins with a HEADERS frame,
- which immediately puts the stream into the "half-closed (remote)"
- state for the server and "half-closed (local)" state for the client,
- and ends with a frame bearing END_STREAM, which places the stream in
- the "closed" state.
-
- Note: The client never sends a frame with the END_STREAM flag for
- a server push.
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 63]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-8.3. The CONNECT Method
-
- In HTTP/1.x, the pseudo-method CONNECT ([RFC7231], Section 4.3.6) is
- used to convert an HTTP connection into a tunnel to a remote host.
- CONNECT is primarily used with HTTP proxies to establish a TLS
- session with an origin server for the purposes of interacting with
- "https" resources.
-
- In HTTP/2, the CONNECT method is used to establish a tunnel over a
- single HTTP/2 stream to a remote host for similar purposes. The HTTP
- header field mapping works as defined in Section 8.1.2.3 ("Request
- Pseudo-Header Fields"), with a few differences. Specifically:
-
- o The ":method" pseudo-header field is set to "CONNECT".
-
- o The ":scheme" and ":path" pseudo-header fields MUST be omitted.
-
- o The ":authority" pseudo-header field contains the host and port to
- connect to (equivalent to the authority-form of the request-target
- of CONNECT requests (see [RFC7230], Section 5.3)).
-
- A CONNECT request that does not conform to these restrictions is
- malformed (Section 8.1.2.6).
-
- A proxy that supports CONNECT establishes a TCP connection [TCP] to
- the server identified in the ":authority" pseudo-header field. Once
- this connection is successfully established, the proxy sends a
- HEADERS frame containing a 2xx series status code to the client, as
- defined in [RFC7231], Section 4.3.6.
-
- After the initial HEADERS frame sent by each peer, all subsequent
- DATA frames correspond to data sent on the TCP connection. The
- payload of any DATA frames sent by the client is transmitted by the
- proxy to the TCP server; data received from the TCP server is
- assembled into DATA frames by the proxy. Frame types other than DATA
- or stream management frames (RST_STREAM, WINDOW_UPDATE, and PRIORITY)
- MUST NOT be sent on a connected stream and MUST be treated as a
- stream error (Section 5.4.2) if received.
-
- The TCP connection can be closed by either peer. The END_STREAM flag
- on a DATA frame is treated as being equivalent to the TCP FIN bit. A
- client is expected to send a DATA frame with the END_STREAM flag set
- after receiving a frame bearing the END_STREAM flag. A proxy that
- receives a DATA frame with the END_STREAM flag set sends the attached
- data with the FIN bit set on the last TCP segment. A proxy that
- receives a TCP segment with the FIN bit set sends a DATA frame with
- the END_STREAM flag set. Note that the final TCP segment or DATA
- frame could be empty.
-
-
-
-Belshe, et al. Standards Track [Page 64]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- A TCP connection error is signaled with RST_STREAM. A proxy treats
- any error in the TCP connection, which includes receiving a TCP
- segment with the RST bit set, as a stream error (Section 5.4.2) of
- type CONNECT_ERROR. Correspondingly, a proxy MUST send a TCP segment
- with the RST bit set if it detects an error with the stream or the
- HTTP/2 connection.
-
-9. Additional HTTP Requirements/Considerations
-
- This section outlines attributes of the HTTP protocol that improve
- interoperability, reduce exposure to known security vulnerabilities,
- or reduce the potential for implementation variation.
-
-9.1. Connection Management
-
- HTTP/2 connections are persistent. For best performance, it is
- expected that clients will not close connections until it is
- determined that no further communication with a server is necessary
- (for example, when a user navigates away from a particular web page)
- or until the server closes the connection.
-
- Clients SHOULD NOT open more than one HTTP/2 connection to a given
- host and port pair, where the host is derived from a URI, a selected
- alternative service [ALT-SVC], or a configured proxy.
-
- A client can create additional connections as replacements, either to
- replace connections that are near to exhausting the available stream
- identifier space (Section 5.1.1), to refresh the keying material for
- a TLS connection, or to replace connections that have encountered
- errors (Section 5.4.1).
-
- A client MAY open multiple connections to the same IP address and TCP
- port using different Server Name Indication [TLS-EXT] values or to
- provide different TLS client certificates but SHOULD avoid creating
- multiple connections with the same configuration.
-
- Servers are encouraged to maintain open connections for as long as
- possible but are permitted to terminate idle connections if
- necessary. When either endpoint chooses to close the transport-layer
- TCP connection, the terminating endpoint SHOULD first send a GOAWAY
- (Section 6.8) frame so that both endpoints can reliably determine
- whether previously sent frames have been processed and gracefully
- complete or terminate any necessary remaining tasks.
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 65]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-9.1.1. Connection Reuse
-
- Connections that are made to an origin server, either directly or
- through a tunnel created using the CONNECT method (Section 8.3), MAY
- be reused for requests with multiple different URI authority
- components. A connection can be reused as long as the origin server
- is authoritative (Section 10.1). For TCP connections without TLS,
- this depends on the host having resolved to the same IP address.
-
- For "https" resources, connection reuse additionally depends on
- having a certificate that is valid for the host in the URI. The
- certificate presented by the server MUST satisfy any checks that the
- client would perform when forming a new TLS connection for the host
- in the URI.
-
- An origin server might offer a certificate with multiple
- "subjectAltName" attributes or names with wildcards, one of which is
- valid for the authority in the URI. For example, a certificate with
- a "subjectAltName" of "*.example.com" might permit the use of the
- same connection for requests to URIs starting with
- "https://a.example.com/" and "https://b.example.com/".
-
- In some deployments, reusing a connection for multiple origins can
- result in requests being directed to the wrong origin server. For
- example, TLS termination might be performed by a middlebox that uses
- the TLS Server Name Indication (SNI) [TLS-EXT] extension to select an
- origin server. This means that it is possible for clients to send
- confidential information to servers that might not be the intended
- target for the request, even though the server is otherwise
- authoritative.
-
- A server that does not wish clients to reuse connections can indicate
- that it is not authoritative for a request by sending a 421
- (Misdirected Request) status code in response to the request (see
- Section 9.1.2).
-
- A client that is configured to use a proxy over HTTP/2 directs
- requests to that proxy through a single connection. That is, all
- requests sent via a proxy reuse the connection to the proxy.
-
-9.1.2. The 421 (Misdirected Request) Status Code
-
- The 421 (Misdirected Request) status code indicates that the request
- was directed at a server that is not able to produce a response.
- This can be sent by a server that is not configured to produce
- responses for the combination of scheme and authority that are
- included in the request URI.
-
-
-
-
-Belshe, et al. Standards Track [Page 66]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- Clients receiving a 421 (Misdirected Request) response from a server
- MAY retry the request -- whether the request method is idempotent or
- not -- over a different connection. This is possible if a connection
- is reused (Section 9.1.1) or if an alternative service is selected
- [ALT-SVC].
-
- This status code MUST NOT be generated by proxies.
-
- A 421 response is cacheable by default, i.e., unless otherwise
- indicated by the method definition or explicit cache controls (see
- Section 4.2.2 of [RFC7234]).
-
-9.2. Use of TLS Features
-
- Implementations of HTTP/2 MUST use TLS version 1.2 [TLS12] or higher
- for HTTP/2 over TLS. The general TLS usage guidance in [TLSBCP]
- SHOULD be followed, with some additional restrictions that are
- specific to HTTP/2.
-
- The TLS implementation MUST support the Server Name Indication (SNI)
- [TLS-EXT] extension to TLS. HTTP/2 clients MUST indicate the target
- domain name when negotiating TLS.
-
- Deployments of HTTP/2 that negotiate TLS 1.3 or higher need only
- support and use the SNI extension; deployments of TLS 1.2 are subject
- to the requirements in the following sections. Implementations are
- encouraged to provide defaults that comply, but it is recognized that
- deployments are ultimately responsible for compliance.
-
-9.2.1. TLS 1.2 Features
-
- This section describes restrictions on the TLS 1.2 feature set that
- can be used with HTTP/2. Due to deployment limitations, it might not
- be possible to fail TLS negotiation when these restrictions are not
- met. An endpoint MAY immediately terminate an HTTP/2 connection that
- does not meet these TLS requirements with a connection error
- (Section 5.4.1) of type INADEQUATE_SECURITY.
-
- A deployment of HTTP/2 over TLS 1.2 MUST disable compression. TLS
- compression can lead to the exposure of information that would not
- otherwise be revealed [RFC3749]. Generic compression is unnecessary
- since HTTP/2 provides compression features that are more aware of
- context and therefore likely to be more appropriate for use for
- performance, security, or other reasons.
-
- A deployment of HTTP/2 over TLS 1.2 MUST disable renegotiation. An
- endpoint MUST treat a TLS renegotiation as a connection error
- (Section 5.4.1) of type PROTOCOL_ERROR. Note that disabling
-
-
-
-Belshe, et al. Standards Track [Page 67]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- renegotiation can result in long-lived connections becoming unusable
- due to limits on the number of messages the underlying cipher suite
- can encipher.
-
- An endpoint MAY use renegotiation to provide confidentiality
- protection for client credentials offered in the handshake, but any
- renegotiation MUST occur prior to sending the connection preface. A
- server SHOULD request a client certificate if it sees a renegotiation
- request immediately after establishing a connection.
-
- This effectively prevents the use of renegotiation in response to a
- request for a specific protected resource. A future specification
- might provide a way to support this use case. Alternatively, a
- server might use an error (Section 5.4) of type HTTP_1_1_REQUIRED to
- request the client use a protocol that supports renegotiation.
-
- Implementations MUST support ephemeral key exchange sizes of at least
- 2048 bits for cipher suites that use ephemeral finite field Diffie-
- Hellman (DHE) [TLS12] and 224 bits for cipher suites that use
- ephemeral elliptic curve Diffie-Hellman (ECDHE) [RFC4492]. Clients
- MUST accept DHE sizes of up to 4096 bits. Endpoints MAY treat
- negotiation of key sizes smaller than the lower limits as a
- connection error (Section 5.4.1) of type INADEQUATE_SECURITY.
-
-9.2.2. TLS 1.2 Cipher Suites
-
- A deployment of HTTP/2 over TLS 1.2 SHOULD NOT use any of the cipher
- suites that are listed in the cipher suite black list (Appendix A).
-
- Endpoints MAY choose to generate a connection error (Section 5.4.1)
- of type INADEQUATE_SECURITY if one of the cipher suites from the
- black list is negotiated. A deployment that chooses to use a black-
- listed cipher suite risks triggering a connection error unless the
- set of potential peers is known to accept that cipher suite.
-
- Implementations MUST NOT generate this error in reaction to the
- negotiation of a cipher suite that is not on the black list.
- Consequently, when clients offer a cipher suite that is not on the
- black list, they have to be prepared to use that cipher suite with
- HTTP/2.
-
- The black list includes the cipher suite that TLS 1.2 makes
- mandatory, which means that TLS 1.2 deployments could have non-
- intersecting sets of permitted cipher suites. To avoid this problem
- causing TLS handshake failures, deployments of HTTP/2 that use TLS
- 1.2 MUST support TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE]
- with the P-256 elliptic curve [FIPS186].
-
-
-
-
-Belshe, et al. Standards Track [Page 68]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- Note that clients might advertise support of cipher suites that are
- on the black list in order to allow for connection to servers that do
- not support HTTP/2. This allows servers to select HTTP/1.1 with a
- cipher suite that is on the HTTP/2 black list. However, this can
- result in HTTP/2 being negotiated with a black-listed cipher suite if
- the application protocol and cipher suite are independently selected.
-
-10. Security Considerations
-
-10.1. Server Authority
-
- HTTP/2 relies on the HTTP/1.1 definition of authority for determining
- whether a server is authoritative in providing a given response (see
- [RFC7230], Section 9.1). This relies on local name resolution for
- the "http" URI scheme and the authenticated server identity for the
- "https" scheme (see [RFC2818], Section 3).
-
-10.2. Cross-Protocol Attacks
-
- In a cross-protocol attack, an attacker causes a client to initiate a
- transaction in one protocol toward a server that understands a
- different protocol. An attacker might be able to cause the
- transaction to appear as a valid transaction in the second protocol.
- In combination with the capabilities of the web context, this can be
- used to interact with poorly protected servers in private networks.
-
- Completing a TLS handshake with an ALPN identifier for HTTP/2 can be
- considered sufficient protection against cross-protocol attacks.
- ALPN provides a positive indication that a server is willing to
- proceed with HTTP/2, which prevents attacks on other TLS-based
- protocols.
-
- The encryption in TLS makes it difficult for attackers to control the
- data that could be used in a cross-protocol attack on a cleartext
- protocol.
-
- The cleartext version of HTTP/2 has minimal protection against cross-
- protocol attacks. The connection preface (Section 3.5) contains a
- string that is designed to confuse HTTP/1.1 servers, but no special
- protection is offered for other protocols. A server that is willing
- to ignore parts of an HTTP/1.1 request containing an Upgrade header
- field in addition to the client connection preface could be exposed
- to a cross-protocol attack.
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 69]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-10.3. Intermediary Encapsulation Attacks
-
- The HTTP/2 header field encoding allows the expression of names that
- are not valid field names in the Internet Message Syntax used by
- HTTP/1.1. Requests or responses containing invalid header field
- names MUST be treated as malformed (Section 8.1.2.6). An
- intermediary therefore cannot translate an HTTP/2 request or response
- containing an invalid field name into an HTTP/1.1 message.
-
- Similarly, HTTP/2 allows header field values that are not valid.
- While most of the values that can be encoded will not alter header
- field parsing, carriage return (CR, ASCII 0xd), line feed (LF, ASCII
- 0xa), and the zero character (NUL, ASCII 0x0) might be exploited by
- an attacker if they are translated verbatim. Any request or response
- that contains a character not permitted in a header field value MUST
- be treated as malformed (Section 8.1.2.6). Valid characters are
- defined by the "field-content" ABNF rule in Section 3.2 of [RFC7230].
-
-10.4. Cacheability of Pushed Responses
-
- Pushed responses do not have an explicit request from the client; the
- request is provided by the server in the PUSH_PROMISE frame.
-
- Caching responses that are pushed is possible based on the guidance
- provided by the origin server in the Cache-Control header field.
- However, this can cause issues if a single server hosts more than one
- tenant. For example, a server might offer multiple users each a
- small portion of its URI space.
-
- Where multiple tenants share space on the same server, that server
- MUST ensure that tenants are not able to push representations of
- resources that they do not have authority over. Failure to enforce
- this would allow a tenant to provide a representation that would be
- served out of cache, overriding the actual representation that the
- authoritative tenant provides.
-
- Pushed responses for which an origin server is not authoritative (see
- Section 10.1) MUST NOT be used or cached.
-
-10.5. Denial-of-Service Considerations
-
- An HTTP/2 connection can demand a greater commitment of resources to
- operate than an HTTP/1.1 connection. The use of header compression
- and flow control depend on a commitment of resources for storing a
- greater amount of state. Settings for these features ensure that
- memory commitments for these features are strictly bounded.
-
-
-
-
-
-Belshe, et al. Standards Track [Page 70]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- The number of PUSH_PROMISE frames is not constrained in the same
- fashion. A client that accepts server push SHOULD limit the number
- of streams it allows to be in the "reserved (remote)" state. An
- excessive number of server push streams can be treated as a stream
- error (Section 5.4.2) of type ENHANCE_YOUR_CALM.
-
- Processing capacity cannot be guarded as effectively as state
- capacity.
-
- The SETTINGS frame can be abused to cause a peer to expend additional
- processing time. This might be done by pointlessly changing SETTINGS
- parameters, setting multiple undefined parameters, or changing the
- same setting multiple times in the same frame. WINDOW_UPDATE or
- PRIORITY frames can be abused to cause an unnecessary waste of
- resources.
-
- Large numbers of small or empty frames can be abused to cause a peer
- to expend time processing frame headers. Note, however, that some
- uses are entirely legitimate, such as the sending of an empty DATA or
- CONTINUATION frame at the end of a stream.
-
- Header compression also offers some opportunities to waste processing
- resources; see Section 7 of [COMPRESSION] for more details on
- potential abuses.
-
- Limits in SETTINGS parameters cannot be reduced instantaneously,
- which leaves an endpoint exposed to behavior from a peer that could
- exceed the new limits. In particular, immediately after establishing
- a connection, limits set by a server are not known to clients and
- could be exceeded without being an obvious protocol violation.
-
- All these features -- i.e., SETTINGS changes, small frames, header
- compression -- have legitimate uses. These features become a burden
- only when they are used unnecessarily or to excess.
-
- An endpoint that doesn't monitor this behavior exposes itself to a
- risk of denial-of-service attack. Implementations SHOULD track the
- use of these features and set limits on their use. An endpoint MAY
- treat activity that is suspicious as a connection error
- (Section 5.4.1) of type ENHANCE_YOUR_CALM.
-
-10.5.1. Limits on Header Block Size
-
- A large header block (Section 4.3) can cause an implementation to
- commit a large amount of state. Header fields that are critical for
- routing can appear toward the end of a header block, which prevents
- streaming of header fields to their ultimate destination. This
- ordering and other reasons, such as ensuring cache correctness, mean
-
-
-
-Belshe, et al. Standards Track [Page 71]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- that an endpoint might need to buffer the entire header block. Since
- there is no hard limit to the size of a header block, some endpoints
- could be forced to commit a large amount of available memory for
- header fields.
-
- An endpoint can use the SETTINGS_MAX_HEADER_LIST_SIZE to advise peers
- of limits that might apply on the size of header blocks. This
- setting is only advisory, so endpoints MAY choose to send header
- blocks that exceed this limit and risk having the request or response
- being treated as malformed. This setting is specific to a
- connection, so any request or response could encounter a hop with a
- lower, unknown limit. An intermediary can attempt to avoid this
- problem by passing on values presented by different peers, but they
- are not obligated to do so.
-
- A server that receives a larger header block than it is willing to
- handle can send an HTTP 431 (Request Header Fields Too Large) status
- code [RFC6585]. A client can discard responses that it cannot
- process. The header block MUST be processed to ensure a consistent
- connection state, unless the connection is closed.
-
-10.5.2. CONNECT Issues
-
- The CONNECT method can be used to create disproportionate load on an
- proxy, since stream creation is relatively inexpensive when compared
- to the creation and maintenance of a TCP connection. A proxy might
- also maintain some resources for a TCP connection beyond the closing
- of the stream that carries the CONNECT request, since the outgoing
- TCP connection remains in the TIME_WAIT state. Therefore, a proxy
- cannot rely on SETTINGS_MAX_CONCURRENT_STREAMS alone to limit the
- resources consumed by CONNECT requests.
-
-10.6. Use of Compression
-
- Compression can allow an attacker to recover secret data when it is
- compressed in the same context as data under attacker control.
- HTTP/2 enables compression of header fields (Section 4.3); the
- following concerns also apply to the use of HTTP compressed content-
- codings ([RFC7231], Section 3.1.2.1).
-
- There are demonstrable attacks on compression that exploit the
- characteristics of the web (e.g., [BREACH]). The attacker induces
- multiple requests containing varying plaintext, observing the length
- of the resulting ciphertext in each, which reveals a shorter length
- when a guess about the secret is correct.
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 72]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- Implementations communicating on a secure channel MUST NOT compress
- content that includes both confidential and attacker-controlled data
- unless separate compression dictionaries are used for each source of
- data. Compression MUST NOT be used if the source of data cannot be
- reliably determined. Generic stream compression, such as that
- provided by TLS, MUST NOT be used with HTTP/2 (see Section 9.2).
-
- Further considerations regarding the compression of header fields are
- described in [COMPRESSION].
-
-10.7. Use of Padding
-
- Padding within HTTP/2 is not intended as a replacement for general
- purpose padding, such as might be provided by TLS [TLS12]. Redundant
- padding could even be counterproductive. Correct application can
- depend on having specific knowledge of the data that is being padded.
-
- To mitigate attacks that rely on compression, disabling or limiting
- compression might be preferable to padding as a countermeasure.
-
- Padding can be used to obscure the exact size of frame content and is
- provided to mitigate specific attacks within HTTP, for example,
- attacks where compressed content includes both attacker-controlled
- plaintext and secret data (e.g., [BREACH]).
-
- Use of padding can result in less protection than might seem
- immediately obvious. At best, padding only makes it more difficult
- for an attacker to infer length information by increasing the number
- of frames an attacker has to observe. Incorrectly implemented
- padding schemes can be easily defeated. In particular, randomized
- padding with a predictable distribution provides very little
- protection; similarly, padding payloads to a fixed size exposes
- information as payload sizes cross the fixed-sized boundary, which
- could be possible if an attacker can control plaintext.
-
- Intermediaries SHOULD retain padding for DATA frames but MAY drop
- padding for HEADERS and PUSH_PROMISE frames. A valid reason for an
- intermediary to change the amount of padding of frames is to improve
- the protections that padding provides.
-
-10.8. Privacy Considerations
-
- Several characteristics of HTTP/2 provide an observer an opportunity
- to correlate actions of a single client or server over time. These
- include the value of settings, the manner in which flow-control
- windows are managed, the way priorities are allocated to streams, the
- timing of reactions to stimulus, and the handling of any features
- that are controlled by settings.
-
-
-
-Belshe, et al. Standards Track [Page 73]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- As far as these create observable differences in behavior, they could
- be used as a basis for fingerprinting a specific client, as defined
- in Section 1.8 of [HTML5].
-
- HTTP/2's preference for using a single TCP connection allows
- correlation of a user's activity on a site. Reusing connections for
- different origins allows tracking across those origins.
-
- Because the PING and SETTINGS frames solicit immediate responses,
- they can be used by an endpoint to measure latency to their peer.
- This might have privacy implications in certain scenarios.
-
-11. IANA Considerations
-
- A string for identifying HTTP/2 is entered into the "Application-
- Layer Protocol Negotiation (ALPN) Protocol IDs" registry established
- in [TLS-ALPN].
-
- This document establishes a registry for frame types, settings, and
- error codes. These new registries appear in the new "Hypertext
- Transfer Protocol version 2 (HTTP/2) Parameters" section.
-
- This document registers the HTTP2-Settings header field for use in
- HTTP; it also registers the 421 (Misdirected Request) status code.
-
- This document registers the "PRI" method for use in HTTP to avoid
- collisions with the connection preface (Section 3.5).
-
-11.1. Registration of HTTP/2 Identification Strings
-
- This document creates two registrations for the identification of
- HTTP/2 (see Section 3.3) in the "Application-Layer Protocol
- Negotiation (ALPN) Protocol IDs" registry established in [TLS-ALPN].
-
- The "h2" string identifies HTTP/2 when used over TLS:
-
- Protocol: HTTP/2 over TLS
-
- Identification Sequence: 0x68 0x32 ("h2")
-
- Specification: This document
-
- The "h2c" string identifies HTTP/2 when used over cleartext TCP:
-
- Protocol: HTTP/2 over TCP
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 74]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- Identification Sequence: 0x68 0x32 0x63 ("h2c")
-
- Specification: This document
-
-11.2. Frame Type Registry
-
- This document establishes a registry for HTTP/2 frame type codes.
- The "HTTP/2 Frame Type" registry manages an 8-bit space. The "HTTP/2
- Frame Type" registry operates under either of the "IETF Review" or
- "IESG Approval" policies [RFC5226] for values between 0x00 and 0xef,
- with values between 0xf0 and 0xff being reserved for Experimental
- Use.
-
- New entries in this registry require the following information:
-
- Frame Type: A name or label for the frame type.
-
- Code: The 8-bit code assigned to the frame type.
-
- Specification: A reference to a specification that includes a
- description of the frame layout, its semantics, and flags that the
- frame type uses, including any parts of the frame that are
- conditionally present based on the value of flags.
-
- The entries in the following table are registered by this document.
-
- +---------------+------+--------------+
- | Frame Type | Code | Section |
- +---------------+------+--------------+
- | DATA | 0x0 | Section 6.1 |
- | HEADERS | 0x1 | Section 6.2 |
- | PRIORITY | 0x2 | Section 6.3 |
- | RST_STREAM | 0x3 | Section 6.4 |
- | SETTINGS | 0x4 | Section 6.5 |
- | PUSH_PROMISE | 0x5 | Section 6.6 |
- | PING | 0x6 | Section 6.7 |
- | GOAWAY | 0x7 | Section 6.8 |
- | WINDOW_UPDATE | 0x8 | Section 6.9 |
- | CONTINUATION | 0x9 | Section 6.10 |
- +---------------+------+--------------+
-
-11.3. Settings Registry
-
- This document establishes a registry for HTTP/2 settings. The
- "HTTP/2 Settings" registry manages a 16-bit space. The "HTTP/2
- Settings" registry operates under the "Expert Review" policy
- [RFC5226] for values in the range from 0x0000 to 0xefff, with values
- between and 0xf000 and 0xffff being reserved for Experimental Use.
-
-
-
-Belshe, et al. Standards Track [Page 75]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- New registrations are advised to provide the following information:
-
- Name: A symbolic name for the setting. Specifying a setting name is
- optional.
-
- Code: The 16-bit code assigned to the setting.
-
- Initial Value: An initial value for the setting.
-
- Specification: An optional reference to a specification that
- describes the use of the setting.
-
- The entries in the following table are registered by this document.
-
- +------------------------+------+---------------+---------------+
- | Name | Code | Initial Value | Specification |
- +------------------------+------+---------------+---------------+
- | HEADER_TABLE_SIZE | 0x1 | 4096 | Section 6.5.2 |
- | ENABLE_PUSH | 0x2 | 1 | Section 6.5.2 |
- | MAX_CONCURRENT_STREAMS | 0x3 | (infinite) | Section 6.5.2 |
- | INITIAL_WINDOW_SIZE | 0x4 | 65535 | Section 6.5.2 |
- | MAX_FRAME_SIZE | 0x5 | 16384 | Section 6.5.2 |
- | MAX_HEADER_LIST_SIZE | 0x6 | (infinite) | Section 6.5.2 |
- +------------------------+------+---------------+---------------+
-
-11.4. Error Code Registry
-
- This document establishes a registry for HTTP/2 error codes. The
- "HTTP/2 Error Code" registry manages a 32-bit space. The "HTTP/2
- Error Code" registry operates under the "Expert Review" policy
- [RFC5226].
-
- Registrations for error codes are required to include a description
- of the error code. An expert reviewer is advised to examine new
- registrations for possible duplication with existing error codes.
- Use of existing registrations is to be encouraged, but not mandated.
-
- New registrations are advised to provide the following information:
-
- Name: A name for the error code. Specifying an error code name is
- optional.
-
- Code: The 32-bit error code value.
-
- Description: A brief description of the error code semantics, longer
- if no detailed specification is provided.
-
-
-
-
-
-Belshe, et al. Standards Track [Page 76]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- Specification: An optional reference for a specification that
- defines the error code.
-
- The entries in the following table are registered by this document.
-
- +---------------------+------+----------------------+---------------+
- | Name | Code | Description | Specification |
- +---------------------+------+----------------------+---------------+
- | NO_ERROR | 0x0 | Graceful shutdown | Section 7 |
- | PROTOCOL_ERROR | 0x1 | Protocol error | Section 7 |
- | | | detected | |
- | INTERNAL_ERROR | 0x2 | Implementation fault | Section 7 |
- | FLOW_CONTROL_ERROR | 0x3 | Flow-control limits | Section 7 |
- | | | exceeded | |
- | SETTINGS_TIMEOUT | 0x4 | Settings not | Section 7 |
- | | | acknowledged | |
- | STREAM_CLOSED | 0x5 | Frame received for | Section 7 |
- | | | closed stream | |
- | FRAME_SIZE_ERROR | 0x6 | Frame size incorrect | Section 7 |
- | REFUSED_STREAM | 0x7 | Stream not processed | Section 7 |
- | CANCEL | 0x8 | Stream cancelled | Section 7 |
- | COMPRESSION_ERROR | 0x9 | Compression state | Section 7 |
- | | | not updated | |
- | CONNECT_ERROR | 0xa | TCP connection error | Section 7 |
- | | | for CONNECT method | |
- | ENHANCE_YOUR_CALM | 0xb | Processing capacity | Section 7 |
- | | | exceeded | |
- | INADEQUATE_SECURITY | 0xc | Negotiated TLS | Section 7 |
- | | | parameters not | |
- | | | acceptable | |
- | HTTP_1_1_REQUIRED | 0xd | Use HTTP/1.1 for the | Section 7 |
- | | | request | |
- +---------------------+------+----------------------+---------------+
-
-11.5. HTTP2-Settings Header Field Registration
-
- This section registers the HTTP2-Settings header field in the
- "Permanent Message Header Field Names" registry [BCP90].
-
- Header field name: HTTP2-Settings
-
- Applicable protocol: http
-
- Status: standard
-
- Author/Change controller: IETF
-
-
-
-
-
-Belshe, et al. Standards Track [Page 77]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- Specification document(s): Section 3.2.1 of this document
-
- Related information: This header field is only used by an HTTP/2
- client for Upgrade-based negotiation.
-
-11.6. PRI Method Registration
-
- This section registers the "PRI" method in the "HTTP Method Registry"
- ([RFC7231], Section 8.1).
-
- Method Name: PRI
-
- Safe: Yes
-
- Idempotent: Yes
-
- Specification document(s): Section 3.5 of this document
-
- Related information: This method is never used by an actual client.
- This method will appear to be used when an HTTP/1.1 server or
- intermediary attempts to parse an HTTP/2 connection preface.
-
-11.7. The 421 (Misdirected Request) HTTP Status Code
-
- This document registers the 421 (Misdirected Request) HTTP status
- code in the "HTTP Status Codes" registry ([RFC7231], Section 8.2).
-
- Status Code: 421
-
- Short Description: Misdirected Request
-
- Specification: Section 9.1.2 of this document
-
-11.8. The h2c Upgrade Token
-
- This document registers the "h2c" upgrade token in the "HTTP Upgrade
- Tokens" registry ([RFC7230], Section 8.6).
-
- Value: h2c
-
- Description: Hypertext Transfer Protocol version 2 (HTTP/2)
-
- Expected Version Tokens: None
-
- Reference: Section 3.2 of this document
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 78]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-12. References
-
-12.1. Normative References
-
- [COMPRESSION] Peon, R. and H. Ruellan, "HPACK: Header Compression for
- HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015,
- <http://www.rfc-editor.org/info/rfc7541>.
-
- [COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265,
- DOI 10.17487/RFC6265, April 2011,
- <http://www.rfc-editor.org/info/rfc6265>.
-
- [FIPS186] NIST, "Digital Signature Standard (DSS)", FIPS PUB
- 186-4, July 2013,
- <http://dx.doi.org/10.6028/NIST.FIPS.186-4>.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
- RFC2119, March 1997,
- <http://www.rfc-editor.org/info/rfc2119>.
-
- [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, DOI 10.17487/
- RFC2818, May 2000,
- <http://www.rfc-editor.org/info/rfc2818>.
-
- [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter,
- "Uniform Resource Identifier (URI): Generic Syntax",
- STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005,
- <http://www.rfc-editor.org/info/rfc3986>.
-
- [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
- Encodings", RFC 4648, DOI 10.17487/RFC4648, October
- 2006, <http://www.rfc-editor.org/info/rfc4648>.
-
- [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing
- an IANA Considerations Section in RFCs", BCP 26,
- RFC 5226, DOI 10.17487/RFC5226, May 2008,
- <http://www.rfc-editor.org/info/rfc5226>.
-
- [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for
- Syntax Specifications: ABNF", STD 68, RFC 5234,
- DOI 10.17487/ RFC5234, January 2008,
- <http://www.rfc-editor.org/info/rfc5234>.
-
- [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext
- Transfer Protocol (HTTP/1.1): Message Syntax and
- Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014,
- <http://www.rfc-editor.org/info/rfc7230>.
-
-
-
-Belshe, et al. Standards Track [Page 79]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext
- Transfer Protocol (HTTP/1.1): Semantics and Content",
- RFC 7231, DOI 10.17487/RFC7231, June 2014,
- <http://www.rfc-editor.org/info/rfc7231>.
-
- [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext
- Transfer Protocol (HTTP/1.1): Conditional Requests",
- RFC 7232, DOI 10.17487/RFC7232, June 2014,
- <http://www.rfc-editor.org/info/rfc7232>.
-
- [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed.,
- "Hypertext Transfer Protocol (HTTP/1.1): Range
- Requests", RFC 7233, DOI 10.17487/RFC7233, June 2014,
- <http://www.rfc-editor.org/info/rfc7233>.
-
- [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
- Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
- RFC 7234, DOI 10.17487/RFC7234, June 2014,
- <http://www.rfc-editor.org/info/rfc7234>.
-
- [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext
- Transfer Protocol (HTTP/1.1): Authentication",
- RFC 7235, DOI 10.17487/RFC7235, June 2014,
- <http://www.rfc-editor.org/info/rfc7235>.
-
- [TCP] Postel, J., "Transmission Control Protocol", STD 7, RFC
- 793, DOI 10.17487/RFC0793, September 1981,
- <http://www.rfc-editor.org/info/rfc793>.
-
- [TLS-ALPN] Friedl, S., Popov, A., Langley, A., and E. Stephan,
- "Transport Layer Security (TLS) Application-Layer
- Protocol Negotiation Extension", RFC 7301,
- DOI 10.17487/RFC7301, July 2014,
- <http://www.rfc-editor.org/info/rfc7301>.
-
- [TLS-ECDHE] Rescorla, E., "TLS Elliptic Curve Cipher Suites with
- SHA-256/384 and AES Galois Counter Mode (GCM)",
- RFC 5289, DOI 10.17487/RFC5289, August 2008,
- <http://www.rfc-editor.org/info/rfc5289>.
-
- [TLS-EXT] Eastlake 3rd, D., "Transport Layer Security (TLS)
- Extensions: Extension Definitions", RFC 6066,
- DOI 10.17487/RFC6066, January 2011,
- <http://www.rfc-editor.org/info/rfc6066>.
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 80]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- [TLS12] Dierks, T. and E. Rescorla, "The Transport Layer
- Security (TLS) Protocol Version 1.2", RFC 5246,
- DOI 10.17487/ RFC5246, August 2008,
- <http://www.rfc-editor.org/info/rfc5246>.
-
-12.2. Informative References
-
- [ALT-SVC] Nottingham, M., McManus, P., and J. Reschke, "HTTP
- Alternative Services", Work in Progress, draft-ietf-
- httpbis-alt-svc-06, February 2015.
-
- [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration
- Procedures for Message Header Fields", BCP 90,
- RFC 3864, September 2004,
- <http://www.rfc-editor.org/info/bcp90>.
-
- [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving
- the CRIME Attack", July 2013,
- <http://breachattack.com/resources/
- BREACH%20-%20SSL,%20gone%20in%2030%20seconds.pdf>.
-
- [HTML5] Hickson, I., Berjon, R., Faulkner, S., Leithead, T.,
- Doyle Navara, E., O'Connor, E., and S. Pfeiffer,
- "HTML5", W3C Recommendation REC-html5-20141028, October
- 2014, <http://www.w3.org/TR/2014/REC-html5-20141028/>.
-
- [RFC3749] Hollenbeck, S., "Transport Layer Security Protocol
- Compression Methods", RFC 3749, DOI 10.17487/RFC3749,
- May 2004, <http://www.rfc-editor.org/info/rfc3749>.
-
- [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and
- B. Moeller, "Elliptic Curve Cryptography (ECC) Cipher
- Suites for Transport Layer Security (TLS)", RFC 4492,
- DOI 10.17487/RFC4492, May 2006,
- <http://www.rfc-editor.org/info/rfc4492>.
-
- [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status
- Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012,
- <http://www.rfc-editor.org/info/rfc6585>.
-
- [RFC7323] Borman, D., Braden, B., Jacobson, V., and R.
- Scheffenegger, Ed., "TCP Extensions for High
- Performance", RFC 7323, DOI 10.17487/RFC7323, September
- 2014, <http://www.rfc-editor.org/info/rfc7323>.
-
- [TALKING] Huang, L., Chen, E., Barth, A., Rescorla, E., and C.
- Jackson, "Talking to Yourself for Fun and Profit",
- 2011, <http://w2spconf.com/2011/papers/websocket.pdf>.
-
-
-
-Belshe, et al. Standards Track [Page 81]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- [TLSBCP] Sheffer, Y., Holz, R., and P. Saint-Andre,
- "Recommendations for Secure Use of Transport Layer
- Security (TLS) and Datagram Transport Layer Security
- (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May
- 2015, <http://www.rfc-editor.org/info/rfc7525>.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 82]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-Appendix A. TLS 1.2 Cipher Suite Black List
-
- An HTTP/2 implementation MAY treat the negotiation of any of the
- following cipher suites with TLS 1.2 as a connection error
- (Section 5.4.1) of type INADEQUATE_SECURITY:
-
- o TLS_NULL_WITH_NULL_NULL
-
- o TLS_RSA_WITH_NULL_MD5
-
- o TLS_RSA_WITH_NULL_SHA
-
- o TLS_RSA_EXPORT_WITH_RC4_40_MD5
-
- o TLS_RSA_WITH_RC4_128_MD5
-
- o TLS_RSA_WITH_RC4_128_SHA
-
- o TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5
-
- o TLS_RSA_WITH_IDEA_CBC_SHA
-
- o TLS_RSA_EXPORT_WITH_DES40_CBC_SHA
-
- o TLS_RSA_WITH_DES_CBC_SHA
-
- o TLS_RSA_WITH_3DES_EDE_CBC_SHA
-
- o TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA
-
- o TLS_DH_DSS_WITH_DES_CBC_SHA
-
- o TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA
-
- o TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA
-
- o TLS_DH_RSA_WITH_DES_CBC_SHA
-
- o TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA
-
- o TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
-
- o TLS_DHE_DSS_WITH_DES_CBC_SHA
-
- o TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
-
- o TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
-
-
-
-
-Belshe, et al. Standards Track [Page 83]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- o TLS_DHE_RSA_WITH_DES_CBC_SHA
-
- o TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
-
- o TLS_DH_anon_EXPORT_WITH_RC4_40_MD5
-
- o TLS_DH_anon_WITH_RC4_128_MD5
-
- o TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA
-
- o TLS_DH_anon_WITH_DES_CBC_SHA
-
- o TLS_DH_anon_WITH_3DES_EDE_CBC_SHA
-
- o TLS_KRB5_WITH_DES_CBC_SHA
-
- o TLS_KRB5_WITH_3DES_EDE_CBC_SHA
-
- o TLS_KRB5_WITH_RC4_128_SHA
-
- o TLS_KRB5_WITH_IDEA_CBC_SHA
-
- o TLS_KRB5_WITH_DES_CBC_MD5
-
- o TLS_KRB5_WITH_3DES_EDE_CBC_MD5
-
- o TLS_KRB5_WITH_RC4_128_MD5
-
- o TLS_KRB5_WITH_IDEA_CBC_MD5
-
- o TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA
-
- o TLS_KRB5_EXPORT_WITH_RC2_CBC_40_SHA
-
- o TLS_KRB5_EXPORT_WITH_RC4_40_SHA
-
- o TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5
-
- o TLS_KRB5_EXPORT_WITH_RC2_CBC_40_MD5
-
- o TLS_KRB5_EXPORT_WITH_RC4_40_MD5
-
- o TLS_PSK_WITH_NULL_SHA
-
- o TLS_DHE_PSK_WITH_NULL_SHA
-
- o TLS_RSA_PSK_WITH_NULL_SHA
-
-
-
-
-Belshe, et al. Standards Track [Page 84]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- o TLS_RSA_WITH_AES_128_CBC_SHA
-
- o TLS_DH_DSS_WITH_AES_128_CBC_SHA
-
- o TLS_DH_RSA_WITH_AES_128_CBC_SHA
-
- o TLS_DHE_DSS_WITH_AES_128_CBC_SHA
-
- o TLS_DHE_RSA_WITH_AES_128_CBC_SHA
-
- o TLS_DH_anon_WITH_AES_128_CBC_SHA
-
- o TLS_RSA_WITH_AES_256_CBC_SHA
-
- o TLS_DH_DSS_WITH_AES_256_CBC_SHA
-
- o TLS_DH_RSA_WITH_AES_256_CBC_SHA
-
- o TLS_DHE_DSS_WITH_AES_256_CBC_SHA
-
- o TLS_DHE_RSA_WITH_AES_256_CBC_SHA
-
- o TLS_DH_anon_WITH_AES_256_CBC_SHA
-
- o TLS_RSA_WITH_NULL_SHA256
-
- o TLS_RSA_WITH_AES_128_CBC_SHA256
-
- o TLS_RSA_WITH_AES_256_CBC_SHA256
-
- o TLS_DH_DSS_WITH_AES_128_CBC_SHA256
-
- o TLS_DH_RSA_WITH_AES_128_CBC_SHA256
-
- o TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
-
- o TLS_RSA_WITH_CAMELLIA_128_CBC_SHA
-
- o TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA
-
- o TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA
-
- o TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA
-
- o TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA
-
- o TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA
-
-
-
-
-Belshe, et al. Standards Track [Page 85]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- o TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
-
- o TLS_DH_DSS_WITH_AES_256_CBC_SHA256
-
- o TLS_DH_RSA_WITH_AES_256_CBC_SHA256
-
- o TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
-
- o TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
-
- o TLS_DH_anon_WITH_AES_128_CBC_SHA256
-
- o TLS_DH_anon_WITH_AES_256_CBC_SHA256
-
- o TLS_RSA_WITH_CAMELLIA_256_CBC_SHA
-
- o TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA
-
- o TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA
-
- o TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA
-
- o TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA
-
- o TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA
-
- o TLS_PSK_WITH_RC4_128_SHA
-
- o TLS_PSK_WITH_3DES_EDE_CBC_SHA
-
- o TLS_PSK_WITH_AES_128_CBC_SHA
-
- o TLS_PSK_WITH_AES_256_CBC_SHA
-
- o TLS_DHE_PSK_WITH_RC4_128_SHA
-
- o TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA
-
- o TLS_DHE_PSK_WITH_AES_128_CBC_SHA
-
- o TLS_DHE_PSK_WITH_AES_256_CBC_SHA
-
- o TLS_RSA_PSK_WITH_RC4_128_SHA
-
- o TLS_RSA_PSK_WITH_3DES_EDE_CBC_SHA
-
- o TLS_RSA_PSK_WITH_AES_128_CBC_SHA
-
-
-
-
-Belshe, et al. Standards Track [Page 86]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- o TLS_RSA_PSK_WITH_AES_256_CBC_SHA
-
- o TLS_RSA_WITH_SEED_CBC_SHA
-
- o TLS_DH_DSS_WITH_SEED_CBC_SHA
-
- o TLS_DH_RSA_WITH_SEED_CBC_SHA
-
- o TLS_DHE_DSS_WITH_SEED_CBC_SHA
-
- o TLS_DHE_RSA_WITH_SEED_CBC_SHA
-
- o TLS_DH_anon_WITH_SEED_CBC_SHA
-
- o TLS_RSA_WITH_AES_128_GCM_SHA256
-
- o TLS_RSA_WITH_AES_256_GCM_SHA384
-
- o TLS_DH_RSA_WITH_AES_128_GCM_SHA256
-
- o TLS_DH_RSA_WITH_AES_256_GCM_SHA384
-
- o TLS_DH_DSS_WITH_AES_128_GCM_SHA256
-
- o TLS_DH_DSS_WITH_AES_256_GCM_SHA384
-
- o TLS_DH_anon_WITH_AES_128_GCM_SHA256
-
- o TLS_DH_anon_WITH_AES_256_GCM_SHA384
-
- o TLS_PSK_WITH_AES_128_GCM_SHA256
-
- o TLS_PSK_WITH_AES_256_GCM_SHA384
-
- o TLS_RSA_PSK_WITH_AES_128_GCM_SHA256
-
- o TLS_RSA_PSK_WITH_AES_256_GCM_SHA384
-
- o TLS_PSK_WITH_AES_128_CBC_SHA256
-
- o TLS_PSK_WITH_AES_256_CBC_SHA384
-
- o TLS_PSK_WITH_NULL_SHA256
-
- o TLS_PSK_WITH_NULL_SHA384
-
- o TLS_DHE_PSK_WITH_AES_128_CBC_SHA256
-
-
-
-
-Belshe, et al. Standards Track [Page 87]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- o TLS_DHE_PSK_WITH_AES_256_CBC_SHA384
-
- o TLS_DHE_PSK_WITH_NULL_SHA256
-
- o TLS_DHE_PSK_WITH_NULL_SHA384
-
- o TLS_RSA_PSK_WITH_AES_128_CBC_SHA256
-
- o TLS_RSA_PSK_WITH_AES_256_CBC_SHA384
-
- o TLS_RSA_PSK_WITH_NULL_SHA256
-
- o TLS_RSA_PSK_WITH_NULL_SHA384
-
- o TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256
-
- o TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA256
-
- o TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA256
-
- o TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA256
-
- o TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256
-
- o TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA256
-
- o TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256
-
- o TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA256
-
- o TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA256
-
- o TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA256
-
- o TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256
-
- o TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA256
-
- o TLS_EMPTY_RENEGOTIATION_INFO_SCSV
-
- o TLS_ECDH_ECDSA_WITH_NULL_SHA
-
- o TLS_ECDH_ECDSA_WITH_RC4_128_SHA
-
- o TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
-
- o TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
-
-
-
-
-Belshe, et al. Standards Track [Page 88]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- o TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA
-
- o TLS_ECDHE_ECDSA_WITH_NULL_SHA
-
- o TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
-
- o TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
-
- o TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
-
- o TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
-
- o TLS_ECDH_RSA_WITH_NULL_SHA
-
- o TLS_ECDH_RSA_WITH_RC4_128_SHA
-
- o TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
-
- o TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
-
- o TLS_ECDH_RSA_WITH_AES_256_CBC_SHA
-
- o TLS_ECDHE_RSA_WITH_NULL_SHA
-
- o TLS_ECDHE_RSA_WITH_RC4_128_SHA
-
- o TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
-
- o TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
-
- o TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
-
- o TLS_ECDH_anon_WITH_NULL_SHA
-
- o TLS_ECDH_anon_WITH_RC4_128_SHA
-
- o TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA
-
- o TLS_ECDH_anon_WITH_AES_128_CBC_SHA
-
- o TLS_ECDH_anon_WITH_AES_256_CBC_SHA
-
- o TLS_SRP_SHA_WITH_3DES_EDE_CBC_SHA
-
- o TLS_SRP_SHA_RSA_WITH_3DES_EDE_CBC_SHA
-
- o TLS_SRP_SHA_DSS_WITH_3DES_EDE_CBC_SHA
-
-
-
-
-Belshe, et al. Standards Track [Page 89]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- o TLS_SRP_SHA_WITH_AES_128_CBC_SHA
-
- o TLS_SRP_SHA_RSA_WITH_AES_128_CBC_SHA
-
- o TLS_SRP_SHA_DSS_WITH_AES_128_CBC_SHA
-
- o TLS_SRP_SHA_WITH_AES_256_CBC_SHA
-
- o TLS_SRP_SHA_RSA_WITH_AES_256_CBC_SHA
-
- o TLS_SRP_SHA_DSS_WITH_AES_256_CBC_SHA
-
- o TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
-
- o TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
-
- o TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
-
- o TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384
-
- o TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
-
- o TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
-
- o TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
-
- o TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384
-
- o TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256
-
- o TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384
-
- o TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256
-
- o TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384
-
- o TLS_ECDHE_PSK_WITH_RC4_128_SHA
-
- o TLS_ECDHE_PSK_WITH_3DES_EDE_CBC_SHA
-
- o TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA
-
- o TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA
-
- o TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256
-
- o TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA384
-
-
-
-
-Belshe, et al. Standards Track [Page 90]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- o TLS_ECDHE_PSK_WITH_NULL_SHA
-
- o TLS_ECDHE_PSK_WITH_NULL_SHA256
-
- o TLS_ECDHE_PSK_WITH_NULL_SHA384
-
- o TLS_RSA_WITH_ARIA_128_CBC_SHA256
-
- o TLS_RSA_WITH_ARIA_256_CBC_SHA384
-
- o TLS_DH_DSS_WITH_ARIA_128_CBC_SHA256
-
- o TLS_DH_DSS_WITH_ARIA_256_CBC_SHA384
-
- o TLS_DH_RSA_WITH_ARIA_128_CBC_SHA256
-
- o TLS_DH_RSA_WITH_ARIA_256_CBC_SHA384
-
- o TLS_DHE_DSS_WITH_ARIA_128_CBC_SHA256
-
- o TLS_DHE_DSS_WITH_ARIA_256_CBC_SHA384
-
- o TLS_DHE_RSA_WITH_ARIA_128_CBC_SHA256
-
- o TLS_DHE_RSA_WITH_ARIA_256_CBC_SHA384
-
- o TLS_DH_anon_WITH_ARIA_128_CBC_SHA256
-
- o TLS_DH_anon_WITH_ARIA_256_CBC_SHA384
-
- o TLS_ECDHE_ECDSA_WITH_ARIA_128_CBC_SHA256
-
- o TLS_ECDHE_ECDSA_WITH_ARIA_256_CBC_SHA384
-
- o TLS_ECDH_ECDSA_WITH_ARIA_128_CBC_SHA256
-
- o TLS_ECDH_ECDSA_WITH_ARIA_256_CBC_SHA384
-
- o TLS_ECDHE_RSA_WITH_ARIA_128_CBC_SHA256
-
- o TLS_ECDHE_RSA_WITH_ARIA_256_CBC_SHA384
-
- o TLS_ECDH_RSA_WITH_ARIA_128_CBC_SHA256
-
- o TLS_ECDH_RSA_WITH_ARIA_256_CBC_SHA384
-
- o TLS_RSA_WITH_ARIA_128_GCM_SHA256
-
-
-
-
-Belshe, et al. Standards Track [Page 91]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- o TLS_RSA_WITH_ARIA_256_GCM_SHA384
-
- o TLS_DH_RSA_WITH_ARIA_128_GCM_SHA256
-
- o TLS_DH_RSA_WITH_ARIA_256_GCM_SHA384
-
- o TLS_DH_DSS_WITH_ARIA_128_GCM_SHA256
-
- o TLS_DH_DSS_WITH_ARIA_256_GCM_SHA384
-
- o TLS_DH_anon_WITH_ARIA_128_GCM_SHA256
-
- o TLS_DH_anon_WITH_ARIA_256_GCM_SHA384
-
- o TLS_ECDH_ECDSA_WITH_ARIA_128_GCM_SHA256
-
- o TLS_ECDH_ECDSA_WITH_ARIA_256_GCM_SHA384
-
- o TLS_ECDH_RSA_WITH_ARIA_128_GCM_SHA256
-
- o TLS_ECDH_RSA_WITH_ARIA_256_GCM_SHA384
-
- o TLS_PSK_WITH_ARIA_128_CBC_SHA256
-
- o TLS_PSK_WITH_ARIA_256_CBC_SHA384
-
- o TLS_DHE_PSK_WITH_ARIA_128_CBC_SHA256
-
- o TLS_DHE_PSK_WITH_ARIA_256_CBC_SHA384
-
- o TLS_RSA_PSK_WITH_ARIA_128_CBC_SHA256
-
- o TLS_RSA_PSK_WITH_ARIA_256_CBC_SHA384
-
- o TLS_PSK_WITH_ARIA_128_GCM_SHA256
-
- o TLS_PSK_WITH_ARIA_256_GCM_SHA384
-
- o TLS_RSA_PSK_WITH_ARIA_128_GCM_SHA256
-
- o TLS_RSA_PSK_WITH_ARIA_256_GCM_SHA384
-
- o TLS_ECDHE_PSK_WITH_ARIA_128_CBC_SHA256
-
- o TLS_ECDHE_PSK_WITH_ARIA_256_CBC_SHA384
-
- o TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256
-
-
-
-
-Belshe, et al. Standards Track [Page 92]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- o TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384
-
- o TLS_ECDH_ECDSA_WITH_CAMELLIA_128_CBC_SHA256
-
- o TLS_ECDH_ECDSA_WITH_CAMELLIA_256_CBC_SHA384
-
- o TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256
-
- o TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384
-
- o TLS_ECDH_RSA_WITH_CAMELLIA_128_CBC_SHA256
-
- o TLS_ECDH_RSA_WITH_CAMELLIA_256_CBC_SHA384
-
- o TLS_RSA_WITH_CAMELLIA_128_GCM_SHA256
-
- o TLS_RSA_WITH_CAMELLIA_256_GCM_SHA384
-
- o TLS_DH_RSA_WITH_CAMELLIA_128_GCM_SHA256
-
- o TLS_DH_RSA_WITH_CAMELLIA_256_GCM_SHA384
-
- o TLS_DH_DSS_WITH_CAMELLIA_128_GCM_SHA256
-
- o TLS_DH_DSS_WITH_CAMELLIA_256_GCM_SHA384
-
- o TLS_DH_anon_WITH_CAMELLIA_128_GCM_SHA256
-
- o TLS_DH_anon_WITH_CAMELLIA_256_GCM_SHA384
-
- o TLS_ECDH_ECDSA_WITH_CAMELLIA_128_GCM_SHA256
-
- o TLS_ECDH_ECDSA_WITH_CAMELLIA_256_GCM_SHA384
-
- o TLS_ECDH_RSA_WITH_CAMELLIA_128_GCM_SHA256
-
- o TLS_ECDH_RSA_WITH_CAMELLIA_256_GCM_SHA384
-
- o TLS_PSK_WITH_CAMELLIA_128_GCM_SHA256
-
- o TLS_PSK_WITH_CAMELLIA_256_GCM_SHA384
-
- o TLS_RSA_PSK_WITH_CAMELLIA_128_GCM_SHA256
-
- o TLS_RSA_PSK_WITH_CAMELLIA_256_GCM_SHA384
-
- o TLS_PSK_WITH_CAMELLIA_128_CBC_SHA256
-
-
-
-
-Belshe, et al. Standards Track [Page 93]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
- o TLS_PSK_WITH_CAMELLIA_256_CBC_SHA384
-
- o TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256
-
- o TLS_DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384
-
- o TLS_RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256
-
- o TLS_RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384
-
- o TLS_ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256
-
- o TLS_ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384
-
- o TLS_RSA_WITH_AES_128_CCM
-
- o TLS_RSA_WITH_AES_256_CCM
-
- o TLS_RSA_WITH_AES_128_CCM_8
-
- o TLS_RSA_WITH_AES_256_CCM_8
-
- o TLS_PSK_WITH_AES_128_CCM
-
- o TLS_PSK_WITH_AES_256_CCM
-
- o TLS_PSK_WITH_AES_128_CCM_8
-
- o TLS_PSK_WITH_AES_256_CCM_8
-
- Note: This list was assembled from the set of registered TLS
- cipher suites at the time of writing. This list includes those
- cipher suites that do not offer an ephemeral key exchange and
- those that are based on the TLS null, stream, or block cipher type
- (as defined in Section 6.2.3 of [TLS12]). Additional cipher
- suites with these properties could be defined; these would not be
- explicitly prohibited.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 94]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-Acknowledgements
-
- This document includes substantial input from the following
- individuals:
-
- o Adam Langley, Wan-Teh Chang, Jim Morrison, Mark Nottingham, Alyssa
- Wilk, Costin Manolache, William Chan, Vitaliy Lvin, Joe Chan, Adam
- Barth, Ryan Hamilton, Gavin Peters, Kent Alstad, Kevin Lindsay,
- Paul Amer, Fan Yang, and Jonathan Leighton (SPDY contributors).
-
- o Gabriel Montenegro and Willy Tarreau (Upgrade mechanism).
-
- o William Chan, Salvatore Loreto, Osama Mazahir, Gabriel Montenegro,
- Jitu Padhye, Roberto Peon, and Rob Trace (Flow control).
-
- o Mike Bishop (Extensibility).
-
- o Mark Nottingham, Julian Reschke, James Snell, Jeff Pinner, Mike
- Bishop, and Herve Ruellan (Substantial editorial contributions).
-
- o Kari Hurtta, Tatsuhiro Tsujikawa, Greg Wilkins, Poul-Henning Kamp,
- and Jonathan Thackray.
-
- o Alexey Melnikov, who was an editor of this document in 2013.
-
- A substantial proportion of Martin's contribution was supported by
- Microsoft during his employment there.
-
- The Japanese HTTP/2 community provided invaluable contributions,
- including a number of implementations as well as numerous technical
- and editorial contributions.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 95]
-\f
-RFC 7540 HTTP/2 May 2015
-
-
-Authors' Addresses
-
- Mike Belshe
- BitGo
-
- EMail: mike@belshe.com
-
-
- Roberto Peon
- Google, Inc
-
- EMail: fenix@google.com
-
-
- Martin Thomson (editor)
- Mozilla
- 331 E Evelyn Street
- Mountain View, CA 94041
- United States
-
- EMail: martin.thomson@gmail.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Belshe, et al. Standards Track [Page 96]
-\f
+++ /dev/null
-
-
-
-
-
-
-Internet Engineering Task Force (IETF) P. McManus
-Request for Comments: 8246 Mozilla
-Category: Standards Track September 2017
-ISSN: 2070-1721
-
-
- HTTP Immutable Responses
-
-Abstract
-
- The immutable HTTP response Cache-Control extension allows servers to
- identify resources that will not be updated during their freshness
- lifetime. This ensures that a client never needs to revalidate a
- cached fresh resource to be certain it has not been modified.
-
-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
- https://www.rfc-editor.org/info/rfc8246.
-
-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
- (https://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.
-
-
-
-
-
-
-
-
-McManus Standards Track [Page 1]
-\f
-RFC 8246 HTTP Immutable Response September 2017
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
- 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
- 2. The Immutable Cache-Control Extension . . . . . . . . . . . . 3
- 2.1. About Intermediaries . . . . . . . . . . . . . . . . . . 4
- 2.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 4
- 3. Security Considerations . . . . . . . . . . . . . . . . . . . 4
- 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5
- 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 5
- 5.1. Normative References . . . . . . . . . . . . . . . . . . 5
- 5.2. Informative References . . . . . . . . . . . . . . . . . 5
- Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 6
- Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6
-
-1. Introduction
-
- HTTP's freshness lifetime mechanism [RFC7234] allows a client to
- safely reuse a stored response to satisfy future requests for a
- specified period of time. However, it is still possible that the
- resource will be modified during that period.
-
- For instance, a front-page newspaper photo with a freshness lifetime
- of one hour would mean that no user would see a cached photo more
- than one hour old. However, the photo could be updated at any time,
- resulting in different users seeing different photos depending on the
- contents of their caches for up to one hour. This is compliant with
- the caching mechanism defined in [RFC7234].
-
- Users that need to confirm there have been no updates to their cached
- responses typically use the reload (or refresh) mechanism in their
- user agents. This in turn generates a conditional request [RFC7232],
- and either a new representation or, if unmodified, a 304 (Not
- Modified) response [RFC7232] is returned. A user agent that
- understands HTML and fetches its dependent sub-resources might issue
- hundreds of conditional requests to refresh all portions of a common
- page [REQPERPAGE].
-
- However, some content providers never create more than one variant of
- a sub-resource, because they use "versioned" URLs. When these
- resources need an update, they are simply published under a new URL,
- typically embedding an identifier unique to that version of the
- resource in the path, and references to the sub-resource are updated
- with the new path information.
-
- For example, "https://www.example.com/101016/main.css" might be
- updated and republished as "https://www.example.com/102026/main.css",
- with any links that reference it being changed at the same time.
-
-
-
-McManus Standards Track [Page 2]
-\f
-RFC 8246 HTTP Immutable Response September 2017
-
-
- This design pattern allows a very large freshness lifetime to be used
- for the sub-resource without guessing when it will be updated in the
- future.
-
- Unfortunately, the user agent does not know when this versioned URL
- design pattern is used. As a result, user-driven refreshes still
- translate into wasted conditional requests for each sub-resource as
- each will return 304 responses.
-
- The immutable HTTP response Cache-Control extension allows servers to
- identify responses that will not be updated during their freshness
- lifetimes.
-
- This effectively informs clients that any conditional request for
- that response can be safely skipped without worrying that it has been
- updated.
-
-1.1. Notational Conventions
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
- "OPTIONAL" in this document are to be interpreted as described in BCP
- 14 [RFC2119] [RFC8174] when, and only when, they appear in all
- capitals, as shown here.
-
-2. The Immutable Cache-Control Extension
-
- When present in an HTTP response, the immutable Cache-Control
- extension indicates that the origin server will not update the
- representation of that resource during the freshness lifetime of the
- response.
-
- Clients SHOULD NOT issue a conditional request during the response's
- freshness lifetime (e.g., upon a reload) unless explicitly overridden
- by the user (e.g., a force reload).
-
- The immutable extension only applies during the freshness lifetime of
- the stored response. Stale responses SHOULD be revalidated as they
- normally would be in the absence of the immutable extension.
-
- The immutable extension takes no arguments. If any arguments are
- present, they have no meaning and MUST be ignored. Multiple
- instances of the immutable extension are equivalent to one instance.
- The presence of an immutable Cache-Control extension in a request has
- no effect.
-
-
-
-
-
-
-McManus Standards Track [Page 3]
-\f
-RFC 8246 HTTP Immutable Response September 2017
-
-
-2.1. About Intermediaries
-
- An immutable response has the same semantic meaning when received by
- proxy clients as it does when received by user-agent-based clients.
- Therefore, proxies SHOULD skip conditionally revalidating fresh
- responses containing the immutable extension unless there is a signal
- from the client that a validation is necessary (e.g., a no-cache
- Cache-Control request directive defined in Section 5.2.1.4 of
- [RFC7234]).
-
- A proxy that uses the immutable extension to bypass a conditional
- revalidation can choose whether to reply with a 304 or 200 response
- to its requesting client based on the request headers the proxy
- received.
-
-2.2. Example
-
- Cache-Control: max-age=31536000, immutable
-
-3. Security Considerations
-
- The immutable mechanism acts as form of soft pinning and, as with all
- pinning mechanisms, creates a vector for amplification of cache
- corruption incidents. These incidents include cache-poisoning
- attacks. Three mechanisms are suggested for mitigation of this risk:
-
- o Clients SHOULD ignore the immutable extension from resources that
- are not part of an authenticated context such as HTTPS.
- Authenticated resources are less vulnerable to cache poisoning.
-
- o User agents often provide two different refresh mechanisms: reload
- and some form of force-reload. The latter is used to rectify
- interrupted loads and other corruption. These reloads, typically
- indicated through no-cache request attributes, SHOULD ignore the
- immutable extension as well.
-
- o Clients SHOULD ignore the immutable extension for resources that
- do not provide a strong indication that the stored response size
- is the correct response size such as responses delimited by
- connection close.
-
-
-
-
-
-
-
-
-
-
-
-McManus Standards Track [Page 4]
-\f
-RFC 8246 HTTP Immutable Response September 2017
-
-
-4. IANA Considerations
-
- The immutable extension has been registered in the "Hypertext
- Transfer Protocol (HTTP) Cache Directive Registry" per the guidelines
- described in Section 7.1 of [RFC7234].
-
- o Cache Directive: immutable
-
- o Reference: RFC 8246
-
-5. References
-
-5.1. Normative References
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119,
- DOI 10.17487/RFC2119, March 1997,
- <https://www.rfc-editor.org/info/rfc2119>.
-
- [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
- Protocol (HTTP/1.1): Conditional Requests", RFC 7232,
- DOI 10.17487/RFC7232, June 2014,
- <https://www.rfc-editor.org/info/rfc7232>.
-
- [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
- Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
- RFC 7234, DOI 10.17487/RFC7234, June 2014,
- <https://www.rfc-editor.org/info/rfc7234>.
-
- [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
- 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
- May 2017, <https://www.rfc-editor.org/info/rfc8174>.
-
-5.2. Informative References
-
- [REQPERPAGE]
- HTTP Archive, "Total Requests per Page",
- <http://httparchive.org/interesting.php#reqTotal>.
-
-
-
-
-
-
-
-
-
-
-
-
-
-McManus Standards Track [Page 5]
-\f
-RFC 8246 HTTP Immutable Response September 2017
-
-
-Acknowledgments
-
- Thank you to Ben Maurer for partnership in developing and testing
- this idea. Thank you to Amos Jeffries for help with proxy
- interactions and to Mark Nottingham for help with the documentation.
-
-Author's Address
-
- Patrick McManus
- Mozilla
-
- Email: mcmanus@ducksong.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-McManus Standards Track [Page 6]
-\f
projects / thirdparty / squid.git / commitdiff
