D. Bryan Internet Draft Jasomi Networks Document: draft-bryan-midcom-simple-strawman- September 2001 00.txt Expires: Apr, 2002 A Simple Middlebox Protocol Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026 [RFC2026]. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. 1. Abstract This is a very simple strawman protocol for agents to request NAT address translations and firewall pinholes from a middlebox. This protocol uses the underlying transport for reliability and to avoid reinventing TCP. This protocol does not use an existing protocol like COPS, SOAP, HTTP or DIAMETER as these protocols include significant complexity that is not required to solve the middlebox problem. 2. Conventions 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 RFC-2119 [RFC2119]. In the examples, "C->S:" indicates requests from client to server; "S->C:" indicates responses from server to client. Throughout this document, a text-based encoding is used. Appendix A describes a simple binary-encoded alternative for those so inclined. Note that while the examples given may show requests that continue Bryan Expires: Feb 2002 1 Simple MIDCOM Strawman on another line, line-folding is not supported in (the text-based version of) this protocol. 3. Overview This is a strawman protocol for agents to request [NAT] address translations and firewall pinholes from a [middlebox]. This protocol uses the underlying transport for reliability and to avoid reinventing TCP. This protocol does not use an existing protocol like [COPS], [SOAP], [HTTP], or [DIAMETER] as these protocols include significant complexity that is not required to solve the middlebox problem. This proposal is a client-server protocol. The middlebox is a server, and the agent is a client. The agent opens a TCP or [TLS] connection to the middlebox, over which it sends requests to middleboxes. Each request affects a pinhole on a middlebox. Each request is identified by a request ID that is unique to the agent. Each pinhole is identified by a pinhole ID that is unique to the middlebox. There is a response to each request. Servers MUST support TCP and MAY support TLS or [SCTP]. Requests MAY be sent in batches. The response or failure of a request is independent of other requests. 3.1. Basic Operations The Basic operations of the protocol manipulate pinholes and NAT mappings. These four basic operations are ALLOC, OPEN, CLOSE, and DEALLOC. ALLOC: Allocates ports on the middlebox for later use. OPEN: Opens pinholes or creates NAT mappings. May reuse an existing reservation or create a new one. CLOSE: Closes pinholes or removes NAT mappings but DOES NOT free reservations. DEALLOC: Releases allocations and closes any pinholes or NAT mappings associated with those resources. Agents which open pinholes in a firewall-type midbox typically do not require any allocation. The agent SHOULD simply use OPEN to create the pinhole and MAY use either CLOSE or DEALLOC to close it. It is RECOMMENDED that agents which set up a large number of NAT mappings on behalf of multiple end users should allocate a pool of addresses using ALLOC, and then repeatedly OPEN and CLOSE the allocated resources as needed, finally using DEALLOC when the pool is no longer needed, or if the agent is administratively shutdown. Bryan Expires: Feb 2002 2 Simple MIDCOM Strawman Agents that need to learn an outside address and port prior to actually creating the mapping, also use ALLOC and then later OPEN with those resources. The [SDP] portion of [SIP] is an example of a protocol in which the user must advertise a specific port, before the address of the destination of the mapping is available. Resources so allocated SHOULD be released directly using DEALLOC. A separate CLOSE is not necessary. In addition, agents MAY send an empty AUTH message to a well known multicast address (defined later) in order to discover nearby middleboxes. Servers within the local multicast domain SHOULD respond to the client, allowing them to locate these boxes to traverse administrative boundaries. 3.2. Using Tuples to express requested pinholes/mappings A pinholes and mappings are created using a full 10-tuple which MAY contain wildcards. A 10-tuple consists of: - Transport (ex: TCP, UDP, ICMP, GRE) - Direction (ex: Bi-directional or Unidirectional) - Source IP address (IPv4 or IPv6), and Source port number - Destination IP address, and Destination port number - (optional) Inbound middlebox interface (address and port) - (optional) Outbound middlebox interface (address and port) All IP addresses MUST be expressed in IPv6 notation. For example, the IPv4 address "10.1.1.1" is expressed as ":FFFF::10.1.1.1". The same address on port 4000 is expressed as "[:FFFF::10.1.1.1]:4000". For transports that do not use port numbers (for example ICMP), the sender MUST set the port to zero, and the receiver MUST ignore the port number. Most fields in a request can contain wildcards. A value of zero in any field of a 10-tuple signifies a wildcard or don't care situation. Direction is from the perspective of the source field of the tuple to the destination. In the case of connected protocols such as TCP, directionality refers to who can initiate the connection. For example, if a pinhole is opened as unidirectional, connections initiated by the destination will be rejected, while those initiated by the source will be accepted. If the connection is bi-directional, either side may initiate the connection. 3.3. Practical examples The following request allocates any 4 contiguous port numbers (the third argument of ALLOC specifies the number of ports to open) for 1 hour. The first argument of all commands, 1 in this case, is a sequence number specified by the client. Note that the returned port numbers MUST be contiguous, starting from the first port returned, but the hole-ids (in this case, the last four parameters, 5005, Bryan Expires: Feb 2002 3 Simple MIDCOM Strawman 5001, 5002 and 5000) are of significance only to the middlebox. They may be apparently random so long as they are unique on the middlebox. The return also specifies how many ports were allocated and how long they are allocated for, which may be different from the time requested. C->S: ALLOC 1 [:FFFF::0.0.0.0]:0 4 3660secs S->C: 1 success [:FFFF::44.25.1.12]:4096 4 7500secs 5005 5001 5002 5000 This request opens a bi-directional UDP pinhole/mapping from 10.1.1.12:4000 to 178.22.42.15:1969, with a timeout value of one hour. The four addresses provided are the source, incoming interface, outgoing interface, and destination. By setting the two interface fields to zero, the requestor is specifying that they do not care which interfaces are used. Note that the translated addresses (the interfaces) are provided in the response. C->S: OPEN 2 5000 [:FFFF::10.1.1.12]:4000 [:FFFF::0.0.0.0]:0 [:FFFF::0.0.0.0]:0 [:FFFF::178.22.42.15]:1969 UDP bi 3660secs S->C: 2 success 5000 [:FFFF::10.1.1.12]:4000 [:FFFF::10.1.1.1]:3502 [:FFFF::44.25.1.12]:4100 [:FFFF::178.22.42.15]:1969 UDP bi 3000secs The following request closes the pinhole opened in the previous command. C->S: CLOSE 3 5000 S->C: 3 success The following request releases hole-id 5005 into the pool of available resources. Any pinholes or mappings would be automatically closed as well. C->S: DEALLOC 12 5005 S->C: 12 success 3.4. Other Primitives In addition to the pinhole primitives, HTTP-style Basic and Digest authentication [RFC2617] are available using the AUTH request C->S: AUTH 1 Basic ZnJlZDplZ2dwbGFudAo= S->C: 1 success or Bryan Expires: Feb 2002 4 Simple MIDCOM Strawman C->S: LIST 1 S->C: 1 need-auth Basic realm="midbox.domain.org" C->S: AUTH 2 Basic ZnJlZDplZ2dwbGFudAo= S->C: 2 success or C->S: AUTH 1 Digest username="fred", realm="", nonce="", response="" S->C: 1 auth-fail Digest realm="midbox.domain.org", stale="true", nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093" C->S: AUTH 2 Digest username="fred", realm="midbox.domain.org", nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", response="8402e591c2a0b8e4a988a67c579cee45" S->C: 2 success Since all ALLOC and OPEN requests are limited in duration, a REFRESH request is provided to keep these pinholes active. The middlebox MAY change the actual timeout duration to any value it wishes (longer or shorter). The value the middlebox chooses is returned in the response. C->S: REFRESH 5 5002 3660secs S->C: 5 success 1220secs The optional LIST request lists the pinholes which are open or allocated, for which the current user or connection has the authority to modify. C->S: LIST 15 S->C: 15 success 5000 <10tuple> 3660secs 5001 <10tuple> 1880secs [or] 5000 [:FFFF::10.1.1.12]:986 [:FFFF::0.0.0.0]:0 [:FFFF::173.21.3.46]:452 [:FFFF::44.22.37.52]:5678 UDP bi 3660secs 5001 [:FFFF::10.1.1.15]:3909 [:FFFF::0.0.0.0]:0 [:FFFF::173.21.3.46]:457 [:FFFF::192.86.34.23]:7111 UDP uni 1880secs Bryan Expires: Feb 2002 5 Simple MIDCOM Strawman [Note that formatting is for readability ONLY] Finally, the optional ATTRIB request modifies parameters of the pinhole. For example, this request sets the "diffserv" parameter to "ef", which presumably sets expedited forwarding on packets as they leave the middlebox. C->S: ATTRIB 19 5003 diffserv ef S->C: 19 success 4. Semantics Each request begins with an operation name (which must be uppercase), and a request-id. The request-id is unique to the agent on a per-TCP connection basis. [A simple algorithm to generate a unique request-id is to begin at an integer (we suggest 1) and increment by one for each request]. Note that the request-id has no meaning or sequence semantics to the middlebox and is only used to correlate a response with its corresponding request. 4.1. Expiration The expires parameter, in an ALLOC, OPEN, or REFRESH request, indicates how long the agent wishes to maintain the requested resource. The expires parameter is expressed as the number of seconds from the receipt of the request. This may cause a skew of a few seconds between the agent and the middlebox, but this is not considered significant, and avoids the need for clock synchronization. The middlebox returns the actual amount of time (again in seconds) before it will automatically release the allocated resources. This number MAY be larger or smaller than the requested value. Expiration values on the order of minutes or hours are RECOMMENDED. 4.2. Address parameters The Source address is the address and port of the host sending the packets for which the pinhole is established. The Inbound address is the address of the middlebox interface which receives these packets. The Outbound address is the address of the middlebox interface which resends these packets. The Destination address is the address of the host finally receiving the packets. S --- I [ ] O --- D Clients of a firewall-type middlebox frequently will not care about the Inbound or Outbound addresses. In many cases these may be set to zero to indicate the default. In traditional NAT cases, clients will frequently not care about the Inbound addresses. In Twice NAT Bryan Expires: Feb 2002 6 Simple MIDCOM Strawman [RFC2663] cases, all four addresses are needed. In addition, the Inbound and/or Outbound addresses are useful to identify the interface in use on multihomed middleboxes. An address consists of an IPv6 address (or IPv4 address in IPv6 notation) and a port number. For protocols which do not use port numbers (ex: ICMP), the port number is ignored. In general either an IP address or port number may be zero to denote "don't care". 4.3. Pinhole IDs Pinhole IDs are identifiers unique only to a middlebox. Hole-ids are arbitrary identifiers--agents should not attribute any meaning to them. Each hole-id corresponds to a 10-tuple, which may include some null parameters. Allocations for multiple port numbers will result in the same number of hole-ids being assigned. Note that for a range of consecutive port numbers the corresponding hole-ids are not necessarily consecutive. 4.4. Request Operations 4.4.1. The ALLOC Operation The Alloc operation allocates numports consecutive ports on a NAT middlebox. (Numports = 0 is invalid). The IP address portion of "address" indicates from which interface to allocate the ports. This IP address may be zero to request the default public interface. If the port portion of address is nonzero, it represents the lowest (first) port number in the block of consecutive ports requested. If the port portion is zero, the middlebox may choose an appropriate port--provided that if numports is even, the first allocated port number must also be even. Servers and Clients MUST support ALLOC. alloc = "ALLOC" SP req-id SP address SP protocol SP numports SP expires A successful response to an ALLOC request consists of the starting IP address and port number, the number of ports requests, the expiration time for all of the pinholes, and a list of "numports" hole-ids. C->S: ALLOC 1 [:FFFF::0.0.0.0]:0 4 3660secs S->C: 1 success [:FFFF::44.25.1.12]:4096 4 3660secs 5005 5001 5002 5000 4.4.2. The OPEN Operation The OPEN operation opens pinholes or creates NAT mappings. If the hole-id is zero, the middlebox will assign a new hole-id and (if necessary) attempt to allocate a single NAT port. If the hole-id exists, the middlebox closes the old mapping/pinhole and opens the Bryan Expires: Feb 2002 7 Simple MIDCOM Strawman new one. In the case of a NAT, it continues to use the same ports that were previous allocated on the outgoing interface. open = "OPEN" SP req-id SP hole-id SP 10 tuple SP expires C->S: OPEN 2 5000 [:FFFF::10.1.1.12]:4000 [:FFFF::0.0.0.0]:0 [:FFFF::0.0.0.0]:0 [:FFFF::178.22.42.15]:1969 UDP bi 3660secs S->C: 2 success 5000 [:FFFF::10.1.1.12]:4000 [:FFFF::10.1.1.1]:3502 [:FFFF::44.25.1.12]:4100 [:FFFF::178.22.42.15]:1969 UDP bi 3660secs A successful response to an OPEN request contains the hole-id, the 10-tuple as actually opened, and the actual expiration time. If the OPEN is operating on a pure firewall, the input and output address will be used only to determine which interface to use. It is possible to specify the ports in the Inbound and Outbound address if required on a NAT. If the Inbound or Outbound port number corresponds to an interface that does not exists, a "conflict" error is returned. Servers and Clients MUST support OPEN. An OPEN with a source or destination address and/or port of 0, MAY be used to request a fan type configuration. If local policy does not allow this, a "too-promiscuous" error MUST be returned. If the Source and Inbound port number match that of an existing pinhole, a "conflict" error MAY be returned. Likewise, if the direction parameter indicates a bidirectional flow, and the Outbound or Destination port numbers match an existing Source and Inbound port, a "conflict" error MAY also be returned. Middleboxes SHOULD support either fan-type requests, or opening of multiple pinholes that use the same Source and Outside addresses and ports. (They MAY support both). For example, the following request first (unsuccessfully) attempts to allow all UDP traffic from 10.1.1.12 port 9806 to and from any address, then requests follow to open specific ports, first with a preallocated pinhole and then with an argument of 0, allowing the server to create a pinhole id for this transaction. C->S: OPEN 3 5005 [:FFFF::10.1.1.12]:9806 [:FFFF::0.0.0.0]:0 [:FFFF::0.0.0.0]:0 [:FFFF::0.0.0.0]:0 UDP bi 3660secs S->C: 3 too-promiscuous C->S: OPEN 4 5005 [:FFFF::10.1.1.12]:986 [:FFFF::0.0.0.0]:0 [:FFFF::0.0.0.0]:0 [:FFFF::44.22.37.52]:5678 UDP bi 3660secs S->C: 4 success 5005 [:FFFF::10.1.1.12]:986 [:FFFF::0.0.0.0]:0 [:FFFF::173.21.3.46]:452 [:FFFF::44.22.37.52]:5678 Bryan Expires: Feb 2002 8 Simple MIDCOM Strawman UDP bi 3660secs C->S: OPEN 5 0 [:FFFF::10.1.1.12]:986 [:FFFF::0.0.0.0] [:FFFF::173.21.3.46]:452 [:FFFF::192.54.23.12]:1620 UDP bi 1880secs S->C: 5 success 5012 [:FFFF::10.1.1.12]986 [FFFF::0.0.0.0] [:FFFF::173.21.3.46]:452 [:FFFF::192.54.23.12]:1620 UDP bi 1880secs In general, OPEN requests should be removed with a DEALLOC. If you specifically want to save the ports previously allocated by an OPEN, then you must use a CLOSE. 4.4.3. The CLOSE Operation The CLOSE operation closes pinholes or deletes NAT mappings WITHOUT deallocating the hole-ids, ports, and addresses associated with them. A hole-id of zero is invalid. The server returns a "no- pinhole" error if the specified hole-id does not exist. A successful response has no parameters. Servers and Clients MUST support CLOSE. close = "CLOSE" SP req-id SP hole-id C->S: CLOSE 3 5000 S->C: 3 success 4.4.4. The DEALLOC Operation The DEALLOC operation deallocates all resources corresponding to a pinhole, AND closes any associated ports or mappings. A hole-id of zero is invalid. The server returns a "no-pinhole" error if the specified hole-id does not exist. A successful response has no parameters. Servers and Clients MUST support DEALLOC. dealloc = "DEALLOC" SP req-id SP hole-id C->S: DEALLOC 12 5005 S->C: 12 success 4.4.5. The REFRESH Operation The REFRESH operation, renews the bindings of allocated or opened pinholes. The middlebox responds with the actual number of seconds from receipt that the middlebox will maintain state for the hole-id. The middlebox MAY increase or decrease the value requested. Although a client MUST NOT request a refresh of zero seconds, a server MAY respond with a refresh time of zero seconds, to indicate Bryan Expires: Feb 2002 9 Simple MIDCOM Strawman that the pinhole will expire immediately without possibility of further renewal. A hole-id of zero is invalid. The server returns a "no-pinhole" error if the specified hole-id does not exist. Servers and Client MUST support REFRESH. refresh = "REFRESH" SP req-id SP hole-id SP expiration C->S: REFRESH 5 5002 3660secs S->C: 5 success 1220secs 4.4.6. The LIST Operation The LIST operation lists the active hole-ids which the requesting agent or user is authorized to modify. Servers SHOULD support LIST and clients MAY support LIST. list = "LIST" SP req-id C->S: LIST 15 S->C: 15 success 5000 [:FFFF::10.1.1.12]:986 [:FFFF::0.0.0.0]:0 [:FFFF::173.21.3.46]:452 [:FFFF::44.22.37.52]:5678 UDP bi 3660secs 5001 [:FFFF::10.1.1.15]:3909 [:FFFF::0.0.0.0]:0 [:FFFF::173.21.3.46]:457 [:FFFF::192.86.34.23]:7111 UDP uni 1880secs [Note that formatting is for readability ONLY] 4.4.7. The ATTRIB Operation The ATTRIB operation sets parameters relevant to the specified hole- id. Servers and Clients MAY support ATTRIB. Servers which do not support ATTRIB MUST respond with an "unsuported-operation" error, whereas Servers which do not support the named parameter respond with a "parameter-unknown" error. This document does not define any ATTRIB parameters. attrib = "ATTRIB" SP req-id SP hole-id SP parameter SP value C->S: ATTRIB 19 5003 diffserv ef S->C: 19 success 4.4.8. The AUTH Operation The AUTH operation authenticates an agent (typically associated with a single human user) by carrying authentication information used by Basic and Digest authentication as defined in RFC2617 with small Bryan Expires: Feb 2002 10 Simple MIDCOM Strawman deviations noted below. Clients MUST support AUTH. Servers MAY support AUTH. Basic authentication MUST only be used when the agent to middlebox connection is encrypted and integrity protected. Clients MAY attempt to authenticate immediately, or MAY wait until challenged with a realm via a "need-auth" result code. auth = "AUTH" SP basic | digest-response basic = "Basic" SP base64 result-params = success-params | auth-params auth-params = basic-realm | digest-challenge basic-realm = "Basic" SP "realm=" realm C->S: AUTH 1 Basic ZnJlZDplZ2dwbGFudAo= S->C: 1 success or: C->S: LIST 1 S->C: 1 need-auth Basic realm="midbox.domain.org" C->S: AUTH 2 Basic ZnJlZDplZ2dwbGFudAo= S->C: 2 success [Note that the string "ZnJlZDplZ2dwbGFudAo=" is the base-64 encoding of "fred:eggplant" (the username "fred" and the password "eggplant".] For Digest authentication, the domain and digest-uri parameters are null and MUST not be included in a challenge or response. The Server MUST use a fresh nonce for each authentication, as this is the only protection against replay attacks. Replays are particularly insidious for this protocol as they establish an ongoing session with the middlebox. Calculating the response is as specified in RFC2617 section 3.2.2, except that the value of A2 is null. A2 is normally calculated from the method name and digest-uri, for which there is no analogy. Also it does not make sense to include the body of the request (an optional part of A2) in the authentication as message integrity in the lower layers is already a requirement. Therefore the response is ordinarily calculated as the hexadecimal encoding of the MD5 hash of the concatenation of: the password, a colon (:), the MD5 hash of A1, the nonce (unquoted), and a terminating colon character (:). A1 is equal to the concatenation Bryan Expires: Feb 2002 11 Simple MIDCOM Strawman of the username, a colon character (:), the realm, a colon character (:), and the password. C->S: AUTH 1 Digest username="fred", realm="", nonce="", response="" S->C: 1 auth-fail Digest realm="midbox.domain.org", stale="true", nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093" C->S: AUTH 2 Digest username="fred", realm="midbox.domain.org", nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", response="8402e591c2a0b8e4a988a67c579cee45" S->C: 2 success The intermediate steps for creating/verifying the example response are shown below. nonce is dcd98b7102dd2f0e8b11d0f600bfb0c093 A1 is fred:midbox.domain.org:eggplant A2 is null response = hex( MD5( "eggplant:" + MD5( A1 ) + nonce + ":" ) ) response is 8402e591c2a0b8e4a988a67c579cee45 Note well that line folding is for clarity only, and that all quotes are removed prior to calculating MD5. 4.5. Responses Each request has a matching response. Responses begin with the request-ID, followed by a SINGLE space character with the result code. Result codes must consist of at least 4 characters . Result codes may consist of only lowercase 7-bit ASCII alphabetic characters and hyphens ("-" characters, decimal xx). The "success" result code has a variable syntax depending on the type of request. The semantics of successful requests is described with each operation. The need-auth and auth-fail result codes share a specific syntax, and all other responses consist of only the request-id and the result code. A table of result codes and their meanings are listed below Result Code Meaning --------------- ------------------------------------------ success The request was successful Bryan Expires: Feb 2002 12 Simple MIDCOM Strawman need-auth The requester needs to authenticate auth-fail The presented credentials were invalid not-authorized The request is prohibited by user policy too-promiscuous The requests had too many wildcards conflict The request overlaps with another full All relevant middlebox ports are full unsupported The middlebox doesn't handle that operation bad-request Incorrect request syntax no-pinhole No such hole-id exists server-error Server is having trouble parameter-unknown The server does not understand the ATTRIB parameter used 5. Formal Syntax Each request and each response consists of a single line of parameters terminated by a CRLF. Line folding is NOT supported. All parameters are separated by a SINGLE space character (decimal 32). The following syntax specification uses the augmented Backus-Naur Form (BNF) as described in RFC-2234 [BNF]. request-line = request CRLF request = alloc | open | close | dealloc | refresh | list | attrib | auth alloc = "ALLOC" SP req-id SP outside SP protocol SP numports open = "OPEN" SP req-id SP hole-id SP 10tuple SP expires close = "CLOSE" SP req-id SP hole-id dealloc = "DEALLOC" SP req-id SP hole-id refresh = "REFRESH" SP req-id SP hole-id SP expires list = "LIST" SP req-id attrib = "ATTRIB" SP req-id SP hole-id SP param SP value auth = "AUTH" SP req-id SP method ------ response-line = req-id SP result-code [ SP result-params] CRLF Bryan Expires: Feb 2002 13 Simple MIDCOM Strawman result-params = success-params | auth-params success-params = open-result | alloc-result | refresh-result | list-result open-result = hole-id SP 10tuple SP expires alloc-result = outside SP numports SP expires SP hole-list refresh-result = hole-id SP expires list-result = list-item *[ SP list-item ] list-item = hole-id SP 10tuple SP expires hole-list = hole-id *[ SP hole-id ] auth-params = basic-realm | digest-challenge basic-realm = "Basic" SP "realm=" realm ------ 10tuple = source SP input SP output SP dest SP protocol SP direction source = address input = address output = address destination = address direction = "uni" | "bi" expires = int32 "secs" param = token value = token | quoted-string realm = quoted-string address = "[" IPv6-addr "]" ":" port req-id = int16 hole-id = int32 numports = int8 SP = %0d32 6. Open issues: 1) representation of time: use "seconds from now" or NTP time? Representing time in "seconds from now" is very simple, but may result in a slight skew (a small number of seconds). In the opinion of the authors, this skew is insignificant compared to typical timeout values. 2) Binary or text encoding? A sample encoding of each is included. Bryan Expires: Feb 2002 14 Simple MIDCOM Strawman 3) Is notification necessary? The authors view notification as merely a "nice to have", so following the principle of making the protocol as simple as possible, we explicitly chose not to include it. 4) Do we need to add a mask to address? For example, change the BNF for address to: address = IPv6-addr ["/" mask ] ":" port This is useful only for the destination address in firewall middlebox administration. The authors chose to leave this out for now in the name of simplicity. 5) How should ATTRIB parameters be handled? Should all parameters be IANA registered? 7. Security Considerations This protocol is particularly security sensitive in that it is designed to open and close pinholes on firewall middleboxes. All connections between an agent (client) and a middlebox (sever) MUST be authenticated using a suitable mechanism (for example an [IPsec] security association, a mutually-authenticated TLS connection, or the Basic or Digest authentication described in Section 4). The server MUST NOT honor any (non-authentication) requests until authentication is successful. The client and server SHOULD protect their communications with a message integrity mechanism such as available in IPsec or TLS. Use of message integrity is STRONGLY RECOMMENDED. In addition, these connections MAY be encrypted (this is RECOMMENDED). The server MUST NOT permit authentication using Basic authentication unless the connection is encrypted. Authentication similar to HTTP Basic and HTTP Digest is provided. A Server MAY also authenticate based on existence of an IPsec SA, or TLS connection. The Server SHOULD NOT "authenticate" based solely on the source IP address of the request. the Server MAY pass credentials from AUTHBASIC or AUTHDIGEST to a AAA server using a protocol such as RADIUS or DIAMETER. 8. References [NAT]P. Srisuresh and K. Egevang, ôTraditional IP Network Address Translator (Traditional NAT)ö, RFC3022, Internet Engineering Task Force, January 2001 Bryan Expires: Feb 2002 15 Simple MIDCOM Strawman [MIDCOM] P. Srisuresh, et al, ôMiddlebox Communication Architecture and frameworkö, draft-ietf-midcom-framework-04, Internet Engineering Task Force, October 2001 [COPS] D. Durham, et al, ôThe COPS (Common Open Policy Service) Protocol, RFC2748, Internet Engineering Task Force, January 2000 [DIAMETER] P. Calhoun, et al, ôDiameter Base Protocolö, draft-ietf- aaa-diameter-07, Internet Engineering Task Force, July 2001 [TLS]T. Dierks and C. Allen, ôThe TLS Protocol Version 1.0ö, RFC2246, Internet Engineering Task Force, January 1999 [IPsec]R. Atkinson, ôSecurity Architecture for the Internet Protocolö, RFC1825, Internet Engineering Task Force, August 1995 [SCTP] R. Stewart, et al, ôStream Control Transmission Protocolö, RFC2960, Internet Engineering Task Force, October 2000 [RFC2617] J. Franks, et al, ôHTTP Authentication: Basic and Digest Access Authenticationö, RFC2617, Internet Engineering Task Force, June 1999. [SDP] M. Handley and V. Jacobson, ôSDP: Session Description Protocolö, RFC2327, Internet Engineering Task Force, April 1998. [SIP] M. Handley, E. Schooler, and H. Schulzrinne, "SIP: Session Initiation Protocol", RFC2543, Internet Engineering Task Force, Nov 1998. [RFC2026] S Bradner, "The Internet Standards Process -- Revision 3", RFC2026 (BCP), IETF, October 1996. [RFC2119] S. Bradner, "Key words for use in RFCs to indicate requirement levels," Request for Comments (Best Current Practice) 2119, Internet Engineering Task Force, Mar. 1997. [BNF] D Crocker and P Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC2234, IETF, Nov 1997. [RFC2663] P. Srisuresh and M. Holdrege, ôIP Network Address Translator (NAT) Terminology and Considerationsö, RFC2663, Internet Engineering Task Force, August 1999. [SOAP] World Wide Web Consortium, "Simple Object Access Protocol (SOAP) 1.1", , May 2000. [HTTP] Fielding et al, ôHypertext Transfer Protocol -- HTTP/1.1", RFC 2616, Internet Engineering Task Force, June 1999. Bryan Expires: Feb 2002 16 Simple MIDCOM Strawman 10. Acknowledgments Funding for the RFC Editor is currently provided by the Internet Society. 11. Author's Addresses David Bryan Jasomi Networks 2033 Gateway Place, Suite 500 San Jose, CA 95110, USA Phone: +1 408 252 8647 Email: dbryan@jasomi.com Appendix A: Binary encoding The binary alternative presented is a simple TLV (Tag, Length, Value) encoding. All encodings are in network-byte order. All integers are unsigned. In this protocol, an encoding scheme such as ASN.1 is not needed, and so should be avoided. All requests begin with a 16-bit integer opcode, and a 16-bit integer length field. The length field is the number of octets which follows the request-id field. All requests contain at least a request-id (a 32-bit integer). 0 1 2 3 4 5 6 0123456789012345 6789012345678901 23456789012345678901234567890123 +---------------+----------------+--------------------------------+ | | | | | opcode | length | request-id | | | | | +--------------------------------+--------------------------------+ A table of opcodes is listed below. The encoding for each is discussed below briefly. All opcodes values are either a packed binary encoding, or an unterminated string. 0 AUTH 1 ALLOC 2 OPEN 3 CLOSE 4 DEALLOC 5 REFRESH 6 LIST 7 ATTRIB 8 AUTH The value which follows an AUTH request is an unterminated 7-bit ASCII string. The following BNF described the syntax of the string. Bryan Expires: Feb 2002 17 Simple MIDCOM Strawman AUTH-string = method SP auth-params method = ( basic | digest ) digest = "Digest" basic = "Basic" auth-params is identical to the syntax described in the main body of this document. The syntax of a need-auth response to an auth request is the same as for the request. All other responses are empty. ALLOC The value which follows an ALLOC request consists of an IPv6 address (represented as 128-bits in network order), a 16-bit port number, the 16-bit protocol number, 8-bits for the number of ports, and 32- bits for the expiration value. A successful response contains data in an identical format plus a list of 32-bit hole-ids. All other responses are empty. OPEN The value which follows an OPEN request consists of a hole-id, a complete 9-tuple, a direction indicator, and an expiration value. The direction indicator is a single octet which may be 0 for bidrectional or 1 for unidirectional (all other values are reserved). A successful response contains data in an identical format. All other responses are empty. REFRESH The value which follows a REFRESH request consists of a hole-id and expiration. A successful response contains data in an identical format. All other responses are empty. CLOSE/DEALLOC The value which follows a CLOSE or DEALLOC request consists of a single hole-id. The response contains no payload. LIST The payload of the list request is empty. A successful response contains a list of zero or more hole-id and 10 tuple structures. All other responses are empty. ATTRIB The value of an attrib request is an unterminated string--the concatenation of the attribute, a single space character, and the value. The response contains no payload. Responses 0 1 2 3 4 5 6 0123456789012345 6789012345678901 23456789012345678901234567890123 +---------------+----------------+--------------------------------+ Bryan Expires: Feb 2002 18 Simple MIDCOM Strawman | | | | | result | length | request-id | | | | | +--------------------------------+--------------------------------+ Table of Result Codes 0 success 1 need-auth 2 auth-fail 3 not-authorized 4 too-promiscuous 5 conflict 6 full 7 unsupported 8 bad-request 9 no-pinhole 10 server-error 11 parameter-unknown 12 Full Copyright Statement "Copyright (C) The Internet Society (date). 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. Bryan Expires: Feb 2002 19