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 <defined in RFC2617>
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", <http://www.w3.org/TR/2000/NOTE-SOAP-20000508>, 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.
<end of requests> 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
<end of results> 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